MayaFlux::IO::SoundFileReader Class Reference

FFmpeg-based audio file reader for MayaFlux. More...

#include <SoundFileReader.hpp>

Inheritance diagram for MayaFlux::IO::SoundFileReader:

Collaboration diagram for MayaFlux::IO::SoundFileReader:

Public Member Functions
	SoundFileReader ()
	Construct a new SoundFileReader object.
	~SoundFileReader () override
	Destroy the SoundFileReader object.
bool	can_read (const std::string &filepath) const override
	Check if this reader can open the given file.
bool	open (const std::string &filepath, FileReadOptions options=FileReadOptions::ALL) override
	Open an audio file for reading.
void	close () override
	Close the currently open file and release resources.
bool	is_open () const override
	Check if a file is currently open.
std::optional< FileMetadata >	get_metadata () const override
	Get metadata for the currently open file.
std::vector< FileRegion >	get_regions () const override
	Get all regions (markers, loops, etc.) from the file.
std::vector< Kakshya::DataVariant >	read_all () override
	Read the entire audio file into memory.
std::vector< Kakshya::DataVariant >	read_region (const FileRegion &region) override
	Read a specific region from the file.
std::shared_ptr< Kakshya::SignalSourceContainer >	create_container () override
	Create a SignalSourceContainer for this file.
bool	load_into_container (std::shared_ptr< Kakshya::SignalSourceContainer > container) override
	Load file data into an existing SignalSourceContainer.
std::vector< uint64_t >	get_read_position () const override
	Get the current read position in the file.
bool	seek (const std::vector< uint64_t > &position) override
	Seek to a specific position in the file.
std::vector< std::string >	get_supported_extensions () const override
	Get supported file extensions for this reader.
std::type_index	get_data_type () const override
	Get the C++ type of the data returned by this reader.
std::type_index	get_container_type () const override
	Get the C++ type of the container returned by this reader.
std::string	get_last_error () const override
	Get the last error message encountered by the reader.
bool	supports_streaming () const override
	Check if the reader supports streaming access.
uint64_t	get_preferred_chunk_size () const override
	Get the preferred chunk size for streaming reads.
size_t	get_num_dimensions () const override
	Get the number of dimensions in the audio data (typically 2: time, channel).
std::vector< uint64_t >	get_dimension_sizes () const override
	Get the size of each dimension (e.g., frames, channels).
std::vector< Kakshya::DataVariant >	read_frames (uint64_t num_frames, uint64_t offset=0)
	Read a specific number of frames from the file.
void	set_audio_options (AudioReadOptions options)
	Set audio-specific read options.
void	set_target_sample_rate (uint32_t sample_rate)
	Set the target sample rate for resampling.
void	set_target_bit_depth (uint32_t bit_depth)
	Set the target bit depth (ignored, always outputs double).
Public Member Functions inherited from MayaFlux::IO::FileReader
virtual	~FileReader ()=default

Static Public Member Functions
static void	initialize_ffmpeg ()
	Initialize FFmpeg libraries (thread-safe, called automatically).

Private Member Functions
bool	setup_resampler (const std::shared_ptr< FFmpegContext > &ctx)
	Set up the FFmpeg resampler if needed.
void	extract_metadata (const std::shared_ptr< FFmpegContext > &ctx)
	Extract metadata from the file.
void	extract_regions (const std::shared_ptr< FFmpegContext > &ctx)
	Extract region information from the file.
std::vector< Kakshya::DataVariant >	decode_frames (std::shared_ptr< FFmpegContext > ctx, uint64_t num_frames, uint64_t offset)
	Decode a specific number of frames from the file.
bool	seek_internal (std::shared_ptr< FFmpegContext > &ctx, uint64_t frame_position)
	Internal seek implementation.
std::vector< std::vector< double > >	deinterleave_data (const std::vector< double > &interleaved, uint32_t channels)
	Convert interleaved audio data to deinterleaved (planar) format.
void	set_error (const std::string &error) const
	Set the last error message.
void	clear_error () const
	Clear the last error message.

Private Attributes
std::shared_ptr< FFmpegContext >	m_context
std::shared_mutex	m_context_mutex
std::string	m_filepath
	Path to the currently open file.
FileReadOptions	m_options
	File read options used for this session.
AudioReadOptions	m_audio_options = AudioReadOptions::NONE
	Audio-specific read options.
std::string	m_last_error
	Last error message encountered.
std::optional< FileMetadata >	m_cached_metadata
	Cached file metadata.
std::vector< FileRegion >	m_cached_regions
	Cached file regions (markers, loops, etc.).
std::atomic< uint64_t >	m_current_frame_position { 0 }
	Current frame position for reading.
uint32_t	m_target_sample_rate = 0
	Target sample rate for resampling (0 = use source rate).
uint32_t	m_target_bit_depth = 0
	Target bit depth (ignored, always outputs double).
std::mutex	m_metadata_mutex
	Mutex for thread-safe metadata access.

Static Private Attributes
static std::atomic< bool >	s_ffmpeg_initialized { false }
	True if FFmpeg has been initialized.
static std::mutex	s_ffmpeg_init_mutex
	Mutex for FFmpeg initialization.

Additional Inherited Members
Static Protected Member Functions inherited from MayaFlux::IO::FileReader
static std::unordered_map< std::string, Kakshya::RegionGroup >	regions_to_groups (const std::vector< FileRegion > &regions)
	Convert file regions to region groups.

Detailed Description

FFmpeg-based audio file reader for MayaFlux.

SoundFileReader provides a high-level interface for reading and decoding audio files using FFmpeg. It supports a wide range of audio formats, automatic sample format conversion to double precision, resampling, metadata extraction, region/marker extraction, and streaming/seekable access.

Key Features:

• Format detection and demuxing via libavformat
• Audio decoding via libavcodec
• Sample format conversion and resampling via libswresample (always outputs double)
• Metadata and region extraction from FFmpeg's parsed structures
• Seeking and timestamp handling via FFmpeg's APIs
• Automatic creation and population of Kakshya::SoundFileContainer for downstream processing
• Thread-safe access for reading and metadata queries

Usage: SoundFileReader reader; if (reader.open("file.wav")) { auto metadata = reader.get_metadata(); auto all_data = reader.read_all(); auto container = reader.create_container(); // ... reader.close(); }

All audio data is converted to double precision for internal processing. The reader can output data in either interleaved or deinterleaved (planar) layout.

Definition at line 99 of file SoundFileReader.hpp.

---

The documentation for this class was generated from the following files:

• SoundFileReader.hpp
• SoundFileReader.cpp