.. index:: pair: class; EE::Audio::SoundStream
.. _doxid-class_e_e_1_1_audio_1_1_sound_stream:

class EE::Audio::SoundStream
============================

.. toctree::
	:hidden:

	struct_EE_Audio_SoundStream_Chunk.rst

Overview
~~~~~~~~

Abstract base class for streamed audio sources. :ref:`More...<details-class_e_e_1_1_audio_1_1_sound_stream>`


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

	#include <soundstream.hpp>
	
	class SoundStream: public :ref:`EE::Audio::SoundSource<doxid-class_e_e_1_1_audio_1_1_sound_source>` {
	public:
		// structs
	
		struct :ref:`Chunk<doxid-struct_e_e_1_1_audio_1_1_sound_stream_1_1_chunk>`;

		// construction
	
		virtual :target:`~SoundStream<doxid-class_e_e_1_1_audio_1_1_sound_stream_1afaa6ee544d99d009ea077dbf4e8abd65>`();

		// methods
	
		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;
	};

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>`;

		// 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;

.. _details-class_e_e_1_1_audio_1_1_sound_stream:

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

Abstract base class for streamed audio sources.

Unlike audio buffers (see :ref:`SoundBuffer <doxid-class_e_e_1_1_audio_1_1_sound_buffer>`), audio streams are never completely loaded in memory. Instead, the audio data is acquired continuously while the stream is playing. This behavior allows to play a sound with no loading delay, and keeps the memory consumption very low.

:ref:`Sound <doxid-class_e_e_1_1_audio_1_1_sound>` sources that need to be streamed are usually big files (compressed audio musics that would eat hundreds of MB in memory) or files that would take a lot of time to be received (sounds played over the network).

:ref:`SoundStream <doxid-class_e_e_1_1_audio_1_1_sound_stream>` is a base class that doesn't care about the stream source, which is left to the derived class. EEPP provides a built-in specialization for big files (see :ref:`Music <doxid-class_e_e_1_1_audio_1_1_music>`). No network stream source is provided, but you can write your own by combining this class with the network module.

A derived class has to override two virtual functions:

* onGetData fills a new chunk of audio data to be played

* onSeek changes the current playing position in the source

It is important to note that each :ref:`SoundStream <doxid-class_e_e_1_1_audio_1_1_sound_stream>` is played in its own separate thread, so that the streaming loop doesn't block the rest of the program. In particular, the OnGetData and OnSeek virtual functions may sometimes be called from this separate thread. It is important to keep this in mind, because you may have to take care of synchronization issues if you share data between threads.

Usage example:

.. ref-code-block:: cpp

	class CustomStream : public SoundStream
	{
	public:
	
	 bool open(const std::string& location)
	 {
	     // Open the source and get audio settings
	     ...
	     unsigned int channelCount = ...;
	     unsigned int sampleRate = ...;
	
	     // Initialize the stream -- important!
	     initialize(channelCount, sampleRate);
	 }
	
	private:
	
	 virtual bool onGetData(Chunk& data)
	 {
	     // Fill the chunk with audio data from the stream source
	     // (note: must not be empty if you want to continue playing)
	     data.samples = ...;
	     data.sampleCount = ...;
	
	     // Return true to continue playing
	     return true;
	 }
	
	 virtual void onSeek(Uint32 timeOffset)
	 {
	     // Change the current position in the stream source
	     ...
	 }
	}
	
	// Usage
	CustomStream stream;
	stream.open("path/to/stream");
	stream.play();



.. rubric:: See also:

:ref:`Music <doxid-class_e_e_1_1_audio_1_1_music>`

Methods
-------

.. index:: pair: function; play
.. _doxid-class_e_e_1_1_audio_1_1_sound_stream_1abfa1c43cb539039b31f8fe0688ba105b:

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

	virtual void play()

Start or resume playing the audio stream.

This function starts the stream 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 stream is played.



.. rubric:: See also:

:ref:`pause <doxid-class_e_e_1_1_audio_1_1_sound_stream_1ae6e93e1bcd44c0145eb744d7a40682bd>`, :ref:`stop <doxid-class_e_e_1_1_audio_1_1_sound_stream_1a10bcb9b8a5091d3aa8fb4b0574159d19>`

.. index:: pair: function; pause
.. _doxid-class_e_e_1_1_audio_1_1_sound_stream_1ae6e93e1bcd44c0145eb744d7a40682bd:

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

	virtual void pause()

Pause the audio stream.

This function pauses the stream if it was playing, otherwise (stream already paused or stopped) it has no effect.



.. rubric:: See also:

:ref:`play <doxid-class_e_e_1_1_audio_1_1_sound_stream_1abfa1c43cb539039b31f8fe0688ba105b>`, :ref:`stop <doxid-class_e_e_1_1_audio_1_1_sound_stream_1a10bcb9b8a5091d3aa8fb4b0574159d19>`

.. index:: pair: function; stop
.. _doxid-class_e_e_1_1_audio_1_1_sound_stream_1a10bcb9b8a5091d3aa8fb4b0574159d19:

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

	virtual void stop()

Stop playing the audio stream.

This function stops the stream if it was playing or paused, and does nothing if it was already stopped. It also resets the playing position (unlike :ref:`pause() <doxid-class_e_e_1_1_audio_1_1_sound_stream_1ae6e93e1bcd44c0145eb744d7a40682bd>`).



.. rubric:: See also:

:ref:`play <doxid-class_e_e_1_1_audio_1_1_sound_stream_1abfa1c43cb539039b31f8fe0688ba105b>`, :ref:`pause <doxid-class_e_e_1_1_audio_1_1_sound_stream_1ae6e93e1bcd44c0145eb744d7a40682bd>`

.. index:: pair: function; getChannelCount
.. _doxid-class_e_e_1_1_audio_1_1_sound_stream_1a52b455339cd95802ed2139bede6310c0:

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

	unsigned int getChannelCount() const

Return the number of channels of the stream.

1 channel means a mono sound, 2 means stereo, etc.



.. rubric:: Returns:

Number of channels

.. index:: pair: function; getSampleRate
.. _doxid-class_e_e_1_1_audio_1_1_sound_stream_1ae192424d0176426a64f87c4309c9ce85:

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

	unsigned int getSampleRate() const

Get the stream sample rate of the stream.

The sample rate is the number of audio samples played per second. The higher, the better the quality.



.. rubric:: Returns:

Sample rate, in number of samples per second

.. index:: pair: function; getStatus
.. _doxid-class_e_e_1_1_audio_1_1_sound_stream_1ab7a1e64c1412f7d9890bdd7b6eb5eb8c:

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

	virtual :ref:`Status<doxid-class_e_e_1_1_audio_1_1_sound_source_1a09293754fddc60363b39e83a71874111>` getStatus() const

Get the current status of the stream (stopped, paused, playing)



.. rubric:: Returns:

Current status

.. index:: pair: function; setPlayingOffset
.. _doxid-class_e_e_1_1_audio_1_1_sound_stream_1a9464ebdf87f988589113dd87e9d84d57:

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

	void setPlayingOffset(:ref:`Time<doxid-class_e_e_1_1_system_1_1_time>` timeOffset)

Change the current playing position of the stream.

The playing position can be changed when the stream is either paused or playing. Changing the playing position when the stream is stopped has no effect, since playing the stream would reset its position.



.. rubric:: Parameters:

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

	*
		- timeOffset

		- New playing position, from the beginning of the stream



.. rubric:: See also:

:ref:`getPlayingOffset <doxid-class_e_e_1_1_audio_1_1_sound_stream_1a81ed2755ac9b5817198e7f4cd9f243f4>`

.. index:: pair: function; getPlayingOffset
.. _doxid-class_e_e_1_1_audio_1_1_sound_stream_1a81ed2755ac9b5817198e7f4cd9f243f4:

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

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

Get the current playing position of the stream.



.. rubric:: Returns:

Current playing position, from the beginning of the stream



.. rubric:: See also:

:ref:`setPlayingOffset <doxid-class_e_e_1_1_audio_1_1_sound_stream_1a9464ebdf87f988589113dd87e9d84d57>`

.. index:: pair: function; setLoop
.. _doxid-class_e_e_1_1_audio_1_1_sound_stream_1a345ca77a95779e278bdac368794183bd:

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

	void setLoop(bool loop)

Set whether or not the stream should loop after reaching the end.

If set, the stream will restart from beginning after reaching the end and so on, until it is stopped or setLoop(false) is called. The default looping state for streams is false.



.. rubric:: Parameters:

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

	*
		- loop

		- True to play in loop, false to play once



.. rubric:: See also:

:ref:`getLoop <doxid-class_e_e_1_1_audio_1_1_sound_stream_1abbf94ef1d80b63032e03121687526cc3>`

.. index:: pair: function; getLoop
.. _doxid-class_e_e_1_1_audio_1_1_sound_stream_1abbf94ef1d80b63032e03121687526cc3:

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

	bool getLoop() const

Tell whether or not the stream is in loop mode.



.. rubric:: Returns:

True if the stream is looping, false otherwise



.. rubric:: See also:

:ref:`setLoop <doxid-class_e_e_1_1_audio_1_1_sound_stream_1a345ca77a95779e278bdac368794183bd>`