Struct Engine 

pub struct Engine { /* private fields */ }

This is the main moving part of the Second Music System. You create one of these, give it a delegate to handle music decoding, and “turn the handle” in your sound output code to make music come out.

Implementations

impl Engine

pub fn new( sound_delegate: Arc<dyn SoundDelegate>, speaker_layout: SpeakerLayout, sample_rate: PosFloat, num_threads: Option<NonZeroUsize>, affinity: usize, ) -> Engine

Creates a new Engine with the given properties, which will perform loading in the background using a purely internal Switchyard. Only available if you haven’t disabled the "switchyard" feature.

Once these properties are set, they cannot be changed without creating a new Engine.

• speaker_layout: What kind of speaker layout your listener has. When in doubt, use Stereo.
• sample_rate: Number of samples per second you will be outputting.
• num_threads: Number of threads to use for decoding and streaming. If None or 0, will use a reasonable default based on the number of available hardware threads and whether background loading is requested.
• num_threads: If None, will use a reasonable default based on the number of available hardware threads. If Some(x), will use that exact number of hardware threads.
• affinity: Offset added to core affinity of threads. When in doubt, use 0.

pub fn new_with_runtime<Runtime: TaskRuntime>( sound_delegate: Arc<dyn SoundDelegate>, speaker_layout: SpeakerLayout, sample_rate: PosFloat, loading_rt: Arc<Runtime>, ) -> Engine

Creates a new Engine with the given properties using a particular custom TaskRuntime for loading tasks. If you want to perform offline rendering, or another task where you just want all loading to happen synchronously, pass Arc::new(ForegroundTaskRuntime) as the loading runtime. If you don’t care, and haven’t disabled the switchyard feature, just use new instead.

Once these properties are set, they cannot be changed without creating a new Engine.

• speaker_layout: What kind of speaker layout your listener has. When in doubt, use Stereo.
• sample_rate: Number of samples per second you will be outputting.
• num_threads: Number of threads to use for decoding and streaming. If None or 0, will use a reasonable default based on the number of available hardware threads and whether background loading is requested.

pub fn clone_commander(&self) -> Commander

Makes an independent Commander that can send commands to this Engine from another thread.

pub fn copy_live_soundtrack(&self) -> Soundtrack

Gets a copy of the Soundtrack that is currently live.

pub fn copy_all_flow_controls(&self) -> HashMap<CompactString, StringOrNumber>

Gets a copy of all the FlowControls.

pub fn get_speaker_layout(&self) -> SpeakerLayout

Returns the SpeakerLayout this Engine was initialized for.

pub fn get_sample_rate(&self) -> PosFloat

Returns the sample rate this Engine was initialized for.

pub fn turn_handle(&mut self, out: &mut [f32])

Mix some audio, advance time! out must have a number of elements divisible by the number of speaker channels. Any existing data in out is mixed with the active music data. You may or may not want to zero out before this call.

Trait Implementations

impl EngineCommands for Engine

fn begin_transaction(&mut self, length: Option<usize>) -> Transaction<'_, Self>

Starts a new transaction. Commands that are issued will be batched together into one transaction, and delivered and processed all at once when the transaction is complete.

fn replace_soundtrack(&mut self, new_soundtrack: Soundtrack)

Replace the active soundtrack with the given one. Currently-active nodes, sequences, and sounds will do their best to play to their conclusion.

fn precache(&mut self, flow_name: CompactString)

Requests that the given flow be precached for playback. The engine will attempt to load/preroll all requested sounds and streams in the background. Use is_flow_ready to determine when the loading is complete.

fn unprecache(&mut self, flow_name: CompactString)

Undoes a previous request that the given flow be precached for playback. This will lead the relevant sounds and streams to be purged once the flow stops playing (or immediately, if the flow is not currently playing).

fn unprecache_all(&mut self)

Undoes all previous requests for precaching of flows. Flows that are currently in use will still remain in memory.

fn is_flow_ready(&mut self, flow_name: CompactString) -> Response<bool>

Returns a query::Response that will answer the question “Is this flow I precached now ready for instant playback?”

fn is_flow_active(&mut self, flow_name: CompactString) -> Response<bool>

Returns a query::Response that will answer the question “Is this flow either currently playing or waiting to start playing?” (After a flow reaches a natural end without looping, this will return false.)

fn set_flow_control( &mut self, control_name: CompactString, new_value: StringOrNumber, )

Sets a given FlowControl to the given value.

fn get_flow_control( &mut self, control_name: CompactString, ) -> Response<Option<StringOrNumber>>

Returns a query::Response that will answer the question “What value does this flow control currently have?” (Flows can set flow control values themselves, and in doing so, communicate in a very limited way back to the calling program.)

fn get_all_flow_controls( &mut self, ) -> Response<Vec<(CompactString, StringOrNumber)>>

Returns a query::Response that will give you a complete list of flow controls, and the values they are currently set to.

fn get_active_flows(&mut self) -> Response<Vec<CompactString>>

Returns a query::Response that will give you a complete list of flows that are playing.

fn get_active_nodes(&mut self) -> Response<Vec<ActiveNodeReport>>

Returns a query::Response that will give you a complete list of flow nodes that are playing.

fn get_mix_control( &mut self, control_name: CompactString, ) -> Response<Option<f32>>

Returns a query::Response that will answer the question “What volume level is this mix control currently operating at?” If there is a fade in progress, the volume reported will reflect the current moment within the fade.

fn get_all_mix_controls(&mut self) -> Response<Vec<(CompactString, f32)>>

Returns a query::Response that will give you a complete list of mix controls, and the volumes they are currently operating at. If there is a fade in progress, the volumes reported will reflect the current moment within the fade.

fn get_mix_flows(&mut self) -> Response<Vec<MixFlowReport>>

Returns a query::Response that will give you a complete list of flows that are playing, and the volumes they’re playing at.

fn clear_flow_control(&mut self, control_name: CompactString)

Clears a given FlowControl, removing any previous value.

fn clear_prefixed_flow_controls(&mut self, control_prefix: CompactString)

Clears all FlowControls whose names strictly start with the given prefix.

fn clear_all_flow_controls(&mut self)

Clears all FlowControls.

fn fade_mix_control_to( &mut self, control_name: CompactString, target_volume: PosFloat, fade_length: PosFloat, fade_type: FadeType, )

Fades a given MixControl to the given volume (0.0 to 1.0), using the given fading curve, over the given time period (in seconds).

fn fade_prefixed_mix_controls_to( &mut self, control_prefix: CompactString, target_volume: PosFloat, fade_length: PosFloat, fade_type: FadeType, )

Fades all currently existing mix controls whose names strictly start with the given prefix to the given volume (0.0 to 1.0), using the given fading curve, over the given time period (in seconds).

fn fade_all_mix_controls_to( &mut self, target_volume: PosFloat, fade_length: PosFloat, fade_type: FadeType, )

Fades all currently existing mix controls, including main, to the given volume (0.0 to 1.0), using the given fading curve, over the given time period (in seconds).

fn fade_all_mix_controls_except_main_to( &mut self, target_volume: PosFloat, fade_length: PosFloat, fade_type: FadeType, )

Fades all currently existing mix controls, except main, to the given volume (0.0 to 1.0), using the given fading curve, over the given time period (in seconds).

fn fade_mix_control_out( &mut self, control_name: CompactString, fade_length: PosFloat, fade_type: FadeType, )

Fades a given MixControl to zero volume, using the given fading curve, over the given time period (in seconds). When the fade is complete, the MixControl will be removed from existence rather than simply zeroed; future commands to “prefixed” and “all” will not resuscitate it (unless it is the target of a future, specific command).

fn fade_prefixed_mix_controls_out( &mut self, control_prefix: CompactString, fade_length: PosFloat, fade_type: FadeType, )

Fades all currently existing mix controls whose names strictly start with the given prefix to zero volume, using the given fading curve, over the given time period (in seconds). When the fade is complete, the MixControl will be removed from existence rather than simply zeroed; future commands to “prefixed” and “all” will not resuscitate it (unless it is the target of a future, specific command).

fn fade_all_mix_controls_out( &mut self, fade_length: PosFloat, fade_type: FadeType, )

Fades all currently existing mix controls, including main, to zero volume, using the given fading curve, over the given time period (in seconds). When the fade is complete, the MixControl will be removed from existence rather than simply zeroed; future commands to “prefixed” and “all” will not resuscitate it (unless it is the target of a future, specific command).

fn fade_all_mix_controls_except_main_out( &mut self, fade_length: PosFloat, fade_type: FadeType, )

Fades all currently existing mix controls, except main, to zero volume, using the given fading curve, over the given time period (in seconds). When the fade is complete, the MixControl will be removed from existence rather than simply zeroed; future commands to “prefixed” and “all” will not resuscitate it (unless it is the target of a future, specific command).

fn kill_mix_control(&mut self, control_name: CompactString)

Kills a given MixControl instantly, as if you yanked an audio cable.

fn kill_prefixed_mix_controls(&mut self, control_prefix: CompactString)

Kills all MixControls whose names strictly start with the given prefix, as if you yanked an audio cable.

fn kill_all_mix_controls(&mut self)

Kills all MixControls, including main, as if you yanked an audio cable.

fn kill_all_mix_controls_except_main(&mut self)

Kills all MixControls, except main, as if you yanked an audio cable.

fn start_flow( &mut self, flow_name: CompactString, target_volume: PosFloat, fade_length: PosFloat, fade_type: FadeType, )

Starts a given flow if it’s not already playing. If the flow is being newly started, it will be faded up from zero volume to the target volume, with the given fade curve. If the flow was already playing, acts just like fade_flow_to.

fn fade_flow_to( &mut self, flow_name: CompactString, target_volume: PosFloat, fade_length: PosFloat, fade_type: FadeType, )

Fades a given flow to the given volume (0.0 to 1.0), using the given fading curve, over the given time period (in seconds). Does nothing if the flow is not currently playing.

fn fade_prefixed_flows_to( &mut self, flow_prefix: CompactString, target_volume: PosFloat, fade_length: PosFloat, fade_type: FadeType, )

Fades all currently playing flows whose names strictly start with the given prefix to the given volume (0.0 to 1.0), using the given fading curve, over the given time period (in seconds). Does nothing to flows that haven’t been started, or that have finished fading out.

fn fade_all_flows_to( &mut self, target_volume: PosFloat, fade_length: PosFloat, fade_type: FadeType, )

Fades all currently playing flows to the given volume (0.0 to 1.0), using the given fading curve, over the given time period (in seconds). Does nothing to flows that haven’t been started, or that have finished fading out.

fn fade_flow_out( &mut self, flow_name: CompactString, fade_length: PosFloat, fade_type: FadeType, )

Fades a given flow to zero volume, using the given fading curve, over the given time period (in seconds). Does nothing if the flow is not currently playing, or has already faded out. When the fade is complete, the flow will be stopped.

fn fade_prefixed_flows_out( &mut self, flow_prefix: CompactString, fade_length: PosFloat, fade_type: FadeType, )

Fades all currently playing flows whose names strictly start with the given prefix to zero volume, using the given fading curve, over the given time period (in seconds). Does nothing to flows that haven’t been started, or that have already finished fading out.

fn fade_all_flows_out(&mut self, fade_length: PosFloat, fade_type: FadeType)

Fades all currently playing flows to zero volume, using the given fading curve, over the given time period (in seconds). Does nothing to flows that haven’t been started, or that have already finished fading out.

fn kill_flow(&mut self, flow_name: CompactString)

Kills a given flow instantly.

fn kill_prefixed_flows(&mut self, flow_prefix: CompactString)

Kills all currently playing flows whose names strictly start with the given prefix instantly.

fn kill_all_flows(&mut self)

Kills all currently playing flows instantly.