Struct FirewheelCtx

Source

pub struct FirewheelCtx<B: AudioBackend> { /* private fields */ }

Expand description

A Firewheel context

Implementations§

Source §

impl<B: AudioBackend> FirewheelCtx

Source

pub fn new(config: FirewheelConfig) -> Self

Create a new Firewheel context.

Source

pub fn available_input_devices(&self) -> Vec<DeviceInfo>

Get a list of the available audio input devices.

Source

pub fn available_output_devices(&self) -> Vec<DeviceInfo>

Get a list of the available audio output devices.

Source

pub fn can_start_stream(&self) -> bool

Returns true if an audio stream can be started right now.

When calling FirewheelCtx::stop_stream(), it may take some time for the old stream to be fully stopped. This method is used to check if it has been dropped yet.

Note, in rare cases where the audio thread crashes without cleanly dropping its contents, this may never return true. Consider adding a timeout to avoid deadlocking.

Source

pub fn start_stream( &mut self, config: B::Config, ) -> Result<(), StartStreamError<B::StartStreamError>>

Start an audio stream for this context. Only one audio stream can exist on a context at a time.

When calling FirewheelCtx::stop_stream(), it may take some time for the old stream to be fully stopped. Use FirewheelCtx::can_start_stream to check if it has been dropped yet.

Note, in rare cases where the audio thread crashes without cleanly dropping its contents, this may never succeed. Consider adding a timeout to avoid deadlocking.

Source

pub fn stop_stream(&mut self)

Stop the audio stream in this context.

Source

pub fn is_audio_stream_running(&self) -> bool

Returns true if there is currently a running audio stream.

Source

pub fn stream_info(&self) -> Option<&StreamInfo>

Information about the running audio stream.

Returns None if no audio stream is currently running.

Source

pub fn clock_now(&self) -> ClockSeconds

The current time of the clock in the number of seconds since the stream was started.

Note, this clock is not perfectly accurate, but it is good enough for most use cases. This clock also correctly accounts for any output underflows that may occur.

Source

pub fn clock_samples(&self) -> ClockSamples

The current time of the sample clock in the number of samples (of a single channel of audio) that have been processed since the beginning of the stream.

This is more accurate than the seconds clock, and is ideal for syncing events to a musical transport. Though note that this clock does not account for any output underflows that may occur.

Source

pub fn clock_musical(&self) -> MusicalTime

The current musical time of the transport.

If no transport is currently active, then this will have a value of 0.

Source

pub fn set_transport( &mut self, transport: Option<MusicalTransport>, ) -> Result<(), UpdateError<B::StreamError>>

Set the musical transport to use.

If an existing musical transport is already running, then the new transport will pick up where the old one left off. This allows you to, for example, change the tempo dynamically at runtime.

If the message channel is full, then this will return an error.

Source

pub fn start_or_restart_transport( &mut self, ) -> Result<(), UpdateError<B::StreamError>>

Start or restart the musical transport.

If the message channel is full, then this will return an error.

Source

pub fn pause_transport(&mut self) -> Result<(), UpdateError<B::StreamError>>

Pause the musical transport.

If the message channel is full, then this will return an error.

Source

pub fn resume_transport(&mut self) -> Result<(), UpdateError<B::StreamError>>

Resume the musical transport.

If the message channel is full, then this will return an error.

Source

pub fn stop_transport(&mut self) -> Result<(), UpdateError<B::StreamError>>

Stop the musical transport.

If the message channel is full, then this will return an error.

Source

pub fn hard_clip_outputs(&self) -> bool

Whether or not outputs are being hard clipped at 0dB.

Source

pub fn set_hard_clip_outputs( &mut self, hard_clip_outputs: bool, ) -> Result<(), UpdateError<B::StreamError>>

Set whether or not outputs should be hard clipped at 0dB to help protect the system’s speakers.

Note that most operating systems already hard clip the output, so this is usually not needed (TODO: Do research to see if this assumption is true.)

If the message channel is full, then this will return an error.

Source

pub fn update(&mut self) -> Result<(), UpdateError<B::StreamError>>

Update the firewheel context.

This must be called reguarly (i.e. once every frame).

Source

pub fn graph_in_node_id(&self) -> NodeID

The ID of the graph input node

Source

pub fn graph_out_node_id(&self) -> NodeID

The ID of the graph output node

Source

pub fn add_node<T: AudioNode + 'static>( &mut self, node: T, config: Option<T::Configuration>, ) -> NodeID

Add a node to the audio graph.

Source

pub fn add_dyn_node<T: DynAudioNode + 'static>(&mut self, node: T) -> NodeID

Add a node to the audio graph which implements the type-erased DynAudioNode trait.

Source

pub fn remove_node( &mut self, node_id: NodeID, ) -> Result<SmallVec<[EdgeID; 4]>, ()>

Remove the given node from the audio graph.

This will automatically remove all edges from the graph that were connected to this node.

On success, this returns a list of all edges that were removed from the graph as a result of removing this node.

This will return an error if a node with the given ID does not exist in the graph, or if the ID is of the graph input or graph output node.

Source

pub fn node_info(&self, id: NodeID) -> Option<&NodeEntry>

Get information about a node in the graph.

Source

pub fn node_state<T: 'static>(&self, id: NodeID) -> Option<&T>

Get an immutable reference to the custom state of a node.

Source

pub fn node_state_dyn(&self, id: NodeID) -> Option<&dyn Any>

Get a type-erased, immutable reference to the custom state of a node.

Source

pub fn node_state_mut<T: 'static>(&mut self, id: NodeID) -> Option<&mut T>

Get a mutable reference to the custom state of a node.

Source

pub fn node_state_dyn_mut(&mut self, id: NodeID) -> Option<&mut dyn Any>

Source

pub fn nodes<'a>(&'a self) -> impl Iterator<Item = &'a NodeEntry>

Get a list of all the existing nodes in the graph.

Source

pub fn edges<'a>(&'a self) -> impl Iterator<Item = &'a Edge>

Get a list of all the existing edges in the graph.

Source

pub fn set_graph_channel_config( &mut self, channel_config: ChannelConfig, ) -> SmallVec<[EdgeID; 4]>

Set the number of input and output channels to and from the audio graph.

Returns the list of edges that were removed.

Source

pub fn connect( &mut self, src_node: NodeID, dst_node: NodeID, ports_src_dst: &[(PortIdx, PortIdx)], check_for_cycles: bool, ) -> Result<SmallVec<[EdgeID; 4]>, AddEdgeError>

Add connections (edges) between two nodes to the graph.

src_node - The ID of the source node.
dst_node - The ID of the destination node.
ports_src_dst - The port indices for each connection to make, where the first value in a tuple is the output port on src_node, and the second value in that tuple is the input port on dst_node.
check_for_cycles - If true, then this will run a check to see if adding these edges will create a cycle in the graph, and return an error if it does. Note, checking for cycles can be quite expensive, so avoid enabling this when calling this method many times in a row.

If successful, then this returns a list of edge IDs in order.

If this returns an error, then the audio graph has not been modified.

Source

pub fn disconnect( &mut self, src_node: NodeID, dst_node: NodeID, ports_src_dst: &[(PortIdx, PortIdx)], ) -> bool

Remove connections (edges) between two nodes from the graph.

src_node - The ID of the source node.
dst_node - The ID of the destination node.
ports_src_dst - The port indices for each connection to make, where the first value in a tuple is the output port on src_node, and the second value in that tuple is the input port on dst_node.

If none of the edges existed in the graph, then false will be returned.

Source