#target TZX

0x18: CSW recording block

#tzx CSW, [FILE=]"audio.wav", [COMPRESSED], [PAUSE=pause],
          [SAMPLE-RATE=value], [CHANNELS=1|2], [MONO], [STEREO], [SAMPLE-FORMAT=s1|u1|s2|u2|s2x|u2x],
          [HEADER=bytes], [START=frame], [Pseudo instructions: end, .end
8080 pseudo instructions: ENDEND=frame], [COUNT=frames]

This block inserts audio data reduced to 1 bit into the .tzx file. The data is RLE-encoded as a so-called 'compressed square wave' and optionally further compressed with Z-compression.

Currently wav files and raw audio files are supported:
• wav files: 1, 2 and 4 byte PCM, 4 byte FLOAT, A-LAW and µLAW encoding, 1 or 2 channels and any sample rate.
• raw files: 1 or 2 bytes, signed or unsigned, little or big endian samples, 1 or 2 channels and any sample rate.

COMPRESSED: Additionally compress the block using Z-compression.

PAUSE: Length of the gap of silence after this block in ms. Assembler directives: #if, #elif, #else, #endif
Pseudo instructions: if, endifIf PAUSE is omitted then there is no pause after this block.

Raw audio settings

Decoding raw audio files requires some informations:

SAMPLE-RATE: Sample rate of the audio data in samples per second. (STEREO: frames per second.)

CHANNELS: Number of (interleaved) audio channels: 1 or 2. MONO is a short-hand for 1 channel and STEREO is a short-hand for 2 channels.

SAMPLE-FORMAT: The sample format defines 3 aspects of each sample:
s|u: samples are signed (s) or unsigned (u)
1|2: samples are 1 byte or 2 bytes in size.
x:   Assembler directives: #if, #elif, #else, #endif
Pseudo instructions: if, endifif samples are 2 bytes, then the default is that they are in "network byte order" which means: MSB first. Assembler directives: #if, #elif, #else, #endif
Pseudo instructions: if, endifIf they are LSB first (as usual for .wav files) an 'x' must be appended.

HEADER: optional: size of a file header. The header will be skipped before extracting audio data or measuring the file positions for START, Pseudo instructions: end, .end
8080 pseudo instructions: ENDEND and COUNT.

Limit the range to encode

Assembler directives: #if, #elif, #else, #endif
Pseudo instructions: if, endifIf you don't want to import the whole file then you can adjust the range using START, Pseudo instructions: end, .end
8080 pseudo instructions: ENDEND and COUNT, measured in FRAMES after the HEADER. Assembler directives: #if, #elif, #else, #endif
Pseudo instructions: if, endifIf the value for Pseudo instructions: end, .end
8080 pseudo instructions: ENDEND or COUNT exceeds the Pseudo instructions: end, .end
8080 pseudo instructions: ENDend of the file then it is automatically adjusted.

A FRAME is a Pseudo instructions: defl, set and '='
Labels: SETset of one sample for each channel: 1 sample for MONO and 2 samples for STEREO.
E.g. the size of a frame of 2-byte samples in mono is 2*1=2 and of 4-byte float samples in stereo it is 4*2=8.

Note

The CSW block does not define the starting pulse level, therefore a CSW block might be replayed inverted. To correct this problem zasm always stores a 0x2B set signal level block before the CSW block.