Stream music files from disk. More...
#include <Music.h>
Public Types | |
| using | Ptr = std::unique_ptr< Object > |
| Unique object pointer. More... | |
Public Member Functions | |
| Music () | |
| Default constructor. More... | |
| Music (const Music &)=delete | |
| Copy constructor. More... | |
| Music & | operator= (const Music &)=delete |
| Copy assignment operator. More... | |
| Music (Music &&) noexcept | |
| Move constructor. More... | |
| Music & | operator= (Music &&) noexcept |
| Move assignment operator. More... | |
| std::string | getClassName () const override |
| Get the name of this class. More... | |
| void | setSource (const std::string &source) override |
| Set the music file to be played. More... | |
| const std::string & | getSource () const override |
| Get music source. More... | |
| void | setVolume (float volume) override |
| Set the volume of the music. More... | |
| float | getVolume () const override |
| Get the volume of the music. More... | |
| void | setPitch (float pitch) override |
| Set the pitch of the music. More... | |
| float | getPitch () const override |
| Get the pitch of the music. More... | |
| void | setLoop (bool isLooped) override |
| Set whether or not the music should loop after reaching the end. More... | |
| bool | isLooped () const override |
| Check if music is looped or not. More... | |
| void | seek (const Time &position) override |
| Change the current playing position of the music. More... | |
| Time | getPlayingPosition () const override |
| Get the current playing position of the music. More... | |
| void | play () override |
| Play music. More... | |
| void | pause () override |
| Pause music. More... | |
| void | stop () override |
| Stop playing the music. More... | |
| Time | getDuration () const override |
| Get the total duration of the music. More... | |
| Status | getStatus () const override |
| Get the current status of the music (stopped, paused, playing) More... | |
| ~Music () override | |
| Destructor. More... | |
| std::string | getClassType () const override |
| Get the name of this class. More... | |
| void | adjustVolume (float offset) |
| Turn the volume up/down by a given offset. More... | |
| void | setMute (bool mute) |
| Set whether or not the audio should be audible. More... | |
| bool | isMuted () const |
| Check if audio is muted or not. More... | |
| void | restart () |
| Reset the playing position to the beginning. More... | |
| void | setTag (const std::string &tag) |
| Assign the object an alias. More... | |
| const std::string & | getTag () const |
| Get the tag assigned to the object. More... | |
| unsigned int | getObjectId () const |
| Get the unique id of the object. More... | |
| int | onPropertyChange (const std::string &property, const Callback< Property > &callback, bool oneTime=false) |
| Add an event listener to a specific property change event. More... | |
| int | onPropertyChange (const Callback< Property > &callback, bool oneTime=false) |
| Add an event listener to any property change event. More... | |
| void | suspendedEventListener (int id, bool suspend) |
| Pause or resume execution of an event listener. More... | |
| bool | isEventListenerSuspended (int id) const |
| Check if an event listener is suspended or not. More... | |
| bool | removeEventListener (const std::string &event, int id) |
| Remove an event listener from an event. More... | |
| bool | removeEventListener (int id) |
| Remove an event listener. More... | |
| int | onDestruction (const Callback<> &callback) |
| Add a destruction listener. More... | |
| bool | isSameObjectAs (const Object &other) const |
| Check if another object is the same instance as this object. More... | |
Protected Member Functions | |
| void | emitChange (const Property &property) |
| Dispatch a property change event. More... | |
| void | emitDestruction () |
| Emit a destruction event. More... | |
Protected Attributes | |
| EventEmitter | eventEmitter_ |
| Event dispatcher. More... | |
Detailed Description
Stream music files from disk.
ime::audio::Music is ideal for playing long and big audio file such as background music.
The audio file is not loaded in memory but rather streamed from the disk. Therefore, The file must remain accessible on the disk for as long as its being used. You can use ime::audio::SoundEffect to play short sounds such as gun shots and explosions
This class is not meant to be instantiated directly, use ime::Scene::getAudio or ime::Engine::getAudioManager
Member Typedef Documentation
◆ Ptr
|
inherited |
Constructor & Destructor Documentation
◆ Music() [1/3]
| ime::audio::Music::Music | ( | ) |
Default constructor.
◆ Music() [2/3]
|
delete |
Copy constructor.
◆ Music() [3/3]
|
noexcept |
Move constructor.
◆ ~Music()
|
override |
Destructor.
Member Function Documentation
◆ adjustVolume()
|
inherited |
Turn the volume up/down by a given offset.
- Parameters
-
offset Value to increase/decrease the volume by
This function adds on to the current volume. A positive offset increases the volume while a negative offset decreases the volume. This function will unmmute the audio if its muted
- See also
- setMute
◆ emitChange()
|
protectedinherited |
Dispatch a property change event.
- Parameters
-
property The property that changed
This function will invoke all the event listeners of the specified property
- See also
- emit
◆ emitDestruction()
|
protectedinherited |
Emit a destruction event.
- Note
- This function must be the first statement in the definition of a destructor to avoid undefined behavior. In addition, note that destruction listeners are invoked once. Therefore, multiple classes in a hierarchy may call this function but the class that makes the call first will be the one that invokes the destruction listeners
◆ getClassName()
|
overridevirtual |
◆ getClassType()
|
overridevirtualinherited |
Get the name of this class.
- Returns
- The name of this class
Note that this function is only implemented by child classes of Object which also serve as a base class for other classes
- See also
- getClassName
Reimplemented from ime::Object.
◆ getDuration()
|
overridevirtual |
Get the total duration of the music.
- Returns
- The total duration of the music
Implements ime::audio::Audio.
◆ getObjectId()
|
inherited |
Get the unique id of the object.
- Returns
- The unique id of the object
Note that each instance of ime::Object has a unique id
- See also
- setTag
◆ getPitch()
|
overridevirtual |
◆ getPlayingPosition()
|
overridevirtual |
Get the current playing position of the music.
- Returns
- Current playing position of the music
Implements ime::audio::Audio.
◆ getSource()
|
overridevirtual |
◆ getStatus()
|
overridevirtual |
Get the current status of the music (stopped, paused, playing)
- Returns
- Current status of the music
Implements ime::audio::Audio.
◆ getTag()
|
inherited |
◆ getVolume()
|
overridevirtual |
Get the volume of the music.
- Returns
- Volume of the music, in the range [0, 100]
Implements ime::audio::Audio.
◆ isEventListenerSuspended()
|
inherited |
Check if an event listener is suspended or not.
- Parameters
-
id The identification number of the listener to be checked
- Returns
- True if suspended, otherwise false
This function also returns false if the specified event listener does not exist
- See also
- suspendedEventListener
◆ isLooped()
|
overridevirtual |
Check if music is looped or not.
- Returns
- True if music is looped, otherwise false
Implements ime::audio::Audio.
◆ isMuted()
|
inherited |
Check if audio is muted or not.
- Returns
- True if audio is muted or false if audio is not muted
◆ isSameObjectAs()
|
inherited |
Check if another object is the same instance as this object.
- Parameters
-
other The object to compare against this object
- Returns
- True if other is the same instance as this object, otherwise false
◆ onDestruction()
|
inherited |
Add a destruction listener.
- Parameters
-
callback Function to be executed when the object is destroyed
- Returns
- The unique id of the destruction listener
The destruction listener is called when the object reaches the end of its lifetime. Note that an object may have multiple destruction listeners registered to it
- Warning
- It's not advised to call virtual functions in the destruction callback as some parts of the object may have already been destroyed by the time the callback is invoked. In such an event, the behavior is undefined
- See also
- removeEventListener
◆ onPropertyChange() [1/2]
|
inherited |
Add an event listener to any property change event.
- Parameters
-
callback The function to be executed when any property changes oneTime True to execute the callback one-time or false to execute it every time the event is triggered
- Returns
- The unique id of the event listener
When unsubscribing the any property change event handler, you must pass "propertyChange" as the name of the event
- See also
- onPropertyChange(const std::string&, const ime::Callback<ime::Property>&)
◆ onPropertyChange() [2/2]
|
inherited |
Add an event listener to a specific property change event.
- Parameters
-
property The name of the property to add an event listener to oneTime True to execute the callback one-time or false to execute it every time the event is triggered callback The function to be executed when the property changes
- Returns
- The unique id of the event listener
A property change event is triggered by any function that begins with set, where the the text after set is the name of the property. For example, the setTag() function, modifies the tag property of the object, thus will generate a "tag" change event each time it is called
Note that multiple event listeners may be registered to the same property change event. In addition, when adding a property change event listener, the name of the property must be in lowercase.
- See also
- unsubscribe and onPropertyChange(const ime::Callback<ime::Property>&)
◆ operator=() [1/2]
◆ operator=() [2/2]
◆ pause()
|
overridevirtual |
Pause music.
This function pauses the stream if it was playing, otherwise (music already paused or stopped) it has no effect
Implements ime::audio::Audio.
◆ play()
|
overridevirtual |
Play music.
This function starts the music if it was stopped, resumes it if it was paused, and restarts it from the beginning if it was already playing. This function uses its own thread so that it doesn't block the rest of the program while the music is played
Implements ime::audio::Audio.
◆ removeEventListener() [1/2]
|
inherited |
Remove an event listener from an event.
- Parameters
-
event The name of the event to remove an event listener from id The unique id of the event listener to be removed
- Returns
- True if the event listener was removed or false if the event or the event listener is does not exist
◆ removeEventListener() [2/2]
|
inherited |
Remove an event listener.
- Parameters
-
id The id of the event listener to be removed
- Returns
- True if the event listener was removed or false if no such handler exists
◆ restart()
|
inherited |
Reset the playing position to the beginning.
This function will reset the playing position without stopping the audio (unlike stop function), which would require play to be called to get the audio to play again
◆ seek()
|
overridevirtual |
Change the current playing position of the music.
- Parameters
-
position New playing position of the music
The playing position can be changed when the music is either paused or playing. Changing the playing position when the music is stopped has no effect, since playing the music would reset its position
Implements ime::audio::Audio.
◆ setLoop()
|
overridevirtual |
Set whether or not the music should loop after reaching the end.
- Parameters
-
isLooped True to play in loop, false to play once
Implements ime::audio::Audio.
◆ setMute()
|
inherited |
Set whether or not the audio should be audible.
- Parameters
-
mute True to make audio inaudible, or false to make audio audible
When set to true the audio will not be audible but will continue to play if currently playing
◆ setPitch()
|
overridevirtual |
Set the pitch of the music.
- Parameters
-
pitch The new pitch of the music
The pitch represents the perceived fundamental frequency of a sound; thus you can make a sound more acute or grave by changing its pitch. Changing the pitch also changes the playing speed of the music.
The default value for the pitch is 1
Implements ime::audio::Audio.
◆ setSource()
|
overridevirtual |
Set the music file to be played.
- Parameters
-
source Filename of an audio file
The source must refer to an actual music file on the disk. This music file is the one to be played, pitched and done all sorts of things. This function doesn't start the music, it sets the music that will be played when play() is called
- See also
- play
- Warning
- The music is not loaded but rather streamed continuously from the disk. Therefore the the specified music file must remain accessible for as long as its being used
Implements ime::audio::Audio.
◆ setTag()
|
inherited |
Assign the object an alias.
- Parameters
-
tag The alias of the object
This function is useful if you want to refer to the object by a tag instead of its object id. Unlike an object id, multiple objects may have the same tag
By default, the tag is an empty string
- See also
- getObjectId
◆ setVolume()
|
overridevirtual |
Set the volume of the music.
- Parameters
-
volume Volume to set
The volume is a value between 0 (mute) and 100 (full volume).
The default value for the volume is 100
Implements ime::audio::Audio.
◆ stop()
|
overridevirtual |
Stop playing the music.
This function stops the music if it was playing or paused, and does nothing if it was already stopped. It also resets the playing position
Implements ime::audio::Audio.
◆ suspendedEventListener()
|
inherited |
Pause or resume execution of an event listener.
- Parameters
-
id The event listeners unique identification number suspend True to suspend/pause or false to unsuspend/resume
- See also
- isEventListenerSuspended
Member Data Documentation
◆ eventEmitter_
|
protectedinherited |
The documentation for this class was generated from the following file: