Audio Player

Provides functionalities for audio playback within OSLib. More...

Macros
#define	oslSetSoundEndCallback(s, fct)   (s->endCallback = (fct))
	Sets a callback function to be invoked when a sound finishes playing.
#define	oslSetSoundLoop(s, loop)   oslSetSoundEndCallback(s, (loop) ? oslSoundLoopFunc : NULL)
	Sets the looping state of a sound.

Enumerations
enum	{ OSL_FMT_NONE = 0 }
enum	{ OSL_FMT_MASK = 0xff }
enum	{ OSL_FMT_MONO = 0 , OSL_FMT_STEREO = 0x200 , OSL_FMT_STREAM = 0x400 }
enum	{ OSL_FMT_44K = 0 , OSL_FMT_22K = 1 , OSL_FMT_11K = 2 }
enum	oslInitAudioME_formats { OSL_FMT_AT3 = 1 , OSL_FMT_MP3 = 2 , OSL_FMT_ALL = 3 }

Functions
void	oslPlaySound (OSL_SOUND *s, int voice)
	Plays a sound on a specified channel.
void	oslStopSound (OSL_SOUND *s)
	Stops a currently playing sound.
void	oslPauseSound (OSL_SOUND *s, int pause)
	Pauses, resumes, or toggles a sound.
void	oslDeleteSound (OSL_SOUND *s)
	Deletes a sound, freeing associated memory.
int	oslAudioSetSoundFilename (OSL_SOUND *s, const char *filename)
	Remembers the file of a streamed sound, to reopen it after the PSP wakes from stand-by.
void	oslAudioVSync ()
	Synchronizes audio streaming with the PSP's power management.

Detailed Description

Provides functionalities for audio playback within OSLib.

Macro Definition Documentation

oslSetSoundEndCallback

#define oslSetSoundEndCallback	(		s,
			fct
	)		(s->endCallback = (fct))

Sets a callback function to be invoked when a sound finishes playing.

This macro assigns a user-defined callback function to a sound object, which is called when the sound reaches the end of its playback. The callback can determine whether to stop the sound, continue playback, or start a different sound on the same channel.

Parameters

s

Pointer to an OSL_SOUND structure for which the callback is to be set.

fct

Pointer to the callback function that will be called when the sound finishes. The function signature should be: int callback(OSL_SOUND* sound, int voice); sound: a pointer to the OSL_SOUND structure. voice: the channel number on which the sound was playing. The callback function must return: 0: to indicate the sound should stop and the channel should be released. 1: to continue playback, which could involve repeating the same sound or starting a different track.

// Define a callback function that replays the same sound
int repeatSound(OSL_SOUND *sound, int voice) {
    oslPlaySound(sound, voice);  // Replay the sound on the same channel
    return 1;  // Indicate that playback should continue
}
 
OSL_SOUND *backgroundMusic;
// Assume backgroundMusic is already loaded and initialized
 
// Set the repeat function as the end callback
oslSetSoundEndCallback(backgroundMusic, repeatSound);
 
// Start playing the background music
oslPlaySound(backgroundMusic, 0);

This macro facilitates dynamic sound management, allowing for complex audio behavior based on application-specific logic.

oslSetSoundLoop

#define oslSetSoundLoop	(		s,
			loop
	)		oslSetSoundEndCallback(s, (loop) ? oslSoundLoopFunc : NULL)

Sets the looping state of a sound.

This macro configures whether a sound should loop continuously or stop after playing once. It uses the oslSetSoundEndCallback function to assign a loop control callback. If looping is enabled, the oslSoundLoopFunc function is set as the callback, which automatically restarts the sound when it finishes playing. If looping is disabled, no callback is set, allowing the sound to stop after reaching the end.

Parameters

s	Pointer to an OSL_SOUND structure representing the sound to configure.
loop	Boolean value determining the looping behavior: true (non-zero): Sound loops continuously. false (zero): Sound does not loop and stops after playing once.

OSL_SOUND *music;
// Assume music is loaded and needs to be looped
 
// Enable looping
oslSetSoundLoop(music, 1);
 
// Start playing the music, it will now loop indefinitely
oslPlaySound(music, 0);
 
// To stop looping, you can set it like this:
oslSetSoundLoop(music, 0);
// After the current playback, music will not loop but stop.

Utilizing this macro simplifies the process of managing sound playback, especially for background music or long-standing audio effects in games and multimedia applications.

Enumeration Type Documentation

anonymous enum

anonymous enum

General audio format flags for basic settings and operations within OSLib.

Enumerator
OSL_FMT_NONE	Indicates no special format settings are applied. Used as a default or placeholder value.

anonymous enum

anonymous enum

Mask flags used to isolate or filter out specific bits from format flags, typically used in bitwise operations.

Enumerator
OSL_FMT_MASK	Mask used to isolate or filter out specific bits from format flags, typically used in bitwise operations.

anonymous enum

anonymous enum

Defines the audio output configuration and streaming capabilities for playback in OSLib. These flags are used to set the properties of audio channels and to control how audio data is processed and delivered.

Enumerator
OSL_FMT_MONO	Mono audio output. Indicates that audio is output through a single audio channel.
OSL_FMT_STEREO	Stereo audio output. Indicates that audio is output through two separate audio channels, typically left and right channels.
OSL_FMT_STREAM	Stream audio output. Indicates that audio data is streamed from a source rather than being fully preloaded, suitable for large audio files or network streams.

anonymous enum

anonymous enum

Sample rate options for audio playback.

Enumerator
OSL_FMT_44K	44,100 Hz sample rate.
OSL_FMT_22K	22,050 Hz sample rate.
OSL_FMT_11K	11,025 Hz sample rate.

oslInitAudioME_formats

enum oslInitAudioME_formats

Defines the formats that need to be initialized for Media Engine (ME) audio. These are used with oslInitAudioME to prepare specific audio codecs.

Enumerator
OSL_FMT_AT3	Atrac3 and Atrac3+ formats.
OSL_FMT_MP3	MPEG Audio-Layer 3 format.
OSL_FMT_ALL	All supported formats.

Function Documentation

oslPlaySound()

void oslPlaySound ( OSL_SOUND *  s, int  voice  )

extern

Plays a sound on a specified channel.

This function plays a sound on one of the available audio channels, numbered from 0 to 7. If a sound is already playing on the specified channel, it will be stopped and replaced by the new sound. This feature allows up to 8 sounds to be played simultaneously, with each channel capable of handling one sound at a time.

The use of multiple channels enables complex audio scenarios where various sounds do not interfere with each other unless explicitly programmed to do so. For example, background music can be played on one channel, while sound effects like jumps or coin pickups can be managed on others.

Parameters

s	Pointer to an OSL_SOUND structure representing the sound to be played.
voice	Channel number on which to play the sound. Valid values are from 0 to 7.

// Example of loading and playing different sounds on separate channels:
OSL_SOUND *music, *coin, *jump, *stomp;
// Assume sounds are already loaded into these pointers.
 
// Play background music on channel 0
oslPlaySound(music, 0);
 
// Play a coin pickup sound effect on channel 1
oslPlaySound(coin, 1);
 
// Attempt to play another coin sound on channel 1, which stops the first coin sound
oslPlaySound(coin, 1);
 
// Play a jump sound effect on channel 2, allowing it to play alongside the music and coin sound
oslPlaySound(jump, 2);
 
// Replace the coin sound with a stomp sound effect on channel 1
oslPlaySound(stomp, 1);

The example demonstrates managing different sound effects and music tracks, showing how replacing sounds on the same channel can control audio playback dynamically.

Note

Called from an audio thread (an endCallback) on a channel playing another sound, including the callback's own channel, it returns at once: the channel stops its current sound and starts this one when that sound's current buffer is done, so a callback can chain the next track. The stopped sound's endCallback isn't called. A later oslPlaySound on that channel, or oslStopSound / oslDeleteSound of the new sound, cancels the switch if it hasn't happened yet.

oslStopSound()

void oslStopSound ( OSL_SOUND *  s )

extern

Stops a currently playing sound.

This function immediately stops the playback of a specified sound. It is useful for managing audio playback dynamically, allowing you to halt sound effects or music based on game events or user actions. After stopping, the sound can be restarted using oslPlaySound() from the beginning or manipulated further if needed.

Parameters

s	Pointer to an OSL_SOUND structure representing the sound to stop. The sound must be currently playing; otherwise, the function has no effect.

Note

Stopping a sound does not free the memory associated with the sound; it only halts its playback. To completely release a sound resource, use oslDeleteSound().

The custom stopSound hook runs before the wait, so a driver can cancel a blocked audioCallback.

It returns once the sound's audio thread is done with it (up to one buffer and the callback in progress), so the sound can be deleted or reused right after; once a stop is requested, the sound's endCallback is no longer called. Called from an audio thread (an endCallback), it only requests the stop and returns. An endCallback that is already running when the stop comes still runs: if it deletes its sound, don't also stop or delete that sound from another thread.

OSL_SOUND *music;
// Assume music is loaded and playing.
 
// Stop the music based on a user action or an in-game event
oslStopSound(music);
 
// Music can be played again or manipulated further if needed

This function is part of the Audio Player group, which includes other audio control functions.

oslPauseSound()

void oslPauseSound ( OSL_SOUND *  s, int  pause  )

extern

Pauses, resumes, or toggles a sound.

This function controls the pause state of a specified sound. It can pause, resume, or toggle the sound's playback based on the 'pause' parameter. This allows for dynamic control over sound playback, useful in various application scenarios such as pausing the game or responding to user interactions.

Parameters

s	Pointer to an OSL_SOUND structure representing the sound to control.
pause	Control the sound's playback state: 1: Pause the sound. If the sound is already paused, it remains paused. 0: Resume the sound from where it was paused. -1: Toggle between pause and play. If the sound is playing, it will be paused; if paused, it will be resumed.

Note

If the sound is not currently playing, calling this function with a resume or toggle command will have no effect. Neither has it on a sound being stopped: the stop wins.

A sound paused when the PSP enters stand-by stays paused after it wakes up. A streamed sound resumed before its file has been reopened (see oslAudioVSync) starts playing once it has.

OSL_SOUND *backgroundMusic;
// Assume backgroundMusic is loaded and playing.
 
// Pause the music
oslPauseSound(backgroundMusic, 1);
 
// Later, resume the music
oslPauseSound(backgroundMusic, 0);
 
// Toggle music playback
oslPauseSound(backgroundMusic, -1);

This function is part of the Audio Player group.

oslDeleteSound()

void oslDeleteSound ( OSL_SOUND *  s )

extern

Deletes a sound, freeing associated memory.

This function stops any currently playing sound and frees all resources associated with it. It is essential to call this function for every loaded sound when it is no longer needed, to prevent memory leaks and to clean up the audio system resources.

Parameters

s	Pointer to an OSL_SOUND structure that is to be deleted. If the sound is currently playing, it will be stopped first.

Note

After calling this function, the pointer 's' should no longer be used as it refers to freed memory.

From an audio thread, deletion of a playing sound is deferred until its channel finishes using it; cleanup runs on that channel's thread. The pointer is still invalid to the caller immediately after this call.

OSL_SOUND *effect;
// Assume effect is loaded and may be playing.
 
// Delete the sound and free resources
oslDeleteSound(effect);
 
// The pointer 'effect' is now invalid and should not be used.

This function is also part of the Audio Player group.

oslAudioSetSoundFilename()

int oslAudioSetSoundFilename ( OSL_SOUND *  s, const char *  filename  )

extern

Remembers the file of a streamed sound, to reopen it after the PSP wakes from stand-by.

Stores filename in s->filename as an absolute path (from the current directory set with chdir()) when it fits, since the file may be reopened by an audio thread, which has no current directory, or after the app changed directory. A name in the virtual file list is kept as is, as is a path whose absolute form doesn't fit (255 characters). Also marks the sound as opened after the last stand-by.

Note

The current directory is the one chdir() sets; a directory set with sceIoChdir() directly isn't seen.

Parameters

s	The streamed sound; a custom stream driver can call it too.
filename	The name the sound's file was opened with, while it is still open.

Returns

1, or 0 if not even filename fits in s->filename (left empty: the sound can't be reopened).

oslAudioVSync()

void oslAudioVSync ( )

extern

Synchronizes audio streaming with the PSP's power management.

This function ensures that streamed audio files continue to play seamlessly after the PSP resumes from stand-by mode. It should be called regularly within the game loop to maintain audio playback synchronization, especially when handling streamed audio files.

Note

It's crucial to call this function periodically if your application uses streamed audio and the PSP may enter stand-by mode. Failure to call this function frequently enough can result in audio not resuming correctly after the PSP wakes up from stand-by.

Warning

This function is included in the call to oslEndFrame, which handles frame-ending procedures including audio synchronization. If you are already calling oslEndFrame in your loop, you do not need to call oslAudioVSync separately. For newer projects, it is recommended to use oslEndFrame for a cleaner and more comprehensive approach to frame management and audio synchronization.

while (gameRunning) {
    // Game logic and rendering code here
 
    // Synchronize audio playback with frame management
    oslEndFrame();
 
    // Alternatively, if not using oslEndFrame:
    oslAudioVSync();
}

Including this function in your game loop ensures that audio playback issues do not occur after the PSP resumes from a standby state.

Note

It has the files of the streamed sounds that were playing or paused when the PSP entered stand-by reopened, by their channel's thread before its next buffer; the paused ones stay paused.