shairplay-rust

Pure Rust AirPlay server library

A complete AirPlay audio and video receiver as a Rust library. Supports both classic AirPlay (AP1) and AirPlay 2 (AP2) with buffered audio, encrypted transport, HomeKit pairing, and screen mirroring. #![forbid(unsafe_code)].

This is a clean-room Rust implementation — not a wrapper or FFI binding. Every protocol handler, codec, and cryptographic primitive has been reimplemented from scratch in safe Rust. No C code from shairplay, shairport-sync, or any other project is linked or called.

⚠️ Pre-1.0 notice: This crate is under active development. Minor version bumps (e.g. 0.1 → 0.2) may include breaking API changes. Pin your dependency to a specific minor version (shairplay = "0.2") and review the CHANGELOG before upgrading.

Installation

Add the current release from crates.io:

cargo add shairplay

Enable only the protocol capabilities required by the application:

cargo add shairplay --features ap2
cargo add shairplay --features video

Features

	Feature	Details
🎵	AirPlay 1 (Classic)	ALAC/L16 decode, optional AES encryption, DACP remote control — rock solid
🎵	AirPlay 2	Buffered AAC, SRP-6a pairing, ChaCha20-Poly1305 encrypted RTSP
🔊	Multichannel	5.1 and 7.1 AAC decode with ITU-R BS.775 mixdown to stereo
🔄	Resampling	Automatic sample rate conversion via rubato
🔐	HomeKit pairing	Transient (PIN 3939) and normal (persistent key storage)
📺	Video	Screen mirroring — work in progress, behind `video` feature gate
🎬	HLS Video	YouTube and other HLS streams — receiver relays URL to app
🌐	Cross-platform	macOS (native Bonjour) + Linux (pure Rust mDNS)
🔒	Pure safe Rust	`#![forbid(unsafe_code)]`, no C code in this crate¹
⚡	Async	Built on tokio
🛎️	Error notifications	Pairing, SETUP, and codec failures surfaced to your app via `AudioHandler::on_error`

¹ The crate itself contains no unsafe code. On macOS, mDNS service registration uses astro-dnssd, which internally calls Apple's Bonjour C API via FFI. On Linux, mdns-sd provides a pure Rust mDNS implementation with no native dependencies.

Quick Start

AirPlay 1 (Classic)

use std::sync::Arc;
use shairplay::{RaopServer, AudioHandler, AudioSession, AudioFormat};

struct MyHandler;
impl AudioHandler for MyHandler {
    fn audio_init(&self, format: AudioFormat) -> Box<dyn AudioSession> {
        println!("Stream: {}ch {}bit {}Hz", format.channels, format.bits, format.sample_rate);
        Box::new(MySession)
    }
}

struct MySession;
impl AudioSession for MySession {
    fn audio_process(&mut self, samples: &[f32]) {
        // F32 interleaved PCM.
    }
}

#[tokio::main]
async fn main() -> Result<(), shairplay::ShairplayError> {
    let mut server = RaopServer::builder()
        .name("My Speaker")
        .build(Arc::new(MyHandler))?;
    server.start().await?;
    tokio::signal::ctrl_c().await.unwrap();
    server.stop().await;
    Ok(())
}

AirPlay 2

// AP2 adds resampling and multichannel mixdown. Audio-only streams are
// delivered as f32 PCM. Screen-mirroring AAC-ELD is delivered through
// AudioSession::audio_process_encoded for an application decoder.
let mut server = RaopServer::builder()
    .name("My Speaker")
    .output_sample_rate(48000)
    .output_max_channels(2)
    .build(Arc::new(MyHandler))?;

// Or force AP1 mode at runtime (even with ap2 feature compiled in):
use shairplay::AirPlayMode;
let mut server = RaopServer::builder()
    .name("My Speaker")
    .mode(AirPlayMode::AirPlay1)
    .build(Arc::new(MyHandler))?;

Builder Options

Method	Default	Feature	Description
`.name()`	`"Shairplay"`		AirPlay display name
`.hwaddr()`	random locally administered address		6-byte MAC address for mDNS
`.port()`	`5000`		RTSP listening port
`.password()`	none		HTTP Digest auth password
`.max_clients()`	`10`		Maximum concurrent connections
`.bind()`	all interfaces		Bind to specific IPs (multi-interface)
`.header_diagnostics()`	`Disabled`	`diagnostic-headers`	Structured, redacted RTSP header diagnostics
`.advertise_codecs()`	PCM + ALAC	AP1	Set the ordered AP1 `cn` capability list
`.advertise_encryption()`	none	AP1	Set the ordered AP1 `et` capability list
`.output_sample_rate()`	source rate	`resample`	Resample all audio to this rate
`.output_max_channels()`	source channels	`resample`	Mix down to this channel count
`.pin()`	`"3939"`	`ap2`	PIN for HomeKit pairing
`.mode()`	`AirPlayMode::AirPlay2`	`ap2`	Runtime protocol mode (AP1 or AP2)
`.pairing_store()`	`MemoryPairingStore`	`ap2`	Persistent key storage
`.video_handler()`	none	`video`	Video session factory
`.hls_handler()`	none	`hls`	HLS video playback handler

AirPlay 1 Discovery Capabilities

AP1 advertises PCM and ALAC by default (cn=0,1) and uses unencrypted audio transport by default (et=0) for broad sender compatibility. HTTP Digest authentication configured with .password() controls access but does not encrypt the audio payload.

Deployments that require encrypted AP1 transport can advertise only the modes their senders support:

use shairplay::{Ap1Codec, Ap1Encryption, RaopServer};

let builder = RaopServer::builder()
    .advertise_codecs([Ap1Codec::Alac, Ap1Codec::Pcm])
    .advertise_encryption([Ap1Encryption::Rsa, Ap1Encryption::FairPlay]);

The order supplied by the application is preserved. Empty and duplicate lists are rejected during build(). With the ap2 feature enabled, also select AirPlayMode::AirPlay1; AP2 uses a separate fixed capability profile.

Feature Flags

Flag	Dependencies	Description
(default)	—	AirPlay 1 only
`diagnostic-headers`	none	Opt-in, redacted RTSP request and response header diagnostics
`dangerous-raw-headers`	(implies `diagnostic-headers`)	Raw header values for explicit use in debug-assertion builds
`resample`	rubato	Sample rate conversion + channel mixdown
`ap2`	chacha20poly1305, hkdf, symphonia, … (implies `resample`)	Full AirPlay 2 audio
`video`	(implies `ap2`)	Legacy feature set for screen mirroring (`0x527FFEE6`)
`hls`	(implies `video`)	HLS video playback (YouTube, etc.) — receiver relays URL to app

RTSP Header Diagnostics

Header diagnostics are compiled out by default. With the diagnostic-headers feature enabled, applications must still select a policy and enable the dedicated shairplay::protocol_headers tracing target at TRACE:

use shairplay::{HeaderDiagnostics, RaopServer};

let builder = RaopServer::builder()
    .header_diagnostics(HeaderDiagnostics::Redacted);

Redacted exposes values only for a conservative metadata allowlist. Sensitive and unknown header values are replaced with <redacted>. Bodies and media payloads are never logged.

The separate dangerous-raw-headers feature adds HeaderDiagnostics::Raw. Raw mode can expose credentials, pairing material, and stable device identifiers, requires explicit runtime selection, and is rejected by build() when debug assertions are disabled. Control characters remain escaped in every mode.

Implementation Status

✅ AirPlay 1 — Production Ready

Rock solid. ALAC and raw L16 PCM decoding, optional AES encryption, DACP remote control, metadata (artwork, progress, track info). Works with iPhone, iPad, Mac, iTunes, and PipeWire senders.

✅ AirPlay 2 Audio — Production Ready

Full pipeline: SRP-6a pairing → encrypted RTSP → FairPlay → PTP timing → buffered AAC decode → f32 PCM output. Multichannel 5.1/7.1 with ITU-R BS.775 mixdown. Automatic resampling. Both stream types implemented:

Type 103 (buffered) — AAC over TCP with timed playout buffer. Used for music.
Type 96 (realtime) — ALAC over UDP with immediate delivery. Used for Siri, phone calls, system sounds.

Connections are instant (starts streaming in under 50ms) using deterministic key persistence and correct eventPort handling on isRemoteControlOnly channels, matching commercial receiver capabilities.

🧪 Video (Screen Mirroring) — Work in Progress

Behind the video feature gate. Screen mirroring uses the legacy/UxPlay-compatible feature set; AP2 buffered audio is intentionally disabled while video is enabled.

The video feature switches to a UxPlay-compatible legacy feature set (0x527FFEE6) to receive screen mirroring data from iOS 18+. AP2 buffered audio is not available — the iPhone falls back to legacy ALAC (type 96) which is fully supported with FairPlay key decryption and NTP timing.

Video decryption is implemented for the legacy feature-set path; AP2+video hybrid operation remains research work. See AP2-STATUS.md for details.

🔬 Remote Control

AP1 DACP remote control is fully implemented and works.

Third-party AP2 receivers cannot send playback commands (play/pause/skip) to the iPhone. All paths require Apple ecosystem trust:

Type 130 MRP data channel — requires HomeKit seed (Home app pairing)
Companion-link protocol — requires same Apple ID
DACP — iPhone doesn't send Active-Remote header in AP2

See AP2-STATUS.md for the full research. If you have further insights or want to help investigate, please reach out!

Example Player

The included example plays AirPlay audio through the system's default output device:

# AirPlay 1
cargo run --example player

# AirPlay 2
cargo run --example player --features ap2

# With resampling to match output device rate (e.g. 44100→96000 Hz)
cargo run --example player --features ap2 -- --resample

# With persistent device identity (stable MAC + paired keys across restarts)
cargo run --example player --features ap2 -- --persist state.json

# Custom name and interface binding
cargo run --example player --features ap2 -- --name "Kitchen" --bind 192.168.1.100 --persist state.json --resample

# HLS video (YouTube) — requires mpv installed
cargo run --example player --features hls -- --resample

Without --persist, the device gets a random MAC each run and the iPhone treats it as a new device. With --persist, the MAC and paired keys are saved to a JSON file.

Without --resample, audio is delivered at the source's native rate (44100 Hz). If your output device runs at a different rate (e.g. 96000 Hz), use --resample to convert in the example app.

Architecture

src/
├── raop/                RAOP server, RTSP handlers, RTP streaming
│   ├── buffered_audio   AP2 timed playout buffer with decrypt/decode/resample
│   ├── event_channel    AP2 encrypted event channel
│   ├── video            Video handler traits (experimental)
│   └── video_stream     Video stream receiver (experimental)
├── crypto/              RSA, Ed25519+Curve25519, AES, FairPlay
│   ├── pairing_homekit  AP2 SRP-6a + HomeKit pairing + pair-verify
│   ├── chacha_transport AP2 ChaCha20-Poly1305 encrypted RTSP
│   ├── video_cipher     AES-128-CTR streaming cipher for video
│   └── tlv              AP2 TLV codec for pairing messages
├── codec/               Audio decoders
│   ├── alac             ALAC decoder (AP1)
│   ├── aac              AAC decoder via symphonia (AP2)
│   └── resample         Sample rate conversion + channel mixdown
├── proto/               SDP, HTTP/RTSP, binary plist, HTTP Digest auth
├── net/                 Async TCP server, mDNS, PTP timing, feature flags
├── dacp/                DACP remote control client (AP1)
└── error/               Error types

Test Coverage

The test suite includes 17 C-verified pairing vectors from pair_ap and 10 C-verified FairPlay vectors generated from the original shairplay C source:

cargo test                    # AP1 tests
cargo test --features ap2     # AP1 + AP2 tests
cargo test --features video   # All tests

Development

brew install lefthook gitleaks
lefthook install
lefthook run pre-push

The hooks enforce commit format, staged-file hygiene, secret scanning, formatting, and the bounded pre-push checks. CI runs the complete feature, platform, dependency-policy, and coverage matrix.

Acknowledgments

This project builds on the work of many contributors to the AirPlay open-source ecosystem:

shairplay — Original C library this project is a complete rewrite of
shairport-sync — AirPlay 2 C reference implementation by Mike Brady
pair_ap — HomeKit pairing reference (SRP-6a, TLV, HKDF) by Scott Ickle / ejurgensen. 17 C-verified test vectors generated from this codebase
AirPlay 2 Internals — Protocol documentation by Emanuele Cozzi
Unofficial AirPlay Specification — Legacy protocol documentation
rairplay — Rust AirPlay 2 receiver with video support
pyatv — Python Apple TV library (companion-link protocol research)
Dissecting the Media Remote Protocol — Evan Coleman's Apple TV reverse engineering

License

LGPL-3.0-or-later

Disclaimer

All resources in this repository are written using only freely available information from the internet. The code and related resources are meant for educational purposes only. It is the responsibility of the user to make sure all local laws are adhered to. Parts of this project are generated with the help of AI and the expert-in-the-loop approach.

Name		Name	Last commit message	Last commit date
.config		.config
.github		.github
.kiro/steering		.kiro/steering
examples/player		examples/player
fuzz		fuzz
scripts		scripts
src		src
tests		tests
.codacy.yml		.codacy.yml
.editorconfig		.editorconfig
.gitignore		.gitignore
.gitleaks.toml		.gitleaks.toml
.release-please-manifest.json		.release-please-manifest.json
AP2-STATUS.md		AP2-STATUS.md
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
Cargo.lock		Cargo.lock
Cargo.toml		Cargo.toml
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
airport.key		airport.key
deny.toml		deny.toml
lefthook.yml		lefthook.yml
release-please-config.json		release-please-config.json
rust-toolchain.toml		rust-toolchain.toml
rustfmt.toml		rustfmt.toml

Navigation Menu

Uh oh!

Repository files navigation

shairplay-rust

Installation

Features

Quick Start

AirPlay 1 (Classic)

AirPlay 2

Builder Options

AirPlay 1 Discovery Capabilities

Feature Flags

RTSP Header Diagnostics

Implementation Status

✅ AirPlay 1 — Production Ready

✅ AirPlay 2 Audio — Production Ready

🧪 Video (Screen Mirroring) — Work in Progress

🔬 Remote Control

Example Player

Architecture

Test Coverage

Development

Acknowledgments

License

Disclaimer

About

Releases

Packages

Contributors

Languages

Uh oh!

Latest commit

History

Folders and files

Repository files navigation

shairplay-rust

Installation

Features

Quick Start

AirPlay 1 (Classic)

AirPlay 2

Builder Options

AirPlay 1 Discovery Capabilities

Feature Flags

RTSP Header Diagnostics

Implementation Status

✅ AirPlay 1 — Production Ready

✅ AirPlay 2 Audio — Production Ready

🧪 Video (Screen Mirroring) — Work in Progress

🔬 Remote Control

Example Player

Architecture

Test Coverage

Development

Acknowledgments

License

Disclaimer

About

Resources

Contributing

Security policy

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages