MayaFlux::IO::SoundFileWriter Class Reference

Asynchronous audio file encoder with a lock-free work queue. More...

#include <SoundFileWriter.hpp>

Collaboration diagram for MayaFlux::IO::SoundFileWriter:

Classes
struct	CloseCmd
struct	FrameChunk
struct	PlanarChunk

Public Member Functions
std::future< bool >	close ()
	Post a close command to the worker.
bool	is_open () const
	True if the worker is running and the encoder is healthy.
std::string	last_error () const
bool	open (const std::string &filepath, uint32_t channels, uint32_t sample_rate, AVCodecID explicit_codec)
	Open the output file and spawn the worker thread.
SoundFileWriter &	operator= (const SoundFileWriter &)=delete
SoundFileWriter &	operator= (SoundFileWriter &&)=delete
	SoundFileWriter ()
	SoundFileWriter (const SoundFileWriter &)=delete
	SoundFileWriter (SoundFileWriter &&)=delete
void	write (const std::shared_ptr< Buffers::AudioBuffer > &buffer)
	Post one AudioBuffer's mono sample data to the work queue.
void	write (const std::shared_ptr< Kakshya::SoundStreamContainer > &container)
	Post a SoundStreamContainer's planar channel data to the work queue.
void	write (const std::vector< Kakshya::DataVariant > &planar)
	Post planar per-channel data to the work queue.
void	write (std::span< const double > interleaved, uint32_t num_frames=0)
	Post interleaved double-precision frames to the work queue.
	~SoundFileWriter ()

Private Types
using	WorkItem = std::variant< FrameChunk, PlanarChunk, CloseCmd >

Private Member Functions
bool	post (const WorkItem &item)
void	set_error (std::string msg)
void	worker_loop (const std::string &filepath, uint32_t channels, uint32_t sample_rate, AVCodecID codec_id)

Private Attributes
uint32_t	m_channels {}
std::shared_future< bool >	m_close_future
std::promise< bool >	m_close_promise
std::atomic< bool >	m_closing { false }
std::mutex	m_error_mutex
std::string	m_last_error
std::atomic< bool >	m_open { false }
std::unique_ptr< Memory::LockFreeQueue< WorkItem, k_queue_capacity > >	m_queue
std::thread	m_worker

Static Private Attributes
static constexpr size_t	k_queue_capacity = 4096

Detailed Description

Asynchronous audio file encoder with a lock-free work queue.

Accepts audio from multiple source types and encodes it to a file on a dedicated worker thread. The public API is fully non-blocking: every write call posts a work item to an SPSC queue and returns immediately. The worker thread owns all FFmpeg state and is the only thread that touches it.

Supported input paths:

• Raw interleaved double frames (span or vector, for RT/coroutine callers)
• AudioBuffer — drains get_data() as interleaved doubles
• SoundStreamContainer — drains get_data_as_double() (interleaved span)

Threading model: Caller thread → push work items to m_queue (lock-free) Worker thread → drain queue, encode via AudioEncodeContext + FFmpegMuxContext

Lifetime: open() spawns the worker. close() posts a CloseCmd and returns a future<bool> the caller may wait on. The destructor issues close() if still open and joins with a 5-second timeout; on timeout it detaches and logs CRITICAL.

Error handling: Encode errors set last_error() and cause the worker to post false to the close promise. Subsequent write calls after an encode error are silently dropped (is_open() returns false).

Definition at line 51 of file SoundFileWriter.hpp.

---

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

• SoundFileWriter.hpp
• SoundFileWriter.cpp