---

⚠️ 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.

⚖️ FairPlay notice: The FairPlay code (feature fairplay, on by default) has a provenance uncertainty: earlier releases were a port of a GPL-3.0 library, and the current rewrite is not a clean-room implementation. Details and how to opt out: docs/fairplay-provenance.md.

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

The fairplay feature is on by default. If you need to leave the FairPlay code out because of its provenance uncertainty, see docs/fairplay-provenance.md:

cargo add shairplay --no-default-features

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 — same format for AP1 and AP2
    }
}

#[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.
// Output is always f32 interleaved PCM — same as AP1.
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
.pipewire_auth_setup_compat()	false	pipewire-auth-setup-compat	Experimental fixed-probe acknowledgement in classic RAOP; not MFi authentication
.max_clients()	10		Maximum concurrent connections
.bind()	all interfaces		Bind to specific IPs (multi-interface)
.mdns_scope()	MdnsScope::All		Limit the mDNS announcement to the interfaces that carry given addresses (Linux, Windows and macOS)
.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

Limiting the mDNS announcement

.bind() limits the listeners only. Without .mdns_scope() the records still leave on every interface of the host, so a receiver bound to eth0 is also announced on nebula1.

use shairplay::{BindConfig, MdnsScope, RaopServer};

let bind = BindConfig::new().addrs(["192.168.1.10".parse().unwrap()]);
let server = RaopServer::builder()
    .mdns_scope(MdnsScope::from_bind(&bind))
    .bind(bind)
    .build(handler)?;

start() fails if an address is a wildcard or belongs to no interface of the host. It never falls back to announcing everywhere. RaopServer::mdns_scope_applied() reports what applies:

Platform	Result
Linux and others (mdns-sd)	Interfaces(..). The address selects the interface, so other addresses on it are announced too.
macOS (Bonjour)	Interfaces(..). Each service is registered once per interface index, which limits its service records (PTR, SRV, TXT). The address records of the host belong to the system and stay on every interface.

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]); // FairPlay needs the `fairplay` feature (on by default)

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.

Conformant MFi-SAP (et=4) is neither advertised nor implemented. The experimental pipewire-auth-setup-compat feature can acknowledge one fixed POST /auth-setup probe; it does not authenticate the receiver or encrypt audio. See the /auth-setup protocol status for the evidence, limits and requirements for conformant receiver authentication.

Feature Flags

Flag	Dependencies	Description
(default)	fairplay	AirPlay 1 with FairPlay
pipewire-auth-setup-compat	none	Experimental PipeWire probe acknowledgement; explicit runtime opt-in required
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
fairplay	none (on by default)	FairPlay handshake and key decryption (/fp-setup, a=fpaeskey, Ap1Encryption::FairPlay). Provenance uncertainty, see docs/fairplay-provenance.md
ap2	chacha20poly1305, hkdf, symphonia, … (implies resample)	Full AirPlay 2 audio
video	(implies ap2 and fairplay)	Legacy feature set for screen mirroring (0x527FFEE6)
hls	(implies video)	HLS video playback (YouTube, etc.) — receiver relays URL to app

Experimental PipeWire Probe Compatibility

Compile with --features pipewire-auth-setup-compat, then explicitly opt in:

let builder = shairplay::RaopServer::builder()
    .pipewire_auth_setup_compat(true);

When ap2 is also compiled in, select classic mode explicitly:

let builder = shairplay::RaopServer::builder()
    .mode(shairplay::AirPlayMode::AirPlay1)
    .pipewire_auth_setup_compat(true);

The default stays disabled, including in debug and all-feature builds. Enabling it in AirPlayMode::AirPlay2 is rejected; already AP2-paired connections cannot use this compatibility response. Discovery is unchanged. Only an exact, bounded public probe receives an empty acknowledgement, after the normal Digest check. This is not MFi authentication or a confidentiality guarantee. Do not enable it as a substitute for encryption.

Local simulated-sender tests cover PCM delivery over UDP/TCP, teardown and reconnect. Real PipeWire playback remains unqualified, and the current sender's Digest flow does not establish password-protected interoperability. See the contract and known limitations before deployment; the feature does not automatically configure a PipeWire sender.

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.

Scope: the AP2 profile implements HomeKit pairing and, with the fairplay feature, FairPlay, but not licensed MFi-SAP receiver authentication through /auth-setup. The profile does not advertise et=4 or the MFi feature bits; see the /auth-setup protocol status.

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 256 golden FairPlay vectors produced by running the C reference of shairplay (tests/data/fairplay_golden.txt), plus vectors for the individual steps:

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
• playfair — FairPlay library by EstebanKubata, shipped by shairplay under the GPL-3.0. The FairPlay code here was written with knowledge of it and verified against its output, see docs/fairplay-provenance.md
• 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.

FairPlay. The FairPlay key exchange (feature fairplay, enabled by default) has a provenance uncertainty that I describe openly in docs/fairplay-provenance.md. In short: earlier releases (up to 0.10.0) were a port of the GPL-3.0 playfair library. The current code is a rewrite with a different structure, tested against golden vectors from the C reference. It still contains the constant tables and reproduces the forced algorithm, because interoperability leaves no alternative. I take the position that constants have no copyright and that the algorithm is a forced sequence, and I publish it under the LGPL. This is not a clean-room implementation, and no legal question is ever fully certain. If you cannot accept the residual uncertainty, build with default-features = false.

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.