.. index:: pair: class; EE::Audio::InputSoundFile .. _doxid-class_e_e_1_1_audio_1_1_input_sound_file: class EE::Audio::InputSoundFile =============================== .. toctree:: :hidden: Overview ~~~~~~~~ Provide read access to sound files. :ref:`More...` .. ref-code-block:: cpp :class: doxyrest-overview-code-block #include class InputSoundFile: private :ref:`EE::NonCopyable` { public: // construction :target:`~InputSoundFile`(); // methods bool :ref:`openFromFile`(const std::string& filename); bool :ref:`openFromMemory`(const void* data, std::size_t sizeInBytes); bool :ref:`openFromStream`(:ref:`IOStream`& stream); :ref:`Uint64` :ref:`getSampleCount`() const; unsigned int :ref:`getChannelCount`() const; unsigned int :ref:`getSampleRate`() const; :ref:`Time` :ref:`getDuration`() const; :ref:`Time` :ref:`getTimeOffset`() const; :ref:`Uint64` :ref:`getSampleOffset`() const; void :ref:`seek`(:ref:`Uint64` sampleOffset); void :ref:`seek`(:ref:`Time` timeOffset); :ref:`Uint64` :ref:`read`(:ref:`Int16`* samples, :ref:`Uint64` maxCount); }; .. _details-class_e_e_1_1_audio_1_1_input_sound_file: Detailed Documentation ~~~~~~~~~~~~~~~~~~~~~~ Provide read access to sound files. This class decodes audio samples from a sound file. It is used internally by higher-level classes such as :ref:`SoundBuffer ` and :ref:`Music `, but can also be useful if you want to process or analyze audio files without playing them, or if you want to implement your own version of :ref:`Music ` with more specific features. Usage example: .. ref-code-block:: cpp // Open a sound file InputSoundFile file; if (!file.openFromFile("music.ogg")) /* error */; // Print the sound attributes std::cout << "duration: " << file.getDuration().asSeconds() << std::endl; std::cout << "channels: " << file.getChannelCount() << std::endl; std::cout << "sample rate: " << file.getSampleRate() << std::endl; std::cout << "sample count: " << file.getSampleCount() << std::endl; // Read and process batches of samples until the end of file is reached Int16 samples[1024]; Uint64 count; do { count = file.read(samples, 1024); // process, analyze, play, convert, or whatever // you want to do with the samples... } while (count > 0); .. rubric:: See also: :ref:`SoundFileReader `, :ref:`OutputSoundFile ` Methods ------- .. index:: pair: function; openFromFile .. _doxid-class_e_e_1_1_audio_1_1_input_sound_file_1a7f0d17d81f83fa682902d1f85184a505: .. ref-code-block:: cpp :class: doxyrest-title-code-block bool openFromFile(const std::string& filename) Open a sound file from the disk for reading. The supported audio formats are: WAV (PCM only), OGG/Vorbis, FLAC. The supported sample sizes for FLAC and WAV are 8, 16, 24 and 32 bit. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - filename - Path of the sound file to load .. rubric:: Returns: True if the file was successfully opened .. index:: pair: function; openFromMemory .. _doxid-class_e_e_1_1_audio_1_1_input_sound_file_1a2202844335c4644092167add6a6402a5: .. ref-code-block:: cpp :class: doxyrest-title-code-block bool openFromMemory(const void* data, std::size_t sizeInBytes) Open a sound file in memory for reading. The supported audio formats are: WAV (PCM only), OGG/Vorbis, FLAC. The supported sample sizes for FLAC and WAV are 8, 16, 24 and 32 bit. .. 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 the file was successfully opened .. index:: pair: function; openFromStream .. _doxid-class_e_e_1_1_audio_1_1_input_sound_file_1abfec2c06add427d3600eb3b7b68c6162: .. ref-code-block:: cpp :class: doxyrest-title-code-block bool openFromStream(:ref:`IOStream`& stream) Open a sound file from a custom stream for reading. The supported audio formats are: WAV (PCM only), OGG/Vorbis, FLAC. The supported sample sizes for FLAC and WAV are 8, 16, 24 and 32 bit. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - stream - Source stream to read from .. rubric:: Returns: True if the file was successfully opened .. index:: pair: function; getSampleCount .. _doxid-class_e_e_1_1_audio_1_1_input_sound_file_1a699246406da22be57b472d3786f52710: .. ref-code-block:: cpp :class: doxyrest-title-code-block :ref:`Uint64` getSampleCount() const Get the total number of audio samples in the file. .. rubric:: Returns: Number of samples .. index:: pair: function; getChannelCount .. _doxid-class_e_e_1_1_audio_1_1_input_sound_file_1ab1932c455a617aaa9d6335e84e0f6e27: .. ref-code-block:: cpp :class: doxyrest-title-code-block unsigned int getChannelCount() const Get the number of channels used by the sound. .. rubric:: Returns: Number of channels (1 = mono, 2 = stereo) .. index:: pair: function; getSampleRate .. _doxid-class_e_e_1_1_audio_1_1_input_sound_file_1a775dd4470f87128729c7a0b40d67d50c: .. ref-code-block:: cpp :class: doxyrest-title-code-block unsigned int getSampleRate() const Get the sample rate of the sound. .. rubric:: Returns: Sample rate, in samples per second .. index:: pair: function; getDuration .. _doxid-class_e_e_1_1_audio_1_1_input_sound_file_1a3c97439920eb7707bf5f36b123ad92cd: .. ref-code-block:: cpp :class: doxyrest-title-code-block :ref:`Time` getDuration() const Get the total duration of the sound file. This function is provided for convenience, the duration is deduced from the other sound file attributes. .. rubric:: Returns: Duration of the sound file .. index:: pair: function; getTimeOffset .. _doxid-class_e_e_1_1_audio_1_1_input_sound_file_1ab60b33943ba4a3d5c0e8e6569707868c: .. ref-code-block:: cpp :class: doxyrest-title-code-block :ref:`Time` getTimeOffset() const Get the read offset of the file in time. .. rubric:: Returns: Time position .. index:: pair: function; getSampleOffset .. _doxid-class_e_e_1_1_audio_1_1_input_sound_file_1aed727c0fd9a16ae953aa56237b5cd026: .. ref-code-block:: cpp :class: doxyrest-title-code-block :ref:`Uint64` getSampleOffset() const Get the read offset of the file in samples. .. rubric:: Returns: Sample position .. index:: pair: function; seek .. _doxid-class_e_e_1_1_audio_1_1_input_sound_file_1aeb858f4f73a00a1e5828208e66102959: .. ref-code-block:: cpp :class: doxyrest-title-code-block void seek(:ref:`Uint64` sampleOffset) Change the current read position to the given sample offset. This function takes a sample offset to provide maximum precision. If you need to jump to a given time, use the other overload. 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 jumps to the end of the sound file. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - sampleOffset - Index of the sample to jump to, relative to the beginning .. index:: pair: function; seek .. _doxid-class_e_e_1_1_audio_1_1_input_sound_file_1a7468f8ad03a971a6bea864477a1e8a61: .. ref-code-block:: cpp :class: doxyrest-title-code-block void seek(:ref:`Time` timeOffset) Change the current read position to the given time offset. Using a time offset is handy but imprecise. If you need an accurate result, consider using the overload which takes a sample offset. If the given time exceeds to total duration, this function jumps to the end of the sound file. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - timeOffset - Time to jump to, relative to the beginning .. index:: pair: function; read .. _doxid-class_e_e_1_1_audio_1_1_input_sound_file_1a49f69208019dffa5693924197b1827a2: .. ref-code-block:: cpp :class: doxyrest-title-code-block :ref:`Uint64` read(:ref:`Int16`* samples, :ref:`Uint64` maxCount) 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*)