@basmilius/apple-raop 0.9.18 → 0.10.0

package/dist/index.mjs

@@ -6,32 +6,74 @@ import { Context, Discovery, generateActiveRemoteId, generateDacpId, generateSes
 import { RtspClient } from "@basmilius/apple-rtsp";
 
 //#region src/types.ts
+/**
+* Bitmask enum for encryption types supported by the RAOP receiver.
+* Values are parsed from the `et` mDNS TXT record field.
+*/
 let EncryptionType = /* @__PURE__ */ function(EncryptionType) {
+	/** No encryption information available. */
 	EncryptionType[EncryptionType["Unknown"] = 0] = "Unknown";
+	/** Receiver supports unencrypted streams. */
 	EncryptionType[EncryptionType["Unencrypted"] = 1] = "Unencrypted";
+	/** Receiver supports MFi-SAP encryption (AirPort Express). */
 	EncryptionType[EncryptionType["MFiSAP"] = 2] = "MFiSAP";
 	return EncryptionType;
 }({});
+/**
+* Bitmask enum for metadata types supported by the RAOP receiver.
+* Values are parsed from the `md` mDNS TXT record field.
+*/
 let MetadataType = /* @__PURE__ */ function(MetadataType) {
+	/** Receiver does not support metadata. */
 	MetadataType[MetadataType["NotSupported"] = 0] = "NotSupported";
+	/** Receiver supports text metadata (title, artist, album). */
 	MetadataType[MetadataType["Text"] = 1] = "Text";
+	/** Receiver supports album artwork. */
 	MetadataType[MetadataType["Artwork"] = 2] = "Artwork";
+	/** Receiver supports progress/duration information. */
 	MetadataType[MetadataType["Progress"] = 4] = "Progress";
 	return MetadataType;
 }({});
 
 //#endregion
 //#region src/packets.ts
+/**
+* Fixed-size FIFO buffer for recently sent RTP audio packets.
+* Used to fulfill retransmission requests from the receiver when
+* packets are lost in transit.
+*/
 var PacketFifo = class {
+	/** Maximum number of packets to retain. */
 	#maxSize;
+	/** Map of sequence number to packet data. */
 	#packets = /* @__PURE__ */ new Map();
+	/** Insertion-ordered list of sequence numbers for eviction. */
 	#order = [];
+	/**
+	* Creates a new packet FIFO with the given capacity.
+	*
+	* @param maxSize - Maximum number of packets to store before evicting the oldest.
+	*/
 	constructor(maxSize) {
 		this.#maxSize = maxSize;
 	}
+	/**
+	* Retrieves a packet by its RTP sequence number.
+	*
+	* @param seqno - RTP sequence number to look up.
+	* @returns The packet buffer, or undefined if not in the backlog.
+	*/
 	get(seqno) {
 		return this.#packets.get(seqno);
 	}
+	/**
+	* Stores a packet in the backlog. If the sequence number already
+	* exists, the call is ignored. When the backlog exceeds its maximum
+	* size, the oldest packets are evicted.
+	*
+	* @param seqno - RTP sequence number of the packet.
+	* @param packet - Full RTP packet data including header.
+	*/
 	set(seqno, packet) {
 		if (this.#packets.has(seqno)) return;
 		this.#packets.set(seqno, packet);
@@ -41,14 +83,27 @@ var PacketFifo = class {
 			if (oldest !== void 0) this.#packets.delete(oldest);
 		}
 	}
+	/**
+	* Checks whether a packet with the given sequence number is in the backlog.
+	*
+	* @param seqno - RTP sequence number to check.
+	* @returns True if the packet exists in the backlog.
+	*/
 	has(seqno) {
 		return this.#packets.has(seqno);
 	}
+	/**
+	* Removes all packets from the backlog.
+	*/
 	clear() {
 		this.#packets.clear();
 		this.#order.length = 0;
 	}
 };
+/**
+* Encoder for RTP audio packet headers (12 bytes).
+* Produces the standard RTP fixed header used for RAOP audio data packets.
+*/
 const AudioPacketHeader = { encode(header, payloadType, seqno, timestamp, ssrc) {
 	const packet = Buffer.allocUnsafe(12);
 	packet.writeUInt8(header, 0);
@@ -58,6 +113,11 @@ const AudioPacketHeader = { encode(header, payloadType, seqno, timestamp, ssrc)
 	packet.writeUInt32BE(ssrc, 8);
 	return packet;
 } };
+/**
+* Encoder for RAOP timing synchronization packets (20 bytes).
+* Sent periodically over the control channel to synchronize
+* the receiver's playback clock with the sender's RTP timestamps.
+*/
 const SyncPacket = { encode(header, payloadType, seqno, rtpTimestamp, ntpSec, ntpFrac, rtpTimestampNow) {
 	const packet = Buffer.allocUnsafe(20);
 	packet.writeUInt8(header, 0);
@@ -69,6 +129,13 @@ const SyncPacket = { encode(header, payloadType, seqno, rtpTimestamp, ntpSec, nt
 	packet.writeUInt32BE(rtpTimestampNow, 16);
 	return packet;
 } };
+/**
+* Decodes a retransmit request packet received on the control channel.
+* The request contains the starting sequence number and count of lost packets.
+*
+* @param data - Raw UDP packet data from the receiver.
+* @returns Parsed retransmit request with sequence number and packet count.
+*/
 function decodeRetransmitRequest(data) {
 	return {
 		lostSeqno: data.readUInt16BE(4),
@@ -78,11 +145,25 @@ function decodeRetransmitRequest(data) {
 
 //#endregion
 //#region src/utils.ts
+/**
+* Converts a linear volume percentage (0-100) to a dBFS value
+* suitable for the RAOP `volume` SET_PARAMETER command.
+*
+* @param volume - Volume as a percentage (0 = silent, 100 = full).
+* @returns Volume in dBFS (-144 for mute, 0 for full volume).
+*/
 function pctToDbfs(volume) {
 	if (volume <= 0) return -144;
 	if (volume >= 100) return 0;
 	return 20 * Math.log10(volume / 100);
 }
+/**
+* Parses the `et` (encryption types) field from mDNS TXT record
+* properties into an EncryptionType bitmask.
+*
+* @param properties - mDNS TXT record key-value pairs.
+* @returns Bitmask of supported encryption types.
+*/
 function getEncryptionTypes(properties) {
 	const et = properties.get("et");
 	if (!et) return EncryptionType.Unknown;
@@ -94,6 +175,13 @@ function getEncryptionTypes(properties) {
 	}
 	return types;
 }
+/**
+* Parses the `md` (metadata types) field from mDNS TXT record
+* properties into a MetadataType bitmask.
+*
+* @param properties - mDNS TXT record key-value pairs.
+* @returns Bitmask of supported metadata types.
+*/
 function getMetadataTypes(properties) {
 	const md = properties.get("md");
 	if (!md) return MetadataType.NotSupported;
@@ -106,6 +194,14 @@ function getMetadataTypes(properties) {
 	}
 	return types;
 }
+/**
+* Extracts audio format properties from mDNS TXT record fields.
+* Falls back to CD-quality defaults (44100 Hz, 2 channels, 16-bit)
+* when properties are missing.
+*
+* @param properties - mDNS TXT record key-value pairs.
+* @returns A tuple of [sampleRate, channels, bytesPerChannel].
+*/
 function getAudioProperties(properties) {
 	return [
 		parseInt(properties.get("sr") ?? "44100", 10),
@@ -116,31 +212,81 @@ function getAudioProperties(properties) {
 
 //#endregion
 //#region src/controlClient.ts
-function ntpFromTs(timestamp, sampleRate) {
-	const seconds = Math.floor(timestamp / sampleRate);
-	const fraction = timestamp % sampleRate * 4294967295 / sampleRate;
-	return BigInt(seconds) << 32n | BigInt(Math.floor(fraction));
+/**
+* Converts an RTP timestamp to a wall-clock NTP timestamp using anchor points.
+*
+* Uses a fixed anchor pair (RTP timestamp + NTP time) established when the
+* stream starts. The elapsed samples from the anchor are computed with 32-bit
+* unsigned wrap handling, then converted to an NTP offset added to the anchor NTP.
+*
+* @param rtpTimestamp - Current RTP timestamp in audio frames.
+* @param sampleRate - Audio sample rate in Hz.
+* @param anchorRtp - RTP timestamp at the anchor point.
+* @param anchorNtp - NTP timestamp at the anchor point.
+* @returns 64-bit NTP wall-clock timestamp.
+*/
+function ntpFromTs(rtpTimestamp, sampleRate, anchorRtp, anchorNtp) {
+	let elapsedSamples;
+	if (rtpTimestamp >= anchorRtp) elapsedSamples = rtpTimestamp - anchorRtp;
+	else elapsedSamples = 4294967296 - anchorRtp + rtpTimestamp;
+	const elapsedSeconds = Math.floor(elapsedSamples / sampleRate);
+	const elapsedFraction = elapsedSamples % sampleRate * 4294967295 / sampleRate;
+	return anchorNtp + (BigInt(elapsedSeconds) << 32n | BigInt(Math.floor(elapsedFraction)));
 }
+/**
+* UDP control channel client for RAOP streaming. Responsible for two tasks:
+* 1. Sending periodic timing sync packets to the receiver so it can
+*    synchronize its playback clock with our RTP timestamps.
+* 2. Handling retransmit requests from the receiver by resending lost
+*    packets from the packet backlog.
+*/
 var ControlClient = class extends EventEmitter {
+	/** Application context providing logger and device identity. */
+	#appContext;
+	/** UDP socket for the control channel. */
 	#transport;
+	/** Shared streaming state containing timestamps, ports, and audio format. */
 	#context;
+	/** FIFO backlog of recently sent packets for retransmission. */
 	#packetBacklog;
+	/** Interval timer handle for periodic sync packet sending. */
 	#syncTask;
-	#abortController;
+	/** Local UDP port assigned after binding. */
 	#localPort;
-	constructor(context, packetBacklog) {
+	/** RTP timestamp at the anchor point for NTP conversion. */
+	#anchorRtp = 0;
+	/** NTP wall-clock timestamp at the anchor point. */
+	#anchorNtp = 0n;
+	/**
+	* Creates a new control client.
+	*
+	* @param appContext - Application context for logging.
+	* @param context - Shared stream context with RTP state.
+	* @param packetBacklog - Packet FIFO for retransmit lookups.
+	*/
+	constructor(appContext, context, packetBacklog) {
 		super();
+		this.#appContext = appContext;
 		this.#context = context;
 		this.#packetBacklog = packetBacklog;
 	}
+	/** Local UDP port the control channel is bound to, or 0 if not yet bound. */
 	get port() {
 		return this.#localPort ?? 0;
 	}
+	/**
+	* Binds the control channel UDP socket to a local address and port.
+	* Resolves once the socket is listening and the assigned port is known.
+	*
+	* @param localIp - Local IP address to bind to.
+	* @param port - Desired port number (0 for auto-assign).
+	* @throws When the UDP socket encounters a bind error.
+	*/
 	async bind(localIp, port) {
 		return new Promise((resolve, reject) => {
 			this.#transport = createSocket("udp4");
 			this.#transport.on("error", (err) => {
-				console.error("Control connection error:", err);
+				this.#appContext.logger.error("[raop-control]", "Control connection error:", err);
 				reject(err);
 			});
 			this.#transport.on("message", (data, rinfo) => {
@@ -153,6 +299,9 @@ var ControlClient = class extends EventEmitter {
 			this.#transport.bind(port, localIp);
 		});
 	}
+	/**
+	* Stops the sync task and closes the UDP socket, releasing all resources.
+	*/
 	close() {
 		this.stop();
 		if (this.#transport) {
@@ -160,26 +309,41 @@ var ControlClient = class extends EventEmitter {
 			this.#transport = void 0;
 		}
 	}
+	/**
+	* Starts sending periodic sync packets to the receiver. Sync packets
+	* are sent immediately and then every second to keep the receiver's
+	* playback clock aligned.
+	*
+	* @param remoteAddr - IP address of the RAOP receiver.
+	* @throws When the sync task is already running.
+	*/
 	start(remoteAddr) {
 		if (this.#syncTask) throw new Error("Already running");
-		this.#abortController = new AbortController();
+		this.#anchorRtp = this.#context.headTs;
+		this.#anchorNtp = NTP.now();
 		this.#startSyncTask(remoteAddr, this.#context.controlPort);
 	}
+	/**
+	* Stops the periodic sync task without closing the UDP socket.
+	*/
 	stop() {
-		if (this.#abortController) {
-			this.#abortController.abort();
-			this.#abortController = void 0;
-		}
 		if (this.#syncTask) {
 			clearInterval(this.#syncTask);
 			this.#syncTask = void 0;
 		}
 	}
+	/**
+	* Starts the periodic sync packet sending loop. The first packet uses
+	* header byte 0x90 (marker bit set), subsequent packets use 0x80.
+	*
+	* @param addr - Remote receiver IP address.
+	* @param port - Remote control port.
+	*/
 	#startSyncTask(addr, port) {
 		let firstPacket = true;
 		const sendSync = () => {
 			if (!this.#transport) return;
-			const currentTime = ntpFromTs(this.#context.headTs, this.#context.sampleRate);
+			const currentTime = ntpFromTs(this.#context.headTs, this.#context.sampleRate, this.#anchorRtp, this.#anchorNtp);
 			const [currentSec, currentFrac] = NTP.parts(currentTime);
 			const packet = SyncPacket.encode(firstPacket ? 144 : 128, 212, 7, this.#context.headTs - this.#context.latency, currentSec, currentFrac, this.#context.headTs);
 			firstPacket = false;
@@ -188,15 +352,32 @@ var ControlClient = class extends EventEmitter {
 		sendSync();
 		this.#syncTask = setInterval(sendSync, 1e3);
 	}
+	/**
+	* Handles incoming UDP messages on the control channel. Dispatches
+	* retransmit requests (type 0x55) and logs unhandled message types.
+	*
+	* @param data - Raw UDP packet data.
+	* @param rinfo - Remote address info of the sender.
+	*/
 	#onMessage(data, rinfo) {
 		if ((data[1] & 127) === 85) this.#retransmitLostPackets(decodeRetransmitRequest(data), rinfo);
-		else console.debug("Received unhandled control data from", rinfo, data);
-	}
+		else this.#appContext.logger.debug("[raop-control]", "Received unhandled control data from", rinfo, data);
+	}
+	/**
+	* Resends lost packets requested by the receiver. For each requested
+	* sequence number, sends the original packet wrapped in a retransmit
+	* response (type 0xD6). If the packet is no longer in the backlog,
+	* sends an empty futile response to acknowledge the request.
+	*
+	* @param request - Parsed retransmit request with starting sequence number and count.
+	* @param addr - Remote address to send retransmitted packets to.
+	*/
 	#retransmitLostPackets(request, addr) {
 		for (let i = 0; i < request.lostPackets; i++) {
-			const seqno = request.lostSeqno + i;
+			const seqno = request.lostSeqno + i & 65535;
 			if (this.#packetBacklog.has(seqno)) {
 				const packet = this.#packetBacklog.get(seqno);
+				if (packet.byteLength < 4) continue;
 				const originalSeqno = packet.subarray(2, 4);
 				const resp = Buffer.concat([
 					Buffer.from([128, 214]),
@@ -204,16 +385,32 @@ var ControlClient = class extends EventEmitter {
 					packet
 				]);
 				if (this.#transport) this.#transport.send(resp, addr.port, addr.address);
-			} else console.debug(`Packet ${seqno} not in backlog`);
+			} else {
+				const seqBuf = Buffer.alloc(2);
+				seqBuf.writeUInt16BE(seqno);
+				const resp = Buffer.concat([
+					Buffer.from([128, 214]),
+					seqBuf,
+					Buffer.alloc(4)
+				]);
+				if (this.#transport) this.#transport.send(resp, addr.port, addr.address);
+			}
 		}
 	}
 };
 
 //#endregion
 //#region src/rtspClient.ts
+/** User-Agent header value sent with all RTSP requests. */
 const USER_AGENT = "AirPlay/550.10";
+/** Number of audio frames per RTP packet, used in SDP ANNOUNCE payload. */
 const FRAMES_PER_PACKET$1 = 352;
+/** Single-byte flag indicating unencrypted auth-setup mode. */
 const AUTH_SETUP_UNENCRYPTED = Buffer.from([1]);
+/**
+* Static Curve25519 public key sent during `/auth-setup` for
+* MFi-SAP authentication with AirPort Express devices.
+*/
 const CURVE25519_PUB_KEY = Buffer.from([
 	89,
 	2,
@@ -248,12 +445,27 @@ const CURVE25519_PUB_KEY = Buffer.from([
 	29,
 	78
 ]);
+/**
+* Computes an HTTP Digest authentication header value using MD5.
+*
+* @param method - RTSP method (may be empty for default headers).
+* @param uri - Request URI.
+* @param info - Digest credentials and challenge parameters.
+* @returns Formatted Digest authorization header value.
+*/
 function getDigestPayload(method, uri, info) {
 	const ha1 = createHash("md5").update(`${info.username}:${info.realm}:${info.password}`).digest("hex");
 	const ha2 = createHash("md5").update(`${method}:${uri}`).digest("hex");
 	const response = createHash("md5").update(`${ha1}:${info.nonce}:${ha2}`).digest("hex");
 	return `Digest username="${info.username}", realm="${info.realm}", nonce="${info.nonce}", uri="${uri}", response="${response}"`;
 }
+/**
+* Builds an SDP (Session Description Protocol) body for the RTSP
+* ANNOUNCE request, describing the audio format and codec parameters.
+*
+* @param options - Audio format and connection details.
+* @returns SDP payload string with CRLF line endings.
+*/
 function buildAnnouncePayload(options) {
 	return [
 		"v=0",
@@ -266,44 +478,70 @@ function buildAnnouncePayload(options) {
 		`a=fmtp:96 ${FRAMES_PER_PACKET$1} 0 ${options.bitsPerChannel} 40 10 14 ${options.channels} 255 0 0 ${options.sampleRate}`
 	].join("\r\n") + "\r\n";
 }
+/**
+* RAOP-specific RTSP client that extends the base RTSP client with
+* Apple audio streaming commands. Handles the full RAOP RTSP lifecycle:
+* ANNOUNCE, SETUP, RECORD, SET_PARAMETER, FLUSH, TEARDOWN, as well as
+* authentication (auth-setup, digest) and metadata/artwork publishing.
+*/
 var RaopRtspClient = class extends RtspClient {
+	/** Active-Remote identifier used for DACP remote control pairing. */
 	get activeRemoteId() {
 		return this.#activeRemoteId;
 	}
+	/** DACP identifier used for remote control discovery. */
 	get dacpId() {
 		return this.#dacpId;
 	}
+	/** RTSP session identifier string included in session-scoped requests. */
 	get rtspSessionId() {
 		return this.#rtspSessionId;
 	}
+	/** Numeric session identifier used in the RTSP URI path. */
 	get sessionId() {
 		return this.#sessionId;
 	}
+	/** RTSP URI for this session, formatted as `rtsp://<localIp>/<sessionId>`. */
 	get uri() {
 		return `rtsp://${this.connection.localIp}/${this.#sessionId}`;
 	}
+	/** Local and remote IP addresses of the RTSP connection. */
 	get connection() {
 		return {
-			localIp: this.#localIp,
+			localIp: this.localAddress,
 			remoteIp: this.address
 		};
 	}
+	/** Generated Active-Remote identifier for DACP. */
 	#activeRemoteId;
+	/** Generated DACP identifier for remote control. */
 	#dacpId;
+	/** Generated RTSP session identifier. */
 	#rtspSessionId;
+	/** Random numeric session identifier for the RTSP URI. */
 	#sessionId;
-	#localIp = "0.0.0.0";
+	/** Digest authentication credentials, set after a 401 challenge. */
 	#digestInfo;
+	/**
+	* Creates a new RAOP RTSP client and generates unique session identifiers.
+	*
+	* @param context - Application context for logging and device identity.
+	* @param address - IP address of the RAOP receiver.
+	* @param port - RTSP port of the RAOP receiver.
+	*/
 	constructor(context, address, port) {
 		super(context, address, port);
 		this.#activeRemoteId = generateActiveRemoteId();
 		this.#dacpId = generateDacpId();
 		this.#rtspSessionId = generateSessionId();
 		this.#sessionId = Math.floor(Math.random() * 4294967295);
-		this.on("connect", () => {
-			this.#localIp = "0.0.0.0";
-		});
 	}
+	/**
+	* Returns default headers included with every RTSP request, including
+	* DACP identifiers, user-agent, and digest authorization if available.
+	*
+	* @returns Header key-value pairs.
+	*/
 	getDefaultHeaders() {
 		const headers = {
 			"DACP-ID": this.#dacpId,
@@ -314,6 +552,12 @@ var RaopRtspClient = class extends RtspClient {
 		if (this.#digestInfo) headers["Authorization"] = getDigestPayload("", this.uri, this.#digestInfo);
 		return headers;
 	}
+	/**
+	* Fetches device information from the `/info` endpoint. Returns the
+	* parsed plist response as a dictionary, or an empty object on failure.
+	*
+	* @returns Device info dictionary, or empty object if unavailable.
+	*/
 	async info() {
 		try {
 			const response = await this.exchange("GET", "/info", { allowError: true });
@@ -332,6 +576,11 @@ var RaopRtspClient = class extends RtspClient {
 			return {};
 		}
 	}
+	/**
+	* Performs MFi-SAP authentication setup by sending a Curve25519 public
+	* key to `/auth-setup`. Required for AirPort Express devices that use
+	* MFi-SAP encryption.
+	*/
 	async authSetup() {
 		const body = Buffer.concat([AUTH_SETUP_UNENCRYPTED, CURVE25519_PUB_KEY]);
 		await this.exchange("POST", "/auth-setup", {
@@ -340,6 +589,17 @@ var RaopRtspClient = class extends RtspClient {
 			protocol: "HTTP/1.1"
 		});
 	}
+	/**
+	* Sends an RTSP ANNOUNCE request with an SDP body describing the audio
+	* format. If the receiver responds with a 401 challenge and a password
+	* is provided, retries with HTTP Digest authentication.
+	*
+	* @param bytesPerChannel - Bytes per audio channel sample (e.g. 2 for 16-bit).
+	* @param channels - Number of audio channels.
+	* @param sampleRate - Audio sample rate in Hz.
+	* @param password - Optional password for digest authentication.
+	* @returns The RTSP response.
+	*/
 	async announce(bytesPerChannel, channels, sampleRate, password) {
 		const body = buildAnnouncePayload({
 			sessionId: this.#sessionId,
@@ -374,24 +634,60 @@ var RaopRtspClient = class extends RtspClient {
 		}
 		return response;
 	}
+	/**
+	* Sends an RTSP SETUP request to negotiate transport parameters
+	* (ports, protocol) with the receiver.
+	*
+	* @param headers - Optional additional headers (e.g. Transport).
+	* @param body - Optional request body.
+	* @returns The RTSP response containing server-assigned ports in the Transport header.
+	*/
 	async setup(headers, body) {
 		return await this.exchange("SETUP", this.uri, {
 			headers,
 			body
 		});
 	}
+	/**
+	* Sends an RTSP RECORD request to begin audio playback on the receiver.
+	* Includes RTP-Info and Range headers for stream positioning.
+	*
+	* @param headers - Optional headers (typically Range, Session, RTP-Info).
+	*/
 	async record(headers) {
 		await this.exchange("RECORD", this.uri, { headers });
 	}
+	/**
+	* Sends an RTSP FLUSH request to clear the receiver's audio buffer
+	* and reset playback to the specified RTP position.
+	*
+	* @param options - Headers including Session and RTP-Info for flush positioning.
+	*/
 	async flush(options) {
 		await this.exchange("FLUSH", this.uri, { headers: options.headers });
 	}
+	/**
+	* Sends a SET_PARAMETER request with a text/parameters content type.
+	* Used for setting volume, progress, and other scalar parameters.
+	*
+	* @param name - Parameter name (e.g. "volume", "progress").
+	* @param value - Parameter value as a string.
+	*/
 	async setParameter(name, value) {
 		await this.exchange("SET_PARAMETER", this.uri, {
 			contentType: "text/parameters",
 			body: `${name}: ${value}`
 		});
 	}
+	/**
+	* Sends track metadata (title, artist, album, duration) to the receiver
+	* as DAAP-tagged data via SET_PARAMETER.
+	*
+	* @param session - RTSP session identifier.
+	* @param rtpseq - Current RTP sequence number for the RTP-Info header.
+	* @param rtptime - Current RTP timestamp for the RTP-Info header.
+	* @param metadata - Track metadata to send.
+	*/
 	async setMetadata(session, rtpseq, rtptime, metadata) {
 		const daapData = DAAP.encodeTrackMetadata({
 			title: metadata.title,
@@ -408,6 +704,15 @@ var RaopRtspClient = class extends RtspClient {
 			body: daapData
 		});
 	}
+	/**
+	* Sends album artwork to the receiver via SET_PARAMETER. Automatically
+	* detects PNG images by magic bytes, defaulting to JPEG otherwise.
+	*
+	* @param session - RTSP session identifier.
+	* @param rtpseq - Current RTP sequence number for the RTP-Info header.
+	* @param rtptime - Current RTP timestamp for the RTP-Info header.
+	* @param artwork - Image data buffer (JPEG or PNG).
+	*/
 	async setArtwork(session, rtpseq, rtptime, artwork) {
 		let contentType = "image/jpeg";
 		if (artwork[0] === 137 && artwork[1] === 80) contentType = "image/png";
@@ -420,9 +725,22 @@ var RaopRtspClient = class extends RtspClient {
 			body: artwork
 		});
 	}
+	/**
+	* Sends a feedback request to `/feedback` to keep the session alive.
+	* Typically called periodically during active streaming.
+	*
+	* @param allowError - Whether to suppress HTTP error responses.
+	* @returns The feedback response.
+	*/
 	async feedback(allowError = false) {
 		return await this.exchange("POST", "/feedback", { allowError });
 	}
+	/**
+	* Sends an RTSP TEARDOWN request to end the streaming session
+	* and release server-side resources.
+	*
+	* @param session - RTSP session identifier to tear down.
+	*/
 	async teardown(session) {
 		await this.exchange("TEARDOWN", this.uri, { headers: { "Session": session } });
 	}
@@ -430,31 +748,69 @@ var RaopRtspClient = class extends RtspClient {
 
 //#endregion
 //#region src/statistics.ts
+/**
+* Tracks real-time streaming statistics to detect when audio packet
+* sending falls behind wall-clock time. Uses high-resolution monotonic
+* timers to compare actual frames sent against expected frame count.
+*/
 var Statistics = class {
+	/** Audio sample rate in Hz, used to compute expected frame counts. */
 	sampleRate;
+	/** High-resolution monotonic timestamp (nanoseconds) captured at construction. */
 	startTimeNs;
+	/** Millisecond timestamp marking the start of the current reporting interval. */
 	intervalTime;
+	/** Total number of audio frames sent since streaming began. */
 	totalFrames = 0;
+	/** Number of audio frames sent within the current reporting interval. */
 	intervalFrames = 0;
+	/**
+	* Creates a new Statistics tracker, capturing the current time as baseline.
+	*
+	* @param sampleRate - Audio sample rate in Hz (e.g. 44100).
+	*/
 	constructor(sampleRate) {
 		this.sampleRate = sampleRate;
 		this.startTimeNs = process.hrtime.bigint();
 		this.intervalTime = performance.now();
 	}
+	/**
+	* Computes how many audio frames should have been sent by now,
+	* based on elapsed wall-clock time since streaming started.
+	*/
 	get expectedFrameCount() {
 		const elapsedNs = Number(process.hrtime.bigint() - this.startTimeNs);
 		return Math.floor(elapsedNs / (1e9 / this.sampleRate));
 	}
+	/**
+	* Number of frames the sender is lagging behind real-time.
+	* A positive value means packets need to be sent faster.
+	*/
 	get framesBehind() {
 		return this.expectedFrameCount - this.totalFrames;
 	}
+	/**
+	* Whether the current interval has accumulated at least one second
+	* worth of frames, indicating it is time to log and reset.
+	*/
 	get intervalCompleted() {
 		return this.intervalFrames >= this.sampleRate;
 	}
+	/**
+	* Records that additional audio frames have been sent.
+	*
+	* @param sentFrames - Number of frames just sent.
+	*/
 	tick(sentFrames) {
 		this.totalFrames += sentFrames;
 		this.intervalFrames += sentFrames;
 	}
+	/**
+	* Completes the current reporting interval, resetting the interval
+	* frame counter and returning timing information for logging.
+	*
+	* @returns A tuple of [elapsed seconds, frames sent] for the completed interval.
+	*/
 	newInterval() {
 		const endTime = performance.now();
 		const diff = (endTime - this.intervalTime) / 1e3;
@@ -467,51 +823,109 @@ var Statistics = class {
 
 //#endregion
 //#region src/const.ts
+/**
+* Number of recently sent packets to keep in the FIFO backlog
+* for retransmission upon receiver request.
+*/
 const PACKET_BACKLOG_SIZE = 1e3;
+/**
+* Fallback metadata used when the caller does not provide any
+* media metadata for the audio stream.
+*/
 const MISSING_METADATA = {
 	title: "Streaming with apple-raop",
 	artist: "apple-raop",
 	album: "AirPlay",
 	duration: 0
 };
+/**
+* Empty metadata sentinel used as the default value before any
+* metadata has been set on a stream.
+*/
 const EMPTY_METADATA = {
 	title: "",
 	artist: "",
 	album: "",
 	duration: 0
 };
+/**
+* Bitmask of encryption types this client supports.
+* Currently supports unencrypted and MFi-SAP (AirPort Express) encryption.
+*/
 const SUPPORTED_ENCRYPTIONS = EncryptionType.Unencrypted | EncryptionType.MFiSAP;
 
 //#endregion
 //#region src/streamClient.ts
+/**
+* Core streaming engine for RAOP audio. Manages the complete audio streaming
+* lifecycle: initialization (encryption/metadata negotiation, control channel
+* setup), real-time PCM packet sending with timing compensation, metadata
+* and artwork publishing, and teardown.
+*
+* Uses a Statistics tracker to maintain real-time pacing and compensates
+* for slow packet sending by bursting additional packets when falling behind.
+*/
 var StreamClient = class extends EventEmitter {
+	/** Device info dictionary fetched from the receiver during initialization. */
 	get info() {
 		return this.#info;
 	}
+	/**
+	* Current playback info snapshot, substituting fallback metadata
+	* if the caller provided no metadata.
+	*/
 	get playbackInfo() {
 		return {
 			metadata: this.#isMetadataEmpty(this.#metadata) ? MISSING_METADATA : this.#metadata,
 			position: this.#streamContext.position
 		};
 	}
+	/**
+	* Whether MFi-SAP auth-setup is required, determined by the device's
+	* supported encryption types and model name (AirPort devices only).
+	*/
 	get #requiresAuthSetup() {
 		const modelName = this.#properties.get("am") ?? "";
 		return (this.#encryptionTypes & EncryptionType.MFiSAP) !== 0 && modelName.startsWith("AirPort");
 	}
+	/** Application context for logging. */
 	#context;
+	/** RAOP RTSP client for protocol commands. */
 	#rtsp;
+	/** Shared mutable streaming state. */
 	#streamContext;
+	/** Port configuration settings. */
 	#settings;
+	/** Protocol abstraction for transport-level operations. */
 	#protocol;
+	/** FIFO backlog of recently sent packets for retransmission. */
 	#packetBacklog;
+	/** NTP timing server for clock synchronization with the receiver. */
 	#timingServer;
+	/** UDP control channel client, created during initialization. */
 	#controlClient;
+	/** Bitmask of receiver-supported encryption types. */
 	#encryptionTypes = EncryptionType.Unknown;
+	/** Bitmask of receiver-supported metadata types. */
 	#metadataTypes = MetadataType.NotSupported;
+	/** Current track metadata. */
 	#metadata = EMPTY_METADATA;
+	/** Device info dictionary from the receiver. */
 	#info = {};
+	/** mDNS TXT record properties for the device. */
 	#properties = /* @__PURE__ */ new Map();
+	/** Flag controlling the streaming loop; set to false to stop. */
 	#isPlaying = false;
+	/**
+	* Creates a new stream client.
+	*
+	* @param context - Application context for logging.
+	* @param rtsp - Connected RAOP RTSP client.
+	* @param streamContext - Shared mutable streaming state.
+	* @param protocol - Protocol handler for transport operations.
+	* @param settings - Port configuration settings.
+	* @param timingServer - NTP timing server.
+	*/
 	constructor(context, rtsp, streamContext, protocol, settings, timingServer) {
 		super();
 		this.#context = context;
@@ -522,10 +936,19 @@ var StreamClient = class extends EventEmitter {
 		this.#packetBacklog = new PacketFifo(PACKET_BACKLOG_SIZE);
 		this.#timingServer = timingServer;
 	}
+	/**
+	* Closes the control channel, releasing its UDP socket.
+	*/
 	close() {
-		this.#protocol.teardown();
 		this.#controlClient?.close();
 	}
+	/**
+	* Initializes the streaming session by parsing device capabilities,
+	* binding the control channel, fetching device info, performing
+	* auth-setup if required, and running the protocol SETUP handshake.
+	*
+	* @param properties - mDNS TXT record key-value pairs for the device.
+	*/
 	async initialize(properties) {
 		this.#properties = properties;
 		this.#encryptionTypes = getEncryptionTypes(properties);
@@ -534,7 +957,7 @@ var StreamClient = class extends EventEmitter {
 		const intersection = this.#encryptionTypes & SUPPORTED_ENCRYPTIONS;
 		if (!intersection || intersection === EncryptionType.Unknown) this.#context.logger.debug("No supported encryption type, continuing anyway");
 		this.#updateOutputProperties(properties);
-		this.#controlClient = new ControlClient(this.#streamContext, this.#packetBacklog);
+		this.#controlClient = new ControlClient(this.#context, this.#streamContext, this.#packetBacklog);
 		await this.#controlClient.bind(this.#rtsp.connection.localIp, this.#settings.protocols.raop.controlPort);
 		this.#context.logger.debug(`Local ports: control=${this.#controlClient.port}, timing=${this.#timingServer.port}`);
 		const info = await this.#rtsp.info();
@@ -543,14 +966,36 @@ var StreamClient = class extends EventEmitter {
 		if (this.#requiresAuthSetup) await this.#rtsp.authSetup();
 		await this.#protocol.setup(this.#timingServer.port, this.#controlClient.port);
 	}
+	/**
+	* Signals the streaming loop to stop after the current packet.
+	* The `sendAudio()` call will return after teardown completes.
+	*/
 	stop() {
 		this.#context.logger.debug("Stopping audio playback");
 		this.#isPlaying = false;
 	}
+	/**
+	* Changes the playback volume on the receiver via RTSP SET_PARAMETER.
+	*
+	* @param volume - Volume level in dBFS.
+	*/
 	async setVolume(volume) {
 		await this.#rtsp.setParameter("volume", String(volume));
 		this.#streamContext.volume = volume;
 	}
+	/**
+	* Main entry point for streaming audio. Resets the stream context,
+	* connects the UDP audio transport, publishes metadata/artwork/progress,
+	* starts the RTSP RECORD session, and enters the real-time streaming loop.
+	*
+	* On completion or error, performs full teardown: clears the packet backlog,
+	* sends RTSP TEARDOWN, closes the UDP transport, and emits 'stopped'.
+	*
+	* @param source - Audio source providing PCM frames to stream.
+	* @param metadata - Track metadata to display on the receiver.
+	* @param volume - Optional initial volume as a percentage (0-100), converted to dBFS.
+	* @throws When streaming encounters an unrecoverable error.
+	*/
 	async sendAudio(source, metadata = EMPTY_METADATA, volume) {
 		if (!this.#controlClient) throw new Error("Not initialized");
 		this.#streamContext.reset();
@@ -592,7 +1037,7 @@ var StreamClient = class extends EventEmitter {
 			await this.#streamData(source, transport);
 		} catch (err) {
 			this.#context.logger.error("An error occurred during streaming.", err);
-			throw new Error(`An error occurred during streaming: ${err}`);
+			throw new Error("An error occurred during streaming.", { cause: err });
 		} finally {
 			this.#packetBacklog.clear();
 			if (transport) {
@@ -604,6 +1049,16 @@ var StreamClient = class extends EventEmitter {
 			this.emit("stopped");
 		}
 	}
+	/**
+	* Real-time audio streaming loop. Reads PCM frames from the source,
+	* sends them as RTP packets over UDP, and uses wall-clock timing to
+	* maintain real-time pacing. When falling behind, sends compensating
+	* burst packets (up to MAX_PACKETS_COMPENSATE). Logs periodic
+	* throughput statistics and slow-sender warnings.
+	*
+	* @param source - Audio source to read frames from.
+	* @param transport - UDP socket connected to the receiver's audio port.
+	*/
 	async #streamData(source, transport) {
 		const stats = new Statistics(this.#streamContext.sampleRate);
 		const initialTime = performance.now();
@@ -643,6 +1098,17 @@ var StreamClient = class extends EventEmitter {
 		const elapsedNs = Number(process.hrtime.bigint() - stats.startTimeNs);
 		this.#context.logger.debug(`Audio finished sending in ${(elapsedNs / 1e9).toFixed(3)}s`);
 	}
+	/**
+	* Reads one packet's worth of audio frames from the source and sends
+	* it as an RTP packet. If the source is exhausted, sends silence
+	* padding until the latency buffer is filled. Undersized frames
+	* are zero-padded to the expected packet size.
+	*
+	* @param source - Audio source to read frames from.
+	* @param firstPacket - Whether this is the first packet (uses marker payload type 0xE0).
+	* @param transport - UDP socket connected to the receiver's audio port.
+	* @returns Number of audio frames sent, or 0 when padding is exhausted.
+	*/
 	async #sendPacket(source, firstPacket, transport) {
 		if (this.#streamContext.paddingSent >= this.#streamContext.latency) return 0;
 		let frames = await source.readFrames(352);
@@ -658,9 +1124,18 @@ var StreamClient = class extends EventEmitter {
 		const [rtpseq, packet] = await this.#protocol.sendAudioPacket(transport, header, frames);
 		this.#packetBacklog.set(rtpseq, packet);
 		this.#streamContext.rtpseq = (this.#streamContext.rtpseq + 1) % 2 ** 16;
-		this.#streamContext.headTs += Math.floor(frames.length / this.#streamContext.frameSize);
+		this.#streamContext.headTs = this.#streamContext.headTs + Math.floor(frames.length / this.#streamContext.frameSize) >>> 0;
 		return Math.floor(frames.length / this.#streamContext.frameSize);
 	}
+	/**
+	* Sends multiple packets in a burst to compensate for falling behind
+	* real-time playback. Stops early if the source is exhausted.
+	*
+	* @param source - Audio source to read frames from.
+	* @param transport - UDP socket connected to the receiver's audio port.
+	* @param count - Number of packets to send.
+	* @returns A tuple of [total frames sent, whether more packets are available].
+	*/
 	async #sendNumberOfPackets(source, transport, count) {
 		let totalFrames = 0;
 		for (let i = 0; i < count; i++) {
@@ -670,9 +1145,22 @@ var StreamClient = class extends EventEmitter {
 		}
 		return [totalFrames, true];
 	}
+	/**
+	* Checks whether the given metadata has all empty/default values,
+	* indicating no real metadata was provided by the caller.
+	*
+	* @param metadata - Metadata to check.
+	* @returns True if all fields are empty or zero.
+	*/
 	#isMetadataEmpty(metadata) {
 		return metadata.title === "" && metadata.artist === "" && metadata.album === "" && metadata.duration === 0;
 	}
+	/**
+	* Updates the stream context audio format from mDNS TXT record
+	* properties (sample rate, channels, bytes per channel).
+	*
+	* @param properties - mDNS TXT record key-value pairs.
+	*/
 	#updateOutputProperties(properties) {
 		const [sampleRate, channels, bytesPerChannel] = getAudioProperties(properties);
 		this.#streamContext.sampleRate = sampleRate;
@@ -684,30 +1172,58 @@ var StreamClient = class extends EventEmitter {
 
 //#endregion
 //#region src/raop.ts
+/** Default audio sample rate in Hz (CD quality). */
 const SAMPLE_RATE = 44100;
+/** Default number of audio channels (stereo). */
 const CHANNELS = 2;
+/** Default bytes per channel sample (16-bit). */
 const BYTES_PER_CHANNEL = 2;
+/** Number of audio frames per RTP packet. */
 const FRAMES_PER_PACKET = 352;
+/**
+* High-level RAOP client for streaming audio to AirPlay receivers.
+* Wraps the RTSP handshake, UDP audio transport, control channel,
+* and metadata publishing into a simple stream/stop/close API.
+*
+* Instances are created via the static `create()` or `discover()` methods.
+*/
 var RaopClient = class RaopClient extends EventEmitter {
+	/** Application context providing logger and device identity. */
 	get context() {
 		return this.#context;
 	}
+	/** Unique identifier of the discovered RAOP device. */
 	get deviceId() {
 		return this.#discoveryResult.id;
 	}
+	/** IP address of the RAOP receiver. */
 	get address() {
 		return this.#discoveryResult.address;
 	}
+	/** Model name of the RAOP receiver (e.g. "AirPort Express"). */
 	get modelName() {
 		return this.#discoveryResult.modelName;
 	}
+	/** Device info dictionary fetched during initialization. */
 	get info() {
 		return this.#streamClient.info;
 	}
+	/** Application context for logging and identity. */
 	#context;
+	/** RAOP RTSP client for protocol-level commands. */
 	#rtsp;
+	/** Stream client managing audio transport and metadata. */
 	#streamClient;
+	/** mDNS discovery result for this device. */
 	#discoveryResult;
+	/**
+	* Private constructor — use `RaopClient.create()` or `RaopClient.discover()` instead.
+	*
+	* @param context - Application context.
+	* @param rtsp - Connected RTSP client.
+	* @param streamClient - Initialized stream client.
+	* @param discoveryResult - mDNS discovery result for the device.
+	*/
 	constructor(context, rtsp, streamClient, discoveryResult) {
 		super();
 		this.#context = context;
@@ -717,6 +1233,13 @@ var RaopClient = class RaopClient extends EventEmitter {
 		this.#streamClient.on("playing", (info) => this.emit("playing", info));
 		this.#streamClient.on("stopped", () => this.emit("stopped"));
 	}
+	/**
+	* Streams audio from a source to the RAOP receiver. Starts the source,
+	* sends audio data over RTP, and stops the source when finished or on error.
+	*
+	* @param source - Audio source providing PCM frames.
+	* @param options - Optional metadata and volume settings.
+	*/
 	async stream(source, options = {}) {
 		await source.start();
 		try {
@@ -725,16 +1248,37 @@ var RaopClient = class RaopClient extends EventEmitter {
 			await source.stop();
 		}
 	}
+	/**
+	* Signals the stream client to stop sending audio. The current
+	* `stream()` call will complete after flushing remaining data.
+	*/
 	stop() {
 		this.#streamClient.stop();
 	}
+	/**
+	* Changes the playback volume on the receiver.
+	*
+	* @param volume - Volume level in dBFS.
+	*/
 	async setVolume(volume) {
 		await this.#streamClient.setVolume(volume);
 	}
+	/**
+	* Closes all connections and releases resources. Disconnects the
+	* RTSP session and shuts down the control channel.
+	*/
 	async close() {
 		this.#streamClient.close();
 		await this.#rtsp.disconnect();
 	}
+	/**
+	* Creates a new RaopClient from a pre-discovered device. Connects
+	* via RTSP, initializes the stream context, and negotiates transport.
+	*
+	* @param discoveryResult - mDNS discovery result for the target device.
+	* @param timingServer - NTP timing server for clock synchronization.
+	* @returns A fully initialized and connected RaopClient.
+	*/
 	static async create(discoveryResult, timingServer) {
 		const context = new Context(discoveryResult.id);
 		const rtsp = new RaopRtspClient(context, discoveryResult.address, discoveryResult.service.port);
@@ -749,19 +1293,49 @@ var RaopClient = class RaopClient extends EventEmitter {
 		await streamClient.initialize(properties);
 		return new RaopClient(context, rtsp, streamClient, discoveryResult);
 	}
+	/**
+	* Discovers a RAOP device by its device ID via mDNS, then creates
+	* and returns a connected RaopClient.
+	*
+	* @param deviceId - Unique device identifier to search for.
+	* @param timingServer - NTP timing server for clock synchronization.
+	* @returns A fully initialized and connected RaopClient.
+	*/
 	static async discover(deviceId, timingServer) {
 		const result = await Discovery.raop().findUntil(deviceId);
 		return RaopClient.create(result, timingServer);
 	}
 };
+/**
+* RAOP-specific implementation of the StreamProtocol interface.
+* Handles RTSP ANNOUNCE/SETUP for transport negotiation, periodic
+* feedback keepalives, and raw UDP audio packet sending.
+*/
 var RaopStreamProtocol = class {
+	/** RTSP client for protocol commands. */
 	#rtsp;
+	/** Shared stream context for port and format state. */
 	#streamContext;
+	/** Interval timer for periodic feedback requests. */
 	#feedbackInterval;
+	/**
+	* Creates a new RAOP stream protocol handler.
+	*
+	* @param rtsp - RAOP RTSP client for sending protocol commands.
+	* @param streamContext - Shared mutable streaming state.
+	*/
 	constructor(rtsp, streamContext) {
 		this.#rtsp = rtsp;
 		this.#streamContext = streamContext;
 	}
+	/**
+	* Announces the audio format and sets up the RTP transport by
+	* sending RTSP ANNOUNCE and SETUP requests. Parses the server's
+	* response to extract assigned server and control ports.
+	*
+	* @param timingPort - Local NTP timing server port.
+	* @param controlPort - Local control channel port.
+	*/
 	async setup(timingPort, controlPort) {
 		await this.#rtsp.announce(this.#streamContext.bytesPerChannel, this.#streamContext.channels, this.#streamContext.sampleRate);
 		const transport = [
@@ -779,6 +1353,10 @@ var RaopStreamProtocol = class {
 		const controlPortMatch = transportHeader.match(/control_port=(\d+)/);
 		if (controlPortMatch) this.#streamContext.controlPort = parseInt(controlPortMatch[1], 10);
 	}
+	/**
+	* Starts sending periodic feedback POST requests every 2 seconds
+	* to keep the RAOP session alive during streaming.
+	*/
 	async startFeedback() {
 		this.#feedbackInterval = setInterval(async () => {
 			try {
@@ -788,6 +1366,15 @@ var RaopStreamProtocol = class {
 			}
 		}, 2e3);
 	}
+	/**
+	* Sends a single audio packet over the UDP transport by concatenating
+	* the RTP header with the audio payload.
+	*
+	* @param transport - UDP socket connected to the receiver's audio port.
+	* @param header - 12-byte RTP header.
+	* @param audio - Raw audio payload data.
+	* @returns A tuple of [sequence number, full packet buffer] for backlog storage.
+	*/
 	async sendAudioPacket(transport, header, audio) {
 		const packet = Buffer.concat([header, audio]);
 		const seqno = header.readUInt16BE(2);
@@ -796,20 +1383,30 @@ var RaopStreamProtocol = class {
 		});
 		return [seqno, packet];
 	}
+	/**
+	* Stops the feedback interval timer, ending periodic keepalive requests.
+	*/
 	teardown() {
 		if (!this.#feedbackInterval) return;
 		clearInterval(this.#feedbackInterval);
 		this.#feedbackInterval = void 0;
 	}
 };
+/**
+* Creates a fresh StreamContext with CD-quality audio defaults
+* (44100 Hz, stereo, 16-bit) and randomized RTP sequence/timestamp values.
+*
+* @returns A new mutable stream context ready for use in a streaming session.
+*/
 function createStreamContext() {
+	const rtptime = Math.floor(Math.random() * 4294967295);
 	return {
 		sampleRate: SAMPLE_RATE,
 		channels: CHANNELS,
 		bytesPerChannel: BYTES_PER_CHANNEL,
 		rtpseq: Math.floor(Math.random() * 65536),
-		rtptime: Math.floor(Math.random() * 4294967295),
-		headTs: 0,
+		rtptime,
+		headTs: rtptime,
 		latency: Math.floor(SAMPLE_RATE * 2),
 		serverPort: 0,
 		controlPort: 0,