Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions spikes/aes67/.gitignore
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
.build/
.swiftpm/
Package.resolved
*.wav
89 changes: 89 additions & 0 deletions spikes/aes67/FINDINGS.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,89 @@
# AES67 spike: findings (#1235)

A throwaway spike, not app code. It receives one AES67 stream (RTP, L24, 48 kHz, 8 channels, 1 ms packets, multicast) and writes one 24-bit WAV per channel. It runs on macOS against a software sender on the same Mac.

**Measured** means run here on 2026-11-15, on an M5 Pro Mac running macOS 27, with multicast on loopback (lo0, TTL 0). The en0 counters show the stream never went out on the LAN. **Reasoned** means worked out, not run. **Unverified** means not checked on a device or against a primary source.

Loopback can't lose or reorder packets the way a real switch, Wi-Fi bridge or a busy USB-C Ethernet adapter can. So the loss and reordering numbers below show the receiver's bookkeeping is right; they say nothing about a real Dante network. The jitter here mostly comes from the Python sender's timing.

## What's here

| Path | What |
|---|---|
| `Sources/AES67Core` | SDP parsing, RTP header parsing, sequence and timestamp unwrapping, the reassembler (orders packets by RTP timestamp, waits 20 ms for late ones, then writes silence for the gap), loss, jitter and drift stats, and the per-channel WAV writer |
| `Sources/aes67rec` | The CLI: joins the group with BSD sockets (`SO_REUSEPORT`, 4 MB `SO_RCVBUF`, kernel arrival stamps on the monotonic clock), then records and prints a JSON report |
| `Tests/AES67CoreTests` | 8 unit tests: SDP, RTP header, wraparound, reorder, gap, duplicate, WAV bytes |
| `tools/aes67_send.py` | The sender: 1 ms packets, a random first sequence number and timestamp, and options to drop, swap or duplicate packets. Channels 1-7 are sines at 375-3000 Hz; channel 8 is a ramp of the sample index, so every sample can be checked |
| `tools/check_wavs.py` | Checks the WAVs bit for bit against what the sender sent |

```sh
swift build -c release
python3 tools/aes67_send.py --seconds 0 --sdp-out /tmp/s.sdp # write the SDP
.build/release/aes67rec --sdp /tmp/s.sdp --out /tmp/rec --stats /tmp/rec.json &
python3 tools/aes67_send.py --seconds 600 --sdp-out /tmp/s.sdp
python3 tools/check_wavs.py /tmp/rec
```

## Does a 10-minute recording come out clean? Yes (measured, on loopback)

8 channels, 600 s, with nothing else heavy running on the Mac:

| | |
|---|---|
| Packets | 600,000 sent, 600,000 received; 0 lost, 0 reordered, 0 duplicated, 0 gaps, 0 late |
| WAVs | 8 × 28,800,000 frames (600.000 s, 86.4 MB each), **bit-exact** on every channel, across the 16-bit sequence wrap (9 times) and the 24-bit ramp wrap |
| Jitter (arrival minus RTP time, drift removed) | p50 34 µs, p99 81 µs, p99.9 163 µs, max 9.8 ms. RFC 3550 jitter ended at 11 µs, with a highest value of 0.8 ms |
| Longest gap between packets | 10.8 ms. The sender reports its worst send was 9.75 ms late, with 167 packets more than 1 ms late, so that maximum is the sender's own stall |
| Reorder buffer | never held more than 1 packet; the 20 ms window was never used |
| Drift | -0.02 ppm against the kernel's monotonic arrival stamps (one machine, one clock). Against the wall clock it was +184 ppm, because macOS slews the wall clock, so any clock work must use monotonic time |

The bookkeeping and fault handling were checked separately (measured). In a 20 s run, the sender dropped every 997th packet, swapped every 101st pair and duplicated every 503rd. The receiver reported exactly what was injected: 20 lost, 20 gaps (960 frames of silence), 198 reordered and 39 duplicates. The WAVs had the right length, the only wrong samples were the silence in those 960 frames, and no sample shifted.

An independent sender was also checked (measured). ffmpeg (libavformat 63) sent 2-channel `pcm_s24be` RTP for 10 s, using its own packet sizes (156 and 204 frames, not 1 ms). The receiver wrote 480,000 frames per channel with 0 lost, and the channels measured 499.9 Hz and 1499.9 Hz, the right pitch and order. So the byte order and channel interleave aren't a bug the spike's own sender and receiver happen to share. ffmpeg wouldn't send multicast through lo0: nothing arrived, and the en0 counter rose by about the stream's size, so this check used unicast to 127.0.0.1. GStreamer isn't installed.

## How much CPU does it take? About 2% of one core for 8 channels (measured on the Mac)

- Over the 10-minute run: 11.5 CPU seconds in 600 s, so **1.9% of one M5 Pro core** for 1,000 packets/s and 8 WAVs. `ps` samples every 10 s ranged from 0.9% to 2.4%.
- This is one thread doing everything: receive, reorder, swap the byte order, and write to the files. Nothing was tuned: the WAV writer appends byte by byte and uses `FileHandle.write` with 64 KB per channel.
- Memory: 7 MB at the start and 38 MB at the end. The growth is the spike's own jitter statistics, which keep 16 bytes per packet. The recording path's memory is flat.

## How much work is following the PTP clock? A recorder doesn't need to (reasoned)

AES67 senders are locked to a PTPv2 grandmaster, and their RTP timestamps count samples of that clock. The SDP's `a=mediaclk:direct=<offset>` gives the offset, and `a=ts-refclk` names the grandmaster ([AES67](https://en.wikipedia.org/wiki/AES67); [Hildebrand, AES67/ST 2110 synchronization](https://www.aimsalliance.org/wp-content/uploads/2022/11/Clocking-Synchronization-in-RTP-RAVENNA_AES67-ST2110-AVB-and-IPMX-Andreas-Hildebrand.pdf)). For a recorder, that means:

- **Placing samples needs no PTP.** The spike writes sample N where RTP timestamp origin+N says. The files come out at the sender's clock rate with no resampling, whatever the phone's clock does. The 10-minute run did exactly that.
- **Lining up 4 streams needs no PTP either,** provided all the senders lock to the same grandmaster. Their `timestamp - mediaclk offset` is then one shared timeline. Line each stream up by that value, put the same timestamp at sample 0 of every file, and fill gaps per stream.
- **PTP matters only if we:** (a) mix network audio with the iPhone's own clock (live monitoring out of the phone's speaker or headphones, or recording a USB mixer at the same time); (b) want to show that a stream is "locked to grandmaster X"; or (c) want to reject a stream whose timestamps don't match PTP time. Case (a) is an adaptive resampler driven by a drift estimate, and the spike's `TimingStats.driftPPM` already measures that drift without PTP.
- **Cost:** a passive listener that reads PTP Announce and Sync messages to show the grandmaster and lock state would take about 1-2 days. A full PTPv2 follower, with delay requests, a servo and software timestamps, would take about 1-2 weeks and isn't needed for recording. On macOS a normal user could bind UDP 319 and 320 and join 224.0.1.129 (measured). On iOS this is unverified; the same multicast entitlement would cover it.

## What would 4 streams (32 channels) need? (reasoned from the 1-stream numbers)

- **Network:** each 8-channel, 1 ms flow is 1,000 packets/s of 1,164-byte payloads, about 10 Mbit/s on the wire with the RTP, UDP, IP and Ethernet headers. Four flows come to 4,000 packets/s and about 40 Mbit/s, fine for any 100 Mbit or gigabit USB-C Ethernet adapter. Dante Brooklyn II sends AES67 only in 239.x and at most 8 channels per flow (#1234). 4 flows are 4 joins on one socket or four sockets.
- **CPU:** 4 × 1.9% is about 8% of one M5 Pro core as written. An iPhone core is slower, and the byte-by-byte writer is easy to speed up, so expect roughly 5-15% of one core. That's unverified until it runs on a phone.
- **Disk:** 32 × 144 KB/s = 4.6 MB/s, about 16.6 GB an hour. That's the same as a 32-channel USB recording at 48 kHz/24-bit.
- **Code beyond the spike:** a per-stream reassembler (this one), one timeline across the flows built from `mediaclk`, a "flow missing" state for each flow, and SDP entry, typed or pasted. SAP discovery on 239.255.255.255:9875 is extra (about 2 days).
- **Real-time rules (ADR 0002):** the spike receives and writes files on one thread. In the app, the receive thread should only copy packets into a lock-free ring. Ordering and file writes happen off it, as the USB path does now.

## The iOS port: realistic, with risks outside the code (unverified on a device)

- **Entitlement:** `com.apple.developer.networking.multicast` is restricted; Apple approves it on request, and applying for it is one of the first steps Eric chose (#1235). Without it, iOS won't let the app join a multicast group. The app also needs `NSLocalNetworkUsageDescription` and the user's yes at the local-network prompt.
- **Hardware:** an iPhone or iPad with USB-C and a class-compliant USB-C Ethernet adapter. To stay off Wi-Fi, join on the Ethernet interface by name (`IP_BOUND_IF` / `imr_interface`). The spike already picks the interface (`--iface`).
- **Sockets:** the spike uses plain BSD sockets, which exist on iOS. Network.framework's `NWConnectionGroup` is the other option. Both need the entitlement.
- **Background:** whether the app keeps receiving with the screen locked during a show is the biggest unknown. Today the app stays alive through its audio session; with no USB input active, that is unverified.
- **No Dante hardware here.** We haven't tested against a real Brooklyn II or a real network. Ultimo and UltimoX Dante devices can't send AES67 at all (#1234). Dante Controller setup by the user is a support burden.

## Verdict

Recording 32 channels of AES67 on an iPhone looks **realistic technically**. Receiving, ordering and writing a stream is small and cheap: about 2% of one Mac core per 8 channels, and bit-exact for 10 minutes. A recorder doesn't need a PTP stack. The risks are outside the code: the entitlement approval, behavior in the background, real-network loss over USB-C Ethernet, and access to AES67-capable Dante hardware for testing.

Rough effort for 32 channels in the app, after the entitlement arrives and with a test device and AES67 sender on hand:

| Work | Estimate |
|---|---|
| Receiver into ShowRecorderKit as an input: ring buffer, ADR 0002 split, tests | 1 week |
| 4 flows on one timeline, missing-flow state, SDP entry (typed or pasted) | 1 week |
| UI, availability rule (Debug first), Pro gating, guide | 1 week |
| Device Takes on a real Dante/AES67 network, background behavior, adapter quirks | 1 week+ |
| Optional: SAP discovery (2 days); passive PTP lock display (1-2 days) | |

So about **4-5 weeks**, plus however long Apple takes with the entitlement. Before building, the cheap next step is #1234 step 1 (Mac plus Dante Virtual Soundcard, no code). Then repeat this spike over a real switch with a Brooklyn II device, if we can borrow one.
14 changes: 14 additions & 0 deletions spikes/aes67/Package.swift
Original file line number Diff line number Diff line change
@@ -0,0 +1,14 @@
// swift-tools-version:5.9
// Throwaway spike for #1235: receive one AES67 stream and record one WAV per channel.
// Not part of the app or the shipping packages.
import PackageDescription

let package = Package(
name: "AES67Spike",
platforms: [.macOS(.v14)],
targets: [
.target(name: "AES67Core"),
.executableTarget(name: "aes67rec", dependencies: ["AES67Core"]),
.testTarget(name: "AES67CoreTests", dependencies: ["AES67Core"]),
]
)
52 changes: 52 additions & 0 deletions spikes/aes67/Sources/AES67Core/RTP.swift
Original file line number Diff line number Diff line change
@@ -0,0 +1,52 @@
/// One RTP header (RFC 3550). `payload` is the byte range of the audio in the datagram.
public struct RTPHeader: Equatable {
public var payloadType: UInt8
public var marker: Bool
public var sequence: UInt16
public var timestamp: UInt32
public var ssrc: UInt32
public var payload: Range<Int>
}

public func parseRTP(_ b: UnsafeRawBufferPointer) -> RTPHeader? {
guard b.count >= 12, b[0] >> 6 == 2 else { return nil }
let padding = b[0] & 0x20 != 0
let ext = b[0] & 0x10 != 0
let csrc = Int(b[0] & 0x0F)
var start = 12 + csrc * 4
guard b.count >= start else { return nil }
if ext {
guard b.count >= start + 4 else { return nil }
let words = Int(b[start + 2]) << 8 | Int(b[start + 3])
start += 4 + words * 4
}
var end = b.count
if padding, end > start { end -= Int(b[end - 1]) }
guard end >= start else { return nil }
func u16(_ i: Int) -> UInt16 { UInt16(b[i]) << 8 | UInt16(b[i + 1]) }
func u32(_ i: Int) -> UInt32 { UInt32(u16(i)) << 16 | UInt32(u16(i + 2)) }
return RTPHeader(payloadType: b[1] & 0x7F, marker: b[1] & 0x80 != 0, sequence: u16(2), timestamp: u32(4),
ssrc: u32(8), payload: start..<end)
}

/// Turns a wrapping 16-bit sequence number or 32-bit timestamp into a 64-bit count, relative to the
/// highest value seen so far (so an old, reordered value maps below it rather than a whole wrap above).
public struct Unwrapper {
public let bits: Int
private var highest: Int64?
public init(bits: Int) { self.bits = bits }

public mutating func extend(_ value: UInt64) -> Int64 {
let modulus = Int64(1) << bits
let v = Int64(value) & (modulus - 1)
guard let h = highest else {
highest = v
return v
}
var delta = (v - h) & (modulus - 1)
if delta >= modulus / 2 { delta -= modulus }
let e = h + delta
if e > h { highest = e }
return e
}
}
76 changes: 76 additions & 0 deletions spikes/aes67/Sources/AES67Core/Reassembler.swift
Original file line number Diff line number Diff line change
@@ -0,0 +1,76 @@
/// Where reassembled audio goes: interleaved big-endian payload bytes, or a run of silence for a gap.
public protocol FrameSink: AnyObject {
func write(payload: ArraySlice<UInt8>, frames: Int)
func writeSilence(frames: Int)
}

/// Puts packets back in order by RTP timestamp and writes them out, so sample N of the file is always
/// RTP timestamp origin+N. A packet waits up to `windowFrames` for the ones before it; past that the
/// missing span is written as silence and counted as a gap. A packet for a span already written (a late
/// arrival after its gap was filled, or a duplicate) is dropped and counted.
public final class Reassembler {
public let bytesPerFrame: Int
public let windowFrames: Int
public private(set) var origin: Int64?
/// Next frame offset (from `origin`) to write.
public private(set) var cursor: Int64 = 0
private var pending: [Int64: [UInt8]] = [:]
private var newestEnd: Int64 = 0
private let sink: FrameSink

public private(set) var gapEvents = 0
public private(set) var gapFrames: Int64 = 0
public private(set) var lateDropped = 0
public private(set) var pendingDuplicates = 0
public private(set) var framesWritten: Int64 = 0
public private(set) var maxPending = 0

public init(bytesPerFrame: Int, windowFrames: Int, sink: FrameSink) {
self.bytesPerFrame = bytesPerFrame
self.windowFrames = windowFrames
self.sink = sink
}

/// `timestamp` is the extended (unwrapped) RTP timestamp.
public func insert(timestamp: Int64, payload: ArraySlice<UInt8>) {
let frames = payload.count / bytesPerFrame
guard frames > 0 else { return }
if origin == nil { origin = timestamp }
let offset = timestamp - origin!
if offset < cursor {
lateDropped += 1
return
}
if pending[offset] != nil {
pendingDuplicates += 1
return
}
pending[offset] = Array(payload.prefix(frames * bytesPerFrame))
newestEnd = max(newestEnd, offset + Int64(frames))
maxPending = max(maxPending, pending.count)
drain(force: false)
}

/// Writes everything still waiting, filling holes with silence. Call at the end of a recording.
public func finish() { drain(force: true) }

private func drain(force: Bool) {
while !pending.isEmpty {
if let p = pending.removeValue(forKey: cursor) {
let frames = p.count / bytesPerFrame
sink.write(payload: p[...], frames: frames)
cursor += Int64(frames)
framesWritten += Int64(frames)
continue
}
guard force || newestEnd - cursor > Int64(windowFrames) else { return }
let next = pending.keys.min()!
let gap = next - cursor
sink.writeSilence(frames: Int(gap))
gapEvents += 1
gapFrames += gap
framesWritten += gap
cursor = next
}
}
}
78 changes: 78 additions & 0 deletions spikes/aes67/Sources/AES67Core/SDP.swift
Original file line number Diff line number Diff line change
@@ -0,0 +1,78 @@
import Foundation

/// The parts of an AES67 SDP the receiver needs.
public struct StreamDescription: Equatable {
public var group: String
public var port: UInt16
public var payloadType: UInt8
public var encoding: String
public var sampleRate: Int
public var channels: Int
public var ptimeMs: Double?
public var sourceFilter: String?
/// `a=ts-refclk`, e.g. `ptp=IEEE1588-2008:39-A7-94-FF-FE-07-CB-D0:0`.
public var refClock: String?
/// `a=mediaclk`, e.g. `direct=0` (RTP timestamp = PTP time in samples + offset).
public var mediaClock: String?

public var bytesPerSample: Int { encoding == "L16" ? 2 : 3 }
}

public enum SDPError: Error, Equatable {
case missing(String)
case unsupported(String)
}

public func parseSDP(_ text: String) throws -> StreamDescription {
var group: String?
var port: UInt16?
var pt: UInt8?
var encoding: String?
var rate: Int?
var channels = 1
var ptime: Double?
var filter: String?
var refclk: String?
var mediaclk: String?

for raw in text.split(whereSeparator: \.isNewline) {
let line = raw.trimmingCharacters(in: .whitespaces)
if line.hasPrefix("c=") {
// c=IN IP4 239.69.83.67/32
let parts = line.dropFirst(2).split(separator: " ")
if parts.count >= 3 { group = String(parts[2].split(separator: "/")[0]) }
} else if line.hasPrefix("m=audio ") {
// m=audio 5004 RTP/AVP 98
let parts = line.dropFirst(2).split(separator: " ")
if parts.count >= 4 {
port = UInt16(parts[1])
pt = UInt8(parts[3])
}
} else if line.hasPrefix("a=rtpmap:") {
// a=rtpmap:98 L24/48000/8
let body = line.dropFirst("a=rtpmap:".count)
let parts = body.split(separator: " ", maxSplits: 1)
guard parts.count == 2 else { continue }
if let pt, UInt8(parts[0]) != pt { continue }
let fmt = parts[1].split(separator: "/")
encoding = String(fmt[0])
if fmt.count > 1 { rate = Int(fmt[1]) }
if fmt.count > 2 { channels = Int(fmt[2]) ?? 1 }
} else if line.hasPrefix("a=ptime:") {
ptime = Double(line.dropFirst("a=ptime:".count))
} else if line.hasPrefix("a=source-filter:") {
filter = String(line.dropFirst("a=source-filter:".count)).trimmingCharacters(in: .whitespaces)
} else if line.hasPrefix("a=ts-refclk:") {
refclk = String(line.dropFirst("a=ts-refclk:".count))
} else if line.hasPrefix("a=mediaclk:") {
mediaclk = String(line.dropFirst("a=mediaclk:".count))
}
}
guard let group else { throw SDPError.missing("c=") }
guard let port, let pt else { throw SDPError.missing("m=audio") }
guard let encoding, let rate else { throw SDPError.missing("a=rtpmap") }
guard encoding == "L24" || encoding == "L16" else { throw SDPError.unsupported(encoding) }
return StreamDescription(group: group, port: port, payloadType: pt, encoding: encoding, sampleRate: rate,
channels: channels, ptimeMs: ptime, sourceFilter: filter, refClock: refclk,
mediaClock: mediaclk)
}
Loading
Loading