oxisound — The COOLJAPAN audio device I/O facade

oxisound is the top-level façade crate for the OxiSound ecosystem. It gives you one flat, ergonomic API — open_output, open_input, play_callback, enumerate_devices, and friends — that hides which backend is doing the work. Cargo feature flags select the backend: the default pure feature uses the cpal backend (oxisound-cpal), while optional features pull in native JACK (oxisound-jack), MIDI device I/O (oxisound-midi), Standard MIDI File support (oxisound-smf), or Open Sound Control (oxisound-osc). All device traits and shared types come from oxisound-core and are re-exported at the crate root, so most programs only ever use oxisound::….

The crate is #![forbid(unsafe_code)] at the facade layer. Pure-Rust status depends on the features you enable. The default pure (cpal), tokio, midi, smf, and osc paths are Pure Rust. The jack and jack-native features link the system libjack2, and the asio feature requires the Steinberg ASIO SDK — these are not Pure Rust and exist only as opt-in escape hatches for low-latency professional audio.

Installation

[dependencies]
# Default: Pure-Rust cpal backend
oxisound = "0.1.3"

# Async streaming (tokio) + Pure-Rust playback
oxisound = { version = "0.1.3", features = ["tokio"] }

# Add live MIDI + Standard MIDI File playback
oxisound = { version = "0.1.3", features = ["midi", "smf"] }

# Add Open Sound Control
oxisound = { version = "0.1.3", features = ["osc"] }

Quick Start

use oxisound::StreamConfig;

// Open the default output device and play a 1-second sine tone.
let mut stream = oxisound::open_output(StreamConfig::stereo_48k())
    .expect("no output device");
let buf = oxisound::sine_test_tone(440.0, 1.0, StreamConfig::stereo_48k());
stream.write(&buf).expect("write failed");

Zero-copy real-time callback

use oxisound::StreamConfig;

// The closure runs on the real-time audio thread; drop the guard to stop.
let _guard = oxisound::play_callback(StreamConfig::stereo_48k(), |buf| {
    for s in buf.iter_mut() {
        *s = 0.0; // fill with your own DSP
    }
}).expect("no output device");

Enumerate devices

let devices = oxisound::enumerate_devices().expect("enumeration failed");
print!("{}", oxisound::format_devices(&devices));

Feature Flags

The smf + midi combination additionally unlocks play_smf (parse and play a .mid straight to a MIDI port).

API Overview

Test-tone generators (no hardware, always available)

Pure-computation helpers that return interleaved Vec<f32> buffers — handy for tests, demos, and DSP scaffolding.

Device & stream entry points (pure feature)

Callback streams (pure feature)

Monitoring, hot-plug & resilience

Async streaming (tokio feature)

MIDI device I/O (midi feature)

Standard MIDI File (smf feature)

Open Sound Control (osc feature)

Re-exports from oxisound-osc: OscArg, OscMessage, OscBundle, OscPacket, OscTimeTag, OscError, OscSender, OscReceiver, plus encode_osc / decode_osc (the crate's encode / decode functions, renamed at re-export).

Native JACK (jack-native feature — not Pure Rust)

Session & permissions

Re-exported core types (always at crate root)

From oxisound-core: AudioDevice, InputStream, OutputStream, DuplexStream, StreamConfig, StreamStats, SampleFormat, NegotiatedConfig, Channel, ChannelRouting, HostApi, DeviceInfo, DeviceCapabilities, DeviceEvent, DeviceSelector, DefaultSelector, NameMatchSelector, LatencyOptimalSelector, DeviceNotificationCallback, CallbackPriority, MidiDevice, MidiInput, MidiOutput, MidiDeviceInfo, MidiMessage, SessionCategory, SessionInterruptionEvent, and the crate error type OxiSoundError.

Backend-specific re-exports appear under their features: CpalDevice, CpalOutputStream, CpalCallbackInputStream, CpalCallbackOutputStream, CpalDeviceWatcher, DeviceChangeGuard, AdaptiveBufferSizer, StreamHealth (pure); CpalAsyncInputStream, CpalAsyncOutputStream, AsyncInputStream, AsyncOutputStream (tokio).

Platform Support

Related crates

• oxisound-core — device/stream traits and shared types (re-exported here)
• oxisound-cpal — the default Pure-Rust cpal backend (pure, tokio, wasm, jack, asio)
• oxisound-jack — native JACK client backend (jack-native)
• oxisound-midi — live MIDI device I/O (midi)
• oxisound-smf — Standard MIDI File reader/writer/player (smf)
• oxisound-osc — Open Sound Control codec and UDP transport (osc)
• oxisound-session — iOS/macOS audio session management (session, macos-session)

License

Apache-2.0 — COOLJAPAN OU (Team Kitasan)