Sound Loading

Functions for loading and managing sounds. More...

Functions
OSL_SOUND *	oslLoadSoundFile (const char *filename, int stream)
	Loads a sound file and determines its format based on the file extension.
OSL_SOUND *	oslLoadSoundFileWAV (const char *filename, int stream)
	Loads a WAV sound file.
OSL_SOUND *	oslLoadSoundFileBGM (const char *filename, int stream)
	Loads a BGM sound file.
OSL_SOUND *	oslLoadSoundFileMOD (const char *filename, int stream)
	Loads a MOD sound file.
OSL_SOUND *	oslLoadSoundFileMP3 (const char *filename, int stream)
	Loads an MP3 sound file.
OSL_SOUND *	oslLoadSoundFileAT3 (const char *filename, int stream)
	Loads an AT3 (ATRAC3) sound file.
void	oslSetModSampleRate (int freq, int stereo, int shift)
	Sets the sample rate for MOD file playback in OSLib.

Detailed Description

Functions for loading and managing sounds.

Function Documentation

oslLoadSoundFile()

OSL_SOUND * oslLoadSoundFile ( const char * filename, int stream )

extern

Loads a sound file and determines its format based on the file extension.

Supported formats include WAV, MP3, AT3, and BGM. The function selects streaming or full memory loading based on the 'stream' parameter.

Parameters

filename	Path to the sound file.
stream	Streaming mode; OSL_FMT_STREAM for streaming, OSL_FMT_NONE for full loading.

Returns

Pointer to the loaded sound object.

oslLoadSoundFileWAV()

OSL_SOUND * oslLoadSoundFileWAV ( const char * filename, int stream )

extern

Loads a WAV sound file.

This function specifically handles the loading of WAV sound files. It determines whether to load the file entirely into memory or to stream it from disk based on the 'stream' parameter. For more details on the parameters and the behavior regarding streamed versus fully loaded sounds, refer to oslLoadSoundFile().

WAV files are a common uncompressed audio format that offers high fidelity, making them suitable for short sound effects where quality is a priority over file size.

Parameters

filename	Path to the WAV sound file. It should be a valid file stored on the memory stick. Alternate file sources have not been tested and may not work properly.
stream	Determines the mode of operation: OSL_FMT_STREAM: Sound is streamed from the file, minimizing memory usage but requiring more CPU resources. OSL_FMT_NONE: Sound is completely loaded into memory, providing faster access at the cost of increased memory usage.

Returns

Pointer to the loaded OSL_SOUND structure, or NULL if loading fails.

See also

oslLoadSoundFile

oslLoadSoundFileBGM()

OSL_SOUND * oslLoadSoundFileBGM ( const char * filename, int stream )

extern

Loads a BGM sound file.

This function is designed to load BGM (Background Music) files, a custom audio format specific to OSLib. The BGM format is optimized for space efficiency, storing sound data in a mono format which takes up less room compared to uncompressed formats like WAV.

The function determines whether to stream the sound or load it entirely into memory based on the 'stream' parameter. Streaming uses less memory but requires more CPU resources to handle real-time decoding and playback.

Encoders for creating BGM files and additional tools for handling them can be found in the OSLib distribution. Additional sound formats and utilities are provided in the OSTools extension library.

Parameters

filename	Path to the BGM sound file. Ensure that this is a valid path on the memory stick as alternate storage locations have not been extensively tested.
stream	Determines the loading method: OSL_FMT_STREAM: Stream the sound from the file, which uses less memory. OSL_FMT_NONE: Load the sound entirely into memory, which is faster but uses more memory.

Returns

Pointer to the loaded OSL_SOUND structure, or NULL if the loading fails.

See also

oslLoadSoundFile

oslLoadSoundFileMOD()

OSL_SOUND * oslLoadSoundFileMOD	(	const char *	filename,
		int	stream )

Loads a MOD sound file.

This function loads MOD format sound files, including variations like .mod, .it, .s3m, and .xm. MOD files are known for their tracker formats, widely used for creating music with pattern sequences. It requires linking with the MikMod library (-lmikmod). Note that OSLib currently supports only one MOD sound being played at a time; attempting to play multiple MOD sounds concurrently may result in unexpected behavior such as increased playback speed and volume.

Warning

Streaming is not supported for MOD files. Always set the stream parameter to OSL_FMT_NONE to ensure the sound is loaded entirely into RAM. Using OSL_FMT_STREAM can lead to incompatibilities in future OSLib versions.

MOD playback is resource-intensive, significantly impacting memory usage and CPU load. It can increase CPU usage by up to 50% with certain tracks. If your application is CPU-intensive, consider using a different sound format or adjusting the MOD sample rate with oslSetModSampleRate to reduce the load.

It's less of an issue in applications that are GPU-intensive, where CPU cycles are available during GPU waits. Adjustments to the MOD playback settings should be carefully managed to balance performance and audio quality.

Parameters

filename	Path to the MOD file. The file should be stored locally on the device as streaming is not supported.
stream	Must be OSL_FMT_NONE. Streaming is not supported for MOD files due to their resource-intensive nature.

Returns

Pointer to the loaded OSL_SOUND structure, or NULL if the file fails to load. Ensure proper error handling in your application.

Note

Linking with -lmikmod is required to use this functionality.

oslLoadSoundFileMP3()

OSL_SOUND * oslLoadSoundFileMP3	(	const char *	filename,
		int	stream )

Loads an MP3 sound file.

This function loads an MP3 sound file into the OSLib sound system. MP3 is a widely-used compressed audio format that allows for efficient storage of high-quality audio. Before calling this function, it is mandatory to initialize the Media Engine audio subsystem by calling oslInitAudioME in kernel mode. Failing to do so will result in a program crash, as MP3 playback relies on features available only in kernel mode.

Parameters

filename	Path to the MP3 file. The file should be accessible on the device, and the path must be correctly specified.
stream	Determines the loading behavior: OSL_FMT_STREAM: Stream the sound from the file, using less memory but requiring more CPU for real-time decoding. OSL_FMT_NONE: Load the entire sound file into memory, which uses more memory but less CPU during playback.

Returns

Pointer to the loaded OSL_SOUND structure, or NULL if the file fails to load or initialization requirements are not met.

Warning

Ensure that oslInitAudioME has been called in kernel mode prior to using this function.

oslLoadSoundFileAT3()

OSL_SOUND * oslLoadSoundFileAT3	(	const char *	filename,
		int	stream )

Loads an AT3 (ATRAC3) sound file.

This function handles the loading of ATRAC3 format sound files, which are proprietary audio formats developed by Sony that offer good compression rates and sound quality. Similar to MP3, initializing the Media Engine audio subsystem with oslInitAudioME in kernel mode is required before using this function to prevent the program from crashing.

Parameters

filename	Path to the AT3 file. Ensure the file is stored locally and the path is correctly specified for successful loading.
stream	Determines the loading method: OSL_FMT_STREAM: Stream the sound from the file. This method minimizes memory usage but might increase CPU load due to ongoing decoding. OSL_FMT_NONE: Load the sound completely into memory for quicker access at the cost of increased memory usage.

Returns

Pointer to the loaded OSL_SOUND structure, or NULL if the file fails to load or if pre-conditions are not met.

Warning

The Media Engine audio subsystem must be initialized in kernel mode prior to calling this function to ensure proper functionality and to avoid crashes.

oslSetModSampleRate()

void oslSetModSampleRate	(	int	freq,
		int	stereo,
		int	shift )

Sets the sample rate for MOD file playback in OSLib.

This function configures the sample rate for MOD file audio playback. Adjusting the sample rate can significantly affect both the CPU load required for decoding the audio and the playback quality. The function also requires setting a shift value to adjust the playback speed relative to the sample rate to match the internal PSP audio capabilities.

Parameters

freq	Sample rate in samples per second. The higher the sample rate, the higher the CPU load: 44100 Hz for high quality (default) 22050 Hz for medium quality 11025 Hz for low quality Decreasing the sample rate reduces CPU load but also audio quality.
stereo	Currently, the only supported value is 1, indicating stereo output.
shift	Sets the playback speed adjustment. It compensates for sample rate changes to maintain proper playback speed: 0: Normal speed (use with 44100 Hz) 1: Half speed (use with 22050 Hz to normalize speed when played at 44100 Hz) 2: Quarter speed (use with 11025 Hz to normalize speed when played at 44100 Hz) Values are powers of two; the actual playback speed is divided by 2^shift.

Note

Setting sample rates other than 44100, 22050, or 11025 Hz is not recommended as it can lead to untested and unpredictable behavior. Future versions of OSLib might not support such customizations.

// Examples of typical usage:
oslSetModSampleRate(11025, 1, 2); // Very low CPU usage, reduced sound quality
oslSetModSampleRate(22050, 1, 1); // Balanced CPU usage and sound quality
oslSetModSampleRate(44100, 1, 0); // High CPU usage, best sound quality
 
// Examples of advanced, non-recommended usage:
oslSetModSampleRate(22050, 1, 0); // Plays at double speed
oslSetModSampleRate(33075, 1, 0); // Plays at 1.5 times normal speed
oslSetModSampleRate(11025, 1, 1); // Plays at double speed, low quality