tpt-av-control

A pure-Rust, real-time safe studio protocol suite. OSC, MIDI 2.0, DMX, and hardware control. The integration layer of the TPT AV stack.

License: MIT OR Apache-2.0 Status: Early-stage / Pre-1.0 Ecosystem: TPT Solutions Open Source

---

Overview

tpt-av-control is the protocol and hardware integration layer of the TPT AV Stack. It provides pure-Rust, real-time safe implementations of the studio control protocols used in audio, video, lighting, and live performance.

• Unified protocol suite — OSC, MIDI 2.0 (UMP), DMX512, Art-Net, and sACN in one cohesive library.
• Real-time safe — protocol parsing is allocation-free and lock-free where it matters; safe to feed results to audio callbacks.
• MIDI 2.0 / UMP native — full support for Universal MIDI Packet with MIDI 1.0 backward compatibility.
• Hardware control surfaces — a unified API for physical controllers (mixers, Stream Decks, generic MIDI).
• Permissive licensing — dual MIT OR Apache-2.0, zero copyleft contamination, enforced via cargo-deny in CI.

Crates

Every crate ships its own README (usage, protocol notes, testing) and CHANGELOG alongside its sources.

Crate	Purpose
tpt-av-control-utils	Shared types, errors, lock-free RT queue, timecode, parameter mapping
tpt-av-control-osc	Open Sound Control 1.0/1.1: parse, encode, UDP server/client
tpt-av-control-midi	MIDI 1.0 and MIDI 2.0 (UMP), device I/O, clock, MTC/MSC, MIDI-CI
tpt-av-control-dmx	DMX512 universes, Art-Net, sACN/E1.31, fixture definitions
tpt-av-control-surface	Hardware control surfaces (generic MIDI, X32, Stream Deck, custom)
tpt-av-control-webrtc	WebRTC data channel transport for networked control

avctl is a companion command-line tool (not published to crates.io) for sending/monitoring OSC, MIDI, and DMX traffic on-site — useful for checking a console's OSC output or watching MIDI CCs arrive without writing any Rust. See its README for the full command list.

Engines integrating with this suite: see INTEGRATION.md for the Message/MessageQueue contract consumed by tpt-audio and tpt-visual.

Get started in under 5 minutes

No hardware required — these loop back to themselves over a real network socket:

cargo run -p tpt-av-control-examples --bin hello_dmx   # cross-fades a virtual RGB fixture
cargo run -p tpt-av-control-examples --bin hello_midi   # prints notes from a connected MIDI device

Quick start

[dependencies]
tpt-av-control-osc = "0.1"

use tpt_av_control_osc::{OscClient, OscMessage, OscArg};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let target = "127.0.0.1:8000".parse()?;
    let mut client = OscClient::new(target)?;
    let msg = OscMessage::new("/track/1/volume", &[OscArg::Float(0.75)])?;
    client.send(&msg)?;
    Ok(())
}

Each crate is independently useful — use just OSC, just MIDI, or just DMX.

Examples

Runnable demos live in the examples workspace member:

cargo run -p tpt-av-control-examples --bin osc_server
cargo run -p tpt-av-control-examples --bin midi_controller
cargo run -p tpt-av-control-examples --bin dmx_lighting
cargo run -p tpt-av-control-examples --bin control_surface
cargo run -p tpt-av-control-examples --bin hello_dmx
cargo run -p tpt-av-control-examples --bin hello_midi

Config-driven fixtures & mappings

With the serde feature, tpt-av-control-dmx fixture patches and tpt-av-control-surface mappings can be loaded from JSON instead of built in Rust — useful for non-Rust-fluent lighting/AV techs. See the tpt-av-control-dmx and tpt-av-control-surface READMEs.

Observability

tpt-av-control-osc, -midi, -dmx, and -utils support an optional tracing feature that emits spans/events for received packets, parse failures, and dropped (queue-full) messages — the signals you want when diagnosing a live show. See the per-crate READMEs' "Observability" sections.

Real-time safety

Protocol parsing (parse_osc_message, parse_midi1, UMP handling) performs no heap allocation for fixed-size messages, and network I/O is kept off the real-time thread:

Network Thread (async, can allocate)   →  lock-free SPSC queue  →  Audio/Video Thread (zero allocation)
MIDI Thread (blocking, can allocate)   →  lock-free SPSC queue  →

License

Dual-licensed under either of

• Apache License, Version 2.0 (LICENSE-APACHE)
• MIT license (LICENSE-MIT)

at your option. Dependencies are restricted to permissively licensed crates (MIT, Apache-2.0, BSD, ISC, Zlib); GPL/LGPL/AGPL/MPL are banned and enforced by deny.toml in CI.

See CONTRIBUTING.md for contribution terms.