.. index:: pair: class; EE::Audio::Music
.. _doxid-class_e_e_1_1_audio_1_1_music:

class EE::Audio::Music
======================

.. toctree::
	:hidden:

	struct_EE_Audio_Music_Span.rst

Overview
~~~~~~~~

Streamed music played from an audio file. :ref:`More...<details-class_e_e_1_1_audio_1_1_music>`


.. ref-code-block:: cpp
	:class: doxyrest-overview-code-block

	#include <music.hpp>
	
	class Music: public :ref:`EE::Audio::SoundStream<doxid-class_e_e_1_1_audio_1_1_sound_stream>` {
	public:
		// typedefs
	
		typedef :ref:`Span<doxid-struct_e_e_1_1_audio_1_1_music_1_1_span>`<:ref:`Time<doxid-class_e_e_1_1_system_1_1_time>`> :target:`TimeSpan<doxid-class_e_e_1_1_audio_1_1_music_1ac3b58efcdc43c2c89c35eb2379d365b5>`;

		// structs
	
		template <typename T>
		struct :ref:`Span<doxid-struct_e_e_1_1_audio_1_1_music_1_1_span>`;

		// construction
	
		:target:`~Music<doxid-class_e_e_1_1_audio_1_1_music_1ae989ef08d00fcabb90326167cb97f012>`();

		// methods
	
		static Music* :target:`New<doxid-class_e_e_1_1_audio_1_1_music_1a6a7e81280617cb9e9fb6b64e4722b390>`();
		bool :ref:`openFromFile<doxid-class_e_e_1_1_audio_1_1_music_1afc2b3ce03c01ce0b53f8eaef4e7a1fe5>`(const std::string& filename);
		bool :ref:`openFromMemory<doxid-class_e_e_1_1_audio_1_1_music_1aef3a1e05f61b3797d95e94ba39531971>`(const void* data, std::size_t sizeInBytes);
		bool :ref:`openFromStream<doxid-class_e_e_1_1_audio_1_1_music_1a63ccf554d8e774d741eaf16f52261661>`(:ref:`IOStream<doxid-class_e_e_1_1_system_1_1_i_o_stream>`& stream);
		bool :target:`openFromPack<doxid-class_e_e_1_1_audio_1_1_music_1ae5e2df7fc0068175fb68179a938ff75a>`(:ref:`Pack<doxid-class_e_e_1_1_system_1_1_pack>`* pack, const std::string& filePackPath);
		:ref:`Time<doxid-class_e_e_1_1_system_1_1_time>` :ref:`getDuration<doxid-class_e_e_1_1_audio_1_1_music_1aafcf87ca769b1b9a428c1c483ceef294>`() const;
		:ref:`TimeSpan<doxid-class_e_e_1_1_audio_1_1_music_1ac3b58efcdc43c2c89c35eb2379d365b5>` :ref:`getLoopPoints<doxid-class_e_e_1_1_audio_1_1_music_1a3ef75fc666b6d410d9360610d157de25>`() const;
		void :ref:`setLoopPoints<doxid-class_e_e_1_1_audio_1_1_music_1ab6204b4dcccb3a161d2ffd7c4d9e4d02>`(:ref:`TimeSpan<doxid-class_e_e_1_1_audio_1_1_music_1ac3b58efcdc43c2c89c35eb2379d365b5>` timePoints);
	};

Inherited Members
-----------------

.. ref-code-block:: cpp
	:class: doxyrest-overview-inherited-code-block

	public:
		// enums
	
		enum :ref:`Status<doxid-class_e_e_1_1_audio_1_1_sound_source_1a09293754fddc60363b39e83a71874111>`;

		// structs
	
		struct :ref:`Chunk<doxid-struct_e_e_1_1_audio_1_1_sound_stream_1_1_chunk>`;

		// methods
	
		void :ref:`setPitch<doxid-class_e_e_1_1_audio_1_1_sound_source_1a6ebc9019d048be4be32b2ea3a20c0a34>`(float pitch);
		void :ref:`setVolume<doxid-class_e_e_1_1_audio_1_1_sound_source_1a3a2e0cf6ff2ee726a12450e91369ab2f>`(float volume);
		void :ref:`setPosition<doxid-class_e_e_1_1_audio_1_1_sound_source_1a8b1f39cca03ad22284344d58f0fb4dec>`(float x, float y, float z);
		void :ref:`setPosition<doxid-class_e_e_1_1_audio_1_1_sound_source_1a4850d9621033aeccf39ef9a83041165a>`(const :ref:`Vector3f<doxid-namespace_e_e_1_1_math_1a65f51d609aa1cb43626e6301465375db>`& position);
		void :ref:`setRelativeToListener<doxid-class_e_e_1_1_audio_1_1_sound_source_1a81ee0bc1c3e4b4348e6a7a791f31fb4b>`(bool relative);
		void :ref:`setMinDistance<doxid-class_e_e_1_1_audio_1_1_sound_source_1acf61df2388f55cbc759d112c389e84af>`(float distance);
		void :ref:`setAttenuation<doxid-class_e_e_1_1_audio_1_1_sound_source_1a90d1941023ac569193b269065d73de00>`(float attenuation);
		float :ref:`getPitch<doxid-class_e_e_1_1_audio_1_1_sound_source_1a6cd19d074c46b26801948c8d90cfb9f3>`() const;
		float :ref:`getVolume<doxid-class_e_e_1_1_audio_1_1_sound_source_1aca9cd53b4aa90f98fc5061ab7e57c93d>`() const;
		:ref:`Vector3f<doxid-namespace_e_e_1_1_math_1a65f51d609aa1cb43626e6301465375db>` :ref:`getPosition<doxid-class_e_e_1_1_audio_1_1_sound_source_1a3e36d949b0a5cb869d3f02dde2651c32>`() const;
		bool :ref:`isRelativeToListener<doxid-class_e_e_1_1_audio_1_1_sound_source_1ad7a78ac0d348c767a0ee6f4058f95bc3>`() const;
		float :ref:`getMinDistance<doxid-class_e_e_1_1_audio_1_1_sound_source_1a14d801b275c0fd45998fd249db937276>`() const;
		float :ref:`getAttenuation<doxid-class_e_e_1_1_audio_1_1_sound_source_1a23012b8face222ffac3500715de69e20>`() const;
		:ref:`SoundSource<doxid-class_e_e_1_1_audio_1_1_sound_source>`& :ref:`operator=<doxid-class_e_e_1_1_audio_1_1_sound_source_1aa4e8e5e469eca903896981c09242a1fa>`(const :ref:`SoundSource<doxid-class_e_e_1_1_audio_1_1_sound_source>`& right);
		virtual void :ref:`play<doxid-class_e_e_1_1_audio_1_1_sound_source_1aa944f65970d35222ea1a99229f09ea34>`() = 0;
		virtual void :ref:`pause<doxid-class_e_e_1_1_audio_1_1_sound_source_1a4c2bb65671291cc419b6f2cea28f3216>`() = 0;
		virtual void :ref:`stop<doxid-class_e_e_1_1_audio_1_1_sound_source_1a176f14707c5af0641bb167b01acffb16>`() = 0;
		virtual :ref:`Status<doxid-class_e_e_1_1_audio_1_1_sound_source_1a09293754fddc60363b39e83a71874111>` :ref:`getStatus<doxid-class_e_e_1_1_audio_1_1_sound_source_1a748100b271fae1d64514922c5c5b8abc>`() const;
		virtual void :ref:`play<doxid-class_e_e_1_1_audio_1_1_sound_stream_1abfa1c43cb539039b31f8fe0688ba105b>`();
		virtual void :ref:`pause<doxid-class_e_e_1_1_audio_1_1_sound_stream_1ae6e93e1bcd44c0145eb744d7a40682bd>`();
		virtual void :ref:`stop<doxid-class_e_e_1_1_audio_1_1_sound_stream_1a10bcb9b8a5091d3aa8fb4b0574159d19>`();
		unsigned int :ref:`getChannelCount<doxid-class_e_e_1_1_audio_1_1_sound_stream_1a52b455339cd95802ed2139bede6310c0>`() const;
		unsigned int :ref:`getSampleRate<doxid-class_e_e_1_1_audio_1_1_sound_stream_1ae192424d0176426a64f87c4309c9ce85>`() const;
		virtual :ref:`Status<doxid-class_e_e_1_1_audio_1_1_sound_source_1a09293754fddc60363b39e83a71874111>` :ref:`getStatus<doxid-class_e_e_1_1_audio_1_1_sound_stream_1ab7a1e64c1412f7d9890bdd7b6eb5eb8c>`() const;
		void :ref:`setPlayingOffset<doxid-class_e_e_1_1_audio_1_1_sound_stream_1a9464ebdf87f988589113dd87e9d84d57>`(:ref:`Time<doxid-class_e_e_1_1_system_1_1_time>` timeOffset);
		:ref:`Time<doxid-class_e_e_1_1_system_1_1_time>` :ref:`getPlayingOffset<doxid-class_e_e_1_1_audio_1_1_sound_stream_1a81ed2755ac9b5817198e7f4cd9f243f4>`() const;
		void :ref:`setLoop<doxid-class_e_e_1_1_audio_1_1_sound_stream_1a345ca77a95779e278bdac368794183bd>`(bool loop);
		bool :ref:`getLoop<doxid-class_e_e_1_1_audio_1_1_sound_stream_1abbf94ef1d80b63032e03121687526cc3>`() const;

.. _details-class_e_e_1_1_audio_1_1_music:

Detailed Documentation
~~~~~~~~~~~~~~~~~~~~~~

Streamed music played from an audio file.

Musics are sounds that are streamed rather than completely loaded in memory. This is especially useful for compressed musics that usually take hundreds of MB when they are uncompressed: by streaming it instead of loading it entirely, you avoid saturating the memory and have almost no loading delay. This implies that the underlying resource (file, stream or memory buffer) must remain valid for the lifetime of the :ref:`Music <doxid-class_e_e_1_1_audio_1_1_music>` object.

Apart from that, a :ref:`Music <doxid-class_e_e_1_1_audio_1_1_music>` has almost the same features as the :ref:`SoundBuffer <doxid-class_e_e_1_1_audio_1_1_sound_buffer>` / :ref:`Sound <doxid-class_e_e_1_1_audio_1_1_sound>` pair: you can play/pause/stop it, request its parameters (channels, sample rate), change the way it is played (pitch, volume, 3D position, ...), etc.

As a sound stream, a music is played in its own thread in order not to block the rest of the program. This means that you can leave the music alone after calling :ref:`play() <doxid-class_e_e_1_1_audio_1_1_sound_stream_1abfa1c43cb539039b31f8fe0688ba105b>`, it will manage itself very well.

Usage example:

.. ref-code-block:: cpp

	// Declare a new music
	Music music;
	
	// Open it from an audio file
	if (!music.openFromFile("music.ogg"))
	{
	 // error...
	}
	
	// Change some parameters
	music.setPosition(0, 1, 10); // change its 3D position
	music.setPitch(2);         // increase the pitch
	music.setVolume(50);         // reduce the volume
	music.setLoop(true);         // make it loop
	
	// Play it
	music.play();



.. rubric:: See also:

:ref:`Sound <doxid-class_e_e_1_1_audio_1_1_sound>`, :ref:`SoundStream <doxid-class_e_e_1_1_audio_1_1_sound_stream>`

Methods
-------

.. index:: pair: function; openFromFile
.. _doxid-class_e_e_1_1_audio_1_1_music_1afc2b3ce03c01ce0b53f8eaef4e7a1fe5:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	bool openFromFile(const std::string& filename)

Open a music from an audio file.

This function doesn't start playing the music (call :ref:`play() <doxid-class_e_e_1_1_audio_1_1_sound_stream_1abfa1c43cb539039b31f8fe0688ba105b>` to do so). See the documentation of :ref:`InputSoundFile <doxid-class_e_e_1_1_audio_1_1_input_sound_file>` for the list of supported formats.

.. warning::

	Since the music is not loaded at once but rather streamed continuously, the file must remain accessible until the :ref:`Music <doxid-class_e_e_1_1_audio_1_1_music>` object loads a new music or is destroyed.



.. rubric:: Parameters:

.. list-table::
	:widths: 20 80

	*
		- filename

		- Path of the music file to open



.. rubric:: Returns:

True if loading succeeded, false if it failed



.. rubric:: See also:

:ref:`openFromMemory <doxid-class_e_e_1_1_audio_1_1_music_1aef3a1e05f61b3797d95e94ba39531971>`, :ref:`openFromStream <doxid-class_e_e_1_1_audio_1_1_music_1a63ccf554d8e774d741eaf16f52261661>`

.. index:: pair: function; openFromMemory
.. _doxid-class_e_e_1_1_audio_1_1_music_1aef3a1e05f61b3797d95e94ba39531971:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	bool openFromMemory(const void* data, std::size_t sizeInBytes)

Open a music from an audio file in memory.

This function doesn't start playing the music (call :ref:`play() <doxid-class_e_e_1_1_audio_1_1_sound_stream_1abfa1c43cb539039b31f8fe0688ba105b>` to do so). See the documentation of :ref:`InputSoundFile <doxid-class_e_e_1_1_audio_1_1_input_sound_file>` for the list of supported formats.

.. warning::

	Since the music is not loaded at once but rather streamed continuously, the *data* buffer must remain accessible until the :ref:`Music <doxid-class_e_e_1_1_audio_1_1_music>` object loads a new music or is destroyed. That is, you can't deallocate the buffer right after calling this function.



.. rubric:: Parameters:

.. list-table::
	:widths: 20 80

	*
		- data

		- Pointer to the file data in memory

	*
		- sizeInBytes

		- Size of the data to load, in bytes



.. rubric:: Returns:

True if loading succeeded, false if it failed



.. rubric:: See also:

:ref:`openFromFile <doxid-class_e_e_1_1_audio_1_1_music_1afc2b3ce03c01ce0b53f8eaef4e7a1fe5>`, :ref:`openFromStream <doxid-class_e_e_1_1_audio_1_1_music_1a63ccf554d8e774d741eaf16f52261661>`

.. index:: pair: function; openFromStream
.. _doxid-class_e_e_1_1_audio_1_1_music_1a63ccf554d8e774d741eaf16f52261661:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	bool openFromStream(:ref:`IOStream<doxid-class_e_e_1_1_system_1_1_i_o_stream>`& stream)

Open a music from an audio file in a custom stream.

This function doesn't start playing the music (call :ref:`play() <doxid-class_e_e_1_1_audio_1_1_sound_stream_1abfa1c43cb539039b31f8fe0688ba105b>` to do so). See the documentation of :ref:`InputSoundFile <doxid-class_e_e_1_1_audio_1_1_input_sound_file>` for the list of supported formats.

.. warning::

	Since the music is not loaded at once but rather streamed continuously, the *stream* must remain accessible until the :ref:`Music <doxid-class_e_e_1_1_audio_1_1_music>` object loads a new music or is destroyed.



.. rubric:: Parameters:

.. list-table::
	:widths: 20 80

	*
		- stream

		- Source stream to read from



.. rubric:: Returns:

True if loading succeeded, false if it failed



.. rubric:: See also:

:ref:`openFromFile <doxid-class_e_e_1_1_audio_1_1_music_1afc2b3ce03c01ce0b53f8eaef4e7a1fe5>`, :ref:`openFromMemory <doxid-class_e_e_1_1_audio_1_1_music_1aef3a1e05f61b3797d95e94ba39531971>`

.. index:: pair: function; getDuration
.. _doxid-class_e_e_1_1_audio_1_1_music_1aafcf87ca769b1b9a428c1c483ceef294:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	:ref:`Time<doxid-class_e_e_1_1_system_1_1_time>` getDuration() const

Get the total duration of the music.



.. rubric:: Returns:

:ref:`Music <doxid-class_e_e_1_1_audio_1_1_music>` duration

.. index:: pair: function; getLoopPoints
.. _doxid-class_e_e_1_1_audio_1_1_music_1a3ef75fc666b6d410d9360610d157de25:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	:ref:`TimeSpan<doxid-class_e_e_1_1_audio_1_1_music_1ac3b58efcdc43c2c89c35eb2379d365b5>` getLoopPoints() const

Get the positions of the of the sound's looping sequence.

.. warning::

	Since :ref:`setLoopPoints() <doxid-class_e_e_1_1_audio_1_1_music_1ab6204b4dcccb3a161d2ffd7c4d9e4d02>` performs some adjustments on the provided values and rounds them to internal samples, a call to :ref:`getLoopPoints() <doxid-class_e_e_1_1_audio_1_1_music_1a3ef75fc666b6d410d9360610d157de25>` is not guaranteed to return the same times passed into a previous call to :ref:`setLoopPoints() <doxid-class_e_e_1_1_audio_1_1_music_1ab6204b4dcccb3a161d2ffd7c4d9e4d02>`. However, it is guaranteed to return times that will map to the valid internal samples of this :ref:`Music <doxid-class_e_e_1_1_audio_1_1_music>` if they are later passed to :ref:`setLoopPoints() <doxid-class_e_e_1_1_audio_1_1_music_1ab6204b4dcccb3a161d2ffd7c4d9e4d02>`.



.. rubric:: Returns:

Loop Time position class.



.. rubric:: See also:

:ref:`setLoopPoints <doxid-class_e_e_1_1_audio_1_1_music_1ab6204b4dcccb3a161d2ffd7c4d9e4d02>`

.. index:: pair: function; setLoopPoints
.. _doxid-class_e_e_1_1_audio_1_1_music_1ab6204b4dcccb3a161d2ffd7c4d9e4d02:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	void setLoopPoints(:ref:`TimeSpan<doxid-class_e_e_1_1_audio_1_1_music_1ac3b58efcdc43c2c89c35eb2379d365b5>` timePoints)

Sets the beginning and end of the sound's looping sequence using Time.

Loop points allow one to specify a pair of positions such that, when the music is enabled for looping, it will seamlessly seek to the beginning whenever it encounters the end. Valid ranges for timePoints.offset and timePoints.length are [0, Dur) and (0, Dur-offset] respectively, where Dur is the value returned by :ref:`getDuration() <doxid-class_e_e_1_1_audio_1_1_music_1aafcf87ca769b1b9a428c1c483ceef294>`. Note that the EOF "loop point" from the end to the beginning of the stream is still honored, in case the caller seeks to a point after the end of the loop range. This function can be safely called at any point after a stream is opened, and will be applied to a playing sound without affecting the current playing offset.

.. warning::

	Setting the loop points while the stream's status is Paused will set its status to Stopped. The playing offset will be unaffected.



.. rubric:: Parameters:

.. list-table::
	:widths: 20 80

	*
		- timePoints

		- The definition of the loop. Can be any time points within the sound's length



.. rubric:: See also:

:ref:`getLoopPoints <doxid-class_e_e_1_1_audio_1_1_music_1a3ef75fc666b6d410d9360610d157de25>`