Appendix A: Sound

FM instrument patch presets

# Instrument Name   # Instrument Name
0 Acoustic Grand Piano   64 Soprano Sax †
1 Bright Acoustic Piano   65 Alto Sax †
2 Electric Grand Piano   66 Tenor Sax †
3 Honky-tonk Piano   67 Baritone Sax
4 Electric Piano 1   68 Oboe †
5 Electric Piano 2   69 English Horn †
6 Harpsichord   70 Bassoon
7 Clavinet   71 Clarinet †
8 Celesta   72 Piccolo
9 Glockenspiel   73 Flute †
10 Music Box   74 Recorder
11 Vibraphone †   75 Pan Flute
12 Marimba   76 Blown Bottle
13 Xylophone   77 Shakuhachi
14 Tubular Bells   78 Whistle †
15 Dulcimer   79 Ocarina
16 Drawbar Organ †   80 Lead 1 (Square) †
17 Percussive Organ †   81 Lead 2 (Sawtooth) †
18 Rock Organ †   82 Lead 3 (Triangle) †
19 Church Organ   83 Lead 4 (Chiff+Sine) †
20 Reed Organ   84 Lead 5 (Charang) †
21 Accordion   85 Lead 6 (Voice) †
22 Harmonica   86 Lead 7 (Fifths) †
23 Bandoneon   87 Lead 8 (Solo) †
24 Acoustic Guitar (Nylon)   88 Pad 1 (Fantasia) †
25 Acoustic Guitar (Steel)   89 Pad 2 (Warm) †
26 Electric Guitar (Jazz)   90 Pad 3 (Polysynth) †
27 Electric Guitar (Clean)   91 Pad 4 (Choir) †
28 Electric Guitar (Muted)   92 Pad 5 (Bowed)
29 Electric Guitar (Overdriven)   93 Pad 6 (Metallic)
30 Electric Guitar (Distortion)   94 Pad 7 (Halo) †
31 Electric Guitar (Harmonics)   95 Pad 8 (Sweep) †
32 Acoustic Bass   96 FX 1 (Raindrop)
33 Electric Bass (finger)   97 FX 2 (Soundtrack) †
34 Electric Bass (picked)   98 FX 3 (Crystal)
35 Fretless Bass   99 FX 4 (Atmosphere) †
36 Slap Bass 1   100 FX 5 (Brightness) †
37 Slap Bass 2   101 FX 6 (Goblin)
38 Synth Bass 1   102 FX 7 (Echo)
39 Synth Bass 2   103 FX 8 (Sci-Fi) †
40 Violin †   104 Sitar
41 Viola †   105 Banjo
42 Cello †   106 Shamisen
43 Contrabass †   107 Koto
44 Tremolo Strings †   108 Kalimba
45 Pizzicato Strings   109 Bagpipe
46 Orchestral Harp   110 Fiddle †
47 Timpani   111 Shanai †
48 String Ensemble 1 †   112 Tinkle Bell
49 String Ensemble 2 †   113 Agogo
50 Synth Strings 1 †   114 Steel Drum
51 Synth Strings 2 †   115 Woodblock
52 Choir Aahs †   116 Taiko Drum
53 Voice Doos   117 Melodic Tom
54 Synth Voice †   118 Synth Drum
55 Orchestra Hit   119 Reverse Cymbal
56 Trumpet †   120 Fret Noise
57 Trombone   121 Breath Noise
58 Tuba   122 Seashore †
59 Muted Trumpet †   123 Bird Tweet
60 French Horn   124 Telephone Ring
61 Brass Section   125 Helicopter
62 Synth Brass 1   126 Applause †
63 Synth Brass 2   127 Gunshot

† Instrument is affected by the LFO, giving it a vibrato or tremolo effect.

FM extended instrument patch presets

These presets exist mainly to support playback of drum sounds, and many of them only work correctly or sound musical at certain pitches or within a small range of pitches.

# Instrument Name   # Instrument Name  
128 Silent   146 Vibraslap  
129 Snare Roll   147 Bongo  
130 Snap   148 Maracas  
131 High Q   149 Short Whistle  
132 Scratch   150 Long Whistle  
133 Square Click   151 Short Guiro  
134 Kick   152 Long Guiro  
135 Rim   153 Mute Cuica  
136 Snare   154 Open Cuica  
137 Clap   155 Mute Triangle  
138 Tom   156 Open Triangle  
139 Closed Hi-Hat   157 Jingle Bell  
140 Pedal Hi-Hat   158 Bell Tree  
141 Open Hi-Hat   159 Mute Surdo  
142 Crash   160 Pure Sine  
143 Ride Cymbal   161 Timbale  
144 Splash Cymbal   162 Open Surdo  
145 Tambourine        

Drum presets

These are the percussion instrument mappings for the drum number argument of the ym_playdrum and ym_setdrum API calls, and the FMDRUM BASIC command.

# Instrument Name   # Instrument Name
      56 Cowbell
25 Snare Roll   57 Crash Cymbal 2
26 Finger Snap   58 Vibraslap
27 High Q   59 Ride Cymbal 2
28 Slap   60 High Bongo
29 Scratch Pull   61 Low Bongo
30 Scratch Push   62 Mute High Conga
31 Sticks   63 Open High Conga
32 Square Click   64 Low Conga
33 Metronome Bell   65 High Timbale
34 Metronome Click   66 Low Timbale
35 Acoustic Bass Drum   67 High Agogo
36 Electric Bass Drum   68 Low Agogo
37 Side Stick   69 Cabasa
38 Acoustic Snare   70 Maracas
39 Hand Clap   71 Short Whistle
40 Electric Snare   72 Long Whistle
41 Low Floor Tom   73 Short Guiro
42 Closed Hi-Hat   74 Long Guiro
43 High Floor Tom   75 Claves
44 Pedal Hi-Hat   76 High Woodblock
45 Low Tom   77 Low Woodblock
46 Open Hi-Hat   78 Mute Cuica
47 Low-Mid Tom   79 Open Cuica
48 High-Mid Tom   80 Mute Triangle
49 Crash Cymbal 1   81 Open Triangle
50 High Tom   82 Shaker
51 Ride Cymbal 1   83 Jingle Bell
52 Chinese Cymbal   84 Belltree
53 Ride Bell   85 Castanets
54 Tambourine   86 Mute Surdo
55 Splash Cymbal   87 Open Surdo

BASIC FMPLAY and PSGPLAY string macros

Overview

The play commands use a string of tokens to define sequences of notes to be played on a single voice of the corresponding sound chip. Tokens cause various effects to happen, such as triggering notes, changing the playback speed, etc. In order to minimize the amount of text required to specify a sequence of sound, the player maintains an internal state for most note parameters.

Stateful Player Behavior:

Playback parameters such as tempo, octave, volume, note duration, etc do not need to be specified for each note. These states are global between all voices of both the FM and PSG sound chips. The player maintains parameter state during and after playback. For instance, setting the octave to 5 in an FMPLAY command will result in subsequent FMPLAY and PSGPLAY statements beginning with the octave set to 5.

The player state is reset to default values whenever FMINIT or PSGINIT are used.

Parameter Default Equivalent Token
Tempo 120 T120
Octave 4 O4
Length 4 L4
Note Spacing 1 S1
Using Tokens:

The valid tokens are: A-G,I,K,L,O,P,R,S,T,V,<,>.

Each token may be followed by optional modifiers such as numbers or symbols. Options to a token must be given in the order they are expected, and must have no spacing between them. Tokens may have spaces between them as desired. Any unknown characters are ignored.

Example:

FMPLAY 0,"L4"      : REM DEFAULT LENGTH = QUARTER NOTE
FMPLAY 0,"A2. C+." : REM VALID
FMPLAY 0,"A.2 C.+" : REM INVALID

The valid command plays A as a dotted half, followed by C♯ as a dotted quarter.

The invalid example would play A as a dotted quarter (not half) because length must come before dots. Next, it would ignore the 2 as garbage. Then it would play natural C (not sharp) as a dotted quarter. Finally, it would ignore the + as garbage, because sharp/flat must precede length and dot.

Token definitions:

Musical notes

  • Synopsis: Play a musical note, optionally setting the length.
  • Syntax: <A-G>[<+/->][<length>][.]

Example:

FMPLAY 0,"A+2A4C.G-8."

On the YM2151 using channel 0, plays in the current octave an A♯ half note? followed by an A quarter note?, followed by C dotted quarter note, followed by G♭ dotted eighth note?.

Lengths and dots after the note name or rest set the length just for the current note or rest. To set the default length for subsequent notes and rests, use the L macro.

Rests

  • Synopsis: Wait for a period of silence equal to the length of a note, optionally setting the length.
  • Syntax: R[<length>][.]

Example:

PSGPLAY 0,"CR2DRE"

On the VERA PSG using voice 0, plays in the current octave a C quarter note, followed by a half rest (silence), followed by a quarter D, followed by a quarter rest (silence), and finally a quarter E.

The numeral 2 in R2 sets the length for the R itself but does not alter the default note length (assumed as 4 - quarter notes in this example).

Note Length

  • Synopsis: Set the default length for notes and rests that follow
  • Syntax: L[<length>][.]

Example values:

  • L4 = quarter note (crotchet)
  • L16 = sixteenth note (semiquaver)
  • L12 = 8th note triplets (quaver triplet)
  • L4. = dotted quarter note (1.5x the length)
  • L4.. = double-dotted quarter note (1.75x the length)

Example program:

10 FMPLAY 0,"L4"
20 FOR I=1 TO 2
30 FMPLAY 0,"CDECL8"
40 NEXT

On the YM2151 using channel 0, this program, when RUN, plays in the current octave the sequence C D E C first as quarter notes, then as eighth notes the second time around.

Articulation

  • Synopsis: Set the spacing between notes, from legato to extreme staccato
  • Syntax: S<0-7>

S0 indicates legato. For FMPLAY, this also means that notes after the first in a phrase don’t implicitly retrigger.

S1 is the default value, which plays a note for 7/8 of the duration of the note, and releases the note for the remaining 1/8 of the note’s duration.

You can think of S is, out of 8, how much space is put between the notes.

Example:

FMPLAY 0,"L4S1CDES0CDES4CDE"

On the YM2151 using channel 0, plays in the current octave the sequence C D E three times, first with normal articulation, next with legato (notes all run together and without retriggering), and finally with a moderate staccato.

Explicit retrigger

  • Synopsis: on the YM2151, when using S0 legato, retrigger on the next note.
  • Syntax: K

Example:

FMPLAY 0,"S0CDEKFGA"

On the YM2151 using channel 0, plays in the current octave the sequence C D E using legato, only triggering on the first note, then the sequence F G A the same way. The note F is triggered without needing to release the previous note early.

Octave

  • Synopsis: Explictly set the octave number for notes that follow
  • Syntax: O<0-7>

Example:

PSGPLAY 0,"O4AO2AO6CDE"

On the VERA PSG using voice 0, changes to octave 4 and plays A (440Hz), then switches to octave 2, and plays A (110Hz), then switches to octave 6 and plays the sequence C D E

Octave Up

  • Synopsis: Increases the octave by 1
  • Syntax: >

If the octave would go above 7, this macro has no effect.

Example:

PSGPLAY 0,"O4AB>C+DE"

On the VERA PSG using voice 0, changes to octave 4 and plays the first five notes of the A major scale by switching to octave 5 starting at the C♯

Octave Down

  • Synopsis: Decreases the octave by 1
  • Syntax: <

If the octave would go below 0, this macro has no effect. Example:

PSGPLAY 0,"O5GF+EDC<BAG"

On the VERA PSG using voice 0, changes to octave 5 and plays the G major scale from the top down by switching to octave 4 starting at the B

Tempo

  • Synopsis: Sets the BPM, the number of quarter notes per minute
  • Syntax: T<1-255>

High tempo values and short notes tend to have inaccurate lengths due to quantization error. Delays within a string do keep track of fractional frames so the overall playback length should be relatively consistent.

Low tempo values that cause delays (lengths) to exceed 255 frames will also end up being inaccurate. For very long notes, it may be better to use legato to string several together.

Example:

10 FMPLAY 0,"T120C4CGGAAGR"
20 FMPLAY 0,"T180C4CGGAAGR"

On the YM2151 using channel 0, plays in the current octave the first 7 notes of Twinkle Twinkle Little Star, first at 120 beats per minute, then again 1.5 times as fast at 180 beats per minute.

Volume

  • Synopsis: Set the channel or voice volume
  • Syntax: V<0-63>

This macro mirrors the PSGVOL and FMVOL BASIC commands for setting a channel or voice’s volume. 0 is silent, 63 is maximum volume.

Example:

FMPLAY 0,"V40ECV45ECV50ECV55ECV60ECV63EC"

On the YM2151 using channel 0, starting at a moderate volume, plays the sequence E C, repeatedly, increasing the volume steadily each time.

Panning

  • Synopsis: Sets the stereo output of a channel or voice to left, right, or both.
  • Syntax: P<1-3>

1 = Left
2 = Right
3 = Both

Example:

10 FOR I=1 TO 4
20 PSGPLAY 0,"P1CP2B+"
30 NEXT I
40 PSGPLAY 0,"P3C"

On the VERA PSG using voice 0, in the current octave, repeatedly plays a C out of the left speaker, then a B♯ (effectively a C one octave higher) out of the right speaker. After 4 such loops, it plays a C out of both speakers.

Instrument change

  • Synopsis: Sets the FM instrument (like FMINST) or PSG waveform (like PSGWAV)
  • Syntax: I<0-255> (0-162 for FM)

Note: This macro is available starting in ROM version R43.

Example:

10 FMINIT
20 FMVIB 200,15
30 FMCHORD 0,"I11CI11EI11G"

This program sets up appropriate vibrato/tremolo and plays a C major chord with the vibraphone patch across FM channels 0, 1, and 2.