Files
lintunes/lintunes/airplay/raop.py
T
trav efbee5c465 v0.59.0: LinTunes' own AirPlay 1 sender for third-party speakers
pyatv's handshakes play nothing on a WiiM; Music Assistant's cliairplay
plays on it through libraop's RAOP client. airplay/raop.py reproduces that
client's behaviour on the wire: one RTSP session with auth-setup, an
AppleLossless ANNOUNCE and RECORD carrying RTP-Info, OPTIONS keepalives,
a 2 s buffer, NTP-locked timestamps, a start that sends the first two
seconds at once, the timing responder and resends. Non-Apple speakers
stream through it; pyatv only finds them. Verified against shairport-sync
(decoded tone, flush on pause/seek, volume, metadata). Round 88's pyatv
compat hooks are gone.
2026-10-16 23:12:38 -07:00

637 lines
25 KiB
Python
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
"""LinTunes' own AirPlay 1 (RAOP) sender, for speakers pyatv can't play on.
pyatv's handshakes reach a WiiM (Linkplay) speaker and play nothing (Round
88); Music Assistant's cliairplay plays on it through libraop's RAOP client
(its "RAOP-compat" route: AirPlay 1 plus auth-setup, NTP timing). This is that
client's *behaviour* on the wire, written from the protocol rather than
translated, request for request:
- one RTSP session for the whole connection — ANNOUNCE (ALAC), SETUP,
RECORD carrying `RTP-Info`, no FLUSH before the first packet — kept alive
with OPTIONS every 25 s; songs, pauses and seeks are FLUSH + restart;
- auth-setup whenever the speaker's `et` lists 4, whatever its model;
- the iTunes User-Agent plus Client-Instance / DACP-ID / Active-Remote;
- a **2 s** buffer (`latency_frames` 88200, plus the 11025 every receiver
adds) against pyatv's 1.5 s — LinkPlay speakers go silent with a shallow
one — and RTP timestamps on the NTP clock itself, so the sync packet says
"frame `ts - latency` plays at NTP(`ts`)";
- a start `START_LEAD_MS` out: the first packets are already late when they
leave, so the first ~2 s go out at once and the speaker begins with a full
buffer;
- the NTP timing responder, resends from a 512-packet backlog, and a sync
packet every second.
One deliberate difference: audio is *uncompressed* ALAC (`alac_verbatim`).
libraop compresses with Apple's encoder; ffmpeg's encoder only writes
4096-sample frames (RAOP needs 352), and adaptive Rice coding in Python
would cost a share of a core on the GUI's interpreter. cliairplay's own
`--raw` is the same uncompressed form.
Pure asyncio, run on the AirPlay `AsyncLoop`; `NativeDevice` gives
`AirPlaySink` the slice of a pyatv device it uses.
"""
import asyncio
import contextlib
import logging
import os
import secrets
import socket
import struct
import time
from lintunes.airplay.support import alac_verbatim
log = logging.getLogger("lintunes.airplay.raop")
FRAMES_PER_PACKET = 352
SAMPLE_RATE = 44100
RAOP_LATENCY_MIN = 11025 # what every receiver adds to the sync's
DEFAULT_LATENCY_MS = 2000
START_LEAD_MS = 200 # libraop's minimum RAOP start lead
USER_AGENT = "iTunes/7.6.2 (Windows; N;)"
KEEPALIVE_S = 25.0
SYNC_INTERVAL_S = 1.0
BACKLOG = 512
RTSP_TIMEOUT_S = 10.0
VOLUME_MIN_DB = -30.0
VOLUME_MUTE_DB = -144.0
class RaopError(ConnectionError):
"""The speaker refused or dropped the session."""
# ---- clocks ----
# NTP here is a 32.32 fixed-point second count (on the Unix epoch, as
# libraop's gettimeofday-based clock is: only differences reach the speaker).
# A timestamp ("ts") is that clock counted in frames.
def ntp_now() -> int:
ns = time.time_ns()
seconds, rest = divmod(ns, 1_000_000_000)
return (seconds << 32) | ((rest << 32) // 1_000_000_000)
def ntp2ts(ntp: int, rate: int = SAMPLE_RATE) -> int:
return ((ntp >> 16) * rate) >> 16
def ts2ntp(ts: int, rate: int = SAMPLE_RATE) -> int:
return ((ts << 16) // rate) << 16
def ms2ts(ms: float, rate: int = SAMPLE_RATE) -> int:
return int(ms * rate // 1000)
def percent_to_db(percent: float) -> float:
"""pyatv's / libraop's volume: 0–100 linear onto −30..0 dB, 0 muted."""
percent = max(0.0, min(100.0, float(percent)))
if percent <= 0:
return VOLUME_MUTE_DB
return VOLUME_MIN_DB + (-VOLUME_MIN_DB) * percent / 100.0
# ---- packets ----
def audio_packet(first: bool, seq: int, ts: int, ssrc: int,
payload: bytes) -> bytes:
return struct.pack(">BBHII", 0x80, 0xE0 if first else 0x60,
seq & 0xFFFF, ts & 0xFFFFFFFF, ssrc) + payload
def sync_packet(first: bool, head_ts: int, latency_frames: int) -> bytes:
""""Frame `head - latency` plays at NTP(head)"; seq is always 7."""
ntp = ts2ntp(head_ts)
return struct.pack(">BBHIIII", 0x90 if first else 0x80, 0xD4, 7,
(head_ts - latency_frames) & 0xFFFFFFFF,
(ntp >> 32) & 0xFFFFFFFF, ntp & 0xFFFFFFFF,
head_ts & 0xFFFFFFFF)
def timing_reply(request: bytes, now_ntp: int) -> bytes | None:
"""Answer a timing request (type 0x52): its send time becomes our
reference, and we received and sent it 'now'."""
if len(request) < 32:
return None
send_time = request[24:32]
now = struct.pack(">II", (now_ntp >> 32) & 0xFFFFFFFF,
now_ntp & 0xFFFFFFFF)
return (bytes([request[0], 0x53 | 0x80]) + request[2:4] + b"\0\0\0\0"
+ send_time + now + now)
def parse_resend(data: bytes) -> tuple[int, int] | None:
"""A resend request (type 0x55): (first lost seq, count)."""
if len(data) != 8 or data[1] & 0x7F != 0x55:
return None
seq, count = struct.unpack(">HH", data[4:8])
return seq, count
def resend_packet(packet: bytes) -> bytes:
return b"\x80\xd6\x00\x01" + packet
def daap_item(title: str, artist: str, album: str) -> bytes:
"""Now-playing text as an `mlit` listing, libraop's layout."""
def tag(code: bytes, data: bytes) -> bytes:
return code + struct.pack(">I", len(data)) + data
body = tag(b"mikd", b"\x02")
for code, value in ((b"minm", title), (b"asar", artist),
(b"asal", album)):
if value:
body += tag(code, value.encode("utf-8"))
return tag(b"mlit", body)
def announce_sdp(sid: str, local_ip: str, peer_ip: str,
rate: int = SAMPLE_RATE) -> str:
return ("v=0\r\n"
f"o=iTunes {sid} 0 IN IP4 {local_ip}\r\n"
"s=iTunes\r\n"
f"c=IN IP4 {peer_ip}\r\n"
"t=0 0\r\n"
"m=audio 0 RTP/AVP 96\r\n"
"a=rtpmap:96 AppleLossless\r\n"
f"a=fmtp:96 {FRAMES_PER_PACKET} 0 16 40 10 14 2 255 0 0 {rate}\r\n")
def parse_transport(value: str) -> dict[str, int]:
ports = {}
for token in (value or "").split(";"):
key, _, number = token.partition("=")
if key.strip() in ("server_port", "control_port", "timing_port"):
with contextlib.suppress(ValueError):
ports[key.strip()] = int(number)
return ports
def metadata_caps(md: str) -> set[str]:
caps = set()
for digit, name in (("0", "text"), ("1", "artwork"), ("2", "progress")):
if digit in (md or ""):
caps.add(name)
return caps
def auth_setup_body() -> bytes:
"""0x01 (unencrypted) and a fresh X25519 public key, as libraop sends."""
from cryptography.hazmat.primitives.asymmetric.x25519 import (
X25519PrivateKey)
from cryptography.hazmat.primitives.serialization import (
Encoding, PublicFormat)
key = X25519PrivateKey.generate().public_key()
return b"\x01" + key.public_bytes(Encoding.Raw, PublicFormat.Raw)
# ---- RTSP ----
class _Rtsp:
"""Requests in libraop's header order, one at a time."""
def __init__(self, user_agent: str, extra: list[tuple[str, str]]):
self.user_agent = user_agent
self.extra = extra
self.url = ""
self.session: str | None = None
self.local_ip = ""
self._cseq = 0
self._reader = None
self._writer = None
self._lock = asyncio.Lock()
async def open(self, host: str, port: int, sid: str):
self._reader, self._writer = await asyncio.wait_for(
asyncio.open_connection(host, port), RTSP_TIMEOUT_S)
self.local_ip = self._writer.get_extra_info("sockname")[0]
self.url = f"rtsp://{host}/{sid}"
def closed(self) -> bool:
return (self._writer is None or self._writer.is_closing()
or self._reader.at_eof())
async def request(self, method: str, headers=(), body: bytes = b"",
content_type: str | None = None, url: str | None = None,
must_succeed: bool = True):
async with self._lock:
if self.closed():
raise RaopError("the speaker closed the connection")
self._cseq += 1
lines = [f"{method} {url or self.url} RTSP/1.0"]
lines += [f"{key}: {value}" for key, value in headers]
if content_type and body:
lines += [f"Content-Type: {content_type}",
f"Content-Length: {len(body)}"]
lines += [f"CSeq: {self._cseq}", f"User-Agent: {self.user_agent}"]
lines += [f"{key}: {value}" for key, value in self.extra]
if self.session is not None:
lines.append(f"Session: {self.session}")
message = ("\r\n".join(lines) + "\r\n\r\n").encode() + body
log.debug("> %s", message[:600])
self._writer.write(message)
try:
await self._writer.drain()
code, reply_headers, reply_body = await asyncio.wait_for(
self._response(), RTSP_TIMEOUT_S)
except (OSError, asyncio.IncompleteReadError,
asyncio.TimeoutError) as e:
raise RaopError(f"{method} got no answer ({e or type(e).__name__})")
log.debug("< %s %s %s", method, code, reply_headers)
if must_succeed and code != 200:
raise RaopError(f"the speaker refused {method} ({code})")
return code, reply_headers, reply_body
async def _response(self):
status = (await self._reader.readuntil(b"\r\n")).decode(
"latin-1").split()
code = int(status[1]) if len(status) > 1 and status[1].isdigit() else 0
headers = {}
while True:
line = (await self._reader.readuntil(b"\r\n")).decode("latin-1")
if line in ("\r\n", "\n"):
break
key, _, value = line.partition(":")
headers[key.strip().lower()] = value.strip()
length = int(headers.get("content-length", "0") or 0)
body = await self._reader.readexactly(length) if length else b""
return code, headers, body
def close(self):
if self._writer is not None:
self._writer.close()
self._writer = None
# ---- UDP ----
class _Udp(asyncio.DatagramProtocol):
def __init__(self, on_datagram=None):
self.transport = None
self._on_datagram = on_datagram
def connection_made(self, transport):
self.transport = transport
def datagram_received(self, data, addr):
if self._on_datagram is not None:
self._on_datagram(data, addr)
def error_received(self, exc):
log.debug("udp error: %s", exc)
@property
def port(self) -> int:
return self.transport.get_extra_info("sockname")[1]
def close(self):
if self.transport is not None:
self.transport.close()
self.transport = None
async def _udp(local_ip: str, on_datagram=None) -> _Udp:
loop = asyncio.get_running_loop()
_, protocol = await loop.create_datagram_endpoint(
lambda: _Udp(on_datagram), local_addr=(local_ip, 0),
family=socket.AF_INET)
return protocol
# ---- the session ----
class RaopClient:
"""One speaker: connect once, then play stretch after stretch.
State mirrors libraop: DOWN → FLUSHED (connected, nothing playing) →
STREAMING; `flush()` goes back to FLUSHED.
"""
def __init__(self, host: str, port: int, properties: dict,
latency_ms: int = DEFAULT_LATENCY_MS):
self.host = host
self.port = port
self.properties = dict(properties or {})
self.latency_frames = max(ms2ts(latency_ms), RAOP_LATENCY_MIN)
self.caps = metadata_caps(self.properties.get("md", ""))
self.state = "down"
self.volume_db: float | None = None
self.head_ts = 0
self.seq = secrets.randbelow(1 << 16)
self.ssrc = int.from_bytes(os.urandom(4), "big")
self._first = False
self._backlog: dict[int, bytes] = {}
self._rtsp: _Rtsp | None = None
self._timing: _Udp | None = None
self._control: _Udp | None = None
self._audio: _Udp | None = None
self._ports: dict[str, int] = {}
self._tasks: list[asyncio.Task] = []
self._last_keepalive = 0.0
# -- connecting --
@property
def latency(self) -> int:
"""Frames from a packet's timestamp to its being heard."""
return self.latency_frames + RAOP_LATENCY_MIN
def connected(self) -> bool:
return self.state != "down" and self._rtsp is not None \
and not self._rtsp.closed()
async def connect(self):
await self._teardown_quietly()
sid = f"{secrets.randbelow(10**10):010d}"
extra = [("Client-Instance", secrets.token_hex(8)),
("DACP-ID", secrets.token_hex(8).upper()),
("Active-Remote", str(secrets.randbelow(1 << 32)))]
model = self.properties.get("am", "")
agent = ("AirPlay/999.0.0" if "AudioAccessory" in model
or "AppleTV" in model else USER_AGENT)
rtsp = _Rtsp(agent, extra)
self._rtsp = rtsp
try:
await rtsp.open(self.host, self.port, sid)
except (OSError, asyncio.TimeoutError) as e:
raise RaopError(f"couldn't reach the speaker ({e})")
try:
if "4" in self.properties.get("et", ""):
# libraop carries on whatever the answer.
await rtsp.request("POST", body=auth_setup_body(),
content_type="application/octet-stream",
url="/auth-setup", must_succeed=False)
local = rtsp.local_ip
# Timing before ANNOUNCE: some receivers query it straight away.
self._timing = await _udp(local, self._on_timing)
await rtsp.request(
"ANNOUNCE", content_type="application/sdp",
body=announce_sdp(sid, local, self.host).encode())
self._control = await _udp(local, self._on_control)
self._audio = await _udp(local)
transport = ("RTP/AVP/UDP;unicast;interleaved=0-1;mode=record;"
f"control_port={self._control.port};"
f"timing_port={self._timing.port}")
_, headers, _ = await rtsp.request(
"SETUP", headers=[("Transport", transport)])
rtsp.session = (headers.get("session") or "").strip() or None
self._ports = parse_transport(headers.get("transport", ""))
if (rtsp.session is None or not self._ports.get("server_port")
or not self._ports.get("control_port")):
raise RaopError("the speaker's SETUP answer had no ports")
_, headers, _ = await rtsp.request("RECORD", headers=[
("Range", "npt=0-"),
("RTP-Info", f"seq={(self.seq + 1) & 0xFFFF};"
f"rtptime={ntp2ts(ntp_now()) & 0xFFFFFFFF}")])
with contextlib.suppress(ValueError):
self.latency_frames = max(
int(headers.get("audio-latency", "0")), self.latency_frames)
self.state = "flushed"
self._last_keepalive = time.monotonic()
self._tasks = [asyncio.ensure_future(self._control_loop())]
if self.volume_db is not None and self.volume_db > VOLUME_MUTE_DB:
await self._send_volume()
log.info("connected to %s:%d (latency %d frames)", self.host,
self.port, self.latency)
except BaseException:
await self._teardown_quietly()
raise
async def ensure_connected(self):
if not self.connected():
await self.connect()
# -- playing --
def start(self, start_ntp: int | None = None):
"""Begin a stretch: its first frame is heard at `start_ntp` (default
START_LEAD_MS from now). Mirrors raopcl_start_at + accept_frames."""
if start_ntp is None:
start_ntp = ntp_now() + ts2ntp(ms2ts(START_LEAD_MS))
self.head_ts = ntp2ts(start_ntp) - self.latency
self._first = True
self.state = "streaming"
self._send_sync(first=True)
def ready_for(self) -> float:
"""Seconds until the next packet is due (≤ 0: send it now)."""
due = self.head_ts + FRAMES_PER_PACKET
return (due - ntp2ts(ntp_now())) / SAMPLE_RATE
def send(self, pcm: bytes):
"""One packet of 352 frames of s16be stereo PCM."""
if len(pcm) < FRAMES_PER_PACKET * 4:
pcm = pcm + bytes(FRAMES_PER_PACKET * 4 - len(pcm))
self.seq = (self.seq + 1) & 0xFFFF
packet = audio_packet(self._first, self.seq, self.head_ts, self.ssrc,
alac_verbatim(pcm))
self._first = False
self._backlog[self.seq % BACKLOG] = (self.seq, packet)
self.head_ts += FRAMES_PER_PACKET
if self._audio is not None and self._audio.transport is not None:
self._audio.transport.sendto(
packet, (self.host, self._ports["server_port"]))
def heard_at(self, ts: int) -> float:
"""time.time() at which frame `ts` comes out of the speaker."""
return (ts + self.latency) / SAMPLE_RATE
async def flush(self):
"""Stop what the speaker has queued (pause, seek, next song)."""
if self.state != "streaming":
return
self.state = "flushed"
await self._rtsp.request("FLUSH", headers=[(
"RTP-Info", f"seq={(self.seq + 1) & 0xFFFF};"
f"rtptime={(self.head_ts + 1) & 0xFFFFFFFF}")],
must_succeed=False)
async def set_volume(self, db: float):
self.volume_db = db
if self.connected():
await self._send_volume()
async def _send_volume(self):
await self._rtsp.request(
"SET_PARAMETER", content_type="text/parameters",
body=f"volume: {self.volume_db:f}\r\n".encode())
async def set_metadata(self, title="", artist="", album="",
artwork: bytes | None = None,
elapsed_ms: int = 0, duration_ms: int = 0):
"""Now playing, as far as the speaker said it takes each part
(`md`). Best effort: a refusal is never fatal (libraop's rule)."""
rtptime = (self.head_ts + self.latency_frames) & 0xFFFFFFFF
info = [("RTP-Info", f"rtptime={rtptime}")]
if "text" in self.caps:
await self._rtsp.request(
"SET_PARAMETER", headers=info,
content_type="application/x-dmap-tagged",
body=daap_item(title, artist, album), must_succeed=False)
if "artwork" in self.caps and artwork:
await self._rtsp.request(
"SET_PARAMETER", headers=info, content_type="image/jpeg",
body=artwork, must_succeed=False)
if "progress" in self.caps and self.state == "streaming":
now = ntp2ts(ntp_now())
started = now - ms2ts(elapsed_ms)
end = started + ms2ts(duration_ms) if duration_ms else now
await self._rtsp.request(
"SET_PARAMETER", content_type="text/parameters",
body=(f"progress: {started & 0xFFFFFFFF}/{now & 0xFFFFFFFF}/"
f"{end & 0xFFFFFFFF}\r\n").encode(),
must_succeed=False)
# -- the background --
def _send_sync(self, first: bool = False):
if self.state != "streaming" or self._control is None \
or self._control.transport is None:
return
self._control.transport.sendto(
sync_packet(first, self.head_ts, self.latency_frames),
(self.host, self._ports["control_port"]))
def _on_timing(self, data: bytes, addr):
reply = timing_reply(data, ntp_now())
if reply is not None and self._timing is not None \
and self._timing.transport is not None:
self._timing.transport.sendto(reply, addr)
def _on_control(self, data: bytes, addr):
lost = parse_resend(data)
if lost is None or self._control is None:
return
first, count = lost
for i in range(count):
seq = (first + i) & 0xFFFF
entry = self._backlog.get(seq % BACKLOG)
if entry is not None and entry[0] == seq \
and self._control.transport is not None:
self._control.transport.sendto(
resend_packet(entry[1]),
(self.host, self._ports["control_port"]))
async def _control_loop(self):
while self.state != "down":
await asyncio.sleep(SYNC_INTERVAL_S)
if self.state == "down":
break
self._send_sync()
if time.monotonic() - self._last_keepalive >= KEEPALIVE_S:
self._last_keepalive = time.monotonic()
try:
await self._rtsp.request("OPTIONS", url="*",
must_succeed=False)
except RaopError as e:
log.info("keepalive failed: %s", e)
self.state = "down"
# -- closing --
async def close(self):
"""FLUSH and TEARDOWN, as libraop's disconnect does."""
if self.connected():
with contextlib.suppress(RaopError):
await self._rtsp.request("FLUSH", headers=[(
"RTP-Info", f"seq={(self.seq + 1) & 0xFFFF};"
f"rtptime={(self.head_ts + 1) & 0xFFFFFFFF}")],
must_succeed=False)
with contextlib.suppress(RaopError):
await self._rtsp.request("TEARDOWN", must_succeed=False)
await self._teardown_quietly()
async def _teardown_quietly(self):
self.state = "down"
tasks, self._tasks = self._tasks, []
for task in tasks:
task.cancel()
for task in tasks:
with contextlib.suppress(BaseException):
await task
for udp in (self._timing, self._control, self._audio):
if udp is not None:
udp.close()
self._timing = self._control = self._audio = None
if self._rtsp is not None:
self._rtsp.close()
self._rtsp = None
self._backlog.clear()
# ---- what AirPlaySink drives ----
class NativeDevice:
"""The pieces of a pyatv device `AirPlaySink` uses — `stream.stream_file`,
`audio.set_volume`, `close()` — over a RaopClient."""
def __init__(self, client: RaopClient):
self.client = client
self.stream = self
self.audio = self
async def connect(self):
await self.client.connect()
async def stream_file(self, request, metadata=None):
"""Play one stretch of a song: ffmpeg's PCM, paced packet by packet,
then wait until the last of it has been heard. A cancel (pause,
seek, next) flushes what the speaker has queued."""
from lintunes.airplay.stream import _ffmpeg_source
client = self.client
request.latency_ms = START_LEAD_MS
await client.ensure_connected()
if client.state == "streaming":
await client.flush()
source = await _ffmpeg_source().open(request, SAMPLE_RATE, 2, 2)
try:
client.start()
meta_task = asyncio.ensure_future(self._metadata(request, metadata))
last_ts = None
while True:
pcm = await source.readframes(FRAMES_PER_PACKET)
if not pcm:
break
wait = client.ready_for()
if wait > 0:
await asyncio.sleep(wait)
if not client.connected():
return # dropped: the request isn't exhausted
last_ts = client.head_ts
client.send(pcm)
meta_task.cancel()
if last_ts is not None:
# Until the end has been heard, as pyatv's padding waits.
end = client.heard_at(last_ts + FRAMES_PER_PACKET)
while time.time() < end and client.connected():
await asyncio.sleep(min(0.25, end - time.time()))
except asyncio.CancelledError:
with contextlib.suppress(Exception):
await asyncio.wait_for(client.flush(), 2.0)
raise
finally:
await source.close()
async def _metadata(self, request, metadata):
if metadata is None:
return
try:
await self.client.set_metadata(
getattr(metadata, "title", "") or "",
getattr(metadata, "artist", "") or "",
getattr(metadata, "album", "") or "",
getattr(metadata, "artwork", None),
elapsed_ms=request.start_ms,
duration_ms=int((getattr(metadata, "duration", 0) or 0)
* 1000))
except RaopError as e:
log.info("metadata: %s", e)
async def set_volume(self, percent: float):
await self.client.set_volume(percent_to_db(percent))
def close(self):
return [self.client.close()]