X16 Reference - Appendix A - Sound.md

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.