Crate phonic 

phonic is a cross-platform audio playback and DSP library for Rust. It provides a flexible, low-latency audio engine and related tools for desktop and web-based music applications

Overview

• Player is the central component that manages audio playback. It takes an output device instance, plays sounds and manages DSP effects.

• OutputDevice represents the audio backend stream. phonic provides implementations for different platforms, such as cpal for native applications and webauddio for WebAssembly. The DefaultOutputDevice is an alias for the recommended output device for the current build target.

• Source produces audio signals. You can use the built-in FileSource for playing back audio files, SynthSource for generating synthesized tones or can create your own source implementation. File sources can be preloaded into memory or streamed on-the-fly.

• Effect applies DSP effects to audio signals signals. By default, only one mixer is present in the player and will route all sources through it. To create more complex routings you can create sub-mixers via Player::add_mixer and route sources to them. Each mixer instance has its own chain of DSP effects, which can be set up via Player::add_effect. You can use the built in effects impls in effects or create your own ones.

Getting Started

Here’s a basic example of how to play audio files with DSP effects.

use phonic::{
    DefaultOutputDevice, Player, FilePlaybackOptions, Error,
    effects::{ChorusEffect, ReverbEffect, CompressorEffect},
};

fn main() -> Result<(), Error> {
    // Create a player with the default audio output device.
    let mut player = Player::new(DefaultOutputDevice::open()?, None);

    // Add a new sub-mixer with a chorus and reverb effect to the main mixer.
    let sub_mixer_id = {
        let mixer_id = player.add_mixer(None)?;
        player.add_effect(ChorusEffect::default(), mixer_id)?;
        player.add_effect(ReverbEffect::default(), mixer_id)?;
        mixer_id
    };

    // Add a limiter to the main mixer. All sounds, including the sub mixer's output
    // will be routed through this effect now.
    player.add_effect(CompressorEffect::new_limiter(), None)?;

    // Play a file with default options on the sub mixer. It will start playing immediately
    // and will be routed through a chorus and reverb effect and the main mixer's limiter.
    player.play_file("path/to/your/file.wav",
      FilePlaybackOptions::default().target_mixer(sub_mixer_id)
    )?;

    // Play a file with default options on the main mixer and schedule it two seconds ahead
    // of the current output time. It will be routed through the limiter effect only.
    let sample_rate = player.output_sample_rate() as u64;
    player.play_file("path/to/your/some_other_file.wav",
      FilePlaybackOptions::default().start_at_time(
        player.output_sample_frame_position() + 2 * sample_rate)
    )?;

    // The player's audio output stream runs on a separate thread, so we need to keep
    // the main thread alive to hear the audio.
    std::thread::sleep(std::time::Duration::from_secs(5));

    Ok(())
}

For more advanced usage, such as monitoring playback, sequencing source playback or managing creating more complex mixer graphs, please see the examples in the README.md and the /examples directory of the repository.

Modules

effects

Set of basic, common DSP Effect implementations.

outputs

Default OutputDevice implementations.

parameters

Effect Parameter implementations.

sources

Set of basic, common File & Synth tone Source implementations.

utils

DSP tools, musical unit conversion functions and related UI tools.

Structs

FilePlaybackOptions

Options to control playback of a FileSource.

Player

Playback controller, which continuously fills an OutputDevices stream with audio data generated by one or more Sources.

SourceTime

Timing info for Source impls.

SynthPlaybackOptions

Options to control playback of a SynthSource.

Enums

Error

Provides an enumeration of all possible errors reported by phonic.

FilePlaybackMessage

Events to control playback of a FileSource

ParameterScaling

Effect parameter scaling for float parameters, applied to convert normalized UI or automation values to the internal values.

ParameterType

Describes the type of a Parameter to e.g. select a proper visual representation in a UI.

ParameterValueUpdate

An update for a Parameter’s value, consumed by Effects in audio time.

PlaybackStatusEvent

Events send back from File or Synth sources via the player to the user.

ResamplingQuality

The resampler quality an audio source should be resampled with.

SynthPlaybackMessage

Events to control playback of a synth source

Traits

ClonableParameter

Allows creating dyn Parameter clones.

Effect

Effects manipulate audio samples in f32 format and can be Send and Synced across threads.

EffectMessage

Carries Effect specific payloads/automation, which can’t or should not be expressed as Parameter.

FileSource

A source which decodes and plays back an audio file.

OutputDevice

Audio output stream device.

Parameter

Describes a single parameter of an Effect for use in UIs or for automation.

Source

Source types produce audio samples in f32 format and can be Send and Synced across threads.

SynthSource

A source which creates samples from a synthesized signal.

Type Aliases

DefaultOutputDevicecpal-output or web-output

The enabled audio output type: cpal or web

EffectId

Unique ID for newly added effects.

EffectMessagePayload

Type used in Effect::process_message to receive messages.

EffectTime

Frame and wall-clock time reference for an audio effect’s process function.

MixerId

Unique ID for newly added mixers.

PlaybackId

Unique ID for played back file or synth sources.

PlaybackStatusContext

Custom context type for playback status events.