@corewire/airplay 0.0.0 → 1.0.0-next.1

package/dist/raop.d.mts

@@ -0,0 +1,344 @@
+import { n as TimingServer, r as AudioSource } from "./index-YqIv0vCR.mjs";
+import { n as RtspClient } from "./index-BlcOBfSz.mjs";
+import { EventEmitter } from "node:events";
+import { CloseReason, Context } from "@corewire/core/transport";
+import { Socket } from "node:dgram";
+import { DiscoverOptions, DiscoveryResult } from "@corewire/core/discovery";
+
+//#region src/raop/types.d.ts
+/** Where a RAOP receiver is. */
+type RaopTarget = {
+  readonly address: string; /** RTSP port of the RAOP service; 7000 when omitted. */
+  readonly port?: number; /** Tags the logs, usually the mDNS name. Defaults to the address. */
+  readonly id?: string; /** The RAOP TXT record; the encryption, metadata and audio properties come from it. */
+  readonly txt?: Readonly<Record<string, string>>;
+};
+/** The track a stream shows on the receiver. */
+type MediaMetadata = {
+  readonly title: string;
+  readonly artist: string;
+  readonly album: string; /** Duration in seconds. */
+  readonly duration: number; /** Album artwork as JPEG or PNG. */
+  readonly artwork?: Buffer;
+};
+type RaopPlaybackInfo = {
+  readonly metadata: MediaMetadata; /** Playback position in audio frames. */
+  readonly position: number;
+};
+/**
+* State shared by the RAOP streaming parts and updated in place: RTP state,
+* audio format and the ports from RTSP SETUP.
+*/
+type StreamContext = {
+  /** Sample rate in Hz. */sampleRate: number;
+  channels: number; /** Bytes per sample per channel. */
+  bytesPerChannel: number; /** RTP sequence number, wraps at 16 bits. */
+  rtpseq: number; /** Initial RTP timestamp for the RECORD and FLUSH headers. */
+  rtptime: number; /** Timestamp of the latest frame sent. */
+  headTs: number; /** Latency in audio frames, usually 2 seconds. */
+  latency: number; /** Receiver audio data port from SETUP. */
+  serverPort: number; /** Receiver control port for sync and retransmits. */
+  controlPort: number;
+  rtspSession: string; /** Volume in dBFS. */
+  volume: number; /** Playback position in audio frames. */
+  position: number; /** Bytes per audio packet payload. */
+  packetSize: number; /** Bytes per frame: channels * bytesPerChannel. */
+  frameSize: number; /** Silence frames sent after the source ran out. */
+  paddingSent: number; /** Resets the RTP state, the padding counter and the position for a new stream. */
+  reset(): void;
+};
+/** The protocol steps to set up, feed and tear down an audio stream. */
+interface StreamProtocol {
+  /**
+  * Sends RTSP ANNOUNCE and SETUP to negotiate the ports.
+  *
+  * @param timingPort - Local NTP timing server port.
+  * @param controlPort - Local control channel port.
+  */
+  setup(timingPort: number, controlPort: number): Promise<void>;
+  /** Starts the periodic feedback requests that keep the session alive. */
+  startFeedback(): Promise<void>;
+  /**
+  * Sends one audio packet.
+  *
+  * @returns The sequence number and the full packet, for the backlog.
+  */
+  sendAudioPacket(transport: Socket, header: Buffer, audio: Buffer): Promise<[number, Buffer]>;
+  /** Stops the feedback and releases the session. */
+  teardown(): void;
+}
+/** Local RAOP port bindings. */
+interface Settings {
+  protocols: {
+    raop: {
+      /** Control channel port; 0 picks a free one. */controlPort: number; /** NTP timing server port; 0 picks a free one. */
+      timingPort: number;
+    };
+  };
+}
+/** Encryption types a RAOP receiver supports, from the `et` TXT field. */
+declare enum EncryptionType {
+  /** The TXT record has no encryption field. */
+  Unknown = 0,
+  Unencrypted = 1,
+  /** The receiver supports MFi-SAP encryption, as the AirPort Express does. */
+  MFiSAP = 2
+}
+/** Metadata types a RAOP receiver supports, from the `md` TXT field. */
+declare enum MetadataType {
+  NotSupported = 0,
+  /** The receiver shows title, artist and album. */
+  Text = 1,
+  Artwork = 2,
+  /** The receiver shows progress and duration. */
+  Progress = 4
+}
+/** How {@link connect} reaches the receiver and what a stream shows by default. */
+type RaopConnectOptions = {
+  /** NTP timing server the receiver synchronizes with; SETUP announces its port. */readonly timing: TimingServer; /** Logger to use. Built from {@link RaopTarget.id} when omitted. */
+  readonly context?: Context; /** Shown on the receiver while a stream comes without metadata. Title `Streaming with CoreWire`, artist `CoreWire` and album `AirPlay` when omitted. */
+  readonly metadata?: Partial<Pick<MediaMetadata, "title" | "artist" | "album">>; /** Answers a digest challenge on ANNOUNCE from a receiver with a password. */
+  readonly password?: string; /** Ends the session, or interrupts the handshake, when aborted. */
+  readonly signal?: AbortSignal;
+};
+type RaopStreamOptions = {
+  /** Track metadata to show on the receiver; the defaults of {@link RaopConnectOptions.metadata} when omitted. */readonly metadata?: MediaMetadata; /** Volume in dBFS, -144 (silent) to 0, sent after FLUSH. The receiver keeps its own when omitted. */
+  readonly volumeDb?: number;
+};
+/** A running RAOP stream. */
+type RaopPlayback = {
+  /**
+  * Settles when streaming is over: resolves once the source ran out and TEARDOWN went out,
+  * rejects when the stream failed.
+  */
+  readonly ended: Promise<void>; /** Stops the source; the stream winds down and sends TEARDOWN. */
+  stop(): void;
+};
+type RaopEventMap = {
+  /** The session ended, see {@link CloseReason}. */closed: [reason: CloseReason, error?: Error]; /** A stream started, with the metadata it shows. */
+  playing: [playbackInfo: RaopPlaybackInfo]; /** A stream ended. */
+  stopped: [];
+};
+//#endregion
+//#region src/raop/rtspClient.d.ts
+/**
+* RTSP client for the RAOP commands: ANNOUNCE, SETUP, RECORD, SET_PARAMETER,
+* FLUSH and TEARDOWN, plus auth-setup, digest authentication, metadata and
+* artwork.
+*/
+declare class RaopRtspClient extends RtspClient {
+  #private;
+  /** Active-Remote identifier for DACP remote control. */
+  get activeRemoteId(): string;
+  /** DACP identifier for remote control discovery. */
+  get dacpId(): string;
+  /** RTSP session identifier for session-scoped requests. */
+  get rtspSessionId(): string;
+  /** Numeric session identifier in the RTSP URI path. */
+  get sessionId(): number;
+  /** RTSP URI of this session, in the form `rtsp://<localIp>/<sessionId>`. */
+  get uri(): string;
+  get connection(): {
+    localIp: string;
+    remoteIp: string;
+  };
+  constructor(context: Context, address: string, port: number);
+  /** Headers on every request: the DACP identifiers, User-Agent and, after a challenge, digest authorization. */
+  protected override getDefaultHeaders(): Record<string, string | number>;
+  /**
+  * Fetches the device info plist from `/info`.
+  *
+  * @returns The info dictionary, or an empty object on failure.
+  */
+  info(): Promise<Record<string, unknown>>;
+  /**
+  * Sends the Curve25519 public key to `/auth-setup`, which an AirPort
+  * Express with MFi-SAP encryption requires.
+  */
+  authSetup(): Promise<void>;
+  /**
+  * Sends ANNOUNCE with an SDP body for the audio format. On a 401
+  * challenge with a password given, it retries with HTTP Digest
+  * authentication.
+  *
+  * @param bytesPerChannel - Bytes per sample per channel, 2 for 16-bit.
+  * @param sampleRate - Sample rate in Hz.
+  */
+  announce(bytesPerChannel: number, channels: number, sampleRate: number, password?: string): Promise<Response>;
+  /**
+  * Sends SETUP to negotiate the transport (ports, protocol).
+  *
+  * @param headers - Extra headers, for example Transport.
+  * @returns The response, with the receiver's ports in its Transport header.
+  */
+  setup(headers?: Record<string, string>, body?: Buffer | string | Record<string, unknown>): Promise<Response>;
+  /**
+  * Sends RECORD to start playback on the receiver.
+  *
+  * @param headers - Usually Range, Session and RTP-Info.
+  */
+  record(headers?: Record<string, string>): Promise<void>;
+  /**
+  * Sends FLUSH to clear the receiver's audio buffer and move playback to
+  * the RTP position in the headers.
+  *
+  * @param options - Headers with Session and RTP-Info.
+  */
+  flush(options: {
+    headers: Record<string, string>;
+  }): Promise<void>;
+  /**
+  * Sends a `text/parameters` SET_PARAMETER, for volume, progress and other
+  * scalar values.
+  *
+  * @param name - For example `volume` or `progress`.
+  */
+  setParameter(name: string, value: string): Promise<void>;
+  /**
+  * Sends title, artist, album and duration as DAAP-tagged SET_PARAMETER.
+  *
+  * @param rtpseq - RTP sequence number for the RTP-Info header.
+  * @param rtptime - RTP timestamp for the RTP-Info header.
+  */
+  setMetadata(session: string, rtpseq: number, rtptime: number, metadata: MediaMetadata): Promise<void>;
+  /**
+  * Sends album artwork as SET_PARAMETER. The magic bytes tell PNG apart;
+  * anything else goes as JPEG.
+  *
+  * @param rtpseq - RTP sequence number for the RTP-Info header.
+  * @param rtptime - RTP timestamp for the RTP-Info header.
+  */
+  setArtwork(session: string, rtpseq: number, rtptime: number, artwork: Buffer): Promise<void>;
+  /**
+  * Posts to `/feedback`, which keeps the session alive during streaming.
+  *
+  * @param allowError - Resolves on an HTTP error status instead of throwing.
+  */
+  feedback(allowError?: boolean): Promise<Response>;
+  /** Sends TEARDOWN to end the streaming session. */
+  teardown(session: string): Promise<void>;
+}
+//#endregion
+//#region src/raop/streamClient.d.ts
+type EventMap = {
+  readonly playing: [playbackInfo: RaopPlaybackInfo]; /** The stream ended, at the end of the source or through {@link StreamClient.stop}. */
+  readonly stopped: [];
+};
+/**
+* Streams RAOP audio: negotiates encryption and metadata, sets up the control
+* channel, sends PCM packets in real time, publishes metadata and artwork and
+* tears down. When sending falls behind, it bursts extra packets to catch up.
+*/
+declare class StreamClient extends EventEmitter<EventMap> {
+  #private;
+  /** The `/info` dictionary fetched during initialization. */
+  get info(): Record<string, unknown>;
+  /** The playback info, with the fallback metadata when the caller gave none. */
+  get playbackInfo(): RaopPlaybackInfo;
+  /**
+  * @param missingMetadata - Shown on the receiver when a stream comes without metadata.
+  */
+  constructor(context: Context, rtsp: RaopRtspClient, streamContext: StreamContext, protocol: StreamProtocol, settings: Settings, timingServer: TimingServer, missingMetadata: MediaMetadata);
+  /** Closes the control channel and its UDP socket. */
+  close(): void;
+  /**
+  * Reads the receiver's capabilities, binds the control channel, fetches
+  * `/info`, sends auth-setup when needed and runs the protocol SETUP.
+  *
+  * @param properties - The receiver's mDNS TXT record.
+  */
+  initialize(properties: Map<string, string>): Promise<void>;
+  /**
+  * Stops the streaming loop after the current packet. {@link sendAudio}
+  * returns once the teardown is done.
+  */
+  stop(): void;
+  /**
+  * Sets the receiver volume with SET_PARAMETER.
+  *
+  * @param volume - Volume in dBFS.
+  */
+  setVolume(volume: number): Promise<void>;
+  /**
+  * Streams PCM after setting up metadata, volume and RTSP RECORD.
+  * On completion or error, clears the backlog, tears down RTSP, closes UDP and emits `stopped`.
+  *
+  * @param volumeDb - Initial volume in dBFS, -144 to 0; the receiver keeps its own when omitted.
+  * @param onStreaming - Runs once the setup is done and the audio starts to flow.
+  */
+  sendAudio(source: AudioSource, metadata?: MediaMetadata, volumeDb?: number, onStreaming?: () => void): Promise<void>;
+}
+//#endregion
+//#region src/raop/session.d.ts
+/**
+* Connects to a RAOP (AirPlay 1 audio) receiver and returns a ready session: the RTSP connection,
+* the control channel, `GET /info`, `/auth-setup` for an AirPort, then ANNOUNCE and SETUP.
+*
+* @throws {ConnectionClosedError} When the signal aborts during the handshake.
+*/
+declare function connect(target: RaopTarget, options: RaopConnectOptions): Promise<RaopSession>;
+/**
+* One RAOP connection to a receiver. It lives once: it ends exactly once, with a reason, and then
+* its {@link signal} aborts and a running stream stops. One stream runs at a time.
+*/
+declare class RaopSession extends EventEmitter<RaopEventMap> {
+  #private;
+  /** Why the session ended, or undefined while it is open. */
+  get closeReason(): CloseReason | undefined;
+  get context(): Context;
+  /** The `/info` plist of the receiver; empty when it did not answer. */
+  get info(): Record<string, unknown>;
+  get isOpen(): boolean;
+  /** Aborts with a {@link ConnectionClosedError} when the session ends. */
+  get signal(): AbortSignal;
+  get target(): RaopTarget;
+  /** The volume last sent to the receiver, in dBFS. */
+  get volumeDb(): number;
+  /** Use {@link connect}; a session starts from a finished handshake. */
+  constructor(target: RaopTarget, context: Context, rtsp: RaopRtspClient, streamClient: StreamClient, streamContext: StreamContext, signal?: AbortSignal);
+  /** Stops a running stream and closes the connection, without TEARDOWN of an idle session. */
+  close(): Promise<void>;
+  /** Sends a volume in dBFS, -144 (silent) to 0, with SET_PARAMETER. */
+  setVolumeDb(volumeDb: number): Promise<void>;
+  /**
+  * Streams PCM audio: metadata, RECORD, FLUSH and the volume, then the audio over RTP. Resolves
+  * once the audio flows; {@link RaopPlayback.ended} settles when the source ran out and TEARDOWN
+  * went out. The source is stopped in every case.
+  *
+  * @throws {PlaybackError} When a stream is already running.
+  */
+  stream(source: AudioSource, options?: RaopStreamOptions): Promise<RaopPlayback>;
+}
+//#endregion
+//#region src/raop/discovery.d.ts
+declare const RAOP_SERVICE = "_raop._tcp.local";
+/** Finds the RAOP (AirPlay 1 audio) receivers on the local network. */
+declare function discover(options?: DiscoverOptions): Promise<DiscoveryResult[]>;
+/** The connect target for a discovered receiver. */
+declare function toTarget(result: DiscoveryResult): RaopTarget;
+//#endregion
+//#region src/raop/utils.d.ts
+/**
+* Converts a volume percentage to dBFS for the RAOP `volume` SET_PARAMETER.
+*
+* @param volume - Volume percentage, from 0 (silent) to 100 (full).
+* @returns Volume in dBFS, from -144 (mute) to 0 (full).
+*/
+declare function pctToDbfs(volume: number): number;
+/**
+* Reads the encryption types from the `et` field of the mDNS TXT record.
+*/
+declare function getEncryptionTypes(properties: Map<string, string>): EncryptionType;
+/**
+* Reads the metadata types from the `md` field of the mDNS TXT record.
+*/
+declare function getMetadataTypes(properties: Map<string, string>): MetadataType;
+/**
+* Reads the audio format from the mDNS TXT record, with CD quality
+* (44100 Hz, 2 channels, 16-bit) for missing fields.
+*
+* @returns `[sampleRate, channels, bytesPerChannel]`.
+*/
+declare function getAudioProperties(properties: Map<string, string>): [number, number, number];
+//#endregion
+export { EncryptionType, type MediaMetadata, MetadataType, RAOP_SERVICE, type RaopConnectOptions, type RaopEventMap, type RaopPlayback, type RaopPlaybackInfo, RaopSession, type RaopStreamOptions, type RaopTarget, connect, discover, getAudioProperties, getEncryptionTypes, getMetadataTypes, pctToDbfs, toTarget };