ChipTuneSoundFormat

From vgmrips

ChipTuneSoundFormat is a extensible logged music format which can support several sound chips. No known implementations exist.

This is a kind of draft format and may be adjusted by discussions.

File format

All numbers are in small-endian format. All text is case-sensitive unless otherwise specified.

It is important to know that a lot of things mentioned are not required to be implemented, such as any metadata and any sound chip and most of the digital I/O features; also some things may only be dummy or partial implementation, such as filters. However, the documentation for the program should mention what is and is not implemented. In fact, it is even possible that some programs only support certain configurations and all others don't work, if it is a very limited program.

Blocks

The file consists of blocks in the order:

  • Master header
  • Master metadata
  • Clock rates
  • Mixer settings
  • Chip definitions
  • Macro definitions
  • External bit output specifications
  • ROM images
  • Envelopes
  • Lookup tables
  • Track data

Master header

  • (8) ASCII characters spelling "chiptune"
  • (1) Version (currently zero)
  • (1) Number of real channels
  • (1) Number of virtual channels
  • (1) Number of clock sources
  • (4) Command rate (in decihertz)
  • (1) Number of ROM images
  • (1) Number of tracks
  • (1) Number of external bit outputs
  • (1) Master volume (unsigned; 128=default)
  • (1) Number of chips
  • (1) Number of macros
  • (1) Number of envelope groups
  • (1) Number of lookup tables

Channels

This format uses two kind of channels, being real channels and virtual channels. Virtual channels are sent to a mixer which is then outputs to real channels.

Usually the real channels would be defined as follows:

  • 1 channel: mono.
  • 2 channels: stereo. channel 0 = left, channel 1 = right.
  • 4 channels: surround. channel 0 = left front, channel 1 = right front, channel 2 = left back, channel 3 = right back.

Metadata

Metadata consists of a number of records, separated by the ASCII record separator, and terminated by the ASCII end of text. Parts of a record are delimited by the ASCII unit separator. All records are optional, and can normally appear in any order.

Each metadata record consists of a key as the first part, and then usually there will also be a second part which is a value. All data must be given in ASCII format. Optionally a third part is possible, which is the same thing in UTF-8.

Some possible keys can be:

  • TITLE: The title of the song (or group, if applicable).
  • COMPOSER: Name of composer.
  • COPYRIGHT: Copyright notice.
  • SYSTEM: Name of system being emulated/logged. This should usually be same as the values recommended for GD3 tags. (It is possible that a player may use this data for optimization if it knows how to play back music for a particular system.)
  • UNIXTIME: The UNIX timestamp (as an integer in decimal notation, with an optional - for times before the UNIX epoch). The third part here, if used, is an amount of microseconds, not the same thing in UTF-8.
  • COMMENT: A comment text. You can use CRLF to make line breaks, and form feeds for page breaks.
  • RATE: A decimal number with similar meaning to the data at offset 0x24 in the VGM format, except in decihertz instead of hertz.
  • VOLUME: A decimal number (can optionally have - or + in front) with similar meaning to Volume Modifier in VGM. However, here you have to use -64 for a factor of 0.25 rather than using -63. Unlike the master volume specification in this file's header, this metadata is of optional use, and is only a suggestion.
  • PINOUT: No UTF-8 part. Given as names of digital output signals of the files, with unit separators in between each one.
  • CHIP-PINOUT: No UTF-8 part. The first data is chip number, second is default values for digital outputs which can be 0 or 1. It is intended for use if the implementation does not support that chip or does not support that many outputs.
  • DISABLE-EFFECT: No data. Recommends to disable user-specified surround, EQ filter, reverb, etc. However, depending on the implementation, the user may override it.
  • CHIP-NAME: The name of a chip (for example if it is a clone of a chip, or a combined chip, rather than ordinary.). In place of the UTF-8, put the chip number. You can have more than one with unit separators in between.

It is recommended that unofficial keys are named using "X-" at front like Internet protocols are commonly using.

Clock rates

Clock rates are given in decihertz in four-bytes. They are in order as if digital outputs of chip number 255 with all clock sources on, starting with output pin number zero.

Mixer settings

There is one mixer per real channel. Each one is specified as a sequence of commands as follows:

  • 0: Terminator.
  • 1: Mix in. Takes two single-byte arguments, first the virtual channel number, and then the unsigned volume level.
  • 2: Butterworth low-pass filter. First argument is one-byte filter order, and second is a four-byte cutoff frequency in decihertz. (This is mainly meant for use with emulation of Amiga LED filter.)
  • 128: Subsection terminator. This terminates a subsection and applies it to the output, starting new with a blank signal, so that filters and so on can affect each subsection individually. Subsections are then added together to make the final output.
  • 129-255: Gated command. Between the command number and arguments are a chip number and digital output number. If the signal is high then the command is used, otherwise it is bypassed.

Chip definitions

Each chip definition begins with a header as follows:

  • (1) Length of name
  • (1) Length of parameter
  • (1) Number of digital inputs
  • (1) Number of analog outputs

After this, the name (in ASCII) follows, and then the parameter (which can be arbitrary binary data, depending on the chip), followed by digital inputs, and then analog outputs. It is recommended that chips which are not officially specified are using names with "X-" at first.

For each digital input:

  • (1) Chip number (255 = clock)
  • (1) Digital output number from chip (+128 for inverted signal; if clock, use 127 for constant low)

For each analog output:

  • (1) Virtual channel number
  • (2) Volume level (signed)

It is permitted to have as many instances of a chip as you want, and they may have same or different clock rates, and same or different parameters.

Macro definitions

Each macro consists of a series of commands.

Each command consists of an opcode in the low nybble and an argument type in the high nybble. Opcode zero indicates that no more commands follow. Depending on the argument type, there may be more byte follow as the argument data.

Opcodes:

  • 0: Delay and end macro. This command acts the same as command 1 except it is also the terminator for the macro definition.
  • 1: Delay. Argument is number of frames (at command rate) to delay before continuing execution.
  • 2: Chip select. Argument is the zero-based chip number. The initial chip select is undefined.
  • 3: Set address. Argument is an address. It doesn't do anything yet; it just sets an address, and it is associated with the currently selected chip. The initial address is undefined.
  • 4: Write data. Argument is data to write, and uses the current address and chip number to write.
  • 5: Activate ROM. If the chip uses any external ROM, this selects it. The argument is the ROM number, and the address is a bank number the bank size depends on the chip type).
  • 6: Select envelope group and lookup table number. This command selects both the current envelope group and lookup table number for use with further commands. If bit8 is set, playback of the selected envelope group will be stopped.
  • 7: Lookup table. The argument is an index into the lookup table, and the value stored there is put into the "previous argument" register.
  • 8: Write from lookup table. Reads as in command 7, but instead of storing into an internal register the result is written to the chip register as if it is command 4.
  • 9: Activate envelope. Argument is an envelope number within the current envelope group; if 255, it stops the envelope group. Either way, the global Misc registers are copied into the envelope group.
  • 10: Read Misc registers from envelope group given as argument, and stops playback of that envelope group.
  • 11: (reserved)
  • 12: Set Misc1 register. This is a global register. Its initial value when a track starts playing is zero.
  • 13: Set Misc2 register.
  • 14: Set Misc3 register.
  • 15: Set Misc4 register.

Argtypes:

  • 0: Zero.
  • 1: One byte immediate. An immediate value is given in the macro definition and is used as the argoument value.
  • 2: Two byte immediate.
  • 3: Four byte immediate.
  • 4: Previous argument. Uses the value of the previous argument read from the pattern, or from command 7.
  • 5: One byte argument. Read a value from the pattern.
  • 6: Two byte argument.
  • 7: Four byte argument.
  • 8: Misc1 with postincrement.
  • 9: Misc3 minus Misc4.
  • 10: Misc1 plus Misc2.
  • 11: Misc3 plus Misc4.
  • 12: Misc1.
  • 13: Misc2.
  • 14: Misc3.
  • 15: Misc4.

External bit output specifications

External outputs are considered as digital inputs into a chip which is not actually specified. Its meaning is implementation-dependent.

Normally, these do nothing, however some playback software may use them to synchronize with graphics or for other purposes.

ROM images

ROM images consist of a four-byte length followed by the raw data.

Envelope groups

Each envelope group contains the following header:

  • (1) Number of envelopes in this group
  • (1) Flag

The flag is: 

[.... ABCD]
      ||||
      |||+--- Initialize Misc1 to zero if set
      ||+---- Initialize Misc2 to zero if set
      |+----- Initialize Misc3 to zero if set
      +------ Initialize Misc4 to zero if set

Initial values are inherited from the current value of the calling macro if these flags are not set.

After the header is a macro definition (see above), although commands 9 and 10 cannot be used within the envelope, and command 6 with bit8 set is also not allowed.

After that follows data for each envelope.

Envelopes

Envelope local header:

  • (2) Length of envelope (number of macro invocations)
  • (2) Loop start position (same as length if not looping)
  • (2) Length of loop (zero if not looping)

The data in the envelope is then according to the arguments of the macro which is defined to be part of this group. (The data will be empty if the macro takes no arguments, although the header is still present and can still have a nonzero length and loops despite this.)

All Misc registers, as well as the current chip number and address, and the active lookup table number, are all local to each envelope group.

Lookup tables

Each lookup table consists of the following header:

  • (2) Number of entries
  • (1) Flag

The flag is: 

[.... ..LL]
        ||
        ++----- Length of each entry (00=1, 01=2, 10=4, 11=reserved)

After the header, the data is given, which is the specified length, for each entry in the table.

Track data

Each track consists of:

  • Local header
  • Local metadata
  • Play order table
  • Patterns

The local header:

  • (1) Number of patterns
  • (1) Number of entries in play order table
  • (1) Zero-based loop start index into play order table
  • (1) Default loop count
  • (1) Number of order table entries to use inside the loop

The local metadata is in the same format as the global metadata. Different keys may be used. One possible set of keys to use is as follows:

  • TITLE: The title of the song.
  • COMPOSER: Name of composer, if different for each track.
  • COPYRIGHT: Copyright notice, if different for each track.
  • UNIXTIME: The UNIX timestamp (as an integer in decimal notation, with an optional - for times before the UNIX epoch). The third part here, if used, is an amount of microseconds, not the same thing in UTF-8.
  • DURATION: The estimated duration in seconds, given as an integer in decimal notation. The third part here, if used, is an amount of microseconds, not the same thing in UTF-8.
  • COMMENT: A comment text. You can use CRLF to make line breaks, and form feeds for page breaks.
  • LOOP: Two numbers, with the ASCII unit separator in between, with purposes similar to the Loop Base and Loop Modifier of VGM format. The player might use this instead of (or in addition to) the default loop count, or it might ignore both.
  • FOLLOW-TRACK: If this track does not loop, the specified track is played next. (This is mainly designed for use with MegaZeux.)

The play order table is a list of one-byte zero-based pattern numbers.

Patterns

A pattern consists of a command list. Each entry in the command list is either a macro number followed by the arguments, or 255 followed by a command list as in a macro definition.

If the macro commands are used here, then commands numbered $40 to $7F now have a different meaning than inside of macros, which is to delay a number of frames equal to the given number minus $40, and then terminate both the command list and the pattern.

Sound chips

You can use the talk page for discussion of proposals and so on. They can also be posted directly on here if agreed with.

Any extra address/data bits will be ignored if not otherwise specified.

Intel 8253

  • Status: Draft
  • Name: INTEL8253
  • Address bits: 2
  • Data bits: 8

Signals:

  • input 0: CLK0
  • input 1: CLK1
  • input 2: CLK2
  • input 3: GATE0
  • input 4: GATE1
  • input 5: GATE2
  • output 0: OUT0
  • output 1: OUT1
  • output 2: OUT2
  • analog 0: OUT0
  • analog 1: OUT1
  • analog 2: OUT2

Nintendo 2A03

  • Status: Draft
  • Name: 2A03
  • Address bits: 8
  • Data bits: 8
  • ROM size: 32K or 16K

Signals:

  • input 0: Clock
  • output 0: OUT0
  • output 1: OUT1
  • output 2: OUT2
  • analog 0: Square channels
  • analog 1: Triangle, noise, DPCM

Format of first byte of parameter: 

[.... R.PT]
      | ||
      | |+----- Set to enable APU test mode
      | +------ NTSC/PAL switch: set for PAL, clear for NTSC
      +-------- ROM size: clear for 32K, set for 16K

The ROM is used for DPCM, and represents the addresses $8000-$FFFF. Normally only $C000-$FFFF is used, but if the playback wraps around then the rest of the data might also be accessed (if it is a 16K ROM size, then it is effectively mirrored).

Interrupts are not used at all, and writes to OAM DMA register are not allowed.

NTSC/PAL switch affects rate of DPCM playback.

General Instruments AY-3-8910

  • Status: Draft
  • Name: AY-3-8910
  • Address bits: 4
  • Data bits: 8

Signals:

  • input 0: Clock
  • output 0 to 7: I/O port A (pin 0 = bit 0)
  • output 8 to 15: I/O port B
  • analog 0 to 2: Three square wave channels

Parameter is used for the chip subtype (if applicable). Based on the chip variant, I/O ports might not work, or it will be a requirement that all three channels are output to the same virtual channel and using the same volume level for each one.

If this is AY8930 and using extended mode, then change the name to AY8930 instead; everything else works similarly.

Values of I/O ports are undefined if they are in input mode or a chip variant not having I/O ports. (It is legal for a playback program to just always output the data, regardless of input/output mode and chip variant. However, this is not guaranteed.)

Nintendo GameBoy

  • Status: Draft
  • Name: GAMEBOY
  • Address bits: 7
  • Data bits: 8

Signals:

  • input 0: Clock
  • output 0: $FF00 bit4
  • output 1: $FF00 bit5
  • output 2: Vin left output select
  • output 3: Vin right output select
  • analog 0: Left output
  • analog 1: Right output
  • analog 2: Mono output (when headphone is not used)

Note: Unlike VGM, addresses start at $FF00 for this format.

Philips SAA1099

  • Status: Draft
  • Name: SAA1099
  • Address bits: 5
  • Data bits: 8

Signals:

  • input 0: Clock
  • analog 0: Left output
  • analog 1: Right output

Famicom Disk System

  • Status: Draft
  • Name: 2C33
  • Address bits: 8
  • Data bits: 8

Signals:

  • input 0: Clock
  • analog 0: Sound

Address starts at $00 for address $4000; note that you shouldn't use addresses before $40 though. Addresses not having to do with FDS sound should not be touched; it might cause problems if you do.

Software

None is currently known.

External links

Retrieved from "https://vgmrips.net/w/index.php?title=ChipTuneSoundFormat&oldid=1444"