Struct OutStream

pub struct OutStream<'a> {
    pub userdata: Box<OutStreamUserData<'a>>,
    pub phantom: PhantomData<&'a ()>,
}

OutStream represents an output stream for playback.

It is obtained from Device using Device::open_outstream() and can be started and paused.

Fields

userdata: Box<OutStreamUserData<'a>>

phantom: PhantomData<&'a ()>

Implementations

impl<'a> OutStream<'a>

pub fn start(&mut self) -> Result<()>

Starts the stream, returning Ok(()) if it started successfully. Once started the write callback will be periodically called according to the requested latency.

start() should only ever be called once on an OutStream. Do not use start() to resume a stream after pausing it. Instead call pause(false).

This function might directly call the write callback.

Errors

• Error::Streaming
• Error::NoMem
• Error::SystemResources
• Error::BackendDisconnected

pub fn clear_buffer(&mut self) -> Result<()>

Clears the output stream buffer.

This function can be called regardless of whether the outstream is paused or not. Some backends do not support clearing the buffer. On these backends this function will return Error::IncompatibleBackend.

Some devices do not support clearing the buffer. On these devices this function might return Error::IncompatibleDevice.

Errors

• Error::Streaming
• Error::IncompatibleBackend
• Error::IncompatibleDevice

pub fn pause(&mut self, pause: bool) -> Result<()>

If the underlying backend and device support pausing, this pauses the stream. The write_callback() may be called a few more times if the buffer is not full.

Pausing might put the hardware into a low power state which is ideal if your software is silent for some time.

This should not be called before start(). Pausing when already paused or unpausing when already unpaused has no effect and returns Ok(()).

Errors

• Error::BackendDisconnected
• Error::Streaming
• Error::IncompatibleDevice - device does not support pausing/unpausing. This error code might not be returned even if the device does not support pausing/unpausing.
• Error::IncompatibleBackend - backend does not support pausing/unpausing.
• Error::Invalid - outstream not opened and started

pub fn format(&self) -> Format

Returns the stream format.

pub fn sample_rate(&self) -> i32

Sample rate is the number of frames per second.

pub fn software_latency(&self) -> f64

Ignoring hardware latency, this is the number of seconds it takes for the last sample in a full buffer to be played. After you call Device::open_instream(), this value is replaced with the actual software latency, as near to this value as possible.

On systems that support clearing the buffer, this defaults to a large latency, potentially upwards of 2 seconds, with the understanding that you will call clear_buffer() when you want to reduce the latency to 0. On systems that do not support clearing the buffer, this defaults to a reasonable lower latency value.

On backends with high latencies (such as 2 seconds), frame_count_min will be 0, meaning you don’t have to fill the entire buffer. In this case, the large buffer is there if you want it; you only have to fill as much as you want. On backends like JACK, frame_count_min will be equal to frame_count_max and if you don’t fill that many frames, you will get glitches.

If the device has unknown software latency min and max values, you may still set this (in Device::open_outstream()), but you might not get the value you requested. For PulseAudio, if you set this value to non-default, it sets PA_STREAM_ADJUST_LATENCY and is the value used for maxlength and tlength.

For JACK, this value is always equal to Device::software_latency().current.

pub fn name(&self) -> String

The name of the stream, which defaults to “SoundIoOutStream”.

PulseAudio uses this for the stream name. JACK uses this for the client name of the client that connects when you open the stream. WASAPI uses this for the session display name. Must not contain a colon (“:”).

TODO: Currently there is no way to set this.

pub fn bytes_per_frame(&self) -> i32

The number of bytes per frame, equal to the number of bytes per sample, multiplied by the number of channels.

pub fn bytes_per_sample(&self) -> i32

The number of bytes in a sample, e.g. 3 for i24.