Audio playback via native OS backends or host CLI players, with format detection, capability-ranked player matching, 88 embedded sound effects, output-channel routing, and optional OS-specific audio ducking. Use when working with audio playback, the playa package, so-you-say TTS CLI, or implementing sound effects.
Audio playback library that prefers native OS playback when available, falls back to host CLI players when needed, provides 88 embedded sound effects, and supports optional OS-specific audio ducking.
// Simple playback
let audio = Audio::from_path("audio.wav")?;
audio.play()?;
// Builder API with options
Playa::from_path("audio.mp3")?
.speed(1.25)
.volume(0.8)
.play()?;
Playa is no longer just a host-player wrapper.
--force-host or .force_host() skips the native pathNative audio uses bounded device-open deadlines. If a native device-open operation times out, Playa trips a process-local circuit breaker and future native playback attempts fall back directly to host playback for the rest of the process.
Host players are ranked by capability (speed, volume, streaming). Top tier (score 9): mpv, FFplay, SoX.
// Get ranked compatible players
let players = match_available_players(format);
let best = players.first().expect("No compatible player installed");
// Feature-gated: sfx-ui, sfx-cartoon, sfx-reactions, etc.
let effect = SoundEffect::from_name("sad-trombone").expect("effect enabled");
effect.play()?;
Native SFX playback is OS-specific when enabled:
AudioCategory_SoundEffectsmedia.role=eventIf the native SFX path fails, Playa falls back to regular playback or host-player delegation.
playa audio.wav # Play file
playa play --fast audio.mp3 # 1.25x speed
playa effect sad-trombone # Built-in effect
playa list-effects # List all effects
playa list-effects cartoon # Filter effects
playa players # Show host player table
playa output-channels # Show native output devices (with `sfx-native`)
playa --channel "<device>" tone.wav # Route to a specific output device
playa duck-info # Audio ducking backend info
playa --no-duck audio.wav # Disable ducking
playa --force-host audio.wav # Skip native playback
Shell completions are available for Bash, Zsh, and Fish. Effect names, audio files, volume levels, and output channels autocomplete.
Feature-gated via audio-ducking plus the OS slice for the target platform.
use playa::ducking::DuckConfig;
let config = DuckConfig::new(750, 0.25)?;
Playa::from_path("audio.mp3")?
.with_ducked_audio(config)
.play_async()
.await?;
Current backend behavior:
Practical notes:
playa duck-info is the fastest way to inspect the selected backend on the current machine