Struct AUDIOS 

pub struct AUDIOS;

Audio loading, cache and render service.

If the app is running without a VIEW_PROCESS all audios are dummy, see load_in_headless for details.

Implementations

impl AUDIOS

pub fn load_in_headless(&self) -> Var<bool>

If should still download/read audio bytes in headless/renderless mode.

When an app is in headless mode without renderer no VIEW_PROCESS is available, so audios cannot be decoded, in this case all audios are dummy loading and no attempt to download/read the audio files is made. You can enable loading in headless tests to detect IO errors, in this case if there is an error acquiring the audio file the audio will be a dummy with error.

pub fn limits(&self) -> Var<AudioLimits>

Default loading and decoding limits for each audio.

pub fn read(&self, path: impl Into<PathBuf>) -> AudioVar

Request an audio, reads from a path and caches it.

This is shorthand for calling AUDIOS.audio with AudioSource::Read and AudioOptions::cache.

pub fn download<U>(&self, uri: U, accept: Option<Txt>) -> AudioVar

where U: TryInto<Uri>, <U as TryInto<Uri>>::Error: ToTxt,

Request an audio, downloads from an uri and caches it.

Optionally define the HTTP ACCEPT header, if not set all audio formats supported by the view-process backend are accepted.

This is shorthand for calling AUDIOS.audio with AudioSource::Download and AudioOptions::cache.

pub fn from_static( &self, data: &'static [u8], format: impl Into<AudioDataFormat>, ) -> AudioVar

Request an audio from &'static [u8] data.

The data can be any of the formats described in AudioDataFormat.

This is shorthand for calling AUDIOS.audio with AudioSource::Data and AudioOptions::cache.

Examples

Get an audio from a PNG file embedded in the app executable using include_bytes!.

let audio_var = AUDIOS.from_static(include_bytes!("ico.png"), "png");

pub fn from_data( &self, data: IpcBytes, format: impl Into<AudioDataFormat>, ) -> AudioVar

Get a cached audio from shared data.

The data can be any of the formats described in AudioDataFormat.

This is shorthand for calling AUDIOS.audio with AudioSource::Data and AudioOptions::cache.

pub fn audio( &self, source: impl Into<AudioSource>, options: AudioOptions, limits: Option<AudioLimits>, ) -> AudioVar

Request an audio, with full load and cache configuration.

If limits is None the AUDIOS.limits is used.

Always returns a loading audio due to the deferred nature of services. If the audio is already in cache it will be set and bound to it once the current update finishes.

pub fn audio_task<F>( &self, source: impl IntoFuture<IntoFuture = F>, options: AudioOptions, limits: Option<AudioLimits>, ) -> AudioVar

where F: Future<Output = AudioSource> + Send + 'static,

Await for an audio source, then get or load the audio.

If limits is None the AUDIOS.limits is used.

This method returns immediately with a loading AudioVar, when source is ready it is used to get the actual AudioVar and binds it to the returned audio.

Note that the cache_mode always applies to the inner audio, and only to the return audio if cache_key is set.

pub fn register( &self, key: Option<AudioHash>, audio: (ViewAudioHandle, AudioMetadata, AudioDecoded), ) -> AudioVar

Associate the audio produced by direct interaction with the view-process with the key in the cache.

Returns an audio var that tracks the audio, note that if the key is already known does not use the audio data.

Note that you can register tracks in AudioTrack::insert_track, this method is only for tracking a new track.

Note that the audio will not automatically restore on respawn if the view-process fails while decoding.

pub fn clean(&self, key: AudioHash)

Remove the audio from the cache, if it is only held by the cache.

You can use AudioSource::hash128_read and AudioSource::hash128_download to get the key for files or downloads.

pub fn purge(&self, key: AudioHash)

Remove the audio from the cache, even if it is still referenced outside of the cache.

You can use AudioSource::hash128_read and AudioSource::hash128_download to get the key for files or downloads.

pub fn cache_key(&self, audio: &AudioTrack) -> Option<AudioHash>

Gets the cache key of an audio.

pub fn is_cached(&self, audio: &AudioTrack) -> bool

If the audio is cached.

pub fn clean_all(&self)

Clear cached audios that are not referenced outside of the cache.

pub fn purge_all(&self)

Clear all cached audios, including audios that are still referenced outside of the cache.

Audio memory only drops when all strong references are removed, so if an audio is referenced outside of the cache it will merely be disconnected from the cache by this method.

pub fn extend(&self, extension: Box<dyn AudiosExtension>)

Add an audios service extension.

See AudiosExtension for extension capabilities.

pub fn available_formats(&self) -> Vec<AudioFormat>

Audio formats implemented by the current view-process and extensions.

impl AUDIOS

pub fn open_output( &self, id: impl Into<AudioOutputId>, init: impl FnOnce(&mut AudioOutputOptions) + Send + 'static, ) -> ResponseVar<AudioOutput>

Open an audio output stream, or get a reference clone to the already open stream.

If the id is not already open the init closure is called to configure the output request. By default the configuration creates an output for the default audio output device, in the playing state, with 100% volume and speed.

Output remains open until all clones of it are dropped, or until the app exit if AudioOutput::perm is called.

Note that output streams are not direct connections to the audio output device, the view-process will mix all audio streams playing in parallel to the single audio output stream. Also note that usually the view-process will retain the device connection for the duration of the process, created with first output, this is the recommended behavior in most operating systems.