PocketSprite Sound Mixer

The PocketSprite SDK comes with a sound mixer and decoder, capable of decoding mono wave files and music modules in .mod/.s3m/.xm format. It can decode and play multiple of these files simultaneously, mixing them using different volumes.

(ToDo: detail memory use, note that .xm is more intensive than .mod/.s3m)

Functions

int sndmixer_init(int no_channels, int samplerate)

Initialize the sound mixer.

Note
This function internally calls kchal_sound_start, there is no need to do this in your program if you use this function to initialize the sound mixer.
Parameters
  • no_channels: Amount if sounds to be able to be played simultaneously.
  • samplerate: Sample rate to mix all sources to

int sndmixer_queue_wav(const void *wav_start, const void *wav_end, int evictable)

Queue the data of a .wav file to be played.

This queues a sound to be played. It will not be actually played until sndmixer_play is called.

Return
The ID of the queued sound, for use with the other functions.
Parameters
  • wav_start: Start of the wav-file data
  • wav_end: End of the wav-file data
  • evictable: If true, if all audio channels are filled and a new sound is queued, this sound can be stopped to make room for the new sound.

int sndmixer_queue_mod(const void *mod_start, const void *mod_end)

Queue the data of a .mod/.xm/.s3m file to be played.

This queues a piece of tracked music to be played. It will not be actually played until sndmixer_play is called.

Return
The ID of the queued sound, for use with the other functions.
Parameters
  • wav_start: Start of the filedata
  • wav_end: End of the filedata

void sndmixer_set_loop(int id, int loop)

Set or unset a sound to looping mode.

Warning
This may not be implemented yet. TODO: remove this warning when implemented.
Parameters
  • id: ID of the sound, obtained when queueing it
  • loop: If true, the sound will loop back to the beginning when it ends.

void sndmixer_set_volume(int id, int volume)

Set volume of a sound.

A queued sound will always start off with a volume setting of 255 (max volume). This call can be used to adjust the volume of the sound at any time afterwards.

Parameters
  • id: ID of the sound, obtained when queueing it
  • volume: New volume, between 0 (muted) and 255 (full sound).

void sndmixer_play(int id)

Play a sound.

When a sound is queued, it is not playing yet. Use this call to start playback. You can also use this call to resume a sound paused by sndmixer_pause or sndmixer_pause_all.

Parameters
  • id: ID of the sound, obtained when queueing it

void sndmixer_pause(int id)

Pause a sound.

Stops playback of the sound. The sound can be resumed with sndmixer_play().

Parameters
  • id: ID of the sound, obtained when queueing it

void sndmixer_stop(int id)

Stop a sound, free the sound source and channel it used.

Stops playback of the sound and frees all associated structures.

Parameters
  • id: ID of the sound, obtained when queueing it

void sndmixer_pause_all()

Pause all playing sounds.

This can be used when e.g. the game is paused. Sounds can be individually un-paused afterwards and new sounds can still be queued and played, given enough free/evictable channels.

void sndmixer_resume_all()

Resume all paused sounds.

This can be used to undo a sndmixer_pause_all() call.

Structures

struct sndmixer_source_t

Structure describing a sound source.

Public Members

int (*init_source)(const void *data_start, const void *data_end, int req_sample_rate, void **ctx)

Initialize the sound source. Returns size of data returned per call of fill_buffer.

int (*get_sample_rate)(void *ctx)

Get the actual sample rate at which the source returns data

int (*fill_buffer)(void *ctx, int8_t *buffer)

Decode a bufferful of data. Returns 0 when file ended or something went wrong. Returns amount of bytes in buffer (normally what init_source returned) otherwise.

void (*deinit_source)(void *ctx)

Destroy source, free resources