Function spectrusty_audio::carousel::create_carousel

pub fn create_carousel<T>(
    latency: usize,
    sample_frames: usize,
    channels: u8
) -> (AudioFrameProducer<T>, AudioFrameConsumer<T>)where
    T: 'static + AudioSample + Send,

Creates an inter-connected pair or AudioFrameProducer and AudioFrameConsumer.

The latency + 1 specifies how many buffers will be circulating in the carousel. The good indicator of how many are needed depends on the size of the target audio buffers provided by the framework. The size of the target audio buffer divided by the size of the produced frame buffers is a good approximation.

Basically, the larger the latency is the more stable the output sound stream will be, but at the cost of more delayed playback. Implementations should set a good default based on experiments but may allow users to adjust this value eventually.

sample_frames and channels determine the size of the allocated buffers.

Examples found in repository

src/host/cpal.rs (line 208)

    pub fn create_with_device_and_config(
            device: &cpal::Device,
            config: &cpal::StreamConfig,
            frame_duration_nanos: u32,
            latency: usize,
        ) -> Result<Self, AudioHandleError>
    {
        let channels: u8 = config.channels.try_into()
                           .map_err(|_| (format!("number of channels: {} exceed the maximum value of 255", config.channels),
                                         AudioHandleErrorKind::InvalidArguments))?;
        let sample_rate = config.sample_rate.0;

        let frame_duration_secs = Duration::from_nanos(frame_duration_nanos.into()).as_secs_f64();
        let audio_frame_samples = (sample_rate as f64 * frame_duration_secs).ceil() as usize;
        debug!("audio specs: {:?}", config);
        debug!("audio frame samples: {} latency: {}", audio_frame_samples, latency);
        let (producer, mut consumer) = create_carousel::<T>(latency, audio_frame_samples, channels);

        let data_fn = move |out: &mut [T], _: &_| match consumer.fill_buffer(out, false) {
            Ok(unfilled) => {
                if !unfilled.is_empty() {
                    for t in unfilled {
                        *t = T::silence()
                    }
                    debug!("missing buffer");
                }
            }
            Err(_) => {
                error!("fatal: producer terminated");
            }
        };

        let err_fn = |err| error!("an error occurred on stream: {}", err);

        let stream = device.build_output_stream(config, data_fn, err_fn)?;

        Ok(AudioHandle {
            sample_rate,
            channels,
            producer,
            stream
        })
    }

src/host/sdl2.rs (line 156)

    pub fn create_with_specs(
                sdl_context: &Sdl,
                mut desired_spec: AudioSpecDesired,
                frame_duration_nanos: u32,
                latency: usize
            ) -> Result<Self, AudioHandleError>
    {
        let audio_subsystem = sdl_context.audio().map_err(|e| (e, AudioHandleErrorKind::AudioSubsystem))?;
        let frame_duration_secs = Duration::from_nanos(frame_duration_nanos.into()).as_secs_f64();

        if desired_spec.freq.is_none() {
            desired_spec.freq = Some(DEFAULT_SAMPLE_RATE);
        }
        if desired_spec.channels.is_none() {
            desired_spec.channels = Some(DEFAULT_CHANNELS);
        }
        if desired_spec.samples.is_none() {
            let audio_frame_samples = (desired_spec.freq.unwrap() as f64 * frame_duration_secs).ceil() as usize;
            let samples: u16 = (audio_frame_samples * latency.max(1)).checked_next_power_of_two()
                .and_then(|samples| u16::try_from(samples).ok())
                .unwrap_or(0x8000);
            desired_spec.samples = Some(samples);
        }

        let mut producer: Option<AudioFrameProducer<T>> = None;

        let device = audio_subsystem.open_playback(None, &desired_spec, |spec| {
            let audio_frame_samples = (spec.freq as f64 * frame_duration_secs).ceil() as usize;
            let min_latency = (spec.samples as usize / audio_frame_samples).max(1);
            let latency = latency.max(min_latency);
            debug!("audio specs: {:?}", spec);
            debug!("audio frame samples: {} latency: {}", audio_frame_samples, latency);
            let (prd, consumer) = create_carousel::<T>(latency, audio_frame_samples, spec.channels);
            producer = Some(prd);
            AudioCb(consumer)
        }).map_err(|e| (e, AudioHandleErrorKind::AudioStream))?;

        let spec = device.spec();

        Ok(AudioHandle {
            sample_rate: spec.freq as u32,
            channels: spec.channels,
            samples: spec.samples,
            producer: producer.unwrap(),
            device
        })
    }