Revision as of 2014-07-01T17:07:35

The power of the sound library of the Gamebuino is that is allow you to play sounds and musics in the background while you play your game without having to care about it. You just as "play this sound", and the library takes care of everything. But if you want to create sound FX an compose chiptunes, you should understand what happens under the hood. The goal of this article is to explain you how sound is generated and structured.

Layers

The sound library slices the sound data in different layers. We'll start from the deeper layer (wave form generation) and up to "chains".

Wave form generation

PWM is used at 32 KHz to generate an analog output. To be able to play several sounds at the same time, the library generate one waveform per channel and add them to output the result into the speaker. This is done using interruptions at a rate of 56 KHz. The waveform of each channel is changed once per frame, which is 20 Hz by default. A waveform has the folowing characteristics :

• Frequency, picked from a list of predefined frequencies which corresponds to different note pitches.
• Wave form
  • Square wave, 50% duty cycle
  • Noise

But you can't directly access this layer of the sound generation. The value this characteristics take will depend on the above layers : instruments and notes.

Instruments

Instrument sets

Notes

Commands

Patterns

Pattern sets

Chains

OLD

The following is outdated but stays here for reference until I finish to rewrite this article

The simplest way to make sound with your Gamebuino is to use the 3 predefined sounds (gb.sound.playOK(), gb.sound.playCancel() and gb.sound.playTick()). But this is quite limiting, and I'm sure you want some cool sound FX and chiptunes. To do so, you can compose your own musics and sounds using the tracker (you can download it from GitHub). But first you should understand how sound is made and structured.

Sound structure

This part explains how music is structured. In short, there is up to 4 channels, each channel plays a track, which is a mixed set of notes and commands. Each note is played using an instrument, which is a succession of steps. Commands are used to alter the way notes are played.

Channels

The sound library supports up to 4 channels. It means that you can play 4 different notes at the same time. But playing notes is not really interesting, we want to play chiptunes and bad-ass sound effects! That why we use "tracks". You can play one track per channel. For example, using gb.sound.playTrack(myTrack, 0) you play the track "myTrack" on the channel 0. Let's see what's inside a track

Chain

A chain is to top-level structure in a music. It it a array of pattern ID (picked from the pattern set defined using changePatternSet) along with a transposition for each pattern.

Pattern

A pattern is a mixed array of commands and notes (actually a 16 bit integers array).

Commands

Commands are used to alter the way notes are played. Each command has 2 parameters: X is between 0 and 31 and Y is between -16 and 15. A command remains active as long as it's not cancel by passing the command again with X = 0.

Available commands:

• 0 set note volume, X = volume (0 to 9)
• 1 select instrument, X = instrument ID
• 2 volume slide, X = step duration, Y = step size
• 3 arpeggio/portamento, X = step duration, Y = step size
• 4 tremolo, X = step duration, Y = step size

Notes

Each note have the following parameters:

• Pitch, 0 to 58 for pitches from A#2 to D#8. 63 for a silent note.
• Duration in number of frames (1/20s by default). From 0 to 255.

Instrument set

Each channel has a instrument set assigned to it. An instrument set is an array of instruments. When you use the command "select instrument" in a pattern, it select and instrument from the active instrument set. By default, the instruments are

• 0 : continuous square wave
• 1 : continuous noise

But these are really basic instruments. It's better to create your own instruments.

Instrument

An instrument is an array of 16 bits integers. The first int (the header) define 2 parameters:

• instrument length (from 0 to 255) : how many steps there are in the instrument
• last steps looping (from 0 to 255) : when the note duration is longer than the instrument's duration (which is the sum of the duration of its steps), the track will loop on the last X steps of the instrument.

Each following int in the array correspond to a "step". Each step has the following parameters:

• volume (from 0 to 7) : used to create a volume envelope
• waveform: should this step be play either as square wave or as noise
• step duration in number of frames (from 0 to 63)
• pitch offset (from 0 to 63) : an offset to apply to the note's pitch.