Struct songbird::tracks::TrackHandle

pub struct TrackHandle { /* fields omitted */ }

Handle for safe control of a Track from other threads, outside of the audio mixing and voice handling context.

These are cheap to clone, using Arc<...> internally.

Many method calls here are fallible; in most cases, this will be because the underlying Track object has been discarded. Those which aren’t refer to immutable properties of the underlying stream, or shared data not used by the driver.

Implementations

impl TrackHandle

pub fn new(
    command_channel: Sender<TrackCommand>,
    seekable: bool,
    uuid: Uuid,
    metadata: Box<Metadata>
) -> Self

Creates a new handle, using the given command sink and hint as to whether the underlying Input supports seek operations.

pub fn play(&self) -> TrackResult<()>

Unpauses an audio track.

pub fn pause(&self) -> TrackResult<()>

Pauses an audio track.

pub fn stop(&self) -> TrackResult<()>

Stops an audio track.

This is final, and will cause the audio context to fire a TrackEvent::End event.

pub fn set_volume(&self, volume: f32) -> TrackResult<()>

Sets the volume of an audio track.

pub fn make_playable(&self) -> TrackResult<()>

Ready a track for playing if it is lazily initialised.

Currently, only Restartable sources support lazy setup. This call is a no-op for all others.

pub fn is_seekable(&self) -> bool

Denotes whether the underlying Input stream is compatible with arbitrary seeking.

If this returns false, all calls to seek_time will fail, and the track is incapable of looping.

pub fn seek_time(&self, position: Duration) -> TrackResult<()>

Seeks along the track to the specified position.

If the underlying Input does not support seeking, then all calls will fail with TrackError::SeekUnsupported.

pub fn add_event<F: EventHandler + 'static>(
    &self,
    event: Event,
    action: F
) -> TrackResult<()>

Attach an event handler to an audio track. These will receive EventContext::Track.

Events which can only be fired by the global context return TrackError::InvalidTrackEvent

pub fn action<F>(&self, action: F) -> TrackResult<()> where
    F: FnOnce(&mut Track) + Send + Sync + 'static, 

Perform an arbitrary synchronous action on a raw Track object.

Users must ensure that no costly work or blocking occurs within the supplied function or closure. Taking excess time could prevent timely sending of packets, causing audio glitches and delays.

pub async fn get_info(&self) -> TrackResult<Box<TrackState>>

Request playback information and state from the audio context.

pub fn enable_loop(&self) -> TrackResult<()>

Set an audio track to loop indefinitely.

If the underlying Input does not support seeking, then all calls will fail with TrackError::SeekUnsupported.

pub fn disable_loop(&self) -> TrackResult<()>

Set an audio track to no longer loop.

If the underlying Input does not support seeking, then all calls will fail with TrackError::SeekUnsupported.

pub fn loop_for(&self, count: usize) -> TrackResult<()>

Set an audio track to loop a set number of times.

If the underlying Input does not support seeking, then all calls will fail with TrackError::SeekUnsupported.

pub fn uuid(&self) -> Uuid

Returns this handle’s (and track’s) unique identifier.

pub fn metadata(&self) -> &Metadata

Returns the metadata stored in the handle.

Metadata is cloned from the inner Input at the time a track/handle is created, and is effectively read-only from then on.

pub fn typemap(&self) -> &RwLock<TypeMap>

Allows access to this track’s attached TypeMap.

TypeMaps allow additional, user-defined data shared by all handles to be attached to any track.

Driver code will never attempt to lock access to this map, preventing deadlock/stalling.

pub fn send(&self, cmd: TrackCommand) -> TrackResult<()>

Send a raw command to the Track object.

Trait Implementations

impl Clone for TrackHandle

fn clone(&self) -> TrackHandle

Returns a copy of the value.

pub fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for TrackHandle

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

Formats the value using the given formatter.