Crate phonic

Expand description

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. 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 in effects or create your own.

§Getting Started

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

use std::time::Duration;

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);

    // Memorize some consts for event scheduling.
    let now = player.output_sample_frame_position();
    let samples_per_sec = player.output_sample_rate() as u64;

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

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

    // Change effect parameters via the returned handles.
    // Schedule a parameter change 3 seconds from now (sample-accurate)
    limiter.set_parameter(CompressorEffect::MAKEUP_GAIN_ID, 3.0, now + 3 * samples_per_sec);
  
    // Play a file and get a handle to control it.
    let file = player.play_file("path/to/your/file.wav",
      FilePlaybackOptions::default().target_mixer(sub_mixer_id)
    )?;

    // Change sources via the returned handles.
    // Schedule a stop 2 seconds from now (sample-accurate)
    file.stop(now + 2 * samples_per_sec)?;

    // Play another file on the main mixer with scheduled start time
    let some_other_file = player.play_file("path/to/your/some_other_file.wav",
      FilePlaybackOptions::default().start_at_time(now + 2 * samples_per_sec)
    )?;

    // The player's audio output stream runs on a separate thread, so we keep
    // the main thread running here, until all files finished playing.
    while file.is_playing() || some_other_file.is_playing() {
        std::thread::sleep(Duration::from_millis(100));
    }

    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§

EffectHandle: Automate Effect parameters or send messages.
FilePlaybackHandle: Change runtime playback properties of a playing FileSource and test if a source is still playing.
FilePlaybackOptions: Options to control playback properties 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.
SynthPlaybackHandle: Change runtime playback properties of a playing SynthSource and test if a source is still playing.
SynthPlaybackOptions: Options to control playback properties of a SynthSource.

Enums§

EffectMovement: How to move an effect within a mixer.
Error: Provides an enumeration of all possible errors reported by phonic.
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.
SourcePlaybackHandle: A unified FilePlaybackHandle and SynthPlaybackHandle.
SynthPlaybackMessage: Events to control playback of a SynthSource

Traits§

ClonableParameter: Allows creating dyn Parameter clones.
Effect: Effects manipulate audio samples in f32 format and can be Send and Synced across threads. Buffers are processed in-place in the audio real-time thread.
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.

Crate phonic

Crate phonic Copy item path

§Overview

§Getting Started

Modules§

Structs§

Enums§

Traits§

Type Aliases§

Crate phonic