Loading...
Searching...
No Matches
MayaFlux::Kakshya::DynamicSoundStream Class Reference
Dynamic capacity streaming audio container with automatic resizing and circular buffering. More...
#include <DynamicSoundStream.hpp>
Inheritance diagram for MayaFlux::Kakshya::DynamicSoundStream:
Collaboration diagram for MayaFlux::Kakshya::DynamicSoundStream:
Public Member Functions | |
| DynamicSoundStream (uint32_t sample_rate=48000, uint32_t num_channels=2) | |
| Construct a DynamicSoundStream with specified audio parameters. | |
| uint64_t | write_frames (std::span< const double > data, uint64_t start_frame=0, uint32_t channel=0) |
| Write audio frame data to the container with automatic capacity management. | |
| uint64_t | write_frames (std::vector< std::span< const double > > data, uint64_t start_frame=0) |
| uint64_t | read_frames (std::span< double > output, uint64_t count) |
| Read audio frames using sequential reading with automatic position management. | |
| void | set_auto_resize (bool enable) |
| Enable or disable automatic capacity expansion during write operations. | |
| bool | get_auto_resize () const |
| Check if automatic capacity expansion is currently enabled. | |
| void | ensure_capacity (uint64_t required_frames) |
| Pre-allocate capacity for the specified number of frames. | |
| void | enable_circular_buffer (uint64_t capacity) |
| Enable circular buffer mode with fixed capacity. | |
| void | disable_circular_buffer () |
| Disable circular buffer mode and return to linear operation. | |
| bool | is_circular () const |
| Check if the container is currently operating in circular buffer mode. | |
| std::span< const double > | get_channel_frames (uint32_t channel, uint64_t start_frame, uint64_t num_frames) const |
| Get the fixed capacity of the circular buffer if enabled. | |
| void | get_channel_frames (std::span< double > output, uint32_t channel, uint64_t start_frame) const |
| uint64_t | get_circular_capacity () const |
| Public Member Functions inherited from MayaFlux::Kakshya::SoundStreamContainer | |
| SoundStreamContainer (uint32_t sample_rate=48000, uint32_t num_channels=2, uint64_t initial_capacity=0, bool circular_mode=false) | |
| Construct a SoundStreamContainer with specified parameters. | |
| ~SoundStreamContainer () override=default | |
| std::vector< DataDimension > | get_dimensions () const override |
| Get the dimensions describing the structure of the data. | |
| uint64_t | get_total_elements () const override |
| Get the total number of elements in the container. | |
| MemoryLayout | get_memory_layout () const override |
| Get the memory layout used by this container. | |
| void | set_memory_layout (MemoryLayout layout) override |
| Set the memory layout for this container. | |
| uint64_t | get_frame_size () const override |
| Get the number of elements that constitute one "frame". | |
| uint64_t | get_num_frames () const override |
| Get the number of frames in the primary (temporal) dimension. | |
| std::vector< DataVariant > | get_region_data (const Region ®ion) const override |
| Get data for a specific region. | |
| void | set_region_data (const Region ®ion, const std::vector< DataVariant > &data) override |
| Set data for a specific region. | |
| std::vector< DataVariant > | get_region_group_data (const RegionGroup &group) const override |
| Get data for multiple regions efficiently. | |
| std::vector< DataVariant > | get_segments_data (const std::vector< RegionSegment > &segment) const override |
| Get data for multiple region segments efficiently. | |
| std::span< const double > | get_frame (uint64_t frame_index) const override |
| Get a single frame of data efficiently. | |
| void | get_frames (std::span< double > output, uint64_t start_frame, uint64_t num_frames) const override |
| Get multiple frames efficiently. | |
| double | get_value_at (const std::vector< uint64_t > &coordinates) const override |
| Get a single value at the specified coordinates. | |
| void | set_value_at (const std::vector< uint64_t > &coordinates, double value) override |
| Set a single value at the specified coordinates. | |
| uint64_t | coordinates_to_linear_index (const std::vector< uint64_t > &coordinates) const override |
| Convert coordinates to linear index based on current memory layout. | |
| std::vector< uint64_t > | linear_index_to_coordinates (uint64_t linear_index) const override |
| Convert linear index to coordinates based on current memory layout. | |
| void | clear () override |
| Clear all data in the container. | |
| void | lock () override |
| Acquire a lock for thread-safe access. | |
| void | unlock () override |
| Release a previously acquired lock. | |
| bool | try_lock () override |
| Attempt to acquire a lock without blocking. | |
| const void * | get_raw_data () const override |
| Get a raw pointer to the underlying data storage. | |
| bool | has_data () const override |
| Check if the container currently holds any data. | |
| ContainerDataStructure & | get_structure () override |
| Get the data structure defining this container's layout. | |
| const ContainerDataStructure & | get_structure () const override |
| void | set_structure (ContainerDataStructure structure) override |
| Set the data structure for this container. | |
| void | add_region_group (const RegionGroup &group) override |
| Add a named group of regions to the container. | |
| const RegionGroup & | get_region_group (const std::string &name) const override |
| Get a region group by name. | |
| std::unordered_map< std::string, RegionGroup > | get_all_region_groups () const override |
| Get all region groups in the container. | |
| void | remove_region_group (const std::string &name) override |
| Remove a region group by name. | |
| bool | is_region_loaded (const Region ®ion) const override |
| Check if a region is loaded in memory. | |
| void | load_region (const Region ®ion) override |
| Load a region into memory. | |
| void | unload_region (const Region ®ion) override |
| Unload a region from memory. | |
| void | set_read_position (const std::vector< uint64_t > &position) override |
| Set the current read position in the primary temporal dimension per channel. | |
| void | update_read_position_for_channel (size_t channel, uint64_t frame) override |
| Update the read position for a specific channel. | |
| const std::vector< uint64_t > & | get_read_position () const override |
| Get the current read position. | |
| void | advance_read_position (const std::vector< uint64_t > &frames) override |
| Advance the read position by a specified amount. | |
| bool | is_at_end () const override |
| Check if read position has reached the end of the stream. | |
| void | reset_read_position () override |
| Reset read position to the beginning of the stream. | |
| uint64_t | get_temporal_rate () const override |
| Get the temporal rate (e.g., sample rate, frame rate) of the stream. | |
| uint64_t | time_to_position (double time) const override |
| Convert from time (seconds) to position units (e.g., frame/sample index). | |
| double | position_to_time (uint64_t position) const override |
| Convert from position units (e.g., frame/sample index) to time (seconds). | |
| void | set_looping (bool enable) override |
| Enable or disable looping behavior for the stream. | |
| bool | is_looping () const override |
| Check if looping is enabled for the stream. | |
| void | set_loop_region (const Region ®ion) override |
| Set the loop region using a Region. | |
| Region | get_loop_region () const override |
| Get the current loop region. | |
| bool | is_ready () const override |
| Check if the stream is ready for reading. | |
| std::vector< uint64_t > | get_remaining_frames () const override |
| Get the number of remaining frames from the current position, per channel. | |
| uint64_t | read_sequential (std::span< double > output, uint64_t count) override |
| Read data sequentially from the current position. | |
| uint64_t | peek_sequential (std::span< double > output, uint64_t count, uint64_t offset=0) const override |
| Peek at data without advancing the read position. | |
| ProcessingState | get_processing_state () const override |
| Get the current processing state of the container. | |
| void | update_processing_state (ProcessingState new_state) override |
| Update the processing state of the container. | |
| void | register_state_change_callback (std::function< void(std::shared_ptr< SignalSourceContainer >, ProcessingState)> callback) override |
| Register a callback to be invoked on processing state changes. | |
| void | unregister_state_change_callback () override |
| Unregister the state change callback, if any. | |
| bool | is_ready_for_processing () const override |
| Check if the container is ready for processing. | |
| void | mark_ready_for_processing (bool ready) override |
| Mark the container as ready or not ready for processing. | |
| void | create_default_processor () override |
| Create and configure a default processor for this container. | |
| void | process_default () override |
| Process the container's data using the default processor. | |
| void | set_default_processor (std::shared_ptr< DataProcessor > processor) override |
| Set the default data processor for this container. | |
| std::shared_ptr< DataProcessor > | get_default_processor () const override |
| Get the current default data processor. | |
| std::shared_ptr< DataProcessingChain > | get_processing_chain () override |
| Get the current processing chain for this container. | |
| void | set_processing_chain (std::shared_ptr< DataProcessingChain > chain) override |
| Set the processing chain for this container. | |
| uint32_t | register_dimension_reader (uint32_t dimension_index) override |
| Register a reader for a specific dimension. | |
| void | unregister_dimension_reader (uint32_t dimension_index) override |
| Unregister a reader for a specific dimension. | |
| bool | has_active_readers () const override |
| Check if any dimensions currently have active readers. | |
| void | mark_dimension_consumed (uint32_t dimension_index, uint32_t reader_id) override |
| Mark a dimension as consumed for the current processing cycle. | |
| bool | all_dimensions_consumed () const override |
| Check if all active dimensions have been consumed in this cycle. | |
| virtual void | clear_all_consumption () |
| std::vector< DataVariant > & | get_processed_data () override |
| Get a mutable reference to the processed data buffer. | |
| const std::vector< DataVariant > & | get_processed_data () const override |
| Get a const reference to the processed data buffer. | |
| void | mark_buffers_for_processing (bool) override |
| Mark associated buffers for processing in the next cycle. | |
| void | mark_buffers_for_removal () override |
| Mark associated buffers for removal from the system. | |
| virtual uint32_t | get_sample_rate () const |
| virtual uint32_t | get_num_channels () const |
| void | reset_processing_token () override |
| bool | try_acquire_processing_token (int channel) override |
| bool | has_processing_token (int channel) const override |
| std::span< const double > | get_data_as_double () const |
| Get the audio data as a specific type. | |
| const std::vector< DataVariant > & | get_data () override |
| Get a reference to the raw data stored in the container. | |
| DataAccess | channel_data (size_t channel) override |
| Get channel data with semantic interpretation. | |
| std::vector< DataAccess > | all_channel_data () override |
| Get all channel data as accessors. | |
| Public Member Functions inherited from MayaFlux::Kakshya::StreamContainer | |
| virtual | ~StreamContainer ()=default |
| Public Member Functions inherited from MayaFlux::Kakshya::SignalSourceContainer | |
| ~SignalSourceContainer () override=default | |
| Public Member Functions inherited from MayaFlux::Kakshya::NDDataContainer | |
| virtual | ~NDDataContainer ()=default |
Private Member Functions | |
| void | expand_to (uint64_t target_frames) |
| std::vector< DataVariant > | create_expanded_data (uint64_t new_frame_count) |
| void | set_all_data (const DataVariant &new_data) |
| void | set_all_data (const std::vector< DataVariant > &new_data) |
| uint64_t | validate (std::vector< std::span< const double > > &data, uint64_t start_frame=0) |
| uint64_t | validate_single_channel (std::span< const double > data, uint64_t start_frame=0, uint32_t channel=0) |
Private Attributes | |
| bool | m_auto_resize |
| Enable automatic capacity expansion. | |
| bool | m_is_circular {} |
| True when operating in circular buffer mode. | |
| uint64_t | m_circular_capacity {} |
| Fixed capacity for circular mode. | |
Additional Inherited Members | |
| Protected Member Functions inherited from MayaFlux::Kakshya::SoundStreamContainer | |
| void | setup_dimensions () |
| void | notify_state_change (ProcessingState new_state) |
| void | reorganize_data_layout (MemoryLayout new_layout) |
| const std::vector< std::span< double > > & | get_span_cache () const |
| Get the cached spans for each channel, recomputing if dirty. | |
| void | invalidate_span_cache () |
| Invalidate the span cache when data or layout changes. | |
| Protected Attributes inherited from MayaFlux::Kakshya::SoundStreamContainer | |
| std::vector< DataVariant > | m_data |
| std::vector< DataVariant > | m_processed_data |
| std::atomic< int > | m_processing_token_channel { -1 } |
| uint32_t | m_sample_rate = 48000 |
| uint32_t | m_num_channels {} |
| uint64_t | m_num_frames {} |
| std::vector< std::atomic< uint64_t > > | m_read_position |
| bool | m_looping_enabled = false |
| Region | m_loop_region |
| bool | m_circular_mode {} |
| uint64_t | m_circular_write_position {} |
| std::atomic< ProcessingState > | m_processing_state { ProcessingState::IDLE } |
| std::shared_ptr< DataProcessor > | m_default_processor |
| std::shared_ptr< DataProcessingChain > | m_processing_chain |
| std::unordered_map< std::string, RegionGroup > | m_region_groups |
| std::unordered_map< uint32_t, int > | m_active_readers |
| std::unordered_set< uint32_t > | m_consumed_dimensions |
| std::unordered_map< uint32_t, std::unordered_set< uint32_t > > | m_reader_consumed_dimensions |
| std::unordered_map< uint32_t, uint32_t > | m_dimension_to_next_reader_id |
| std::function< void(std::shared_ptr< SignalSourceContainer >, ProcessingState)> | m_state_callback |
| std::shared_mutex | m_data_mutex |
| std::mutex | m_state_mutex |
| std::mutex | m_reader_mutex |
| std::vector< double > | m_cached_ext_buffer |
| std::atomic< bool > | m_double_extraction_dirty { true } |
| std::mutex | m_extraction_mutex |
| ContainerDataStructure | m_structure |
Detailed Description
Dynamic capacity streaming audio container with automatic resizing and circular buffering.
DynamicSoundStream extends SoundStreamContainer to provide dynamic capacity management for real-time audio streaming scenarios where the buffer size cannot be predetermined. It combines the full functionality of SoundStreamContainer with:
Key Features:
- Dynamic Resizing: Automatically expands capacity when writing beyond current bounds
- Circular Buffering: Optional fixed-size circular buffer mode for continuous streaming
- Buffer-Sized Operations: Optimized read/write operations using buffer-sized chunks
- Capacity Management: Manual control over buffer allocation and expansion strategies
- Real-time Safe: Lock-free operations where possible for audio thread compatibility
Use Cases:
- Real-time audio recording with unknown duration
- Streaming buffers that grow dynamically during playback
- Circular delay lines and feedback systems
- Live audio processing with variable latency requirements
- Audio looping and granular synthesis applications
Memory Management: The container supports two primary modes:
- Linear Mode: Automatically expands as data is written, suitable for recording
- Circular Mode: Fixed-size buffer that wraps around, ideal for delay effects
Thread Safety: Inherits full thread safety from SoundStreamContainer including shared/exclusive locks for concurrent read/write access and atomic state management for processing coordination.
Integration: Fully compatible with the MayaFlux processing ecosystem including DataProcessor implementations, region-based operations, buffer manager integration, and sample-accurate timing.
- Note
- When auto-resize is enabled, write operations may trigger memory allocation. For real-time audio threads, consider pre-allocating capacity or using circular mode.
- Warning
- Circular mode discards old data when capacity is exceeded. Ensure appropriate capacity sizing for your use case to prevent data loss.
Definition at line 48 of file DynamicSoundStream.hpp.
The documentation for this class was generated from the following files:
