.. index:: pair: class; EE::Audio::SoundFileReader
.. _doxid-class_e_e_1_1_audio_1_1_sound_file_reader:

class EE::Audio::SoundFileReader
================================

.. toctree::
	:hidden:

	struct_EE_Audio_SoundFileReader_Info.rst

Overview
~~~~~~~~

Abstract base class for sound file decoding. :ref:`More...<details-class_e_e_1_1_audio_1_1_sound_file_reader>`


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

	#include <soundfilereader.hpp>
	
	class SoundFileReader {
	public:
		// structs
	
		struct :ref:`Info<doxid-struct_e_e_1_1_audio_1_1_sound_file_reader_1_1_info>`;

		// construction
	
		virtual :target:`~SoundFileReader<doxid-class_e_e_1_1_audio_1_1_sound_file_reader_1a47ee0b2a4a0a78ac40cfa75d92c74cd1>`();

		// methods
	
		virtual bool :ref:`open<doxid-class_e_e_1_1_audio_1_1_sound_file_reader_1a114e8f0e35127f91c6707bb98b95a544>`(:ref:`IOStream<doxid-class_e_e_1_1_system_1_1_i_o_stream>`& stream, :ref:`Info<doxid-struct_e_e_1_1_audio_1_1_sound_file_reader_1_1_info>`& info) = 0;
		virtual void :ref:`seek<doxid-class_e_e_1_1_audio_1_1_sound_file_reader_1a1c037b661652e33e3fc0d65503c1ef99>`(:ref:`Uint64<doxid-namespace_e_e_1ae05f59b032c290566852fe63cb26135c>` sampleOffset) = 0;
		virtual :ref:`Uint64<doxid-namespace_e_e_1ae05f59b032c290566852fe63cb26135c>` :ref:`read<doxid-class_e_e_1_1_audio_1_1_sound_file_reader_1aefb59a08ec3d7713c81accd1e4f4e339>`(:ref:`Int16<doxid-namespace_e_e_1a73642650c4b4c754551791873b930462>`* samples, :ref:`Uint64<doxid-namespace_e_e_1ae05f59b032c290566852fe63cb26135c>` maxCount) = 0;
	};
.. _details-class_e_e_1_1_audio_1_1_sound_file_reader:

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

Abstract base class for sound file decoding.

This class allows users to read audio file formats not natively supported by EEPP, and thus extend the set of supported readable audio formats.

A valid sound file reader must override the open, seek and write functions, as well as providing a static check function; the latter is used by EEPP to find a suitable writer for a given input file.

To register a new reader, use the :ref:`SoundFileFactory::registerReader <doxid-class_e_e_1_1_audio_1_1_sound_file_factory_1ab86077f1a0fcc023cb8f29b310c9dd75>` template function.

Usage example:

.. ref-code-block:: cpp

	class MySoundFileReader : public SoundFileReader
	{
	public:
	
	 static bool check(IOStream& stream)
	 {
	     // typically, read the first few header bytes and check fields that identify the format
	     // return true if the reader can handle the format
	 }
	
	 virtual bool open(IOStream& stream, Info& info)
	 {
	     // read the sound file header and fill the sound attributes
	     // (channel count, sample count and sample rate)
	     // return true on success
	 }
	
	 virtual void seek(Uint64 sampleOffset)
	 {
	     // advance to the sampleOffset-th sample from the beginning of the sound
	 }
	
	 virtual Uint64 read(Int16* samples, Uint64 maxCount)
	 {
	     // read up to 'maxCount' samples into the 'samples' array,
	     // convert them (for example from normalized float) if they are not stored
	     // as 16-bits signed integers in the file
	     // return the actual number of samples read
	 }
	};
	
	SoundFileFactory::registerReader<MySoundFileReader>();



.. rubric:: See also:

:ref:`InputSoundFile <doxid-class_e_e_1_1_audio_1_1_input_sound_file>`, :ref:`SoundFileFactory <doxid-class_e_e_1_1_audio_1_1_sound_file_factory>`, :ref:`SoundFileWriter <doxid-class_e_e_1_1_audio_1_1_sound_file_writer>`

Methods
-------

.. index:: pair: function; open
.. _doxid-class_e_e_1_1_audio_1_1_sound_file_reader_1a114e8f0e35127f91c6707bb98b95a544:

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

	virtual bool open(:ref:`IOStream<doxid-class_e_e_1_1_system_1_1_i_o_stream>`& stream, :ref:`Info<doxid-struct_e_e_1_1_audio_1_1_sound_file_reader_1_1_info>`& info) = 0

Open a sound file for reading.

The provided stream reference is valid as long as the :ref:`SoundFileReader <doxid-class_e_e_1_1_audio_1_1_sound_file_reader>` is alive, so it is safe to use/store it during the whole lifetime of the reader.



.. rubric:: Parameters:

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

	*
		- stream

		- Source stream to read from

	*
		- info

		- Structure to fill with the properties of the loaded sound



.. rubric:: Returns:

True if the file was successfully opened

.. index:: pair: function; seek
.. _doxid-class_e_e_1_1_audio_1_1_sound_file_reader_1a1c037b661652e33e3fc0d65503c1ef99:

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

	virtual void seek(:ref:`Uint64<doxid-namespace_e_e_1ae05f59b032c290566852fe63cb26135c>` sampleOffset) = 0

Change the current read position to the given sample offset.

The sample offset takes the channels into account. If you have a time offset instead, you can easily find the corresponding sample offset with the following formula: ``timeInSeconds * sampleRate * channelCount`` If the given offset exceeds to total number of samples, this function must jump to the end of the file.



.. rubric:: Parameters:

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

	*
		- sampleOffset

		- Index of the sample to jump to, relative to the beginning

.. index:: pair: function; read
.. _doxid-class_e_e_1_1_audio_1_1_sound_file_reader_1aefb59a08ec3d7713c81accd1e4f4e339:

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

	virtual :ref:`Uint64<doxid-namespace_e_e_1ae05f59b032c290566852fe63cb26135c>` read(:ref:`Int16<doxid-namespace_e_e_1a73642650c4b4c754551791873b930462>`* samples, :ref:`Uint64<doxid-namespace_e_e_1ae05f59b032c290566852fe63cb26135c>` maxCount) = 0

Read audio samples from the open file.



.. rubric:: Parameters:

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

	*
		- samples

		- Pointer to the sample array to fill

	*
		- maxCount

		- Maximum number of samples to read



.. rubric:: Returns:

Number of samples actually read (may be less than *maxCount*)