Using this library has three steps to it

1. Install the player
2. Load the samples (up to 16 samples, you can replace a sample at any time)
3. Send the player commands to start/stop playback and get the current status of the player

Install the player

Installing the player is as simple as executing the .playraw DOT command. This will install the player and setup the environment ready to start playing

10 .playraw

Executing .playraw multiple times will not cause any issues, however you will need to reload your samples.

Load samples

Next we need to load some samples to play. This is done using the .loadraw DOT command. This command will check that the player is installed and give an error if not. The loader will allocate banks from NextOS and load the sound data into the banks. You can load audio data into one of 16 slots (0..15). Slots can be reused simply by loading a new sample into the target slot, this will replace the previous audio data with the newly loaded data.

20 .loadraw 0 "andnow.raw" : REM Load sample into slot 0
30 .loadraw 1 "problem.raw" : REM Load sample into slot 1

Start/Stop Playback

Starting and stopping playback is done by sending commands to the player.

There are 3 addresses used to trigger the actions in the player

Command	Address	Arguments	Description
Start Playback	23768 ($5cd8)	slot number (0..15)	Starts the playback of the audio in the specified slot. NOTE:If the high bit of the slot number is set, the sample will loop until stopped.
Stop Playback	23771 ($5cdb)	N/A	Stops the current playback
Get Status	23774 ($5cde)	N/A	Returns 1 if the player is currently playing audio, 0 if not

Playback flags

The high bits of the slot number act as special flags that you can use to control the playback.

Bit flag	Description
Bit 7 (128)	Loop the playback until you explicitly stop it or start another playback
Bit 6 (64)	Increase the playback rate to 8000 Hz. This is ideal for samples converted to 8000 Hz, but you can use it to create effects for samples at lower/higher bit rates

To make this easier to use, you can use the following code

    1000 DEFPROC StartPlayback(slot,loop=0,hires=0)
    1010   IF loop THEN slot |= 128
    1020   IF hires THEN slot |= 64
    1030   RANDOMIZE USR (23768,slot)
    1040 ENDPROC

    1050 DEFPROC StopPlayback()
    1060   RANDOMIZE USR 23771
    1070 ENDPROC

    1080 DEF FN IsPlaying()= USR 23774

Create your own audio files

The downloadable zip file contains 5 sample audio clips. Using Audcity you can load an audio clip and export it using the following setting

Option	Setting
Format	Other uncompressed files
Channels	Mono
Sample Rate	4000 Hz (Custom) or 8000 Hz
Header	RAW (header-less)
Encoding	Unsigned 8-bit PCM

Exporting using the above settings will give you a file that can be directly loaded using .loadraw.

NOTE:The file must not be larger than 64K (65535 bytes)

Known limitations

• Any commands that rely on the CPU HALT instruction to synchronize to the video generation will not work as expected while audio is playing. This is because the HALT instruction blocks until an interrupt is generated, which under normal circumstances would be 50/60 times per second when the ULA interrupt is generated. When playing back audio, a timer is configured to generate an interrupt 4000/8000 times per second, which releases the HALT much sooner than expected.
  PAUSE and SPRITE MOVE INT, will be affected.
  SPRITE MOVE INT y is unaffected as it waits for a scanline to be reach, and is therefore not affected by the higher interrupt rate
• The ZX Spectrum Next screen save should be disabled as the player code causes issues. The sample shows how to disable the screen saver from code. This issue is under investigation