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.