ofSoundPlayer

ofDocsdocumentation sound ofSoundPlayer

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.

getPan( )

float getPan()

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

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

getPosition( )

float getPosition()

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

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

getPositionMS( )

int getPositionMS()

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

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

getSpeed( )

float getSpeed()

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

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

getVolume( )

float getVolume()

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

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

isLoaded( )

bool isLoaded()

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

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

isPlaying( )

bool isPlaying()

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

load( `...` )

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

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).

ofSoundPlayer( )

ofSoundPlayer()

Creates the ofSoundPlayer instance and initializes the underlying properties in the underlying engine.

play( )

void play()

Starts playback.

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

setLoop( `...` )

void setLoop(bool loop)

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

Parameters:

loop "true" to loop, default is false.

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();

setMultiPlay( `...` )

void setMultiPlay(bool multiplay)

Enables playing multiple simultaneous copies of the sound.

Parameters:

multiplay "true" to enable, default is false.

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

setPan( `...` )

void setPan(float pan)

Sets stereo pan.

Parameters:

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

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

setPaused( `...` )

void setPaused(bool paused)

Enables pause / resume.

Parameters:

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

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

setPosition( `...` )

void setPosition(float percent)

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

Parameters:

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

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

setPositionMS( `...` )

void setPositionMS(int ms)

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

Parameters:

ms number of milliseconds from the start of the file.

This sets the position of the playhead in milliseconds.

setSpeed( `...` )

void 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

setVolume( `...` )

void setVolume(float vol)

Sets playback volume.

Parameters:

vol range is 0 to 1.

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

stop( )

void stop()

Stops playback.

Stops the sound currently playing.

Example:

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

unload( )

void unload()

Stops and unloads the current sound.

#class ofSoundPlayer

##InlineDescription

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.

##Description

##Methods

###float getPan()

_inlined_description: _

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

_description: _

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:
~~~~{.cpp}
    
    ofSoundPlayer mySound;    
    mySound.load("beat.mp3");    
    mySound.play();    
    mySound.getPan();//Returns 0.0     
    mySound.setPan(1.0f);     
    mySound.getPan();//Returns 1.0
~~~~

###shared_ptr< ofBaseSoundPlayer > getPlayer()

_inlined_description: _

_description: _

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.

###float getPosition()

_inlined_description: _

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

_description: _

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:
~~~~{.cpp}    
    ofSoundPlayer mySound;  
    mySound.load("beat.mp3");   
    mySound.play();   
    mySound.getPosition(); //Returns the current position as a percent 0.0-1.0
~~~~

###int getPositionMS()

_inlined_description: _

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

_description: _

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

###float getSpeed()

_inlined_description: _

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

_description: _

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:
~~~~{.cpp}
    
    ofSoundPlayer mySound;    
    mySound.load("beat.mp3");   
    mySound.getSpeed(); //Returns 1.0   
    mySound.setSpeed(2.0f);   
    mySound.getSpeed(); //Returns 2.0f
~~~~

###float getVolume()

_inlined_description: _

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

_description: _

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

###bool isLoaded()

_inlined_description: _

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

_description: _

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

###bool isPlaying()

_inlined_description: _

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

_description: _

###bool load(&fileName, stream = false)

_inlined_description: _

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).

_description: _

### ofSoundPlayer()

_inlined_description: _

_description: _

Creates the ofSoundPlayer instance and initializes the underlying properties in the underlying engine.

###void play()

_inlined_description: _

Starts playback.

_description: _

Examples:

Normal Playback:
~~~~{.cpp}
ofSoundPlayer mySound;
mySound.load("beat.mp3");
mySound.play(); //Plays sound
mySound.play(); //Restarts and plays sound
~~~~

Multiplay:
~~~~{.cpp}
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
~~~~

###void setLoop(loop)

_inlined_description: _

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

**Parameters:**

loop "true" to loop, default is false.

_description: _

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

Example:
~~~~{.cpp}
ofSoundPlayer mySound;
mySound.load("beat.mp3");
mySound.setLoop(true); //Sound will loop
mySound.play();
~~~~

###void setMultiPlay(multiplay)

_inlined_description: _

Enables playing multiple simultaneous copies of the sound.

**Parameters:**

multiplay "true" to enable, default is false.

_description: _

Example:

~~~~{.cpp}
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
~~~~

###void setPan(pan)

_inlined_description: _

Sets stereo pan.

**Parameters:**

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

_description: _

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:
~~~~{.cpp}
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
~~~~

###void setPaused(paused)

_inlined_description: _

Enables pause / resume.

**Parameters:**

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

_description: _

Pauses and un-pauses the playback of the sound.

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

###void setPlayer(newPlayer)

_inlined_description: _

_description: _

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.

~~~~{.cpp}
ofPtr<ofBaseSoundPlayer> soundPtr(new ofOpenALSoundPlayer());
player.setPlayer(soundPtr);
~~~~

###void setPosition(percent)

_inlined_description: _

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

**Parameters:**

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

_description: _

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:
~~~~{.cpp}
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
~~~~

###void setPositionMS(ms)

_inlined_description: _

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

**Parameters:**

ms number of milliseconds from the start of the file.

_description: _

This sets the position of the playhead in milliseconds.

###void setSpeed(speed)

_inlined_description: _

Sets playback speed.

**Parameters:**

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

_description: _

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

Example:
~~~~{.cpp}
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
~~~~

###void setVolume(vol)

_inlined_description: _

Sets playback volume.

**Parameters:**

vol range is 0 to 1.

_description: _

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

Example:
~~~~{.cpp}
ofSoundPlayer mySound;
mySound.load("beat.mp3");
mySound.play();
mySound.setVolume(0.1f); //Sets volume at 10% of maximum
~~~~

###void stop()

_inlined_description: _

Stops playback.

_description: _

Stops the sound currently playing.

Example:
~~~~{.cpp}
ofSoundPlayer mySound;
mySound.load("beat.mp3");
mySound.play(); //Begins playback of sound
mySound.stop(); //Ends playback, stops audio
~~~~

###void unload()

_inlined_description: _

Stops and unloads the current sound.

_description: _

##Variables

###ofPtr player

_inlined_description: _

_description: _

Docs 0.11.0

getPan( )

getPosition( )

getPositionMS( )

getSpeed( )

getVolume( )

isLoaded( )

isPlaying( )

load( `...` )

ofSoundPlayer( )

play( )

setLoop( `...` )

setMultiPlay( `...` )

setPan( `...` )

setPaused( `...` )

setPosition( `...` )

setPositionMS( `...` )

setSpeed( `...` )

setVolume( `...` )

stop( )

unload( )

Variables

Methods

See also

Docs 0.11.0

ofSoundPlayer

getPan( )

getPosition( )

getPositionMS( )

getSpeed( )

getVolume( )

isLoaded( )

isPlaying( )

load( ... )

ofSoundPlayer( )

play( )

setLoop( ... )

setMultiPlay( ... )

setPan( ... )

setPaused( ... )

setPosition( ... )

setPositionMS( ... )

setSpeed( ... )

setVolume( ... )

stop( )

unload( )

Variables

Methods

See also

load( `...` )

setLoop( `...` )

setMultiPlay( `...` )

setPan( `...` )

setPaused( `...` )

setPosition( `...` )

setPositionMS( `...` )

setSpeed( `...` )

setVolume( `...` )