@corewire/airplay 0.0.0 → 1.0.0-next.1

package/dist/identifiers-CsXXbYkW.mjs

@@ -0,0 +1,67 @@
+import { randomBytes } from "node:crypto";
+
+//#region src/audio/sourceSession.ts
+/** Owns one use of a source. Stop settles readers even when a custom source cannot cancel its read. */
+var AudioSourceSession = class {
+	#source;
+	#readers = /* @__PURE__ */ new Set();
+	#starting;
+	#stopping;
+	#stopped = false;
+	constructor(source) {
+		this.#source = source;
+	}
+	get duration() {
+		return this.#source.duration;
+	}
+	get stopped() {
+		return this.#stopped;
+	}
+	start() {
+		if (this.#stopped) return Promise.resolve();
+		return this.#starting ??= Promise.resolve().then(() => this.#stopped ? void 0 : this.#source.start());
+	}
+	async readFrames(count) {
+		if (this.#stopped) return null;
+		return new Promise((resolve, reject) => {
+			const done = (value) => {
+				this.#readers.delete(done);
+				resolve(this.#stopped ? null : value);
+			};
+			this.#readers.add(done);
+			Promise.resolve().then(() => this.#stopped ? null : this.#source.readFrames(count)).then(done, (error) => {
+				this.#readers.delete(done);
+				reject(error);
+			});
+		});
+	}
+	stop() {
+		this.#stopped = true;
+		for (const reader of this.#readers) reader(null);
+		return this.#stopping ??= Promise.resolve(this.#starting).catch(() => {}).then(() => this.#source.stop());
+	}
+	async reset() {
+		throw new Error("Create a new audio session after resetting the source.");
+	}
+};
+
+//#endregion
+//#region src/identifiers.ts
+/**
+* Generates a random DACP Active-Remote identifier for the RTSP headers: a
+* 32-bit unsigned integer as a decimal string.
+*/
+function generateActiveRemoteId() {
+	return randomBytes(4).readUInt32BE(0).toString(10);
+}
+/** Generates a random DACP-ID: a 64-bit integer as an uppercase hex string. */
+function generateDacpId() {
+	return randomBytes(8).toString("hex").toUpperCase();
+}
+/** Generates a random RTSP session identifier: a 32-bit unsigned integer as a decimal string. */
+function generateSessionId() {
+	return randomBytes(4).readUInt32BE(0).toString(10);
+}
+
+//#endregion
+export { AudioSourceSession as i, generateDacpId as n, generateSessionId as r, generateActiveRemoteId as t };

package/dist/index-BlcOBfSz.d.mts

@@ -0,0 +1,87 @@
+import { Connection, Context } from "@corewire/core/transport";
+
+//#region src/rtsp/encoding.d.ts
+/** The RTSP and HTTP methods of the Apple protocols. */
+type Method = "ANNOUNCE" | "FLUSH" | "FLUSHBUFFERED" | "GET" | "GET_PARAMETER" | "OPTIONS" | "POST" | "PUT" | "RECORD" | "SETUP" | "SET_PARAMETER" | "TEARDOWN";
+type RtspRequest = {
+  /** Headers with capitalized names. */readonly headers: Record<string, string>;
+  readonly method: Method; /** Request target, for example `/info` or `/pair-setup`. */
+  readonly path: string; /** Empty when the request has no body. */
+  readonly body: Buffer; /** Bytes the request took from the input buffer, headers and body. */
+  readonly requestLength: number;
+};
+type RtspResponse = {
+  readonly response: Response; /** Bytes the response took from the input buffer, headers and body. */
+  readonly responseLength: number;
+};
+type BuildResponseOptions = {
+  readonly status: number;
+  readonly statusText: string; /** Extra headers; Content-Length is set from the body. */
+  readonly headers?: Record<string, string | number>;
+  readonly body?: Buffer; /** Protocol of the status line, `'RTSP/1.0'` by default. */
+  readonly protocol?: "RTSP/1.0" | "HTTP/1.1";
+};
+/** Serializes an RTSP or HTTP response, with `Content-Length` set from the body. */
+declare function buildResponse(options: BuildResponseOptions): Buffer;
+/**
+* Parses an RTSP or HTTP request from the start of a buffer that fills as
+* TCP data arrives.
+*
+* @returns The request, or `null` while the headers or body are incomplete.
+* @throws Error if the request line is malformed.
+*/
+declare function parseRequest(buffer: Buffer): RtspRequest | null;
+/**
+* Parses an RTSP or HTTP response from the start of a buffer that fills as
+* TCP data arrives.
+*
+* @returns The response, or `null` while the headers or body are incomplete.
+* @throws Error if the status line is malformed.
+*/
+declare function parseResponse(buffer: Buffer): RtspResponse | null;
+//#endregion
+//#region src/rtsp/client.d.ts
+type ExchangeOptions = {
+  /** Content-Type header; `application/x-apple-binary-plist` for a plain object body. */contentType?: string; /** Extra headers, merged after the default headers. */
+  headers?: Record<string, string>; /** A plain object goes as binary plist; strings and buffers go as they are. */
+  body?: Buffer | string | Record<string, unknown>; /** Resolves a non-OK response instead of rejecting with {@link InvalidResponseError}. */
+  allowError?: boolean; /** Protocol of the request line, `'RTSP/1.0'` by default. */
+  protocol?: "RTSP/1.0" | "HTTP/1.1"; /** Response timeout in milliseconds, `HTTP_TIMEOUT` by default. */
+  timeout?: number;
+};
+/**
+* RTSP over TCP with CSeq-based response tracking and binary-plist serialization of object bodies.
+* Keeps ciphertext and plaintext separate to handle partial TCP delivery.
+* Override {@link transformIncoming}, {@link transformOutgoing} and {@link getDefaultHeaders} for encryption and protocol headers.
+*/
+declare class RtspClient extends Connection<{}> {
+  #private;
+  constructor(context: Context, address: string, port: number);
+  /**
+  * Headers on every request, after CSeq and before the headers of
+  * {@link ExchangeOptions.headers}. A subclass adds its session headers
+  * here, such as DACP-ID and Active-Remote.
+  */
+  protected getDefaultHeaders(): Record<string, string | number>;
+  /**
+  * Decrypts incoming TCP data before parsing; a subclass overrides it.
+  *
+  * @returns The plaintext, with the consumed byte count when not all input
+  *          was used, or `false` until a complete encrypted block arrived.
+  */
+  protected transformIncoming(data: Buffer): Buffer | false | {
+    data: Buffer;
+    consumed: number;
+  };
+  /** Encrypts a formatted request before it goes to the socket; a subclass overrides it. */
+  protected transformOutgoing(data: Buffer): Buffer;
+  /**
+  * Sends a request with CSeq tracking and a response timeout. Object bodies become binary plists.
+  *
+  * @throws TimeoutError if no response arrives in time.
+  * @throws InvalidResponseError for non-OK status unless `allowError` is set.
+  */
+  protected exchange(method: Method, path: string, options?: ExchangeOptions): Promise<Response>;
+}
+//#endregion
+export { RtspRequest as a, parseRequest as c, Method as i, parseResponse as l, RtspClient as n, RtspResponse as o, BuildResponseOptions as r, buildResponse as s, ExchangeOptions as t };

package/dist/index-YqIv0vCR.d.mts

@@ -0,0 +1,135 @@
+import { Logger } from "@corewire/core";
+import { RemoteInfo } from "node:dgram";
+
+//#region src/audio/source.d.ts
+/**
+* Interleaved 44100 Hz stereo PCM, signed 16-bit big-endian, with complete frames.
+* Stream owners start the source once and stop it on completion, cancellation or failure.
+*/
+interface AudioSource {
+  /** Total duration in seconds. */
+  get duration(): number;
+  /**
+  * Reads up to `count` frames.
+  *
+  * @returns The PCM data, or null once the source is exhausted.
+  */
+  readFrames(count: number): Promise<Buffer | null>;
+  /** Rewinds the source so it can be read again. */
+  reset(): Promise<void>;
+  /** Starts the underlying decoders or streams. */
+  start(): Promise<void>;
+  /** Stops the source and releases its resources. */
+  stop(): Promise<void>;
+}
+//#endregion
+//#region src/timing/ntp.d.ts
+/**
+* NTP timing server for AirPlay audio synchronization.
+*
+* During audio streaming, Apple devices send NTP timing requests to sync their
+* clock with the controller. The server answers with the current wall-clock
+* time, from which the device derives the playback offset for multiroom audio.
+* It uses `Date.now()`, not the monotonic `process.hrtime`, because NTP
+* timestamps are anchored to the Unix epoch.
+*/
+declare class TimingServer {
+  #private;
+  /** The UDP port the timing server is listening on, or 0 if not yet bound. */
+  get port(): number;
+  /** @param options.logger - Receives the errors of the server; a `timing-server` logger when omitted. */
+  constructor(options?: {
+    readonly logger?: Logger;
+  });
+  /** Closes the UDP socket and resets the port. */
+  close(): void;
+  /**
+  * Binds the UDP socket to a random free port and starts answering NTP
+  * timing requests. Rejects when the socket fails to bind.
+  */
+  listen(): Promise<void>;
+  onError(err: Error): void;
+  /**
+  * Answers an NTP timing request. The reference timestamp echoes the send
+  * time of the request; receive and send time are both now.
+  */
+  onMessage(data: Buffer, info: RemoteInfo): void;
+}
+//#endregion
+//#region src/timing/ptp/index.d.ts
+/**
+* State of the PTP master.
+*
+* - `idle`: the sockets are not bound yet.
+* - `master`: grandmaster, with the Sync and Announce cadences running.
+* - `stopped`: yielded to a peer with a higher priority, or stopped.
+*/
+type PtpMasterState = "idle" | "master" | "stopped";
+/**
+* IEEE 1588 (PTPv2) grandmaster for AirPlay 2 HomePods.
+*
+* A HomePod with `SupportsPTP` (feature bit 41) expects the sender to be the
+* PTP grandmaster. The master binds the two PTP UDP ports, sends Sync and
+* Announce at the macOS rates and answers DelayReq with DelayResp. When a peer
+* with a higher priority announces itself, it sends a Signaling message with
+* `logMessageInterval = 0x7E` and stops.
+*
+* After that yield, audio timestamps keep using the local wall clock; there
+* is no PTP slave. HomePods accept this as long as the Sync messages stop.
+*/
+declare class PtpMaster {
+  #private;
+  /** UDP port for PTP event messages: 319, or an ephemeral port as fallback. */
+  get eventPort(): number;
+  /** UDP port for PTP general messages: 320, or an ephemeral port as fallback. */
+  get generalPort(): number;
+  get state(): PtpMasterState;
+  /** Our 8-byte EUI-64 clock identity, as advertised to peers. */
+  get clockIdentity(): Buffer;
+  /** Number of Sync messages sent to the peer. */
+  get syncsSent(): number;
+  /** Number of Announce messages sent to the peer. */
+  get announcesSent(): number;
+  /** Number of DelayReq messages received from any peer. */
+  get delayReqsReceived(): number;
+  /** Number of DelayResp messages sent in reply. */
+  get delayRespsSent(): number;
+  /** Number of Announce messages received from peers. */
+  get announcesReceived(): number;
+  /**
+  * @param peerAddress - IPv4 address of the receiver, the destination of Sync, FollowUp and Announce.
+  */
+  constructor(peerAddress: string);
+  /**
+  * Binds both PTP sockets and starts acting as the grandmaster. It prefers
+  * the privileged ports 319 and 320 and falls back to ephemeral ports on
+  * `EACCES`, so it runs on Linux without root. Some HomePods reject PTP on
+  * non-standard ports.
+  *
+  * @returns The bound event and general ports.
+  */
+  start(): Promise<{
+    eventPort: number;
+    generalPort: number;
+  }>;
+  /**
+  * Stops the cadence timers and closes both sockets. Safe to call more than once.
+  */
+  stop(): void;
+  /**
+  * Answers a DelayReq on the event port with a DelayResp that carries our
+  * receive timestamp. A master ignores the other event messages.
+  */
+  onEventPacket(buf: Buffer, info: RemoteInfo): void;
+  /**
+  * Handles an Announce on the general port. When the peer has a strictly
+  * better priority1 than ours, the master yields and stops.
+  */
+  onGeneralPacket(buf: Buffer, info: RemoteInfo): void;
+  /** Logs the error only; {@link stop} owns the socket lifecycle. */
+  onEventError(err: Error): void;
+  /** Logs the error only; {@link stop} owns the socket lifecycle. */
+  onGeneralError(err: Error): void;
+}
+//#endregion
+export { TimingServer as n, AudioSource as r, PtpMaster as t };

package/dist/index.d.mts

@@ -0,0 +1,105 @@
+import { n as TimingServer, r as AudioSource, t as PtpMaster } from "./index-YqIv0vCR.mjs";
+import { $ as EventChannel, Q as UrlPlayback, Z as PlaybackInfo, a as PairOptions, at as ControlChannel, c as RemoteControlOptions, d as DataChannel, et as EventChannelEventMap, f as DataChannelEventMap, i as ConnectOptions, it as AudioStreamStats, l as SessionCloseReason, n as connect, nt as PlayQueueState, o as PlayUrlOptions, r as AirPlayTarget, rt as AudioPlayback, s as RemoteControlChannels, t as AirPlaySession, tt as PlayQueueCommand, u as StreamAudioOptions } from "./session-oDF9A9as.mjs";
+import { Context } from "@corewire/core/transport";
+import { AccessoryCredentials, AccessoryKeys, PairSetup } from "@corewire/core/pairing";
+import { DiscoverOptions, DiscoveryResult } from "@corewire/core/discovery";
+
+//#region src/pairing.d.ts
+/**
+* Starts a PIN pairing: connects, fetches `/info` and asks the receiver to show its PIN. Finish
+* with {@link PinPairing.pin}, which runs pair-setup M1 to M6 and returns the long-term credentials.
+*
+* @throws {PairingError} When the receiver refuses to start pairing.
+*/
+declare function pair(target: AirPlayTarget, options?: PairOptions): Promise<PinPairing>;
+/** A PIN pairing whose PIN the receiver shows now. One connection, used once. */
+declare class PinPairing {
+  #private;
+  /** Aborts when the pairing connection closes. */
+  get signal(): AbortSignal;
+  constructor(control: ControlChannel, setup: PairSetup);
+  /**
+  * Runs pair-setup M1 to M6 with the PIN from the screen. A wrong PIN leaves the connection
+  * open; call {@link close} when giving up.
+  *
+  * @throws {PairingError} When a step fails or the PIN is wrong.
+  */
+  pin(code: string): Promise<AccessoryCredentials>;
+  /** Closes the pairing connection. */
+  close(): void;
+}
+//#endregion
+//#region src/airplayFeatures.d.ts
+/**
+* AirPlay feature flags as bigint bits of the `features` field in the mDNS TXT
+* record. Each flag is a capability the device advertises.
+*/
+declare const AirPlayFeatureFlags: Record<string, bigint>;
+type AirPlayFeatureFlagName = string;
+/** The pairing an AirPlay device requires before it accepts a connection. */
+type PairingRequirement = "none" | "pin" | "transient" | "homekit";
+declare function hasFeatureFlag(features: bigint, flag: bigint): boolean;
+/** Names of the flags set in the bitmask, for debugging and diagnostics. */
+declare function describeFlags(features: bigint): AirPlayFeatureFlagName[];
+/**
+* Reads the AirPlay version from the mDNS TXT record. The flag
+* SupportsUnifiedMediaControl or SupportsCoreUtilsPairingAndEncryption means
+* AirPlay 2.
+*/
+declare function getProtocolVersion(txt: Record<string, string>): 1 | 2;
+/**
+* Reads the pairing requirement from the feature and status flags of the
+* mDNS TXT record. The order of precedence is HomeKit, PIN required,
+* transient (system) pairing, legacy PIN, none.
+*/
+declare function getPairingRequirement(txt: Record<string, string>): PairingRequirement;
+/** True when the `pw` TXT field or the password bit of the `sf` status flags is set. */
+declare function isPasswordRequired(txt: Record<string, string>): boolean;
+/**
+* True when the device has the SupportsHangdogRemoteControl flag, which it
+* needs to receive HID events. In practice only an Apple TV has it.
+*/
+declare function isRemoteControlSupported(txt: Record<string, string>): boolean;
+//#endregion
+//#region src/const.d.ts
+/** Default bytes per sample per channel, for 16-bit PCM. */
+declare const AUDIO_BYTES_PER_CHANNEL = 2;
+/** Default number of audio channels, for stereo. */
+declare const AUDIO_CHANNELS = 2;
+/** Default sample rate in Hz, for CD quality. */
+declare const AUDIO_SAMPLE_RATE = 44100;
+//#endregion
+//#region src/discovery.d.ts
+declare const AIRPLAY_SERVICE = "_airplay._tcp.local";
+/** An AirPlay service with the feature mask from its TXT record, when that parses. */
+type AirPlayDiscoveryResult = DiscoveryResult & {
+  readonly features?: bigint;
+};
+/** Finds the AirPlay receivers on the local network. */
+declare function discover(options?: DiscoverOptions): Promise<AirPlayDiscoveryResult[]>;
+/** The connect target for a discovered receiver. */
+declare function toTarget(result: DiscoveryResult): AirPlayTarget;
+/** Adds the parsed feature mask of the `features` (or `ft`) TXT value. */
+declare function withFeatures(result: DiscoveryResult): AirPlayDiscoveryResult;
+//#endregion
+//#region src/features.d.ts
+/**
+* Parses the `features` TXT value of an mDNS record: one hex value, or two comma-separated 32-bit
+* hex values (low,high) that form a 64-bit mask.
+*
+* @throws If the value has neither form.
+*/
+declare function parseFeatures(features: string): bigint;
+//#endregion
+//#region src/identifiers.d.ts
+/**
+* Generates a random DACP Active-Remote identifier for the RTSP headers: a
+* 32-bit unsigned integer as a decimal string.
+*/
+declare function generateActiveRemoteId(): string;
+/** Generates a random DACP-ID: a 64-bit integer as an uppercase hex string. */
+declare function generateDacpId(): string;
+/** Generates a random RTSP session identifier: a 32-bit unsigned integer as a decimal string. */
+declare function generateSessionId(): string;
+//#endregion
+export { AIRPLAY_SERVICE, AUDIO_BYTES_PER_CHANNEL, AUDIO_CHANNELS, AUDIO_SAMPLE_RATE, type AirPlayDiscoveryResult, type AirPlayFeatureFlagName, AirPlayFeatureFlags, AirPlaySession, type AirPlayTarget, AudioPlayback, type AudioSource, type AudioStreamStats, type ConnectOptions, DataChannel, type DataChannelEventMap, EventChannel, type EventChannelEventMap, type PairOptions, type PairingRequirement, PinPairing, type PlayQueueCommand, type PlayQueueState, type PlayUrlOptions, type PlaybackInfo, PtpMaster, type RemoteControlChannels, type RemoteControlOptions, type SessionCloseReason, type StreamAudioOptions, TimingServer, UrlPlayback, connect, describeFlags, discover, generateActiveRemoteId, generateDacpId, generateSessionId, getPairingRequirement, getProtocolVersion, hasFeatureFlag, isPasswordRequired, isRemoteControlSupported, pair, parseFeatures, toTarget, withFeatures };