Trait SampleResource 

pub trait SampleResource {
    // Required methods
    fn info(&self) -> SampleResourceInfo;
    fn fill_buffers_f32(
        &self,
        buffer: &mut [&mut [f32]],
        buffer_range: Range<usize>,
        start_frame: u64,
    ) -> usize;

    // Provided methods
    fn cache_info(&self) -> Option<&SampleCacheInfo> { ... }
    fn cache(&self, start_frame: u64, priority: u32) { ... }
    fn notify_playhead_behavior(&self, behavior: PlayheadBehavior) { ... }
}

A resource of audio samples with a known length.

Implementation examples

// Interleaved example
struct MyInterleavedResource {
    data: Vec<i16>,
    channels: usize,
    sample_rate: Option<f64>,
}

impl SampleResource for MyInterleavedResource {
    fn info(&self) -> SampleResourceInfo {
        SampleResourceInfo {
            num_channels: self.channels,
            len_frames: (self.data.len() / self.channels) as u64,
            sample_rate: self.sample_rate,
        }
    }

    fn fill_buffers_f32(
        &self,
        buffer: &mut [&mut [f32]],
        buffer_range: Range<usize>,
        start_frame: u64,
    ) -> usize {
        sample_resource::helpers::fill_buffers_interleaved(
            buffer,
            buffer_range,
            start_frame,
            self.channels,
            self.data.len() / self.channels,
            &self.data,
        )
    }
}

// Deinterleaved example
struct MyDeinterleavedResource {
    data: Vec<Vec<i16>>,
    frames: usize,
    channels: usize,
    sample_rate: Option<f64>,
}

impl SampleResource for MyDeinterleavedResource {
    fn info(&self) -> SampleResourceInfo {
        SampleResourceInfo {
            num_channels: self.channels,
            len_frames: self.frames as u64,
            sample_rate: self.sample_rate,
        }
    }

    fn fill_buffers_f32(
        &self,
        buffer: &mut [&mut [f32]],
        buffer_range: Range<usize>,
        start_frame: u64,
    ) -> usize {
        sample_resource::helpers::fill_buffers_deinterleaved(
            buffer,
            buffer_range,
            start_frame,
            self.frames,
            &self.data,
        )
    }
}

Realtime Safety

3rd party libraries that implement this trait should expect that all methods in this trait may be called in a realtime thread. For more information, see: http://www.rossbencina.com/code/real-time-audio-programming-101-time-waits-for-nothing

Required Methods

fn info(&self) -> SampleResourceInfo

Retrieve information about this sample resource. This information is NOT allowed to change for the lifetime of this sample resource.

fn fill_buffers_f32( &self, buffer: &mut [&mut [f32]], buffer_range: Range<usize>, start_frame: u64, ) -> usize

Fill the given buffers with audio data in f32 format starting from the given starting frame in the sample resource.

Returns the number of frames (samples in a single channel of audio) that were successfully written to the buffer. This may be less than the requested number of frames if buffer_range falls outside the range of the sample resource or if a cache miss occured.

• buffer - The buffers to fill with data. If the length of buffers is greater than the number of channels in this resource, then the extra channels will be left untouched.
• buffer_range - The range inside each channel slice in buffers to fill with data.
  • If a range falls outside the range of the sample resource, then that range will be left untouched. (Note it is the caller’s responsibility to handle looping behavior, not the sample resource’s responsibility.)
  • If a cache miss occured, then the range [buffer_range.start + return_value..buffer_range.end] will be filled with zeros.
• start_frame - The frame (sample of a single channel of audio) in the sample resource to start copying from (inclusive).

The data will NOT be declicked (as in clicking caused by pausing/resuming, the playhead jumping to a different position, or by a cache miss). It is up to the caller to do their own declicking.

When playing backwards (notified in SampleResource::notify_playhead_behavior()), the data in the buffer will NOT be reversed. It is up to the caller to reverse the data themselves.

Panics

Panics if buffer_range is out-of-bounds for any channel slice in buffer.

Provided Methods

fn cache_info(&self) -> Option<&SampleCacheInfo>

Information about the caching behavior of this sample resource. Returns None if caching is not used by this resource.

This information is allowed to change (usually in response to a call to SampleResource::notify_playhead_behavior()).

This is only relevant for sample resources which don’t have all of their data loaded in memory, such as those that stream data from a disk or over a network. Sample resources which already have all of their data loaded in memory should return None.

By default this returns None.

fn cache(&self, start_frame: u64, priority: u32)

Request the sample resource to cache a block of frames (samples in a single channel of audio).

• start_frame - The starting frame (samples in a single channel of audio) in the sample resource to cache a new block (inclusive). If a resulting range falls outside the range of the sample resource, then ignore that range.
• priority - A number describing how important this cache is (higher means more important). This can be used by the resource to determine which caches to discard if there are no more cache blocks available.

This is only relevant for sample resources which stream data from disk or over a network. Sample resources which already have all their contents stored in memory do not need to implement this method.

fn notify_playhead_behavior(&self, behavior: PlayheadBehavior)

Notify the sample resource the speed and the direction that the playhead is moving. This can be used to help the sample resource make optimal caching decisions.

Until this method is called, sample resources should assume that playback_speed = 1.0 and is_playing_backwards = false.

This is only relevant for sample resources which stream data from disk or over a network. Sample resources which already have all their contents stored in memory do not need to implement this method.

Implementors