Jo Engine 2026.11.6
Jo Sega Saturn Engine
Loading...
Searching...
No Matches
audio.h File Reference

Jo Engine Function prototypes for audio. More...

Go to the source code of this file.

Data Structures

struct  jo_sound

Macros

#define JO_SOUND_MAX_CHANNEL
 Channels of sounds (2 slots of the SCSP each; the slots 16 and 17 take the CD audio).
#define JO_DEFAULT_AUDIO_VOLUME
 Default audio volume.
#define JO_MAX_AUDIO_VOLUME
 Max audio volume available for jo_audio_set_volume().
#define JO_MIN_AUDIO_VOLUME
 Min audio volume available for jo_audio_set_volume().
#define JO_AUDIO_CD_VOLUME_MAX
 Maximum level of the CD audio (see jo_audio_set_cd_volume()), the default.

Enumerations

enum  jo_sound_mode { JoSoundMono8Bit , JoSoundMono16Bit , JoSoundStereo8Bit , JoSoundStereo16Bit }

Functions

void jo_audio_init (void)
 Start the sound again as jo_core_init() does: the program of the 68000 (the sound driver, or its idle loop), the slots keyed off, the sounds loaded forgotten.
void jo_audio_play_cd_track (const int from_track, const int to_track, const bool repeat_infinitely)
 Play a track from the CD.
void jo_audio_stop_cd (void)
 Stop playing audio track.
void jo_audio_pause_cd (void)
 Pause the audio track played by jo_audio_play_cd_track().
void jo_audio_resume_cd (void)
 Resume the audio track paused by jo_audio_pause_cd().
bool jo_audio_is_cd_paused (void)
 Check if the CD audio is paused (see jo_audio_pause_cd()).
bool jo_audio_is_cd_playing (void)
 Check if the CD drive is playing.
void jo_audio_set_volume (const unsigned char vol)
 Set the audio volume.
void jo_audio_set_cd_volume (const unsigned char level)
 Set the level of the CD audio in the mix (the music tracks of the CD, see jo_audio_play_cd_track()).
bool jo_audio_is_channel_playing (const unsigned char channel)
 Checks whether a given audio channel is currently playing a sound.
void jo_audio_play_sound_on_channel (jo_sound *const sound, const unsigned char channel)
 Play a sound on a specific channel.
void jo_audio_play_sound_loop_on_channel (jo_sound *const sound, const unsigned char channel)
 Play a sound again and again on a specific channel, until the channel is stopped (an engine for instance).
void jo_audio_set_channel_sample_rate (const unsigned char channel, const unsigned short sample_rate)
 Change the sampling rate of the sound played on a channel (its pitch: a faster engine for instance).
void jo_audio_set_channel_volume (const unsigned char channel, const unsigned char volume)
 Change the volume of the sound played on a channel.
void jo_audio_set_channel_reverb (const unsigned char channel, const unsigned char level)
 Change the send of the sound played on a channel to the reverberation (JO_COMPILE_WITH_AUDIO_DSP_MODULE).
void jo_audio_play_sound (jo_sound *const sound)
 Play a sound on first available channel.
void jo_audio_stop_sound (const jo_sound *const sound)
 Stop a sound.
void jo_audio_stop_channel (const unsigned char channel)
 Stop the sound played on a channel.
bool jo_audio_load_pcm (const char *const filename, const jo_sound_mode mode, jo_sound *sound)
 Load PCM file from CD.
bool jo_audio_load_pcm_async (const char *const filename, const jo_sound_mode mode, jo_sound *sound)
 Load PCM file from CD asynchronously.
bool jo_audio_load_wav (const char *const filename, jo_sound *sound)
 Load a WAV file from CD (PCM, 8 or 16 bits, mono or stereo, any sample rate: the sound gets its mode and its sample rate from the file).
bool jo_audio_play_music (const char *const filename, const bool loop)
 Play a music streamed from a WAV file of the CD (only a few seconds of it in memory).
void jo_audio_stop_music (void)
 Stop the music (jo_audio_play_music()).
void jo_audio_pause_music (void)
 Pause the music (jo_audio_play_music()).
void jo_audio_resume_music (void)
 Resume the music paused by jo_audio_pause_music().
bool jo_audio_is_music_playing (void)
 Check if the music is playing (jo_audio_play_music()).
bool jo_audio_is_music_paused (void)
 Check if the music is paused (jo_audio_pause_music()).
void jo_audio_set_music_volume (const unsigned char volume)
 Set the volume of the music (jo_audio_play_music()).
unsigned int jo_audio_get_music_underruns (void)
 Count the times the music had no data to play (the drive was too late: a silence of about 0.1 s).
bool jo_audio_make_resident (jo_sound *sound)
 Keep a sound in the sound RAM (512 KB) and free its copy in the work RAM (the jo_malloc() memory).
void jo_audio_free_resident (void)
 Forget all the resident sounds (a new level): their room in the sound RAM is free again.
void jo_audio_free_pcm (jo_sound *sound)
 Free pcm sound loaded with jo_audio_load_pcm().
int jo_audio_usage_percent (void)
 Get audio channel usage.

Detailed Description

Jo Engine Function prototypes for audio.

Author
Johannes Fetz
Bug
No known bugs.

Data Structure Documentation

◆ jo_sound

struct jo_sound
Data Fields
unsigned char current_playing_channel
char * data
unsigned int data_length
jo_sound_mode mode
char pan
unsigned int resident
unsigned char reverb
unsigned short sample_rate
unsigned char volume

Macro Definition Documentation

◆ JO_AUDIO_CD_VOLUME_MAX

#define JO_AUDIO_CD_VOLUME_MAX

Maximum level of the CD audio (see jo_audio_set_cd_volume()), the default.

◆ JO_DEFAULT_AUDIO_VOLUME

#define JO_DEFAULT_AUDIO_VOLUME

Default audio volume.

◆ JO_MAX_AUDIO_VOLUME

#define JO_MAX_AUDIO_VOLUME

Max audio volume available for jo_audio_set_volume().

◆ JO_MIN_AUDIO_VOLUME

#define JO_MIN_AUDIO_VOLUME

Min audio volume available for jo_audio_set_volume().

◆ JO_SOUND_MAX_CHANNEL

#define JO_SOUND_MAX_CHANNEL

Channels of sounds (2 slots of the SCSP each; the slots 16 and 17 take the CD audio).

Enumeration Type Documentation

◆ jo_sound_mode

Enumerator
JoSoundMono8Bit 
JoSoundMono16Bit 
JoSoundStereo8Bit 
JoSoundStereo16Bit 

Function Documentation

◆ jo_audio_free_pcm()

void jo_audio_free_pcm ( jo_sound * sound)

Free pcm sound loaded with jo_audio_load_pcm().

Parameters
soundSound definition

◆ jo_audio_free_resident()

void jo_audio_free_resident ( void )

Forget all the resident sounds (a new level): their room in the sound RAM is free again.

Remarks
The jo_sound of the resident sounds must not be played any more

◆ jo_audio_get_music_underruns()

unsigned int jo_audio_get_music_underruns ( void )

Count the times the music had no data to play (the drive was too late: a silence of about 0.1 s).

Returns
Count since jo_audio_play_music()

◆ jo_audio_init()

void jo_audio_init ( void )

Start the sound again as jo_core_init() does: the program of the 68000 (the sound driver, or its idle loop), the slots keyed off, the sounds loaded forgotten.

Remarks
After the game used the 68000 and the sound RAM by itself (a video player that decodes its sound on the 68000)

◆ jo_audio_is_cd_paused()

bool jo_audio_is_cd_paused ( void )

Check if the CD audio is paused (see jo_audio_pause_cd()).

Returns
true if the CD audio is paused
Warning
Requires JO_COMPILE_WITH_FS_MODULE

◆ jo_audio_is_cd_playing()

bool jo_audio_is_cd_playing ( void )

Check if the CD drive is playing.

Returns
true if the CD audio is playing
Remarks
Useful to know when the last track is finished (without repeat)
Warning
Requires JO_COMPILE_WITH_FS_MODULE
The CD drive is also in "play" status when a file is loading

◆ jo_audio_is_channel_playing()

bool jo_audio_is_channel_playing ( const unsigned char channel)

Checks whether a given audio channel is currently playing a sound.

Parameters
channelChannel to check (0 to JO_SOUND_MAX_CHANNEL - 1)
Returns
true if the channel is playing, false otherwise

◆ jo_audio_is_music_paused()

bool jo_audio_is_music_paused ( void )

Check if the music is paused (jo_audio_pause_music()).

Returns
true if the music is paused

◆ jo_audio_is_music_playing()

bool jo_audio_is_music_playing ( void )

Check if the music is playing (jo_audio_play_music()).

Returns
true if the music is playing or paused, false when it is over (no loop) or stopped

◆ jo_audio_load_pcm()

bool jo_audio_load_pcm ( const char *const filename,
const jo_sound_mode mode,
jo_sound * sound )

Load PCM file from CD.

Parameters
filenamePcm filename (example: A.PCM)
modePCM audio mode (JoSoundMono16Bit, etc)
soundSound definition (output)
Remarks
To convert any audio file to PCM under Linux or Windows => http://ffmpeg.org
ffmpeg -i A.WAV -f s8 -ar 44100 A.PCM
ffmpeg -i A.MP3 -f s8 -ac 1 -ar 8000 A.PCM
Returns
true if succeed otherwise false

◆ jo_audio_load_pcm_async()

bool jo_audio_load_pcm_async ( const char *const filename,
const jo_sound_mode mode,
jo_sound * sound )

Load PCM file from CD asynchronously.

Parameters
filenamePcm filename (example: A.PCM)
modePCM audio mode (JoSoundMono16Bit, etc)
soundSound definition (output)
Remarks
To convert any audio file to PCM under Linux or Windows => http://ffmpeg.org
ffmpeg -i A.WAV -f s8 -ar 44100 A.PCM
ffmpeg -i A.MP3 -f s8 -ac 1 -ar 8000 A.PCM
Returns
true if succeed otherwise false

◆ jo_audio_load_wav()

bool jo_audio_load_wav ( const char *const filename,
jo_sound * sound )

Load a WAV file from CD (PCM, 8 or 16 bits, mono or stereo, any sample rate: the sound gets its mode and its sample rate from the file).

Parameters
filenameWAV filename (example: SHOT.WAV)
soundSound definition (output)
Remarks
The samples are converted for the SCSP (16 bits: big endian; 8 bits: signed; stereo: the left samples then the right ones). A WAV file can be listened to on a computer: export them with any audio tool (16 bits recommended: 8 bits samples hiss in the quiet parts, the end of an echo)
A sound plays 65535 samples per channel at most (the SCSP: 1.5 s at 44100 Hz, 3 s at 22050 Hz): a longer one is cut. Longer: jo_audio_play_music()
Returns
true if succeed otherwise false

◆ jo_audio_make_resident()

bool jo_audio_make_resident ( jo_sound * sound)

Keep a sound in the sound RAM (512 KB) and free its copy in the work RAM (the jo_malloc() memory).

Parameters
soundSound loaded (jo_audio_load_pcm(), jo_audio_load_wav())
Remarks
The resident sounds fill the sound RAM from its end; the other sounds are copied before them when they play. Many sounds in 16 bits fit there and not in the work RAM
Returns
true if succeed, false if the sound RAM has no room (the sound stays in the work RAM)

◆ jo_audio_pause_cd()

void jo_audio_pause_cd ( void )

Pause the audio track played by jo_audio_play_cd_track().

Remarks
Nothing happens if the CD is not playing or already paused
You can load files while the CD audio is paused
Warning
Requires JO_COMPILE_WITH_FS_MODULE

◆ jo_audio_pause_music()

void jo_audio_pause_music ( void )

Pause the music (jo_audio_play_music()).

◆ jo_audio_play_cd_track()

void jo_audio_play_cd_track ( const int from_track,
const int to_track,
const bool repeat_infinitely )

Play a track from the CD.

Parameters
from_trackFirst track index to play
to_trackLast track index to play
repeat_infinitelyPlay tracks infinitely or not

The track 1 is the data of the game (game.iso): the audio tracks start at 2. They are the audio files of the folder of the game (or of JO_CD_AUDIO_DIR in its makefile, e.g. JO_CD_AUDIO_DIR = tracks) in alphabetical order, the case ignored: with intro.wav and level1.wav, intro.wav is the track 2 and level1.wav the track 3 (01_intro.wav, 02_level1.wav... keep the order you want). The WAV files must be PCM, 44100 Hz, 16 bits, stereo (the format of a CD). game.cue, made at each build, gives the number of each track.

Remarks
JO_CD_SECTOR_SIZE = 2352 in the makefile makes a single image (game.bin with the data and the audio tracks, and game.cue): what the burning tools and all the emulators read. Mednafen refuses a cue sheet that points into a folder (JO_CD_AUDIO_DIR without JO_CD_SECTOR_SIZE = 2352) unless its setting filesys.untrusted_fip_check is 0
Warning
Requires JO_COMPILE_WITH_FS_MODULE

◆ jo_audio_play_music()

bool jo_audio_play_music ( const char *const filename,
const bool loop )

Play a music streamed from a WAV file of the CD (only a few seconds of it in memory).

Parameters
filenameWAV filename (example: MUSIC.WAV): PCM 8 or 16 bits, or IMA ADPCM (4 times smaller: recommended), mono or stereo, up to 88200 Hz (48000 Hz: resampled to 44100 Hz by the SCSP; in 16 bits stereo, the buffer is too short to wait for the drive: underruns, use IMA ADPCM or CCFLAGS += -DJO_AUDIO_MUSIC_BUFFER_SIZE=131072)
loopThe music starts again at its end
Remarks
The music goes on while the files are loaded (jo_fs_read_file()...): the drive reads it again when its buffer is low, then goes back to the file. It uses 64 KB of work RAM (JO_AUDIO_MUSIC_BUFFER_SIZE) and 64 KB of sound RAM
Convert any audio file with ffmpeg (http://ffmpeg.org):
ffmpeg -i MUSIC.MP3 -acodec adpcm_ima_wav -ar 32000 MUSIC.WAV
ffmpeg -i MUSIC.MP3 -acodec pcm_s16le -ar 22050 MUSIC.WAV
Not with the CD audio tracks (jo_audio_play_cd_track()): both use the drive
Returns
true if succeed otherwise false

◆ jo_audio_play_sound()

void jo_audio_play_sound ( jo_sound *const sound)

Play a sound on first available channel.

Parameters
soundSound definition

◆ jo_audio_play_sound_loop_on_channel()

void jo_audio_play_sound_loop_on_channel ( jo_sound *const sound,
const unsigned char channel )

Play a sound again and again on a specific channel, until the channel is stopped (an engine for instance).

Parameters
soundSound definition
channelChannel (0 to JO_SOUND_MAX_CHANNEL - 1)
Remarks
Nothing is played if the channel is still playing a sound (see jo_audio_stop_channel())
See jo_audio_set_channel_sample_rate() and jo_audio_set_channel_volume() to change it while it plays

◆ jo_audio_play_sound_on_channel()

void jo_audio_play_sound_on_channel ( jo_sound *const sound,
const unsigned char channel )

Play a sound on a specific channel.

Parameters
soundSound definition
channelChannel (0 to JO_SOUND_MAX_CHANNEL - 1)
Remarks
Nothing is played if the channel is still playing a sound (see jo_audio_stop_channel())

◆ jo_audio_resume_cd()

void jo_audio_resume_cd ( void )

Resume the audio track paused by jo_audio_pause_cd().

Remarks
The playback continues from the pause position until the end of the last track given to jo_audio_play_cd_track()
Repeated tracks (repeat true): the CD drive then repeats from the pause position, not from the first track
Nothing happens if the CD audio is not paused
Warning
Requires JO_COMPILE_WITH_FS_MODULE

◆ jo_audio_resume_music()

void jo_audio_resume_music ( void )

Resume the music paused by jo_audio_pause_music().

◆ jo_audio_set_cd_volume()

void jo_audio_set_cd_volume ( const unsigned char level)

Set the level of the CD audio in the mix (the music tracks of the CD, see jo_audio_play_cd_track()).

Parameters
level0 (silent) to JO_AUDIO_CD_VOLUME_MAX (7, the default): each step halves the volume (-6 dB)
Remarks
The sounds are not changed: a music too loud for the sounds of the game is lowered with it

◆ jo_audio_set_channel_reverb()

void jo_audio_set_channel_reverb ( const unsigned char channel,
const unsigned char level )

Change the send of the sound played on a channel to the reverberation (JO_COMPILE_WITH_AUDIO_DSP_MODULE).

Parameters
channelChannel (0 to JO_SOUND_MAX_CHANNEL - 1)
level0 (none), 1 to 7 (-36 to 0 dB, 6 dB steps)

◆ jo_audio_set_channel_sample_rate()

void jo_audio_set_channel_sample_rate ( const unsigned char channel,
const unsigned short sample_rate )

Change the sampling rate of the sound played on a channel (its pitch: a faster engine for instance).

Parameters
channelChannel (0 to JO_SOUND_MAX_CHANNEL - 1)
sample_rateSampling rate (Hz, 1378 to 88200: 44100 / 32 to 44100 x 2)

◆ jo_audio_set_channel_volume()

void jo_audio_set_channel_volume ( const unsigned char channel,
const unsigned char volume )

Change the volume of the sound played on a channel.

Parameters
channelChannel (0 to JO_SOUND_MAX_CHANNEL - 1)
volumeVolume: 0 (JO_MIN_AUDIO_VOLUME) to 127 (JO_MAX_AUDIO_VOLUME)

◆ jo_audio_set_music_volume()

void jo_audio_set_music_volume ( const unsigned char volume)

Set the volume of the music (jo_audio_play_music()).

Parameters
volumeVolume (JO_MIN_AUDIO_VOLUME to JO_MAX_AUDIO_VOLUME)

◆ jo_audio_set_volume()

void jo_audio_set_volume ( const unsigned char vol)

Set the audio volume.

Parameters
volVolume level from 0 to 127

◆ jo_audio_stop_cd()

void jo_audio_stop_cd ( void )

Stop playing audio track.

Warning
Requires JO_COMPILE_WITH_FS_MODULE

◆ jo_audio_stop_channel()

void jo_audio_stop_channel ( const unsigned char channel)

Stop the sound played on a channel.

Parameters
channelChannel (0 to JO_SOUND_MAX_CHANNEL - 1)
Remarks
jo_audio_play_sound_on_channel() doesn't play on a busy channel: stop it first to restart a sound (for instance the shots of an automatic weapon, longer than the time between 2 shots)

◆ jo_audio_stop_music()

void jo_audio_stop_music ( void )

Stop the music (jo_audio_play_music()).

◆ jo_audio_stop_sound()

void jo_audio_stop_sound ( const jo_sound *const sound)

Stop a sound.

Parameters
soundSound definition

◆ jo_audio_usage_percent()

int jo_audio_usage_percent ( void )

Get audio channel usage.

Returns
Audio channel usage percent
Remarks
jo_printf(0, 0, "Audio channel usage: %d%% ", jo_audio_usage_percent());