Export music

The music is exported only as a data stream (similar to Leonard's YM ST-Sound format), no external player is provided which decodes the data of instrument, pattern, etc.

The output stream gives for each frame the values to be programmed to AY registers, the information needed to manage SID, samples and the “Entry” and “Signal” options.

Two export formats are available:

• full stream: gives the value of all the streams for each frame
• delta stream: gives only the values modified compared to the previous frame, this is a form of compression. The generated file is easily three times smaller.

Both formats use the same SDS filename extension.

Each frame contains 16 streams of one byte each which represent, in order, the calculated values to be sent in the AY registers 0 to 13, the SID period (encoded on 9 bits) and the Signal/Entry information (combined into one byte).

The values of the period (0, 1, 2, 3, 4, 5, 11, 12) and noise (6) registers are stored directly as they are to be sent to the AY. Therefore, the most significant nibble of the streams of registers 1, 2 and 5 will always be 0, the 3 most significant bits of the stream of register 6 will always be 0.

For register 13, the special value &ff indicates that the register should not be written for this frame.

The streams of registers 7, 8, 9 and 10 have bits added with respect to AY registers which are used to encode the information for SID and sample.

During export processing, the idea is rather not to keep the last “Signal/Entry” stream in the compressed data. Instead, it is more efficient to generate two separate pointer/value arrays, one for the signals and the other to be able to force complete frames and thus have several entry points in the music (including “loop to”).

A stream file is made up of:

• 5 bytes of file signature: “SDST” followed by one &1A byte
• 1 byte &00 (format version number)
• 1 byte &20 (version of the software that created the file, in BCD)
• one MHDR chunk which contains information about the module
• one STHD header chunk
• one chunk which contains stream data: STF for a full stream or STD for a delta stream
• where applicable, AYL and AYLA chunks for the samples and aliases used in the music
• one &1A byte which marks the end of the file

A chunk always starts with its name on 4 characters, followed by the 32 bits data size of the chunk. The values are stored in little-endian.

Only the streams whose value changes compared to the previous frame are stored in a STD chunk. A bitmask indicates which streams are populated in the following bytes.

A frame is therefore coded as follows:

• 2 bytes of bitmask: 1 bit per stream (0=stream inactive; 1=stream active). By convention, bit15 corresponds to stream 0
• n bytes: byte of each active stream (stream 0 first)

The first frame (frame 0) is always complete.

The samples used in the music are saved in AYL chunks. The AY-List of the sample must be terminated with a STOP instruction.

The aliases of samples used in the music are saved in AYLA chunks. The AYL chunk of the parent sample of the alias must have been encountered previously.

Once the music is exported, the SDS file contains all the data needed to replay the music in your application. But before that, an additional step is necessary to apply a compression algorithm to the stream data part to reduce its size. Several methods are proposed below.

Madram's Kit AY is originally intended to convert and compress a YM file. A modified version adapted to the SDS “Stream Full” format of Soundtracker DMA is available in the Downloads section.

It is a tool that runs on CPC and I am warning you, it is very slow, be patient.

Start the Basic file and indicate the SDS file to process. It will generate:

• an OUT.AYC file which contains the streams compressed in AYC format
• an OUT.ASM file which defines the address table of AY-lists (samples)
• an OUT.AYL file which contains the AY-Lists of the samples

The assembler source stkdma_ayc_player.asm contains the code for the decompressor and the player, it includes the three previous files.

The AYC toolkit achieves a very good compression ratio and the decompression routine is very fast, but it requires a 256 byte buffer for each stream. The downside of this method is the amount of RAM needed for these buffers.

to complete (other method)