Struct OutputStreamBuilder

pub struct OutputStreamBuilder<E = fn(StreamError)>
where
    E: FnMut(StreamError) + Send + 'static,
{ /* private fields */ }

Convenience builder for audio output stream. It provides methods to configure several parameters of the audio output and opening default device. See examples for use-cases.

When the OutputStream is dropped playback will end, and the associated output stream will be disposed

Implementations

impl OutputStreamBuilder

pub fn from_device(device: Device) -> Result<OutputStreamBuilder, StreamError>

Sets output device and its default parameters.

pub fn from_default_device() -> Result<OutputStreamBuilder, StreamError>

Sets default output stream parameters for default output audio device.

pub fn open_default_stream() -> Result<OutputStream, StreamError>

Try to open a new output stream for the default output device with its default configuration. Failing that attempt to open output stream with alternative configuration and/or non default output devices. Returns stream for first of the tried configurations that succeeds. If all attempts fail return the initial error.

impl<E> OutputStreamBuilder<E>

where E: FnMut(StreamError) + Send + 'static,

pub fn with_device(self, device: Device) -> OutputStreamBuilder<E>

Sets output audio device keeping all existing stream parameters intact. This method is useful if you want to set other parameters yourself. To also set parameters that are appropriate for the device use Self::from_device() instead.

pub fn with_channels( self, channel_count: ChannelCount, ) -> OutputStreamBuilder<E>

Sets number of output stream’s channels.

pub fn with_sample_rate(self, sample_rate: SampleRate) -> OutputStreamBuilder<E>

Sets output stream’s sample rate.

pub fn with_buffer_size(self, buffer_size: BufferSize) -> OutputStreamBuilder<E>

Sets preferred output buffer size.

To play sound without any glitches the audio card may never receive a sample to late. Some samples might take longer to generate then others. For example because:

• The OS preempts the thread creating the samples. This happens more often if the computer is under high load.
• The decoder needs to read more data from disk.
• Rodio code takes longer to run for some samples then others
• The OS can only send audio samples in groups to the DAC.

The OS solves this by buffering samples. The larger that buffer the smaller the impact of variable sample generation time. On the other hand Rodio controls audio by changing the value of samples. We can not change a sample already in the OS buffer. That means there is a minimum delay (latency) of <buffer size>/<sample_rate*channel_count> seconds before a change made through rodio takes effect.

Large vs Small buffer

• A larger buffer size results in high latency. Changes made trough Rodio (volume/skip/effects etc) takes longer before they can be heard.
• A small buffer might cause:
  • Higher CPU usage
  • Playback interruptions such as buffer underruns.
  • Rodio to log errors like: alsa::poll() returned POLLERR

Recommendation

If low latency is important to you consider offering the user a method to find the minimum buffer size that works well on their system under expected conditions. A good example of this approach can be seen in mumble (specifically the Output Delay & Jitter buffer.

These are some typical values that are a good starting point. They may also break audio completely, it depends on the system.

• Low-latency (audio production, live monitoring): 512-1024
• General use (games, media playback): 1024-2048
• Stability-focused (background music, non-interactive): 2048-4096

pub fn with_sample_format( self, sample_format: SampleFormat, ) -> OutputStreamBuilder<E>

Select scalar type that will carry a sample.

pub fn with_supported_config( self, config: &SupportedStreamConfig, ) -> OutputStreamBuilder<E>

Set available parameters from a CPAL supported config. You can get a list of such configurations for an output device using crate::stream::supported_output_configs()

pub fn with_config(self, config: &StreamConfig) -> OutputStreamBuilder<E>

Set all output stream parameters at once from CPAL stream config.

pub fn with_error_callback<F>(self, callback: F) -> OutputStreamBuilder<F>

where F: FnMut(StreamError) + Send + 'static,

Set a callback that will be called when an error occurs with the stream

pub fn open_stream(self) -> Result<OutputStream, StreamError>

Open output stream using parameters configured so far.

pub fn open_stream_or_fallback(&self) -> Result<OutputStream, StreamError>

where E: Clone,

Try opening a new output stream with the builder’s current stream configuration. Failing that attempt to open stream with other available configurations supported by the device. If all attempts fail returns initial error.

Trait Implementations

impl Debug for OutputStreamBuilder

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for OutputStreamBuilder

fn default() -> Self

Returns the “default value” for a type.