Crate petalsonic 

PetalSonic Core

A real-time safe spatial audio library for Rust that uses Steam Audio for 3D spatialization.

PetalSonic provides a world-driven API where the main thread owns and updates a 3D world (listener + sources), while fixed-size audio processing threads handle spatialization and playback in a real-time safe manner.

Quick Start

use petalsonic_core::*;
use std::sync::Arc;

// Create a world configuration
let config = PetalSonicWorldDesc::default();

// Create the audio world
let world = PetalSonicWorld::new(config.clone())?;

// Create and start the audio engine
let mut engine = PetalSonicEngine::new(config, &world)?;
engine.start()?;

// Load audio data
let audio_data = audio_data::PetalSonicAudioData::from_path("audio.wav")?;

// Register audio with spatial configuration
let source_id = world.register_audio(
    audio_data,
    SourceConfig::spatial(Vec3::new(5.0, 0.0, 0.0), 1.0)
)?;

// Play the audio
world.play(source_id, playback::LoopMode::Once)?;

// Update listener position as your camera/player moves
world.set_listener_pose(Pose::from_position(Vec3::new(0.0, 0.0, 0.0)));

// Poll for events
for event in engine.poll_events() {
    match event {
        PetalSonicEvent::SourceCompleted { source_id } => {
            println!("Audio completed: {:?}", source_id);
        }
        _ => {}
    }
}

Key Components

• PetalSonicWorld: Main API for managing audio sources and playback on the main thread
• PetalSonicEngine: Audio processing engine that runs on a dedicated thread
• SourceConfig: Configuration for spatial vs. non-spatial audio sources
• PetalSonicAudioData: Audio data loaded from files
• PetalSonicEvent: Events emitted by the engine (completion, errors, etc.)

Architecture

PetalSonic uses a three-layer threading model:

1. Main Thread: Owns PetalSonicWorld, loads audio, sends commands
2. Render Thread: Processes commands, spatializes audio, generates samples
3. Audio Callback: Lock-free consumption from ring buffer to audio device

This architecture ensures real-time safety: no allocations or locks in the audio callback path.

Features

• Steam Audio integration for high-quality HRTF-based spatialization
• Support for both spatial and non-spatial audio sources
• Real-time safe audio processing
• Automatic resampling to world sample rate
• Loop modes: once, infinite, or counted loops
• Event-driven architecture for playback notifications
• Performance profiling via timing events

Re-exports

pub use config::PetalSonicWorldDesc;

pub use config::SourceConfig;

pub use engine::AudioFillCallback;

pub use engine::PetalSonicEngine;

pub use error::PetalSonicError;

pub use events::PetalSonicEvent;

pub use events::RenderTimingEvent;

pub use playback::PlayState;

pub use playback::PlaybackCommand;

pub use playback::PlaybackInfo;

pub use playback::PlaybackInstance;

pub use world::PetalSonicAudioListener;

pub use world::PetalSonicAudioSource;

pub use world::PetalSonicWorld;

pub use world::SourceId;

Modules

audio_data

Audio data loading and management.

config

engine

error

Error types for PetalSonic

events

Event types for PetalSonic

math

Math types for PetalSonic

mixer

playback

Playback control and state management.

spatial

world