@basmilius/apple-raop 0.9.18 → 0.10.0

package/dist/index.d.mts

@@ -4,186 +4,662 @@ import { AudioSource, Context, DiscoveryResult, TimingServer } from "@basmilius/
 import { RtspClient } from "@basmilius/apple-rtsp";
 
 //#region src/types.d.ts
+/**
+* Metadata describing the currently streaming media track.
+*/
 type MediaMetadata = {
-  readonly title: string;
-  readonly artist: string;
-  readonly album: string;
-  readonly duration: number;
+  /** Track title. */readonly title: string; /** Artist or performer name. */
+  readonly artist: string; /** Album name. */
+  readonly album: string; /** Total duration of the track in seconds. */
+  readonly duration: number; /** Optional album artwork image data (JPEG or PNG). */
   readonly artwork?: Buffer;
 };
+/**
+* Snapshot of the current playback state, combining metadata
+* with the stream position.
+*/
 type PlaybackInfo = {
-  readonly metadata: MediaMetadata;
+  /** Metadata for the currently playing track. */readonly metadata: MediaMetadata; /** Current playback position in audio frames. */
   readonly position: number;
 };
+/**
+* Mutable state shared across all RAOP streaming components.
+* Holds RTP sequence numbers, timestamps, audio format details,
+* and connection ports negotiated during RTSP SETUP.
+*/
 type StreamContext = {
-  sampleRate: number;
-  channels: number;
-  bytesPerChannel: number;
-  rtpseq: number;
-  rtptime: number;
-  headTs: number;
-  latency: number;
-  serverPort: number;
-  controlPort: number;
-  rtspSession: string;
-  volume: number;
-  position: number;
-  packetSize: number;
-  frameSize: number;
+  /** Audio sample rate in Hz (e.g. 44100). */sampleRate: number; /** Number of audio channels (e.g. 2 for stereo). */
+  channels: number; /** Bytes per channel sample (e.g. 2 for 16-bit). */
+  bytesPerChannel: number; /** Current RTP sequence number (wraps at 16 bits). */
+  rtpseq: number; /** Initial RTP timestamp used in RECORD/FLUSH headers. */
+  rtptime: number; /** Current head timestamp tracking the latest sent audio frame. */
+  headTs: number; /** Latency in audio frames (typically 2 seconds worth). */
+  latency: number; /** Remote server audio data port assigned during SETUP. */
+  serverPort: number; /** Remote control port for sync and retransmit communication. */
+  controlPort: number; /** RTSP session identifier string. */
+  rtspSession: string; /** Current volume level in dBFS. */
+  volume: number; /** Current playback position in audio frames. */
+  position: number; /** Size of a single audio packet payload in bytes. */
+  packetSize: number; /** Size of a single audio frame in bytes (channels * bytesPerChannel). */
+  frameSize: number; /** Number of silence padding frames sent after source exhaustion. */
   paddingSent: number;
+  /**
+  * Resets RTP sequence number, timestamp, head timestamp,
+  * padding counter, and position for a new stream session.
+  */
   reset(): void;
 };
+/**
+* Abstraction over the transport-level protocol operations for
+* setting up and tearing down an audio stream. Allows different
+* protocol backends (e.g. RAOP over RTSP).
+*/
 interface StreamProtocol {
+  /**
+  * Performs RTSP ANNOUNCE and SETUP, negotiating ports with the receiver.
+  *
+  * @param timingPort - Local NTP timing server port.
+  * @param controlPort - Local control channel port.
+  */
   setup(timingPort: number, controlPort: number): Promise<void>;
+  /**
+  * Starts sending periodic feedback requests to maintain the session.
+  */
   startFeedback(): Promise<void>;
+  /**
+  * Sends a single audio packet over the UDP transport.
+  *
+  * @param transport - UDP socket connected to the receiver.
+  * @param header - RTP header for the audio packet.
+  * @param audio - Raw audio payload data.
+  * @returns A tuple of [sequence number, full packet buffer] for backlog storage.
+  */
   sendAudioPacket(transport: Socket, header: Buffer, audio: Buffer): Promise<[number, Buffer]>;
+  /**
+  * Tears down the protocol session, stopping feedback and releasing resources.
+  */
   teardown(): void;
 }
+/**
+* Configuration for RAOP protocol port bindings.
+*/
 interface Settings {
+  /** Protocol-specific port configuration. */
   protocols: {
-    raop: {
-      controlPort: number;
+    /** RAOP control and timing port settings. */raop: {
+      /** Control channel port (0 for auto-assign). */controlPort: number; /** NTP timing server port (0 for auto-assign). */
       timingPort: number;
     };
   };
 }
+/**
+* Bitmask enum for encryption types supported by the RAOP receiver.
+* Values are parsed from the `et` mDNS TXT record field.
+*/
 declare enum EncryptionType {
+  /** No encryption information available. */
   Unknown = 0,
+  /** Receiver supports unencrypted streams. */
   Unencrypted = 1,
+  /** Receiver supports MFi-SAP encryption (AirPort Express). */
   MFiSAP = 2
 }
+/**
+* Bitmask enum for metadata types supported by the RAOP receiver.
+* Values are parsed from the `md` mDNS TXT record field.
+*/
 declare enum MetadataType {
+  /** Receiver does not support metadata. */
   NotSupported = 0,
+  /** Receiver supports text metadata (title, artist, album). */
   Text = 1,
+  /** Receiver supports album artwork. */
   Artwork = 2,
+  /** Receiver supports progress/duration information. */
   Progress = 4
 }
+/**
+* Listener interface for RAOP playback lifecycle events.
+*/
 interface RaopListener {
+  /**
+  * Called when audio playback starts or metadata changes.
+  *
+  * @param playbackInfo - Current playback state information.
+  */
   playing(playbackInfo: PlaybackInfo): void;
+  /**
+  * Called when audio playback stops.
+  */
   stopped(): void;
 }
 //#endregion
 //#region src/packets.d.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.
+*/
 declare class PacketFifo {
   #private;
+  /**
+  * Creates a new packet FIFO with the given capacity.
+  *
+  * @param maxSize - Maximum number of packets to store before evicting the oldest.
+  */
   constructor(maxSize: number);
+  /**
+  * 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: number): Buffer | undefined;
+  /**
+  * 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: number, packet: Buffer): void;
+  /**
+  * 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: number): boolean;
+  /**
+  * Removes all packets from the backlog.
+  */
   clear(): void;
 }
+/**
+* Encoder for RTP audio packet headers (12 bytes).
+* Produces the standard RTP fixed header used for RAOP audio data packets.
+*/
 declare const AudioPacketHeader: {
+  /**
+  * Encodes a 12-byte RTP audio packet header.
+  *
+  * @param header - First byte containing version, padding, and extension flags (typically 0x80).
+  * @param payloadType - RTP payload type (0xE0 for first packet, 0x60 for subsequent).
+  * @param seqno - 16-bit RTP sequence number.
+  * @param timestamp - 32-bit RTP timestamp in audio frames.
+  * @param ssrc - Synchronization source identifier (session ID).
+  * @returns A 12-byte buffer containing the encoded RTP header.
+  */
   encode(header: number, payloadType: number, seqno: number, timestamp: number, ssrc: number): Buffer;
 };
+/**
+* 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.
+*/
 declare const SyncPacket: {
+  /**
+  * Encodes a 20-byte sync packet.
+  *
+  * @param header - First byte (0x90 for first sync, 0x80 for subsequent).
+  * @param payloadType - Payload type identifier (0xD4 for sync).
+  * @param seqno - 16-bit sequence number (typically 0x0007).
+  * @param rtpTimestamp - RTP timestamp of the next audio packet to play, minus latency.
+  * @param ntpSec - NTP seconds component of the current wall-clock time.
+  * @param ntpFrac - NTP fractional seconds component of the current wall-clock time.
+  * @param rtpTimestampNow - RTP timestamp corresponding to the current head position.
+  * @returns A 20-byte buffer containing the encoded sync packet.
+  */
   encode(header: number, payloadType: number, seqno: number, rtpTimestamp: number, ntpSec: number, ntpFrac: number, rtpTimestampNow: number): Buffer;
 };
+/**
+* Decoded retransmit request received from the RAOP receiver,
+* indicating which packets need to be resent.
+*/
 type RetransmitRequest = {
-  readonly lostSeqno: number;
+  /** Starting RTP sequence number of the lost range. */readonly lostSeqno: number; /** Number of consecutive lost packets starting from lostSeqno. */
   readonly lostPackets: number;
 };
+/**
+* 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.
+*/
 declare function decodeRetransmitRequest(data: Buffer): RetransmitRequest;
 //#endregion
 //#region src/utils.d.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).
+*/
 declare function pctToDbfs(volume: number): number;
+/**
+* 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.
+*/
 declare function getEncryptionTypes(properties: Map<string, string>): EncryptionType;
+/**
+* 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.
+*/
 declare function getMetadataTypes(properties: Map<string, string>): MetadataType;
+/**
+* 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].
+*/
 declare function getAudioProperties(properties: Map<string, string>): [number, number, number];
 //#endregion
 //#region src/controlClient.d.ts
+/**
+* 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.
+*/
 declare class ControlClient extends EventEmitter {
   #private;
-  constructor(context: StreamContext, packetBacklog: PacketFifo);
+  /**
+  * 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, context: StreamContext, packetBacklog: PacketFifo);
+  /** Local UDP port the control channel is bound to, or 0 if not yet bound. */
   get port(): number;
+  /**
+  * 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.
+  */
   bind(localIp: string, port: number): Promise<void>;
+  /**
+  * Stops the sync task and closes the UDP socket, releasing all resources.
+  */
   close(): void;
+  /**
+  * 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: string): void;
+  /**
+  * Stops the periodic sync task without closing the UDP socket.
+  */
   stop(): void;
 }
 //#endregion
 //#region src/rtspClient.d.ts
+/**
+* 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.
+*/
 declare class RaopRtspClient extends RtspClient {
   #private;
+  /** Active-Remote identifier used for DACP remote control pairing. */
   get activeRemoteId(): string;
+  /** DACP identifier used for remote control discovery. */
   get dacpId(): string;
+  /** RTSP session identifier string included in session-scoped requests. */
   get rtspSessionId(): string;
+  /** Numeric session identifier used in the RTSP URI path. */
   get sessionId(): number;
+  /** RTSP URI for this session, formatted as `rtsp://<localIp>/<sessionId>`. */
   get uri(): string;
+  /** Local and remote IP addresses of the RTSP connection. */
   get connection(): {
     localIp: string;
     remoteIp: string;
   };
+  /**
+  * 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: Context, address: string, port: number);
+  /**
+  * Returns default headers included with every RTSP request, including
+  * DACP identifiers, user-agent, and digest authorization if available.
+  *
+  * @returns Header key-value pairs.
+  */
   protected getDefaultHeaders(): Record<string, string | number>;
+  /**
+  * 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.
+  */
   info(): Promise<Record<string, unknown>>;
+  /**
+  * Performs MFi-SAP authentication setup by sending a Curve25519 public
+  * key to `/auth-setup`. Required for AirPort Express devices that use
+  * MFi-SAP encryption.
+  */
   authSetup(): Promise<void>;
+  /**
+  * 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.
+  */
   announce(bytesPerChannel: number, channels: number, sampleRate: number, password?: string): Promise<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.
+  */
   setup(headers?: Record<string, string>, body?: Buffer | string | Record<string, unknown>): Promise<Response>;
+  /**
+  * 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).
+  */
   record(headers?: Record<string, string>): Promise<void>;
+  /**
+  * 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.
+  */
   flush(options: {
     headers: Record<string, string>;
   }): Promise<void>;
+  /**
+  * 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.
+  */
   setParameter(name: string, value: string): Promise<void>;
+  /**
+  * 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.
+  */
   setMetadata(session: string, rtpseq: number, rtptime: number, metadata: MediaMetadata): Promise<void>;
+  /**
+  * 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).
+  */
   setArtwork(session: string, rtpseq: number, rtptime: number, artwork: Buffer): Promise<void>;
+  /**
+  * 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.
+  */
   feedback(allowError?: boolean): Promise<Response>;
+  /**
+  * Sends an RTSP TEARDOWN request to end the streaming session
+  * and release server-side resources.
+  *
+  * @param session - RTSP session identifier to tear down.
+  */
   teardown(session: string): Promise<void>;
 }
 //#endregion
 //#region src/statistics.d.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.
+*/
 declare class Statistics {
+  /** Audio sample rate in Hz, used to compute expected frame counts. */
   readonly sampleRate: number;
+  /** High-resolution monotonic timestamp (nanoseconds) captured at construction. */
   readonly startTimeNs: bigint;
+  /** Millisecond timestamp marking the start of the current reporting interval. */
   intervalTime: number;
+  /** Total number of audio frames sent since streaming began. */
   totalFrames: number;
+  /** Number of audio frames sent within the current reporting interval. */
   intervalFrames: number;
+  /**
+  * Creates a new Statistics tracker, capturing the current time as baseline.
+  *
+  * @param sampleRate - Audio sample rate in Hz (e.g. 44100).
+  */
   constructor(sampleRate: number);
+  /**
+  * Computes how many audio frames should have been sent by now,
+  * based on elapsed wall-clock time since streaming started.
+  */
   get expectedFrameCount(): number;
+  /**
+  * Number of frames the sender is lagging behind real-time.
+  * A positive value means packets need to be sent faster.
+  */
   get framesBehind(): number;
+  /**
+  * Whether the current interval has accumulated at least one second
+  * worth of frames, indicating it is time to log and reset.
+  */
   get intervalCompleted(): boolean;
+  /**
+  * Records that additional audio frames have been sent.
+  *
+  * @param sentFrames - Number of frames just sent.
+  */
   tick(sentFrames: number): void;
+  /**
+  * 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(): [number, number];
 }
 //#endregion
 //#region src/streamClient.d.ts
+/**
+* Event map for the StreamClient, emitted during the audio streaming lifecycle.
+*/
 type EventMap$1 = {
-  readonly playing: [playbackInfo: PlaybackInfo];
+  /** Emitted when audio playback starts, providing current playback info. */readonly playing: [playbackInfo: PlaybackInfo]; /** Emitted when audio playback stops (either naturally or via stop()). */
   readonly stopped: [];
 };
+/**
+* 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.
+*/
 declare class StreamClient extends EventEmitter<EventMap$1> {
   #private;
+  /** Device info dictionary fetched from the receiver during initialization. */
   get info(): Record<string, unknown>;
+  /**
+  * Current playback info snapshot, substituting fallback metadata
+  * if the caller provided no metadata.
+  */
   get playbackInfo(): PlaybackInfo;
+  /**
+  * 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: Context, rtsp: RaopRtspClient, streamContext: StreamContext, protocol: StreamProtocol, settings: Settings, timingServer: TimingServer);
+  /**
+  * Closes the control channel, releasing its UDP socket.
+  */
   close(): void;
+  /**
+  * 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.
+  */
   initialize(properties: Map<string, string>): Promise<void>;
+  /**
+  * Signals the streaming loop to stop after the current packet.
+  * The `sendAudio()` call will return after teardown completes.
+  */
   stop(): void;
+  /**
+  * Changes the playback volume on the receiver via RTSP SET_PARAMETER.
+  *
+  * @param volume - Volume level in dBFS.
+  */
   setVolume(volume: number): Promise<void>;
+  /**
+  * 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.
+  */
   sendAudio(source: AudioSource, metadata?: MediaMetadata, volume?: number): Promise<void>;
 }
 //#endregion
 //#region src/raop.d.ts
+/**
+* Event map for the RaopClient, emitted during the streaming lifecycle.
+*/
 type EventMap = {
-  readonly playing: [playbackInfo: PlaybackInfo];
+  /** Emitted when audio playback starts, providing current playback info. */readonly playing: [playbackInfo: PlaybackInfo]; /** Emitted when audio playback stops. */
   readonly stopped: [];
 };
+/**
+* Options for configuring an audio stream session.
+*/
 type StreamOptions = {
-  readonly metadata?: MediaMetadata;
+  /** Optional track metadata to display on the receiver. */readonly metadata?: MediaMetadata; /** Optional initial volume as a percentage (0-100). */
   readonly volume?: number;
 };
+/**
+* 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.
+*/
 declare class RaopClient extends EventEmitter<EventMap> {
   #private;
+  /** Application context providing logger and device identity. */
   get context(): Context;
+  /** Unique identifier of the discovered RAOP device. */
   get deviceId(): string;
+  /** IP address of the RAOP receiver. */
   get address(): string;
+  /** Model name of the RAOP receiver (e.g. "AirPort Express"). */
   get modelName(): string;
+  /** Device info dictionary fetched during initialization. */
   get info(): Record<string, unknown>;
+  /**
+  * 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.
+  */
   private constructor();
+  /**
+  * 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.
+  */
   stream(source: AudioSource, options?: StreamOptions): Promise<void>;
+  /**
+  * Signals the stream client to stop sending audio. The current
+  * `stream()` call will complete after flushing remaining data.
+  */
   stop(): void;
+  /**
+  * Changes the playback volume on the receiver.
+  *
+  * @param volume - Volume level in dBFS.
+  */
   setVolume(volume: number): Promise<void>;
+  /**
+  * Closes all connections and releases resources. Disconnects the
+  * RTSP session and shuts down the control channel.
+  */
   close(): Promise<void>;
+  /**
+  * 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 create(discoveryResult: DiscoveryResult, timingServer: TimingServer): Promise<RaopClient>;
+  /**
+  * 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 discover(deviceId: string, timingServer: TimingServer): Promise<RaopClient>;
 }
 //#endregion