From 8265935d9d2de27421c08eab3274cb06c1da0e24 Mon Sep 17 00:00:00 2001 From: Eric Dahl Date: Sun, 15 Nov 2026 15:35:53 -0500 Subject: [PATCH 1/2] Spike: AES67 receive and record, work in progress (#1235) Swift receiver (SDP, multicast join, reorder by RTP timestamp, gaps as silence, one 24-bit WAV per channel), a Python L24 sender with fault injection, and a bit-exact WAV checker. FINDINGS.md has the status so far. Assisted-by: Claude --- spikes/aes67/.gitignore | 4 + spikes/aes67/FINDINGS.md | 16 ++ spikes/aes67/Package.swift | 14 ++ spikes/aes67/Sources/AES67Core/RTP.swift | 52 +++++ .../aes67/Sources/AES67Core/Reassembler.swift | 76 ++++++ spikes/aes67/Sources/AES67Core/SDP.swift | 78 +++++++ spikes/aes67/Sources/AES67Core/Stats.swift | 102 ++++++++ spikes/aes67/Sources/AES67Core/WAVSet.swift | 83 +++++++ spikes/aes67/Sources/aes67rec/main.swift | 218 ++++++++++++++++++ .../Tests/AES67CoreTests/AES67CoreTests.swift | 128 ++++++++++ spikes/aes67/tools/aes67_send.py | 140 +++++++++++ spikes/aes67/tools/check_wavs.py | 93 ++++++++ 12 files changed, 1004 insertions(+) create mode 100644 spikes/aes67/.gitignore create mode 100644 spikes/aes67/FINDINGS.md create mode 100644 spikes/aes67/Package.swift create mode 100644 spikes/aes67/Sources/AES67Core/RTP.swift create mode 100644 spikes/aes67/Sources/AES67Core/Reassembler.swift create mode 100644 spikes/aes67/Sources/AES67Core/SDP.swift create mode 100644 spikes/aes67/Sources/AES67Core/Stats.swift create mode 100644 spikes/aes67/Sources/AES67Core/WAVSet.swift create mode 100644 spikes/aes67/Sources/aes67rec/main.swift create mode 100644 spikes/aes67/Tests/AES67CoreTests/AES67CoreTests.swift create mode 100644 spikes/aes67/tools/aes67_send.py create mode 100644 spikes/aes67/tools/check_wavs.py diff --git a/spikes/aes67/.gitignore b/spikes/aes67/.gitignore new file mode 100644 index 00000000..7059040d --- /dev/null +++ b/spikes/aes67/.gitignore @@ -0,0 +1,4 @@ +.build/ +.swiftpm/ +Package.resolved +*.wav diff --git a/spikes/aes67/FINDINGS.md b/spikes/aes67/FINDINGS.md new file mode 100644 index 00000000..c3fe079e --- /dev/null +++ b/spikes/aes67/FINDINGS.md @@ -0,0 +1,16 @@ +# AES67 spike: findings (#1235) + +## Status (2026-11-15, paused) + +**Works (measured on macOS, multicast over loopback lo0 with TTL 0; the en0 counters show nothing left the Mac):** +- `aes67rec` (the Swift package here) parses the SDP, joins 239.69.83.67:5004, puts packets back in order by RTP timestamp, fills gaps with silence, and writes one 24-bit WAV per channel. 8 unit tests pass. +- `tools/aes67_send.py` sends L24/48000/8 at 1 ms ptime. `tools/check_wavs.py` checks the WAVs bit for bit: channels 1-7 are sines, and channel 8 is a ramp of the sample index. +- A clean 10 s run crossed the 16-bit sequence wrap and the 32-bit timestamp wrap: 10,000 packets, 0 lost, 0 reordered, 0 gaps, and all 8 WAVs bit-exact. Receiver CPU was 1.4% of one core, with 8 MB resident. +- A 20 s run with faults injected: the receiver's counts match what the sender injected. 20 dropped = 20 lost = 20 gaps (960 frames), 198 swapped = 198 reordered, and 39 duplicated = 39 duplicates. The WAVs are 960,000 frames long, as expected; the only wrong samples are the silent ones in the 960 dropped frames, and no sample shifted. Receiver CPU was 2.3%. +- Clock drift: -0.7 ppm against the kernel's monotonic arrival stamps (sender and receiver are on the same machine, so near 0 is expected), but -195 ppm against the wall clock, because macOS slews the wall clock. Any clock work must use monotonic time. +- Jitter in the 10 s run (mostly the Python sender's pacing): transit spread p50 0.5 ms, p99 1.0 ms, p99.9 2.8 ms, max 6.2 ms. The 20 ms reorder window is ample here. + +**Left:** +- The 10-minute run (loss, reordering, jitter, CPU) and the bit-exact check of its WAVs. +- A short interop run with ffmpeg as an independent sender (GStreamer isn't installed). +- Answers to the four questions: following the PTP clock, CPU, 4 streams (32 channels), and the iOS port (multicast entitlement, USB-C Ethernet). Loopback says nothing about loss on a real network. diff --git a/spikes/aes67/Package.swift b/spikes/aes67/Package.swift new file mode 100644 index 00000000..dbd3868c --- /dev/null +++ b/spikes/aes67/Package.swift @@ -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"]), + ] +) diff --git a/spikes/aes67/Sources/AES67Core/RTP.swift b/spikes/aes67/Sources/AES67Core/RTP.swift new file mode 100644 index 00000000..d2559327 --- /dev/null +++ b/spikes/aes67/Sources/AES67Core/RTP.swift @@ -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 +} + +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.. 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 + } +} diff --git a/spikes/aes67/Sources/AES67Core/Reassembler.swift b/spikes/aes67/Sources/AES67Core/Reassembler.swift new file mode 100644 index 00000000..246f83f2 --- /dev/null +++ b/spikes/aes67/Sources/AES67Core/Reassembler.swift @@ -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, 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) { + 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 + } + } +} diff --git a/spikes/aes67/Sources/AES67Core/SDP.swift b/spikes/aes67/Sources/AES67Core/SDP.swift new file mode 100644 index 00000000..3c2565fa --- /dev/null +++ b/spikes/aes67/Sources/AES67Core/SDP.swift @@ -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) +} diff --git a/spikes/aes67/Sources/AES67Core/Stats.swift b/spikes/aes67/Sources/AES67Core/Stats.swift new file mode 100644 index 00000000..a4e91267 --- /dev/null +++ b/spikes/aes67/Sources/AES67Core/Stats.swift @@ -0,0 +1,102 @@ +/// Packet counts by RTP sequence number: loss, duplicates and reordering. +public struct SequenceStats { + private var unwrap = Unwrapper(bits: 16) + public private(set) var first: Int64? + public private(set) var highest: Int64 = 0 + public private(set) var received = 0 + public private(set) var duplicates = 0 + /// Packets that arrived after one with a higher sequence number. + public private(set) var reordered = 0 + /// Largest distance (in packets) a reordered packet arrived behind the highest one. + public private(set) var maxReorderDepth: Int64 = 0 + private var seen = Set() + + public init() {} + + public mutating func record(_ seq: UInt16) { + let e = unwrap.extend(UInt64(seq)) + received += 1 + if first == nil { first = e; highest = e } + if seen.contains(e) { + duplicates += 1 + return + } + seen.insert(e) + if e < highest { + reordered += 1 + maxReorderDepth = max(maxReorderDepth, highest - e) + } else { + highest = e + } + if seen.count > 8192 { + let floor = highest - 4096 + seen = seen.filter { $0 >= floor } + } + } + + public var unique: Int { received - duplicates } + public var expected: Int64 { first.map { highest - $0 + 1 } ?? 0 } + public var lost: Int64 { expected - Int64(unique) } +} + +/// Arrival timing. `transit` = arrival time (in samples) minus RTP timestamp; its spread is the jitter a +/// receive buffer has to absorb, and its slope against time is the sender's clock drift against ours. +public struct TimingStats { + public let sampleRate: Double + public private(set) var packets = 0 + /// RFC 3550 interarrival jitter, in samples. + public private(set) var rfc3550Jitter: Double = 0 + public private(set) var maxRfc3550Jitter: Double = 0 + private var lastTransit: Double? + private var minTransit = Double.infinity + private var maxTransit = -Double.infinity + /// (elapsed arrival s, transit s) per packet. + private var points: [(x: Double, y: Double)] = [] + // Least squares of transit (s) against arrival (s), for drift. + private var n = 0.0, sx = 0.0, sy = 0.0, sxx = 0.0, sxy = 0.0 + private var t0: Double? + private var lastArrival: Double? + public private(set) var maxInterArrival: Double = 0 + + public init(sampleRate: Double) { self.sampleRate = sampleRate } + + /// `arrival` in seconds (any epoch), `timestamp` the extended RTP timestamp. + public mutating func record(arrival: Double, timestamp: Int64, inOrder: Bool) { + packets += 1 + if t0 == nil { t0 = arrival } + let transit = arrival * sampleRate - Double(timestamp) + if inOrder, let last = lastTransit { + let d = abs(transit - last) + rfc3550Jitter += (d - rfc3550Jitter) / 16 + maxRfc3550Jitter = max(maxRfc3550Jitter, rfc3550Jitter) + } + if inOrder { lastTransit = transit } + if let la = lastArrival { maxInterArrival = max(maxInterArrival, arrival - la) } + lastArrival = arrival + minTransit = min(minTransit, transit) + maxTransit = max(maxTransit, transit) + let x = arrival - t0!, y = transit / sampleRate + points.append((x, y)) + n += 1; sx += x; sy += y; sxx += x * x; sxy += x * y + } + + /// Drift of the sender's sample clock against the arrival clock, in parts per million. + public var driftPPM: Double { + let den = n * sxx - sx * sx + guard n > 2, den != 0 else { return 0 } + return (n * sxy - sx * sy) / den * 1e6 + } + + /// Transit spread in microseconds after removing drift: percentiles of (transit - its lowest value). + /// The top percentile is about how deep a receive buffer has to be to never run dry. + public func spreadMicroseconds(percentiles: [Double]) -> [Double] { + guard !points.isEmpty else { return percentiles.map { _ in 0 } } + let slope = driftPPM / 1e6 + let detrended = points.map { $0.y - slope * $0.x } + let floor = detrended.min()! + let sorted = detrended.map { ($0 - floor) * 1e6 }.sorted() + return percentiles.map { p in sorted[min(sorted.count - 1, Int((Double(sorted.count - 1) * p).rounded()))] } + } + + public var rawSpreadMicroseconds: Double { (maxTransit - minTransit) / sampleRate * 1e6 } +} diff --git a/spikes/aes67/Sources/AES67Core/WAVSet.swift b/spikes/aes67/Sources/AES67Core/WAVSet.swift new file mode 100644 index 00000000..5d8b049c --- /dev/null +++ b/spikes/aes67/Sources/AES67Core/WAVSet.swift @@ -0,0 +1,83 @@ +import Foundation + +/// One mono 24-bit WAV per channel. Takes interleaved big-endian L24 (or L16) payloads and writes +/// little-endian samples, buffered, patching the RIFF sizes on `close()`. +public final class WAVSet: FrameSink { + public let channels: Int + public let sampleRate: Int + public let inBytes: Int + private var handles: [FileHandle] = [] + private var buffers: [[UInt8]] + private var frames: Int64 = 0 + private let flushBytes = 1 << 16 + + public init(directory: URL, prefix: String, channels: Int, sampleRate: Int, inBytesPerSample: Int) throws { + self.channels = channels + self.sampleRate = sampleRate + self.inBytes = inBytesPerSample + buffers = Array(repeating: [], count: channels) + try FileManager.default.createDirectory(at: directory, withIntermediateDirectories: true) + for c in 0.. [UInt8] { + var h = [UInt8]() + func u32(_ v: UInt32) { h += [UInt8(v & 0xFF), UInt8(v >> 8 & 0xFF), UInt8(v >> 16 & 0xFF), UInt8(v >> 24)] } + func u16(_ v: UInt16) { h += [UInt8(v & 0xFF), UInt8(v >> 8)] } + h += Array("RIFF".utf8); u32(36 + dataBytes); h += Array("WAVE".utf8) + h += Array("fmt ".utf8); u32(16); u16(1); u16(1); u32(UInt32(sampleRate)); u32(UInt32(sampleRate * 3)); u16(3); u16(24) + h += Array("data".utf8); u32(dataBytes) + return h + } + + public func write(payload: ArraySlice, frames n: Int) { + payload.withUnsafeBufferPointer { p in + let stride = channels * inBytes + for c in 0..= flushBytes { flush() } + } + + public func writeSilence(frames n: Int) { + for c in 0..= flushBytes { flush() } + } + + private func flush() { + for c in 0.. String? { + let a = CommandLine.arguments + guard let i = a.firstIndex(of: name), i + 1 < a.count else { return nil } + return a[i + 1] +} +func die(_ s: String) -> Never { FileHandle.standardError.write(Data((s + "\n").utf8)); exit(1) } + +guard let sdpPath = arg("--sdp"), let outDir = arg("--out") else { + die("usage: aes67rec --sdp FILE --out DIR [--iface ADDR] [--seconds N] [--window-ms MS] [--stats FILE]") +} +let sdp: StreamDescription +do { sdp = try parseSDP(try String(contentsOfFile: sdpPath, encoding: .utf8)) } catch { die("SDP: \(error)") } +let iface = arg("--iface") ?? "127.0.0.1" +let maxSeconds = Double(arg("--seconds") ?? "0") ?? 0 +let windowMs = Double(arg("--window-ms") ?? "20") ?? 20 +print("stream \(sdp.group):\(sdp.port) PT \(sdp.payloadType) \(sdp.encoding)/\(sdp.sampleRate)/\(sdp.channels) ptime \(sdp.ptimeMs ?? 0) ms refclk \(sdp.refClock ?? "-") mediaclk \(sdp.mediaClock ?? "-")") + +// MARK: socket +let fd = socket(AF_INET, SOCK_DGRAM, IPPROTO_UDP) +guard fd >= 0 else { die("socket: \(errno)") } +var one: Int32 = 1 +setsockopt(fd, SOL_SOCKET, SO_REUSEADDR, &one, socklen_t(MemoryLayout.size)) +setsockopt(fd, SOL_SOCKET, SO_REUSEPORT, &one, socklen_t(MemoryLayout.size)) +setsockopt(fd, SOL_SOCKET, SO_TIMESTAMP, &one, socklen_t(MemoryLayout.size)) +// Kernel arrival time on the monotonic clock (mach_absolute_time), not NTP-slewed like the wall clock. +setsockopt(fd, SOL_SOCKET, 0x0800 /* SO_TIMESTAMP_MONOTONIC */, &one, socklen_t(MemoryLayout.size)) +var timebase = mach_timebase_info_data_t() +mach_timebase_info(&timebase) +func machSeconds(_ t: UInt64) -> Double { Double(t) * Double(timebase.numer) / Double(timebase.denom) / 1e9 } +var rcvbuf: Int32 = 4 << 20 +if setsockopt(fd, SOL_SOCKET, SO_RCVBUF, &rcvbuf, socklen_t(MemoryLayout.size)) != 0 { + rcvbuf = 1 << 20 + setsockopt(fd, SOL_SOCKET, SO_RCVBUF, &rcvbuf, socklen_t(MemoryLayout.size)) +} +var got: Int32 = 0 +var gotLen = socklen_t(MemoryLayout.size) +getsockopt(fd, SOL_SOCKET, SO_RCVBUF, &got, &gotLen) +var tv = timeval(tv_sec: 0, tv_usec: 100_000) +setsockopt(fd, SOL_SOCKET, SO_RCVTIMEO, &tv, socklen_t(MemoryLayout.size)) + +var bindAddr = sockaddr_in() +bindAddr.sin_len = UInt8(MemoryLayout.size) +bindAddr.sin_family = sa_family_t(AF_INET) +bindAddr.sin_port = sdp.port.bigEndian +bindAddr.sin_addr.s_addr = inet_addr(sdp.group) // bind to the group so other groups on the port are not delivered +let bound = withUnsafePointer(to: &bindAddr) { + $0.withMemoryRebound(to: sockaddr.self, capacity: 1) { bind(fd, $0, socklen_t(MemoryLayout.size)) } +} +guard bound == 0 else { die("bind: \(String(cString: strerror(errno)))") } +var mreq = ip_mreq(imr_multiaddr: in_addr(s_addr: inet_addr(sdp.group)), imr_interface: in_addr(s_addr: inet_addr(iface))) +guard setsockopt(fd, IPPROTO_IP, IP_ADD_MEMBERSHIP, &mreq, socklen_t(MemoryLayout.size)) == 0 else { + die("IP_ADD_MEMBERSHIP: \(String(cString: strerror(errno)))") +} +print("joined \(sdp.group) on \(iface), SO_RCVBUF \(got) bytes") + +// MARK: recording state +let bytesPerFrame = sdp.channels * sdp.bytesPerSample +let wavs: WAVSet +do { + wavs = try WAVSet(directory: URL(fileURLWithPath: outDir), prefix: "aes67", channels: sdp.channels, + sampleRate: sdp.sampleRate, inBytesPerSample: sdp.bytesPerSample) +} catch { die("WAV: \(error)") } +let reasm = Reassembler(bytesPerFrame: bytesPerFrame, + windowFrames: Int(windowMs / 1000 * Double(sdp.sampleRate)), sink: wavs) +var seqStats = SequenceStats() +var timing = TimingStats(sampleRate: Double(sdp.sampleRate)) +var timingWallClock = TimingStats(sampleRate: Double(sdp.sampleRate)) // only for its drift figure +var monotonicStamps = 0 +var tsUnwrap = Unwrapper(bits: 32) +var wrongPT = 0, badPackets = 0, otherSSRC = 0 +var ssrc: UInt32? +var packetFrames = Set() +var userTimingMaxLag = 0.0 // kernel timestamp to our read, worst case + +func now() -> Double { var t = timespec(); clock_gettime(CLOCK_REALTIME, &t); return Double(t.tv_sec) + Double(t.tv_nsec) / 1e9 } +func cpuSeconds() -> Double { + var u = rusage(); getrusage(RUSAGE_SELF, &u) + return Double(u.ru_utime.tv_sec) + Double(u.ru_utime.tv_usec) / 1e6 + Double(u.ru_stime.tv_sec) + Double(u.ru_stime.tv_usec) / 1e6 +} + +var running = true +signal(SIGINT) { _ in running = false } +signal(SIGTERM) { _ in running = false } + +var buf = [UInt8](repeating: 0, count: 9000) +var control = [UInt8](repeating: 0, count: 256) +var firstPacketAt: Double? +var lastPacketAt: Double? +var cpuAtFirst = 0.0 +var nextReport = 0.0 +let started = now() + +while running { + var iov = iovec() + var msg = msghdr() + let n: Int = buf.withUnsafeMutableBytes { b in + control.withUnsafeMutableBytes { c in + iov.iov_base = b.baseAddress + iov.iov_len = b.count + return withUnsafeMutablePointer(to: &iov) { iovp in + msg.msg_iov = iovp + msg.msg_iovlen = 1 + msg.msg_control = c.baseAddress + msg.msg_controllen = socklen_t(c.count) + return recvmsg(fd, &msg, 0) + } + } + } + let t = now() + if n < 0 { + if errno != EAGAIN && errno != EINTR { die("recvmsg: \(String(cString: strerror(errno)))") } + } else { + // Kernel arrival time from SO_TIMESTAMP (Darwin aligns cmsg data to 4 bytes). + var arrival = t + var arrivalMono = machSeconds(mach_absolute_time()) + var hadMono = false + control.withUnsafeBytes { c in + var off = 0 + while off + 12 <= Int(msg.msg_controllen) { + let len = Int(c.loadUnaligned(fromByteOffset: off, as: UInt32.self)) + let level = c.loadUnaligned(fromByteOffset: off + 4, as: Int32.self) + let type = c.loadUnaligned(fromByteOffset: off + 8, as: Int32.self) + if level == SOL_SOCKET && type == SCM_TIMESTAMP { + let tv = c.loadUnaligned(fromByteOffset: off + 12, as: timeval.self) + arrival = Double(tv.tv_sec) + Double(tv.tv_usec) / 1e6 + } else if level == SOL_SOCKET && type == 0x04 /* SCM_TIMESTAMP_MONOTONIC */ { + arrivalMono = machSeconds(c.loadUnaligned(fromByteOffset: off + 12, as: UInt64.self)) + hadMono = true + } + guard len > 0 else { break } + off += (len + 3) & ~3 + } + } + userTimingMaxLag = max(userTimingMaxLag, t - arrival) + buf.withUnsafeBytes { b in + let d = UnsafeRawBufferPointer(rebasing: b[0.. before + let ets = tsUnwrap.extend(UInt64(h.timestamp)) + timing.record(arrival: arrivalMono, timestamp: ets, inOrder: inOrder) + timingWallClock.record(arrival: arrival, timestamp: ets, inOrder: inOrder) + if hadMono { monotonicStamps += 1 } + packetFrames.insert(h.payload.count / bytesPerFrame) + reasm.insert(timestamp: ets, payload: buf[h.payload]) + } + } + if let f = firstPacketAt { + if t >= nextReport { + let wall = t - f + print(String(format: "%6.0f s pkts %d lost %lld reord %d dup %d gaps %d jitter %.1f µs cpu %.2f%%", + wall, seqStats.received, seqStats.lost, seqStats.reordered, seqStats.duplicates, reasm.gapEvents, + timing.rfc3550Jitter / Double(sdp.sampleRate) * 1e6, (cpuSeconds() - cpuAtFirst) / wall * 100)) + fflush(stdout) + nextReport += 10 + } + if maxSeconds > 0 && t - f >= maxSeconds { break } + if let l = lastPacketAt, t - l > 2 { break } + } else if maxSeconds > 0 && t - started > maxSeconds + 30 { + die("no packets") + } +} + +reasm.finish() +let end = lastPacketAt ?? now() +let wall = end - (firstPacketAt ?? end) +let cpu = cpuSeconds() - cpuAtFirst +do { try wavs.close() } catch { die("close: \(error)") } +var ru = rusage(); getrusage(RUSAGE_SELF, &ru) +let pct = [0.5, 0.99, 0.999, 1.0] +let spread = timing.spreadMicroseconds(percentiles: pct) +let report: [String: Any] = [ + "seconds": wall, + "channels": sdp.channels, + "packetFrames": packetFrames.sorted(), + "received": seqStats.received, + "expected": seqStats.expected, + "lost": seqStats.lost, + "duplicates": seqStats.duplicates, + "reordered": seqStats.reordered, + "maxReorderDepth": seqStats.maxReorderDepth, + "gapEvents": reasm.gapEvents, + "gapFrames": reasm.gapFrames, + "lateDropped": reasm.lateDropped, + "pendingDuplicates": reasm.pendingDuplicates, + "maxPendingPackets": reasm.maxPending, + "framesWritten": wavs.framesWritten, + "wrongPayloadType": wrongPT, "badPackets": badPackets, "otherSSRC": otherSSRC, + "rfc3550JitterUsFinal": timing.rfc3550Jitter / Double(sdp.sampleRate) * 1e6, + "rfc3550JitterUsMax": timing.maxRfc3550Jitter / Double(sdp.sampleRate) * 1e6, + "transitSpreadUs_p50_p99_p999_max": spread, + "maxInterArrivalMs": timing.maxInterArrival * 1000, + "driftPPM": timing.driftPPM, + "driftPPMAgainstWallClock": timingWallClock.driftPPM, + "kernelMonotonicStamps": monotonicStamps, + "kernelToUserMaxLagMs": userTimingMaxLag * 1000, + "cpuSeconds": cpu, + "cpuPercentOfOneCore": wall > 0 ? cpu / wall * 100 : 0, + "maxRSSMB": Double(ru.ru_maxrss) / 1_048_576, + "rcvbufBytes": got, + "clean": seqStats.lost == 0 && reasm.gapEvents == 0 && reasm.lateDropped == 0, +] +let json = try! JSONSerialization.data(withJSONObject: report, options: [.prettyPrinted, .sortedKeys]) +print(String(data: json, encoding: .utf8)!) +if let p = arg("--stats") { try? json.write(to: URL(fileURLWithPath: p)) } diff --git a/spikes/aes67/Tests/AES67CoreTests/AES67CoreTests.swift b/spikes/aes67/Tests/AES67CoreTests/AES67CoreTests.swift new file mode 100644 index 00000000..ca0eea6b --- /dev/null +++ b/spikes/aes67/Tests/AES67CoreTests/AES67CoreTests.swift @@ -0,0 +1,128 @@ +import XCTest +@testable import AES67Core + +final class Capture: FrameSink { + var out: [Int] = [] // first byte of each frame, 0 for silence + func write(payload: ArraySlice, frames: Int) { + for f in 0.. ArraySlice { + Array((0.. 4 + XCTAssertEqual(c.out, [1, 1, 0, 0, 3, 3, 4, 4, 5, 5]) + XCTAssertEqual(r.gapEvents, 1) + XCTAssertEqual(r.gapFrames, 2) + r.insert(timestamp: 2, payload: packet(2)) // too late + XCTAssertEqual(r.lateDropped, 1) + } + + func testDropsDuplicates() { + let c = Capture() + let r = Reassembler(bytesPerFrame: 3, windowFrames: 10, sink: c) + r.insert(timestamp: 0, payload: packet(1)) + r.insert(timestamp: 4, payload: packet(3)) + r.insert(timestamp: 4, payload: packet(3)) + r.insert(timestamp: 0, payload: packet(1)) + r.insert(timestamp: 2, payload: packet(2)) + r.finish() + XCTAssertEqual(c.out, [1, 1, 2, 2, 3, 3]) + XCTAssertEqual(r.pendingDuplicates, 1) + XCTAssertEqual(r.lateDropped, 1) + } + + func testSequenceStatsCountLossReorderAndDuplicates() { + var s = SequenceStats() + for q: UInt16 in [65533, 65534, 0, 65535, 1, 1, 3] { s.record(q) } + XCTAssertEqual(s.received, 7) + XCTAssertEqual(s.duplicates, 1) + XCTAssertEqual(s.reordered, 1) + XCTAssertEqual(s.expected, 7) // 65533 ... 3 + XCTAssertEqual(s.lost, 1) // 2 + } + + func testWAVSetWritesLittleEndianPerChannel() throws { + let dir = FileManager.default.temporaryDirectory.appendingPathComponent(UUID().uuidString) + let w = try WAVSet(directory: dir, prefix: "t", channels: 2, sampleRate: 48000, inBytesPerSample: 3) + w.write(payload: [0x11, 0x22, 0x33, 0xAA, 0xBB, 0xCC][...], frames: 1) + w.writeSilence(frames: 1) + try w.close() + let a = try Data(contentsOf: dir.appendingPathComponent("t-ch01.wav")) + let b = try Data(contentsOf: dir.appendingPathComponent("t-ch02.wav")) + XCTAssertEqual(Array(a.suffix(6)), [0x33, 0x22, 0x11, 0, 0, 0]) + XCTAssertEqual(Array(b.suffix(6)), [0xCC, 0xBB, 0xAA, 0, 0, 0]) + XCTAssertEqual(a.count, 44 + 6) + XCTAssertEqual(Array(a[40..<44]), [6, 0, 0, 0]) + } +} diff --git a/spikes/aes67/tools/aes67_send.py b/spikes/aes67/tools/aes67_send.py new file mode 100644 index 00000000..775f117c --- /dev/null +++ b/spikes/aes67/tools/aes67_send.py @@ -0,0 +1,140 @@ +#!/usr/bin/env python3 +"""A software AES67 sender for the spike (#1235): RTP L24, 48 kHz, 1 ms packets, to a multicast group. + +Every sample is a pure function of (channel, sample index n), so check_wavs.py can check the WAVs bit for bit: + channels 1..C-1: a sine at 375, 500, 750, 1000, 1500, 2000, 3000 Hz (each divides 48 kHz, so it repeats exactly) + channel C: a ramp, n mod 2^24, so any missing, repeated or misplaced sample shows +Faults can be injected to exercise the receiver's reorder and gap code: --drop-every, --swap-every, --dup-every. + + aes67_send.py --channels 8 --seconds 600 --sdp-out stream.sdp [--iface 127.0.0.1] [--group 239.69.83.67] +""" +import argparse +import math +import os +import random +import socket +import struct +import sys +import time + +RATE = 48000 +FREQS = [375, 500, 750, 1000, 1500, 2000, 3000] +PERIOD = 384 # LCM of 48000/f over FREQS +AMP = 0.5 * (2**23 - 1) + + +def sine_sample(ch, n): + f = FREQS[ch % len(FREQS)] + return int(round(AMP * math.sin(2 * math.pi * f * (n % PERIOD) / RATE))) + + +def b24(v): + return (v & 0xFFFFFF).to_bytes(3, "big") + + +def main(): + p = argparse.ArgumentParser() + p.add_argument("--group", default="239.69.83.67") + p.add_argument("--port", type=int, default=5004) + p.add_argument("--iface", default="127.0.0.1") + p.add_argument("--ttl", type=int, default=0, help="0 keeps the packets on this host") + p.add_argument("--channels", type=int, default=8) + p.add_argument("--ptime-ms", type=float, default=1.0) + p.add_argument("--seconds", type=float, default=10) + p.add_argument("--pt", type=int, default=98) + p.add_argument("--ts-start", type=int, default=None, help="first RTP timestamp (default random)") + p.add_argument("--seq-start", type=int, default=None) + p.add_argument("--drop-every", type=int, default=0) + p.add_argument("--swap-every", type=int, default=0, help="send packet k+1 before packet k") + p.add_argument("--dup-every", type=int, default=0) + p.add_argument("--sdp-out") + a = p.parse_args() + + C = a.channels + frames = int(RATE * a.ptime_ms / 1000) + # One 384-frame cycle of the sine channels, per frame, pre-packed. + sines = [b"".join(b24(sine_sample(c, n)) for c in range(C - 1)) for n in range(PERIOD)] + + ts0 = a.ts_start if a.ts_start is not None else random.getrandbits(32) + seq0 = a.seq_start if a.seq_start is not None else random.getrandbits(16) + ssrc = random.getrandbits(32) + + if a.sdp_out: + with open(a.sdp_out, "w") as f: + f.write( + "v=0\n" + f"o=- {ssrc} 0 IN IP4 {a.iface}\n" + "s=ShowRecorder AES67 spike sender\n" + f"c=IN IP4 {a.group}/32\n" + "t=0 0\n" + "a=clock-domain:PTPv2 0\n" + f"m=audio {a.port} RTP/AVP {a.pt}\n" + f"i={C} channels\n" + f"a=rtpmap:{a.pt} L24/{RATE}/{C}\n" + f"a=ptime:{a.ptime_ms:g}\n" + "a=ts-refclk:ptp=IEEE1588-2008:00-00-00-00-00-00-00-00:0\n" + "a=mediaclk:direct=0\n" + "a=recvonly\n" + ) + + s = socket.socket(socket.AF_INET, socket.SOCK_DGRAM, socket.IPPROTO_UDP) + s.setsockopt(socket.IPPROTO_IP, socket.IP_MULTICAST_IF, socket.inet_aton(a.iface)) + s.setsockopt(socket.IPPROTO_IP, socket.IP_MULTICAST_TTL, a.ttl) + s.setsockopt(socket.IPPROTO_IP, socket.IP_MULTICAST_LOOP, 1) + dest = (a.group, a.port) + + def build(k): + n = k * frames + ts = (ts0 + n) & 0xFFFFFFFF + seq = (seq0 + k) & 0xFFFF + hdr = struct.pack("!BBHII", 0x80, a.pt, seq, ts, ssrc) + body = b"".join(sines[(n + i) % PERIOD] + b24(n + i) for i in range(frames)) + return hdr + body + + total = int(a.seconds * 1000 / a.ptime_ms) + period = a.ptime_ms / 1000 + late_max = 0.0 + late_over_1ms = 0 + sent = dropped = swapped = duped = 0 + held = None + start = time.perf_counter() + 0.05 + cpu0 = time.process_time() + print(f"sending {C} ch, {frames} frames/packet, {total} packets to {a.group}:{a.port} via {a.iface}, " + f"ts0 {ts0} seq0 {seq0}", flush=True) + for k in range(total): + deadline = start + k * period + while True: + d = deadline - time.perf_counter() + if d <= 0: + break + if d > 0.0003: + time.sleep(d - 0.0002) + late = time.perf_counter() - deadline + late_max = max(late_max, late) + if late > 0.001: + late_over_1ms += 1 + pkt = build(k) + if a.drop_every and k % a.drop_every == a.drop_every - 1: + dropped += 1 + continue + if a.swap_every and k % a.swap_every == a.swap_every - 2 and k + 1 < total: + held = pkt + continue + s.sendto(pkt, dest) + sent += 1 + if held is not None: + s.sendto(held, dest) + sent += 1 + swapped += 1 + held = None + if a.dup_every and k % a.dup_every == a.dup_every - 1: + s.sendto(pkt, dest) + duped += 1 + cpu = time.process_time() - cpu0 + print(f"done: sent {sent} (dropped {dropped}, swapped {swapped}, duplicated {duped}); " + f"pacing: worst {late_max*1000:.2f} ms late, {late_over_1ms} packets >1 ms late; " + f"sender cpu {cpu / max(a.seconds, 1e-9) * 100:.1f}%", flush=True) + + +if __name__ == "__main__": + sys.exit(main()) diff --git a/spikes/aes67/tools/check_wavs.py b/spikes/aes67/tools/check_wavs.py new file mode 100644 index 00000000..06bd00b8 --- /dev/null +++ b/spikes/aes67/tools/check_wavs.py @@ -0,0 +1,93 @@ +#!/usr/bin/env python3 +"""Checks the receiver's WAVs bit for bit against what aes67_send.py sent. + +The last channel is the ramp (n mod 2^24); its first sample gives the sample index n0 the recording starts at. +Every other channel must equal the sender's sine at n0+i. Prints, per channel: length, wrong samples, silent +(zero) samples where audio was expected, and the frequency from zero crossings. + + check_wavs.py DIR (expects DIR/aes67-ch01.wav ...) +""" +import glob +import json +import math +import os +import sys + +sys.path.insert(0, os.path.dirname(os.path.abspath(__file__))) +from aes67_send import PERIOD, RATE, sine_sample # noqa: E402 + + +def read_wav(path): + with open(path, "rb") as f: + data = f.read() + assert data[:4] == b"RIFF" and data[8:12] == b"WAVE", path + assert int.from_bytes(data[34:36], "little") == 24, "not 24-bit" + size = int.from_bytes(data[40:44], "little") + return data[44:44 + size] + + +def s24(b, i): + v = int.from_bytes(b[i * 3:i * 3 + 3], "little") + return v - (1 << 24) if v & 0x800000 else v + + +def zero_crossing_hz(b, seconds=1.0, skip=0): + n = min(len(b) // 3 - skip, int(RATE * seconds)) + ups = 0 + prev = s24(b, skip) + for i in range(skip + 1, skip + n): + v = s24(b, i) + if prev < 0 <= v: + ups += 1 + prev = v + return ups / (n / RATE) + + +def main(): + d = sys.argv[1] + files = sorted(glob.glob(os.path.join(d, "aes67-ch*.wav"))) + C = len(files) + chans = [read_wav(f) for f in files] + ramp = chans[-1] + frames = len(ramp) // 3 + n0 = int.from_bytes(ramp[0:3], "little") + result = {"channels": C, "frames": frames, "seconds": frames / RATE, "n0": n0, "perChannel": []} + chunk = PERIOD * 500 + for c, b in enumerate(chans): + is_ramp = c == C - 1 + if is_ramp: + def expect_bytes(start, count): + return b"".join(((n0 + start + i) & 0xFFFFFF).to_bytes(3, "little") for i in range(count)) + else: + pattern = b"".join((sine_sample(c, n) & 0xFFFFFF).to_bytes(3, "little") for n in range(PERIOD)) + def expect_bytes(start, count, pattern=pattern): + off = (n0 + start) % PERIOD + reps = (off + count) // PERIOD + 2 + return (pattern * reps)[off * 3:(off + count) * 3] + wrong = silent = 0 + first_wrong = None + for start in range(0, frames, chunk): + count = min(chunk, frames - start) + got = b[start * 3:(start + count) * 3] + exp = expect_bytes(start, count) + if got == exp: + continue + for i in range(count): + g = got[i * 3:i * 3 + 3] + if g != exp[i * 3:i * 3 + 3]: + wrong += 1 + if g == b"\0\0\0": + silent += 1 + if first_wrong is None: + first_wrong = start + i + entry = {"channel": c + 1, "kind": "ramp" if is_ramp else "sine", "frames": len(b) // 3, + "wrongSamples": wrong, "silentSamples": silent, "firstWrongFrame": first_wrong} + if not is_ramp: + entry["zeroCrossingHz"] = round(zero_crossing_hz(b, skip=min(frames // 2, RATE)), 1) + result["perChannel"].append(entry) + result["bitExact"] = all(e["wrongSamples"] == 0 for e in result["perChannel"]) + print(json.dumps(result, indent=2)) + + +if __name__ == "__main__": + main() From c890ab04fa200a8defb128fec622af1e163ceeba Mon Sep 17 00:00:00 2001 From: Eric Dahl Date: Sun, 15 Nov 2026 15:55:21 -0500 Subject: [PATCH 2/2] Spike: AES67 10-minute run, ffmpeg cross-check and findings (#1235) Assisted-by: Claude --- spikes/aes67/FINDINGS.md | 101 +++++++++++++++++++---- spikes/aes67/Sources/aes67rec/main.swift | 14 +++- 2 files changed, 97 insertions(+), 18 deletions(-) diff --git a/spikes/aes67/FINDINGS.md b/spikes/aes67/FINDINGS.md index c3fe079e..4dd03bb5 100644 --- a/spikes/aes67/FINDINGS.md +++ b/spikes/aes67/FINDINGS.md @@ -1,16 +1,89 @@ # AES67 spike: findings (#1235) -## Status (2026-11-15, paused) - -**Works (measured on macOS, multicast over loopback lo0 with TTL 0; the en0 counters show nothing left the Mac):** -- `aes67rec` (the Swift package here) parses the SDP, joins 239.69.83.67:5004, puts packets back in order by RTP timestamp, fills gaps with silence, and writes one 24-bit WAV per channel. 8 unit tests pass. -- `tools/aes67_send.py` sends L24/48000/8 at 1 ms ptime. `tools/check_wavs.py` checks the WAVs bit for bit: channels 1-7 are sines, and channel 8 is a ramp of the sample index. -- A clean 10 s run crossed the 16-bit sequence wrap and the 32-bit timestamp wrap: 10,000 packets, 0 lost, 0 reordered, 0 gaps, and all 8 WAVs bit-exact. Receiver CPU was 1.4% of one core, with 8 MB resident. -- A 20 s run with faults injected: the receiver's counts match what the sender injected. 20 dropped = 20 lost = 20 gaps (960 frames), 198 swapped = 198 reordered, and 39 duplicated = 39 duplicates. The WAVs are 960,000 frames long, as expected; the only wrong samples are the silent ones in the 960 dropped frames, and no sample shifted. Receiver CPU was 2.3%. -- Clock drift: -0.7 ppm against the kernel's monotonic arrival stamps (sender and receiver are on the same machine, so near 0 is expected), but -195 ppm against the wall clock, because macOS slews the wall clock. Any clock work must use monotonic time. -- Jitter in the 10 s run (mostly the Python sender's pacing): transit spread p50 0.5 ms, p99 1.0 ms, p99.9 2.8 ms, max 6.2 ms. The 20 ms reorder window is ample here. - -**Left:** -- The 10-minute run (loss, reordering, jitter, CPU) and the bit-exact check of its WAVs. -- A short interop run with ffmpeg as an independent sender (GStreamer isn't installed). -- Answers to the four questions: following the PTP clock, CPU, 4 streams (32 channels), and the iOS port (multicast entitlement, USB-C Ethernet). Loopback says nothing about loss on a real network. +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=` 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. diff --git a/spikes/aes67/Sources/aes67rec/main.swift b/spikes/aes67/Sources/aes67rec/main.swift index d1b1fb55..baa6b211 100644 --- a/spikes/aes67/Sources/aes67rec/main.swift +++ b/spikes/aes67/Sources/aes67rec/main.swift @@ -54,11 +54,17 @@ let bound = withUnsafePointer(to: &bindAddr) { $0.withMemoryRebound(to: sockaddr.self, capacity: 1) { bind(fd, $0, socklen_t(MemoryLayout.size)) } } guard bound == 0 else { die("bind: \(String(cString: strerror(errno)))") } -var mreq = ip_mreq(imr_multiaddr: in_addr(s_addr: inet_addr(sdp.group)), imr_interface: in_addr(s_addr: inet_addr(iface))) -guard setsockopt(fd, IPPROTO_IP, IP_ADD_MEMBERSHIP, &mreq, socklen_t(MemoryLayout.size)) == 0 else { - die("IP_ADD_MEMBERSHIP: \(String(cString: strerror(errno)))") +// A unicast c= address (e.g. 127.0.0.1 for the ffmpeg cross-check) is only bound, not joined. +let first = UInt32(bigEndian: inet_addr(sdp.group)) >> 28 +if first == 0xE { + var mreq = ip_mreq(imr_multiaddr: in_addr(s_addr: inet_addr(sdp.group)), imr_interface: in_addr(s_addr: inet_addr(iface))) + guard setsockopt(fd, IPPROTO_IP, IP_ADD_MEMBERSHIP, &mreq, socklen_t(MemoryLayout.size)) == 0 else { + die("IP_ADD_MEMBERSHIP: \(String(cString: strerror(errno)))") + } + print("joined \(sdp.group) on \(iface), SO_RCVBUF \(got) bytes") +} else { + print("unicast \(sdp.group):\(sdp.port), SO_RCVBUF \(got) bytes") } -print("joined \(sdp.group) on \(iface), SO_RCVBUF \(got) bytes") // MARK: recording state let bytesPerFrame = sdp.channels * sdp.bytesPerSample