ofSoundPlayer

class methods

global functions

Extends

This class extends others, you can call their methods on an instance of ofSoundPlayer too:

The ofSoundPlayer class wraps one of several underlying audio utility libraries, depending on your OS and your configuration that can be Fmod, Quicktime, or OpenAL. The ofSoundPlayer is primarily to allow you to load sound files and control and manipulate their playback and properties, if you want more low level access to sound data and to your sound card then you should take a look at the ofSoundStream class.

Documentation from code comments


Plays sound files.

ofSoundPlayer handles simple playback of sound files, with controls for volume, pan, speed, seeking and multiplay. This is a common cross-platform sound player interface which is inherited by each of the platform-specific sound player implementations.

getPan()

float ofSoundPlayer::getPan()

Returns the pan position of the sound. -1.0 - 1.0 range. 0.0 is center pan, -1.0 is full left pan and 1.0 is full right pan. Default is 0.0

Example:


    ofSoundPlayer mySound;    
    mySound.load("beat.mp3");    
    mySound.play();    
    mySound.getPan();//Returns 0.0     
    mySound.setPan(1.0f);     
    mySound.getPan();//Returns 1.0

Documentation from code comments


Gets stereo pan. \return stereo pan in the range -1 to 1.

getPlayer()

shared_ptr< ofBaseSoundPlayer > ofSoundPlayer::getPlayer()

ofSoundPlayer actually wraps a dynamic instance of a specific sound player for a specific engine, that is, it contains an interface to the sound engine being used to load and playback sounds. This allows you access to the pointer that contains the specific interface.

getPosition()

float ofSoundPlayer::getPosition()

Returns the current position of the playhead as a float between 0.0 and 1.0. 0.0 is the beginning of the sound file and 1.0 is the end.

Example:

    ofSoundPlayer mySound;  
    mySound.load("beat.mp3");   
    mySound.play();   
    mySound.getPosition(); //Returns the current position as a percent 0.0-1.0

Documentation from code comments


Gets position of the playhead. \return playhead position as a float between 0 and 1.

getPositionMS()

int ofSoundPlayer::getPositionMS()

This returns the position of the playhead in terms of milliseconds (i.e. 5000 for 5 seconds into the sound).

Documentation from code comments


Gets position of the playhead. \return playhead position in milliseconds.

getSpeed()

float ofSoundPlayer::getSpeed()

Returns the speed of the sound playback in relation to its normal speed. So 2.0 would mean the sound is playing twice as fast. 0.5 would mean half as fast.

Example:


    ofSoundPlayer mySound;    
    mySound.load("beat.mp3");   
    mySound.getSpeed(); //Returns 1.0   
    mySound.setSpeed(2.0f);   
    mySound.getSpeed(); //Returns 2.0f

Documentation from code comments


Gets playback speed. \return playback speed (see ofSoundPlayer::setSpeed()).

getVolume()

float ofSoundPlayer::getVolume()

Returns the current volume of the sound player, as set by setVolume(). 0.0 is silent and 1.0 is full volume.

Documentation from code comments


Gets current volume. \return current volume in the range 0 to 1.

isLoaded()

bool ofSoundPlayer::isLoaded()

Returns whether or not a sound has been successfully loaded into the sound player.

Documentation from code comments


Queries the player to see if its file was loaded successfully. \return whether or not the player is ready to begin playback.

isPlaying()

bool ofSoundPlayer::isPlaying()

Documentation from code comments


Gets current playback state. \return true if the player is currently playing a file.

load(...)

bool ofSoundPlayer::load(const filesystem::path &fileName, bool stream=false)

Documentation from code comments


Tells the sound player which file to play.

Codec support varies by platform but wav, aif, and mp3 are safe.

Parameters:

fileName Path to the sound file, relative to your app's data folder.

stream set "true" to enable streaming from disk (for large files).

play()

void ofSoundPlayer::play()

Plays the sound. If setMultiPlay() has been set to true each play() command will spawn a new copy of the sound on a new channel, letting the existing sounds continue until they are finished. If setMultiPlay() is set to false it will restart the playback of the song.

Examples:

Normal Playback:

ofSoundPlayer mySound;
mySound.load("beat.mp3");
mySound.play(); //Plays sound
mySound.play(); //Restarts and plays sound

Multiplay:

ofSoundPlayer mySound;
mySound.setMultiPlay(true);
mySound.load("beat.mp3");
mySound.play(); //Plays sound
mySound.play(); //Adds new copy of sound to channel and plays over currently playing sound

Documentation from code comments


Starts playback.

setLoop(...)

void ofSoundPlayer::setLoop(bool loop)

Loops the sound if set to true. Does not loop the sound if set to false. Default is false.

Example:

ofSoundPlayer mySound;
mySound.load("beat.mp3");
mySound.setLoop(true); //Sound will loop
mySound.play();

Documentation from code comments


Sets whether to loop once the end of the file is reached.

Parameters:

loop "true" to loop, default is false.

setMultiPlay(...)

void ofSoundPlayer::setMultiPlay(bool multiplay)

Allows a sound to be played multiple times at once. When set to true the play() function will start playing the sound on a new channel, letting the old channels continue until they are done playing. When set to false the play() function will stop the channel before playing the sound.

Example:

ofSoundPlayer mySound;
mySound.setMultiPlay(true);
mySound.load("beat.mp3");
mySound.play(); //Plays sound
mySound.play(); //Adds new copy of sound to channel and plays over currently playing sound

Documentation from code comments


Enables playing multiple simultaneous copies of the sound.

Parameters:

multiplay "true" to enable, default is false.

setPan(...)

void ofSoundPlayer::setPan(float pan)

Sets the pan position (pct) of the sound. -1.0 - 1.0 range. 0.0 is center pan, -1.0 is full left pan and 1.0 is full right pan.

Example:

ofSoundPlayer mySound;
mySound.load("beat.mp3");
mySound.play();
mySound.setPan(-1.0f); //Pans to the left
mySound.setPan(1.0f); //Pans to the right
mySound.setPan(0.0f); //Back to center

Documentation from code comments


Sets stereo pan.

Parameters:

pan range is -1 to 1 (-1 is full left, 1 is full right).

setPaused(...)

void ofSoundPlayer::setPaused(bool paused)

Pauses and un-pauses the playback of the sound.

Example

ofSoundPlayer mySound;
mySound.load("beat.mp3");
mySound.play();
mySound.setPaused(true); //Sound is paused
mySound.setPaused(false); //Sound is unpaused, playback continues

Documentation from code comments


Enables pause / resume.

Parameters:

paused "true" to pause, "false" to resume.

setPlayer(...)

void ofSoundPlayer::setPlayer(shared_ptr< ofBaseSoundPlayer > newPlayer)

ofSoundPlayer actually wraps a dynamic instance of a sound player, that is, it contains an interface to the sound engine being used to load and playback sounds. If you want to set the interface that your system uses, you can pass an ofPtr to an ofSoundPlayer into the ofSoundPlayer and have the ofSoundPlayer manipulate that one instead.

ofPtr<ofBaseSoundPlayer> soundPtr(new ofOpenALSoundPlayer());
player.setPlayer(soundPtr);

setPosition(...)

void ofSoundPlayer::setPosition(float percent)

Sets the playback-head to the position (pct) specified. 0.0 - 1.0 range. 0.0 is the beginning of the sound file and 1.0 is the end.

Example:

ofSoundPlayer mySound;
mySound.load("beat.mp3");
mySound.play();
mySound.setPosition(0.5f); //Moves the playhead to halfway through the sound
mySound.setPosition(0.0f); //Moves the playhead back to the beginning of the sound

Documentation from code comments


Sets position of the playhead within the file (aka "seeking").

Parameters:

percent range is 0 (beginning of file) to 1 (end of file).

setPositionMS(...)

void ofSoundPlayer::setPositionMS(int ms)

This sets the position of the playhead in milliseconds.

Documentation from code comments


Sets position of the playhead within the file (aka "seeking").

Parameters:

ms number of milliseconds from the start of the file.

setSpeed(...)

void ofSoundPlayer::setSpeed(float speed)

Sets the playback speed of the sound. 1.0 is normal speed. 2.0 is double the normal speed etc.

Example:

ofSoundPlayer mySound;
mySound.loadSound("beat.mp3");
mySound.play();
mySound.setSpeed(2.0f); //Chipmunk Voice
mySound.setSpeed(0.2f); //Isaac Hayes on Muscle Relaxers
mySound.setSpeed(1.0f); //Normal again

Documentation from code comments


Sets playback speed.

Parameters:

speed set > 1 for faster playback, < 1 for slower playback.

setVolume(...)

void ofSoundPlayer::setVolume(float vol)

Sets the volume of the sound. 0.0 - 1.0 range. 0.0 is silent and 1.0 is full volume.

Example:

ofSoundPlayer mySound;
mySound.load("beat.mp3");
mySound.play();
mySound.setVolume(0.1f); //Sets volume at 10% of maximum

Documentation from code comments


Sets playback volume.

Parameters:

vol range is 0 to 1.

stop()

void ofSoundPlayer::stop()

Stops the sound currently playing.

Example:

ofSoundPlayer mySound;
mySound.load("beat.mp3");
mySound.play(); //Begins playback of sound
mySound.stop(); //Ends playback, stops audio

Documentation from code comments


Stops playback.

unload()

void ofSoundPlayer::unload()

Documentation from code comments


Stops and unloads the current sound.

ofSoundGetSpectrum(...)

float * ofSoundGetSpectrum(int nBands)

Documentation from code comments


Gets a frequency spectrum sample, taking all current sound players into account.

Each band will be represented as a float between 0 and 1.

Warning: This isn't implemented on mobile & embedded platforms.

Parameters:

nBands number of spectrum bands to return, max 512. \return pointer to an FFT sample, sample size is equal to the nBands parameter.

ofSoundSetVolume(...)

void ofSoundSetVolume(float vol)

Sets the volume of all ofSoundPlayer objects to the volume (vol) specified. 0.0 - 1.0 range. 0.0 is silent and 1.0 is full volume.

Documentation from code comments


Sets global volume for FMOD-based sound players (windows, osx).

Parameters:

vol range is 0 to 1.

ofSoundShutdown()

void ofSoundShutdown()

Documentation from code comments


Cleans up FMOD (windows, osx).

ofSoundStopAll()

void ofSoundStopAll()

Documentation from code comments


Stops all active sound players on FMOD-based systems (windows, osx).

ofSoundUpdate()

void ofSoundUpdate()

Updates sound engine. This should be called every frame.

Documentation from code comments


Call in your app's update() to update FMOD-based sound players.

If you have any doubt about the usage of this module you can ask in the forum.

If you want to contribute better documentation or start documenting this section you can do so here

If you find anything wrong with this docs you can report any error by opening an issue