Sound chip specifications - chiptunecafe/VGMCK_Arch GitHub Wiki

Sound chip specifications

This page lists all of the sound chips supported by VGMCK, along with their respective specifications.

Debug chip

  • Command: #EX-DEBUG
  • Macro commands: (any)
  • Channel groups: (any)
  • c (1) = Clock rate in Hz. If negative, note periods are used. If zero, the note numbers are used directly.
  • n (16) = Note bits.
  • o (9) = Basic octave.
  • x (1) = Miscellaneous.
  • y (0) = Miscellaneous.

This is not a real chip and is not sent to the .VGM file. All commands and notes are allowed, and are sent to the stdout. This is mostly used to debug VGMCK itself, and is not normally very useful otherwise.

SN76489 PSG (Sega, BBC Micro, PCjr, Tandy)

  • Command: #EX-PSG
  • Macro commands: v (0..15) P (-1..+1)
  • Channel groups: square (6), noise (2)
  • H (3579545) = Clock rate in Hz.
  • F (9) = Feedback register. It might not work properly unless it has exactly two bits set. Use 9 for Sega Master System 2/Game Gear/Mega Drive, 3 for Sega Computer 3000H/BBC Micro, and 6 for SN76494/SN76496. It is not recommended to use other numbers here.
  • S (16) = Shift register. Use 16 for Sega Master System 2/Game Gear/Mega Drive and 15 for Sega Computer 3000H/BBC Micro. It is not recommended to use other numbers here.
  • d (on) = Enable /8 clock divider.
  • f (off) = Frequency 0 is 0x400 if this is turned on.
  • n (off) = Output negate flag.
  • s (on) = Enable stereo.

For the noise channel, use of the notes e f f+ is recommended.

OPL2 (Yamaha YM3812)

  • Command: #EX-OPL2
  • Macro commands: v (0..63) @ (macro) @G (0..15)
  • Channel groups: melody (18), Hat (2), Cymbal (2), Tom (2), SD (2), BD (2)
  • H (3579545) = Clock rate in Hz.

The @ command selects a macro defined by @x which sets up the operators:

  • 0: Tremolo/Vibrato/Sustain/KSR/Freq.Mul for modulator. (Bit7 sets tremolo, bit6 sets vibrato, bit5 maintains the sustain level until the note is released, bit4 shortens the envelope by high pitch, low 4 bits set the frequency multiplier: 0=1/2, 1 to 10=1 to 10, 12=12, 14=15)
  • 1: Tremolo/Vibrato/Sustain/KSR/Freq.Mul for carrier.
  • 2: Key Scaling/Output Level for modulator (if the additive mode is used, it is relative to the user volume). (High 2 bits reduce volume by high pitch, low 6 bits set the volume (all bits clear is maximum volume))
  • 3: Key Scaling/Output Level for carrier (relative to user volume).
  • 4: Attack/Decay for modulator. (High 4 bits are attack and low 4 bits are decay; zero is slow and fifteen is fast)
  • 5: Attack/Decay for carrier.
  • 6: Sustain/Release for modulator. (High 4 bits is the sustain level, and the low
  • 4 bits is the release rate; the sustain level can set the attenuation between 0 and 15.)
  • 7: Sustain/Release for carrier.
  • 8: Waveform for modulator. Waveforms: 0=sine, 1=only positive, 2=absolute, 3=only rising of absolute
  • 9: Waveform for carrier.
  • 10: Feedback/Algorithm. Bit 3,2,1 selects feedback, and bit 0 selects algorithm (set for additive, clear for FM).
  • 11: Used only with hat and cymbal channels, change the relative octave setting of the two channels used. This can be positive, negative, or zero.

The operator setting will be shared for the hat, snare, and cymbal channels, due to the function of OPL2. The tom and bass drum channels have their own operators, although the hat, snare, tom, and cymbal channels all share the same notes, unless the hat and cymbal channels are not used.

The @G command changes global settings for the current chip instance:

  • 1 = set for 14 cents vibrato, clear for 7 cents vibrato.
  • 2 = set for 4.8 dB tremolo, clear for 1 dB tremolo.
  • 4 = selects the keyboard split point (unsure how it works).
  • 8 = set for composite sine wave speech synthesis (unsure how it works; it is not available in VGM anyways).

Note: You can only have 12 melody channels if there are two percussion channels, 15 if there is only one percussion channel, or up to 18 if there are no percussion channels.

PC-Engine / HuC6280

  • Command: #EX-PCENGINE
  • Macro commands: v (0..31) P (-15..+15) @W (macro) @ (0..7) @G (0..255) @WM (macro) M (1..1023)
  • Channel groups: normal (12), FM (2), noise (4)
  • H (3579545) = Clock rate in Hz.

Normal channels can only go up to 12 if the other channels are not used. Each noise channel costs one normal slot, and each FM channel costs two normal slots.

The @G macro is used for global panning; the high four bits for left channel and low four bits for right channel. This affects both chip instances (use a direct write command if you want only one).

The @W macro is a waveform of 2, 4, 8, 16, or 32 frames, having numbers 0 to 31 in it, or having -16 to +15 for frequency modulation waveform, which is selected on the FM channel only with the @WM command.

The @ command is usable on the FM channel, and selects the FM depth: 0 for no modulation, 1 for 1x modulation, 2 for 16x modulation, and 3 for 256x modulation. Numbers 4 to 7 can be used to make the modulator period fixed rather than relative to the note being played.

The M command is usable on the FM channel, and is used to multiply the period of the modulator waveform by one fourth of the number specified. For example, M1 specifies to make the modulator four times as fast as the carrier.

NeoGeo Pocket

  • Command: #EX-NGP
  • Macro commands: v (0..15) P (-15..+15) @ (0..1)
  • Channel groups: square (3), special (1)
  • H (3072000) = Clock rate in Hz.

This functions mostly like PSG, except the "special" channel can play notes or white noise, and that the panning has more range. The @ command is only used for the special channel, where 1 means noise and 0 means tones.

Warning: This chip cannot be used together with #EX-PSG in the same file! This is because the the NGP uses 2 partial PSG cores.

Nintendo Famicom

  • Command: #EX-FAMICOM
  • Macro commands: v (0..15) @ (0..3)
  • Channel groups: square (4), triangle (2), noise (2)
  • H (1789772) = Clock rate in Hz. Change this to 1662607 for PAL NES, or to 1773448 for Dendy. The default value can be used for NTSC and RGB Famicom.

The square channels use @ for duty (0=12.5%, 1=25%, 2=50%, 3=75%).

The triangle channel has no volume control.

For the noise channel, select octave 0 for long noise and octave 1 for short noise.

Note: DPCM is currently not supported in VGMCK, although you can still use direct writes to the DPCM registers.

Nintendo GameBoy Dot Matrix Game

  • Command: #EX-GAMEBOY
  • Macro commands: v (0..15) @ (0..3) P (-1..+1) @W (macro) ve (-15..+15)
  • Channel groups: square (4), wavetable (2), noise (2)
  • H (4194304) = Clock rate in Hz.

The square channels use @ for duty (0=12.5%, 1=25%, 2=50%, 3=75%), and volume 0 to 15. Software envelopes are not available for square channels on GameBoy; use hardware envelopes (ve) instead.

The wave channel uses a waveform of 32 frames, with values 0 to 15. This channel can use only volume 0 to 3, and uses software envelopes.

The noise channel uses volume 0 to 15 and uses hardware envelopes.

Q Sound

  • Command: #EX-QSOUND
  • Macro commands: v (0..4095) @S (macro) P (-16..+16)
  • Channel groups: normal (16)
  • Sample format: signed 8-bits mono
  • H (4000000) = Clock rate in Hz.

Sample header:

  • Loop start
  • Loop end
  • Pitch shift bits (range: 1 to 16)
  • Clock rate for calculating pitch (if negative, uses loop period instead)
  • Fixed pitch number (used with negative clock rates)
  • Octave shift: If clock rate is positive, the highest octave number (default 8), otherwise the lowest octave number (default 0).

Note: It is necessary to set the panning for this to work.

OPLL (Yamaha YM2413)

  • Command: #EX-OPLL
  • Macro commands: v (0..15) @ (macro)
  • Channel groups: melody (18), rhythm (2)
  • H (3579545) = Clock rate in Hz.

The melody channels can use the @ command to select a built-in instrument (1 to 15) or a sustained built-in instrument (17 to 31). @x32 and above defines a custom patch, and you can use @0 to use the last defined patch. You cannot use multiple custom instruments at the same time.

Instrument settings (@):

  • 0 = Repeat last custom instrument setting
  • 1 = Violin
  • 2 = Guitar
  • 3 = Piano
  • 4 = Flute
  • 5 = Clarinet
  • 6 = Oboe
  • 7 = Trumpet
  • 8 = Organ
  • 9 = Horn
  • 10 = Synthesizer
  • 11 = Harpsichord
  • 12 = Vibraphone
  • 13 = Synthesizer bass
  • 14 = Acoustic bass
  • 15 = Electric guitar
  • 17 to 31 = Violin to Electric guitar, but sustained

Custom instrument settings (binary values):

  • TVSK MMMM = Tremolo, vibrato, sustain, key scale, and multipler for the modulator, where 0=1/2, 1-10=1-10, 12=12, and 14=15.
  • TVSK MMMM = As above, but for the carrier.
  • KKLL LLLL = K is key scaling and L is the attenuation level of the modulator, where 0 is the loudest and 63 is the quietest.
  • KK-Q WFFF = K is key scaling of carrier. Q and W is carrier and modulator waveforms; 0 for sine wave and 1 for rectify sine wave. F is the feedback amount of modulator.
  • AAAA DDDD = Attack and decay for modulator.
  • AAAA DDDD = Attack and decay for carrier.
  • SSSS RRRR = Sustain and release for modulator. If sustain is zero means max volume (no attenuation), higher numbers attenuate sustain level.
  • SSSS RRRR = Sustain and release for carrier.

Rhythm channels each take up three slots of the melody. On rhythm channels, the @ command selects which drum to play by using five bits (one bit for each drum). The next nine bits, if any are set, fix the frequency register to the specified number. You can also use @S in the same way as @ , so you can use sample lists to program drum kits into MML.

zzo38's notes: Apparently this chip can also be used with teletext, but I don't know how. (I don't even think teletext has music, so I don't know what is the point of that at all.)

Atari POKEY

  • Command: #EX-POKEY
  • Macro commands: v (0..15) @ (0..7) M (-16..+16)
  • Channel groups: normal (4), hi-res (2), filtered (2)
  • H (1789772) = Clock rate in Hz.
  • p (off) = If set, uses 9-bits poly-counters, otherwise 17-bits.
  • c (off) = If set, normal channels use 15 KHz clock, otherwise 64 KHz.
  • x (off) = Makes the M command range from 0 to 255 and makes the filter fixed.

The @ command causes poly-counters to be used to make noise; use 7 for pure tones. If this is 0 or 4, the option "p" will be used.

You can use M on filtered channels to set the filter multiplier. Positive numbers cause multiplication, negative numbers cause division, and zero causes a fixed setting for the filter.

You cannot use hi-res and filtered channels together, and using either of them takes up two slots of the normal channels for each one used.

General Instruments AY-3-8910

  • Command: #EX-GI-AY
  • Macro commands: v (0..15) @S (0..31) @ (0..31) M (any) ve (any)
  • Channel groups: square (6), special (2)
  • H (1789750) = Clock rate in Hz.
  • T (0) = Chip type (0=AY8910, 1=AY8912, 2=AY8913, 3=AY8930, 16=YM2149, 17=YM3439, 18=YMZ284, 19=YMZ294). If AY8930 is selected, it operates in compatibility mode, rather than expanded capability mode (for expanded capability mode, use #EX-AY8930 instead).
  • S (1) = Octave shift between envelope and note on special channels.
  • l (on) = Legacy output.
  • s (off) = Single output.
  • d (off) = Discrete output.
  • r (off) = Raw output.

Square channels - only v and @ can be used, and @ ranges from 0 to 3.

Special channels - @ command has the full range, and only any one command out of v, M and ve can be used at once; using one overrides the others. In addition, @S is used to set the noise period from 0 to 31 (it is not used to select a sample on these channels). The @ command uses a 5-bit number, where: Bit0 is cleared to play square waves. Bit1 is cleared to play noise. Bit2 is set to cause the envelope to hold; if it is clear, it will repeat. Bit3 is set to make the direction alternate. Bit4 specifies envelope direction; set for rising and clear for falling. If ve is used, it sets a volume envelope. Positive numbers cause the envelope to rise when the key is on, and negative numbers will cause it to fall and eventually silence. If M is used, it is a multiplier for the period if positive, and then is divided by 64; if zero or negative, it sets the envelope period directly.

The special channels each take one slot of square channels.

AY8930

  • Command: #EX-AY8930
  • Macro commands: v (0..31) @ (0..255) M (any) ve (any)
  • Channel groups: special (6)
  • H (1789750) = Clock rate in Hz.
  • S (0) = Octave shift between envelope and note.
  • l (on) = Legacy output.
  • s (off) = Single output.
  • d (off) = Discrete output.
  • r (off) = Raw output.

This is mostly like the AY-3-8910, except it only uses special channels, and there are more bits for the @ command. The @S command is unavailable. Bit5, bit6 and bit7 select the duty cycle as follows: 0=1/32, 1=1/16, 2=1/8, 3=1/4, 4=1/2, 5=3/4, 6=7/8, 7=15/16.

Noise can be set up using direct writes.

Warning: This chip cannot be used with #EX-GI-AY in the same file. AY8930 does not currently work properly in VGMPlay (probably because MAME doesn't emulate AY8930; a new GPL'd emulator ought to be written for these sound chips, which will work properly).

Yamaha OPL3 (YMF262)

  • Command: #EX-OPL3
  • Macro commands: v (0..63) P (-1..+1) @ (macro) @G (0..15) @S (0..32767)
  • Channel groups: two-ops (36), four-ops (12), rhythm (2)
  • H (14318180) = Clock rate in Hz.

The four-ops channels each take up two slots of the two-ops channels, and the rhythm channels each take up three slots of the two-ops channels.

The @ command selects the set of FM operators defined using the @x macros. For two-ops the @x is defined as the following for each of two operators (binary values):

  • TVSK MMMM = Set tremolo, vibrato, sustain, envelope scaling, and the multiplication factor for this operator, where 0=1/2, 1-10=1-10, 12=12, and 14=15.
  • KKLL LLLL = Where K is the key scale level to attenuate output level towards higher pitch, and L attenuates the output of this operator, where 0 is the loudest and 63 is quiet.
  • AAAA DDDD = Attack and decay envelopes. Higher values cause shorter envelopes.
  • SSSS RRRR = Sustain level and release envelope.
  • ---A -WWW = Waveform select: 0=sine wave, 1=rectify sine wave, 2=absolute value of sine wave, 3=rising part of absolute value of sine wave ("pulse sine"), 4=even periods only of sine wave, 5=even periods of absolute of sine wave, 6=square wave, 7=derived square wave (I don't think it really is a derived square wave though). A is attenuation override; use 0 to attenuate this channel by the volume controls and 1 to ignore the volume control of this channel.

After that, is the binary value for the algorithm/feedback. For two-ops:

  • ---A -FFF = A is algorithm (0=FM, 1=additive). F is the feedback of the first operator.

For four-ops, the @x command uses the same binary values but for four operators, and this binary value is used for the algorithm/feedback instead:

  • --AA -FFF

Now the algorithms are as follows:

  • 0 = a:b:c:d
  • 1 = a+(b:c:d)
  • 2 = (a:b)+(c:d)
  • 3 = a+(b:c)+d

For the rhythm channels, the @x command uses six operators, and the the algorithm/feedback binary value is the same as the two-ops one. The rhythm channels can also use @S to select which drums to play using the low five bits, and if the other bits are set, it fixes the note frequency to the specified number.

The @G command has the same purpose as OPL2, except that CSW doesn't work.

OPL4

  • Command: #EX-OPL4
  • Macro commands: v (0..127) P (-7..+7) @ (0..3) @S (macro)
  • Channel groups: two-ops (36), four-ops (12), rhythm (2), PCM (48)
  • Sample format: unsigned 8-bits/16-bits mono, big-endian
  • H (33868800) = Clock rate in Hz.

This is mostly the same as the OPL3, except for the PCM channel, which uses the commands listed above instead. The @ command in PCM channels sets the LFO by bit0 (0=start, 1=stop), and sets the reverb by bit1 (0=off, 1=on).

The sample header for PCM channels is:

  • Loop start
  • Loop end
  • Clock rate for calculating pitch
  • Octave shift: Shifts octave number; 0 to use direct numbers -7 to +7.
  • Data bit: 0 for 8-bits, 1 for 12-bits, 2 for 16-bits.

Binary values:

  • --LL LVVV = L is LFO speed, V is vibrato depth.
  • AAAA DDDD = A is attack rate and D is decay rate.
  • LLLL DDDD = L is first decay level, D is second decay rate.
  • CCCC RRRR = C is rate compensation, and R is release rate.
  • ---- -TTT = T is tremolo depth.