diff --git a/X16 Reference - Appendix G - ZSM File Format.md b/X16 Reference - Appendix G - ZSM File Format.md index 495adc4..c26bec3 100644 --- a/X16 Reference - Appendix G - ZSM File Format.md +++ b/X16 Reference - Appendix G - ZSM File Format.md @@ -3,11 +3,11 @@ #### Zsound Repo -ZSM is part of the Zsound suite of Commander X16 audio tools found at: +The Zsound suite of Commander X16 audio tools contains the original ZSM reference player, found at: https://github.com/ZeroByteOrg/zsound/ -An alternative library with PCM support, ZSMKit, is avalable at: -https://github.com/mooinglemur/ZSMKit +A newer, more flexible, and more recently maintained library with PCM support, ZSMKit, is avalable at: +https://github.com/mooinglemur/ZSMKit/ #### Current ZSM Revision: 1 @@ -150,14 +150,28 @@ Players implementing this channel should implement detection routines during ini An expansion HW write will contain the following data: -Chip ID|Number of writes (`N`)| `N` tuples of data ---|--|-- -one byte|one byte|N * tuple_size bytes - -- The total number of bytes MUST equal exactly the number of bytes specified in the preceding EXTCMD. -- The tuple_size is determined by the needs of the device, and thus will be specified per-device along with its chip ID assignment. This is likely to be 1-3 bytes for most devices. - -There are currently no supported expansion HW IDs assigned. +Chip ID|`nnnnnn-1` bytes of data +--|-- +one byte|nnnnnn-1 bytes + +- The length of the EXTCMD `nnnnnn` encompasses the chip_id byte and the data bytes which follow. + +##### Chip IDs +* 0x00 - reserved +* 0x01 - MIDI 1 (Primary MIDI) + * MIDI data embedded in ZSM is limited to status bytes 0x80-0xF8 inclusive, and their arguments, i.e. data which is intended to be transmitted to a synthesizer. + * Metadata such as MIDI header data, ticks per beat, track names, lyrics, and tempo are not included in the data. + * Delta times are not embedded in the MIDI data. Native ZSM delays are used instead. + * With the exception of multiple EXTCMDs for the same Chip ID within the same tick, the first byte of data must be a status byte 0x80-0xF8. + * Status continuation is not permitted from prior ticks, but is allowed within the same tick. + * This restriction allows for simultaneous access to the MIDI device by multiple agents, such as a song player and sound effects player on non-overlapping MIDI channels. + * An example of an EXTCMD containing a single note-on event might look as follows: `0x40 0x44 0x01 0x90 0x69 0x7F` +* 0x02 - MIDI 2 (Secondary MIDI) + * A second separate MIDI stream can be used by players that support multiple active MIDI devices. The data format and restrictions are the same as for Chip ID 0x01. +* 0x03 - reserved +* 0x70-0x7F - Private use area + * These will be ignored by the stock reference players, but can be used for testing or for custom purposes for a particular application. +* 0x80-0xFF - reserved for possible expansion to 15-bit chip IDs #### 2: Synchronization Events