@basmilius/apple-devices 0.9.19 → 0.10.1

package/dist/index.d.mts

@@ -2,173 +2,528 @@
 import * as AirPlay from "@basmilius/apple-airplay";
 import { Proto, Protocol } from "@basmilius/apple-airplay";
 import { EventEmitter } from "node:events";
-import { AccessoryCredentials, AudioSource, CommandError, DiscoveryResult, TimingServer } from "@basmilius/apple-common";
+import { AccessoryCredentials, AudioSource, CommandError, DeviceIdentity, DiscoveryResult, TimingServer } from "@basmilius/apple-common";
 import { AttentionState, ButtonPressType, HidCommandKey, LaunchableApp, MediaControlCommandKey, Protocol as Protocol$1, TextInputState, UserAccount } from "@basmilius/apple-companion-link";
 
 //#region src/airplay/player.d.ts
+/**
+ * Represents a single media player within an app on the Apple TV.
+ * Each app (Client) can have multiple players (e.g. picture-in-picture).
+ * Tracks now-playing metadata, playback state, and provides elapsed time extrapolation
+ * based on Cocoa timestamps and playback rate.
+ */
 declare class Player {
   #private;
+  /** Unique identifier for this player (e.g. a player path). */
   get identifier(): string;
+  /** Human-readable display name for this player. */
   get displayName(): string;
+  /** Whether this is the default fallback player (MediaRemote-DefaultPlayer). */
   get isDefaultPlayer(): boolean;
+  /** Raw now-playing info from the Apple TV, or null if unavailable. */
   get nowPlayingInfo(): Proto.NowPlayingInfo | null;
+  /** Current playback queue, or null if unavailable. */
   get playbackQueue(): Proto.PlaybackQueue | null;
+  /**
+   * Effective playback state.
+   */
   get playbackState(): Proto.PlaybackState_Enum;
+  /** The raw playback state as reported by the Apple TV, without corrections. */
   get rawPlaybackState(): Proto.PlaybackState_Enum;
+  /** Timestamp of the last playback state update, used to discard stale updates. */
   get playbackStateTimestamp(): number;
+  /** List of commands supported by this player. */
   get supportedCommands(): Proto.CommandInfo[];
+  /** Current track title from NowPlayingInfo or content item metadata. */
   get title(): string;
+  /** Current track artist from NowPlayingInfo or content item metadata. */
   get artist(): string;
+  /** Current track album from NowPlayingInfo or content item metadata. */
   get album(): string;
+  /** Genre of the current content item. */
   get genre(): string;
+  /** Series name for TV show content. */
   get seriesName(): string;
+  /** Season number for TV show content, or 0 if not applicable. */
   get seasonNumber(): number;
+  /** Episode number for TV show content, or 0 if not applicable. */
   get episodeNumber(): number;
+  /** Media type of the current content item (music, video, etc.). */
   get mediaType(): Proto.ContentItemMetadata_MediaType;
+  /** Unique content identifier for the current item (e.g. iTunes store ID). */
   get contentIdentifier(): string;
+  /** Duration of the current track in seconds, from NowPlayingInfo or metadata. */
   get duration(): number;
+  /** Current playback rate (1.0 = normal, 0 = paused, 2.0 = double speed). */
   get playbackRate(): number;
+  /** Whether the player is currently playing (based on effective playback state). */
   get isPlaying(): boolean;
+  /** Current shuffle mode, derived from the ChangeShuffleMode command info. */
   get shuffleMode(): Proto.ShuffleMode_Enum;
+  /** Current repeat mode, derived from the ChangeRepeatMode command info. */
   get repeatMode(): Proto.RepeatMode_Enum;
+  /**
+   * Extrapolated elapsed time in seconds. Uses the most recent timestamp
+   * from either NowPlayingInfo or content item metadata, accounting for
+   * playback rate to provide a real-time estimate.
+   */
   get elapsedTime(): number;
+  /** The currently playing content item from the playback queue, or null. */
   get currentItem(): Proto.ContentItem | null;
+  /** Metadata of the current content item, or null if no item is playing. */
   get currentItemMetadata(): Proto.ContentItemMetadata | null;
+  /**
+   * Unique identifier for the current artwork, used for change detection.
+   * Returns null if no artwork evidence exists.
+   */
   get artworkId(): string | null;
+  /**
+   * Resolves the best available artwork URL for the current item.
+   * Checks metadata artworkURL, remote artworks, and iTunes template URLs in order.
+   *
+   * @param width - Desired artwork width in pixels (used for template URLs).
+   * @param height - Desired artwork height in pixels (-1 for automatic).
+   * @returns The artwork URL, or null if no artwork URL is available.
+   */
   artworkUrl(width?: number, height?: number): string | null;
+  /** Raw artwork data (image bytes) for the current item, or null if not embedded. */
   get currentItemArtwork(): Uint8Array | null;
+  /** Convenience getter for the artwork URL at default dimensions (600px). */
   get currentItemArtworkUrl(): string | null;
+  /** Lyrics for the current content item, or null if unavailable. */
   get currentItemLyrics(): Proto.LyricsItem | null;
+  /**
+   * Creates a new Player instance.
+   *
+   * @param identifier - Unique player identifier.
+   * @param displayName - Human-readable display name.
+   */
   constructor(identifier: string, displayName: string);
+  /**
+   * Finds a command by its command type in the supported commands list.
+   *
+   * @param command - The command to look up.
+   * @returns The command info, or null if not found.
+   */
   findCommand(command: Proto.Command): Proto.CommandInfo | null;
+  /**
+   * Checks whether a command is supported and enabled.
+   *
+   * @param command - The command to check.
+   * @returns True if the command is in the supported list and enabled.
+   */
   isCommandSupported(command: Proto.Command): boolean;
+  /**
+   * Updates the now-playing info for this player.
+   *
+   * @param nowPlayingInfo - The new now-playing info from the Apple TV.
+   */
   setNowPlayingInfo(nowPlayingInfo: Proto.NowPlayingInfo): void;
+  /**
+   * Updates the playback queue for this player.
+   *
+   * @param playbackQueue - The new playback queue from the Apple TV.
+   */
   setPlaybackQueue(playbackQueue: Proto.PlaybackQueue): void;
+  /**
+   * Updates the playback state. Ignores updates with a timestamp older than the current one
+   * to prevent stale state from overwriting newer data.
+   *
+   * @param playbackState - The new playback state.
+   * @param playbackStateTimestamp - Timestamp of this state update.
+   */
   setPlaybackState(playbackState: Proto.PlaybackState_Enum, playbackStateTimestamp: number): void;
+  /**
+   * Replaces the list of supported commands for this player.
+   *
+   * @param supportedCommands - The new list of supported commands.
+   */
   setSupportedCommands(supportedCommands: Proto.CommandInfo[]): void;
+  /**
+   * Merges updated content item data into the existing playback queue.
+   * Updates metadata, artwork, lyrics, and info fields for the matching item.
+   *
+   * @param item - The content item with updated fields.
+   */
   updateContentItem(item: Proto.ContentItem): void;
 }
 //#endregion
 //#region src/airplay/client.d.ts
+/**
+ * Represents a now-playing app (client) on the Apple TV.
+ * Each client is identified by its bundle identifier and can contain multiple players.
+ * Proxies now-playing getters to the active player, merging player-specific and
+ * default supported commands.
+ */
 declare class Client {
   #private;
+  /** Bundle identifier of the app (e.g. "com.apple.TVMusic"). */
   get bundleIdentifier(): string;
+  /** Human-readable display name of the app. */
   get displayName(): string;
+  /** Map of all known players for this client, keyed by player identifier. */
   get players(): Map<string, Player>;
+  /** The currently active player, or null if none is active. Falls back to the default player. */
   get activePlayer(): Player | null;
+  /** Now-playing info from the active player, or null. */
   get nowPlayingInfo(): Proto.NowPlayingInfo | null;
+  /** Playback queue from the active player, or null. */
   get playbackQueue(): Proto.PlaybackQueue | null;
+  /** Playback state from the active player, or Unknown. */
   get playbackState(): Proto.PlaybackState_Enum;
+  /** Timestamp of the last playback state update from the active player. */
   get playbackStateTimestamp(): number;
+  /**
+   * Merged list of supported commands from the active player and client defaults.
+   * Player commands take precedence; default commands are appended if not already present.
+   */
   get supportedCommands(): Proto.CommandInfo[];
+  /** Current track title from the active player. */
   get title(): string;
+  /** Current track artist from the active player. */
   get artist(): string;
+  /** Current track album from the active player. */
   get album(): string;
+  /** Genre of the current content from the active player. */
   get genre(): string;
+  /** Series name for TV show content from the active player. */
   get seriesName(): string;
+  /** Season number for TV show content from the active player. */
   get seasonNumber(): number;
+  /** Episode number for TV show content from the active player. */
   get episodeNumber(): number;
+  /** Media type of the current content from the active player. */
   get mediaType(): Proto.ContentItemMetadata_MediaType;
+  /** Content identifier of the current item from the active player. */
   get contentIdentifier(): string;
+  /** Duration of the current track in seconds from the active player. */
   get duration(): number;
+  /** Playback rate from the active player (1.0 = normal, 0 = paused). */
   get playbackRate(): number;
+  /** Whether the active player is currently playing. */
   get isPlaying(): boolean;
+  /** Current shuffle mode from the active player. */
   get shuffleMode(): Proto.ShuffleMode_Enum;
+  /** Current repeat mode from the active player. */
   get repeatMode(): Proto.RepeatMode_Enum;
+  /** Extrapolated elapsed time in seconds from the active player. */
   get elapsedTime(): number;
+  /** Artwork identifier for change detection from the active player. */
   get artworkId(): string | null;
+  /**
+   * Resolves the best available artwork URL from the active player.
+   *
+   * @param width - Desired artwork width in pixels.
+   * @param height - Desired artwork height in pixels (-1 for automatic).
+   * @returns The artwork URL, or null if unavailable.
+   */
   artworkUrl(width?: number, height?: number): string | null;
+  /** Current content item from the active player's playback queue. */
   get currentItem(): Proto.ContentItem | null;
+  /** Metadata of the current content item from the active player. */
   get currentItemMetadata(): Proto.ContentItemMetadata | null;
+  /** Raw artwork data (image bytes) from the active player. */
   get currentItemArtwork(): Uint8Array | null;
+  /** Artwork URL at default dimensions from the active player. */
   get currentItemArtworkUrl(): string | null;
+  /** Lyrics for the current content item from the active player. */
   get currentItemLyrics(): Proto.LyricsItem | null;
+  /**
+   * Creates a new Client instance.
+   *
+   * @param bundleIdentifier - Bundle identifier of the app.
+   * @param displayName - Human-readable app name.
+   */
   constructor(bundleIdentifier: string, displayName: string);
+  /**
+   * Gets an existing player or creates a new one if it does not exist.
+   *
+   * @param identifier - Unique player identifier.
+   * @param displayName - Human-readable player name (defaults to identifier).
+   * @returns The existing or newly created Player.
+   */
   getOrCreatePlayer(identifier: string, displayName?: string): Player;
+  /**
+   * Sets the active player by identifier.
+   *
+   * @param identifier - Identifier of the player to activate.
+   */
   setActivePlayer(identifier: string): void;
+  /**
+   * Removes a player from this client. If the removed player was active,
+   * the active player is reset to null (falling back to the default player).
+   *
+   * @param identifier - Identifier of the player to remove.
+   */
   removePlayer(identifier: string): void;
+  /**
+   * Sets the default supported commands for this client. These are used as
+   * fallback when the active player has no commands of its own.
+   *
+   * @param supportedCommands - The default command list.
+   */
   setDefaultSupportedCommands(supportedCommands: Proto.CommandInfo[]): void;
+  /**
+   * Finds a command by type, checking the active player first,
+   * then falling back to the default supported commands.
+   *
+   * @param command - The command to look up.
+   * @returns The command info, or null if not found.
+   */
   findCommand(command: Proto.Command): Proto.CommandInfo | null;
+  /**
+   * Checks whether a command is supported and enabled, checking both
+   * the active player and default commands.
+   *
+   * @param command - The command to check.
+   * @returns True if the command is supported and enabled.
+   */
   isCommandSupported(command: Proto.Command): boolean;
+  /**
+   * Updates the display name for this client.
+   *
+   * @param displayName - The new display name.
+   */
   updateDisplayName(displayName: string): void;
 }
 //#endregion
 //#region src/airplay/const.d.ts
+/** Symbol used to access the underlying AirPlay Protocol instance from an AirPlayDevice. */
 declare const PROTOCOL: unique symbol;
+/** Symbol used to subscribe AirPlayState to DataStream events. */
 declare const STATE_SUBSCRIBE_SYMBOL: unique symbol;
+/** Symbol used to unsubscribe AirPlayState from DataStream events. */
 declare const STATE_UNSUBSCRIBE_SYMBOL: unique symbol;
 //#endregion
 //#region src/airplay/remote.d.ts
+/**
+ * Error thrown when a SendCommand request fails on the Apple TV side.
+ * Contains the specific send error and handler return status for diagnostics.
+ */
 declare class SendCommandError extends CommandError {
+  /** The send error reported by the Apple TV. */
   readonly sendError: Proto.SendError_Enum;
+  /** The handler return status reported by the Apple TV. */
   readonly handlerReturnStatus: Proto.HandlerReturnStatus_Enum;
+  /**
+   * Creates a new SendCommandError.
+   *
+   * @param sendError - The send error code from the Apple TV.
+   * @param handlerReturnStatus - The handler return status from the Apple TV.
+   */
   constructor(sendError: Proto.SendError_Enum, handlerReturnStatus: Proto.HandlerReturnStatus_Enum);
 }
+/**
+ * Remote control for an AirPlay device.
+ * Provides HID-based navigation and media keys (USB usage pages: Generic Desktop 0x01
+ * and Consumer 0x0c), SendCommand-based media controls, keyboard/text input,
+ * and touch/gesture simulation.
+ */
 declare class export_default$1 {
   #private;
+  /**
+   * Creates a new Remote controller.
+   *
+   * @param device - The AirPlay device to control.
+   */
   constructor(device: export_default);
+  /** Sends an Up navigation key press (Generic Desktop, usage 0x8C). */
   up(): Promise<void>;
+  /** Sends a Down navigation key press (Generic Desktop, usage 0x8D). */
   down(): Promise<void>;
+  /** Sends a Left navigation key press (Generic Desktop, usage 0x8B). */
   left(): Promise<void>;
+  /** Sends a Right navigation key press (Generic Desktop, usage 0x8A). */
   right(): Promise<void>;
+  /** Sends a Menu key press (Generic Desktop, usage 0x86). */
   menu(): Promise<void>;
+  /** Sends a Select/Enter key press (Generic Desktop, usage 0x89). */
   select(): Promise<void>;
+  /** Sends a Home button press (Consumer, usage 0x40). */
   home(): Promise<void>;
+  /** Sends a Suspend/Sleep key press to put the device to sleep (Generic Desktop, usage 0x82). */
   suspend(): Promise<void>;
+  /** Sends a Wake key press to wake the device (Generic Desktop, usage 0x83). */
   wake(): Promise<void>;
+  /** Sends a Play key press (Consumer, usage 0xB0). */
   play(): Promise<void>;
+  /** Sends a Pause key press (Consumer, usage 0xB1). */
   pause(): Promise<void>;
+  /** Toggles play/pause based on the current playback state. */
   playPause(): Promise<void>;
+  /** Sends a Stop key press (Consumer, usage 0xB7). */
   stop(): Promise<void>;
+  /** Sends a Next Track key press (Consumer, usage 0xB5). */
   next(): Promise<void>;
+  /** Sends a Previous Track key press (Consumer, usage 0xB6). */
   previous(): Promise<void>;
+  /** Sends a Volume Up key press (Consumer, usage 0xE9). */
   volumeUp(): Promise<void>;
+  /** Sends a Volume Down key press (Consumer, usage 0xEA). */
   volumeDown(): Promise<void>;
+  /** Sends a Mute key press (Consumer, usage 0xE2). */
   mute(): Promise<void>;
+  /** Sends a Top Menu key press (Consumer, usage 0x60). */
   topMenu(): Promise<void>;
+  /** Sends a Channel Up key press (Consumer, usage 0x9C). */
   channelUp(): Promise<void>;
+  /** Sends a Channel Down key press (Consumer, usage 0x9D). */
   channelDown(): Promise<void>;
+  /** Sends a Play command via the MRP SendCommand protocol. */
   commandPlay(): Promise<void>;
+  /** Sends a Pause command via the MRP SendCommand protocol. */
   commandPause(): Promise<void>;
+  /** Sends a TogglePlayPause command via the MRP SendCommand protocol. */
   commandTogglePlayPause(): Promise<void>;
+  /** Sends a Stop command via the MRP SendCommand protocol. */
   commandStop(): Promise<void>;
+  /** Sends a NextTrack command via the MRP SendCommand protocol. */
   commandNextTrack(): Promise<void>;
+  /** Sends a PreviousTrack command via the MRP SendCommand protocol. */
   commandPreviousTrack(): Promise<void>;
+  /**
+   * Sends a SkipForward command with a configurable interval.
+   *
+   * @param interval - Seconds to skip forward (defaults to 15).
+   */
   commandSkipForward(interval?: number): Promise<void>;
+  /**
+   * Sends a SkipBackward command with a configurable interval.
+   *
+   * @param interval - Seconds to skip backward (defaults to 15).
+   */
   commandSkipBackward(interval?: number): Promise<void>;
+  /**
+   * Seeks to an absolute playback position.
+   *
+   * @param position - The target position in seconds.
+   */
   commandSeekToPosition(position: number): Promise<void>;
+  /**
+   * Sets the shuffle mode.
+   *
+   * @param mode - The desired shuffle mode.
+   */
   commandSetShuffleMode(mode: Proto.ShuffleMode_Enum): Promise<void>;
+  /**
+   * Sets the repeat mode.
+   *
+   * @param mode - The desired repeat mode.
+   */
   commandSetRepeatMode(mode: Proto.RepeatMode_Enum): Promise<void>;
+  /**
+   * Changes the playback rate (speed).
+   *
+   * @param rate - The desired playback rate (e.g. 1.0 for normal, 2.0 for double speed).
+   */
   commandChangePlaybackRate(rate: number): Promise<void>;
+  /** Cycles the shuffle mode to the next value. */
   commandAdvanceShuffleMode(): Promise<void>;
+  /** Cycles the repeat mode to the next value. */
   commandAdvanceRepeatMode(): Promise<void>;
+  /** Begins fast-forwarding playback. */
   commandBeginFastForward(): Promise<void>;
+  /** Ends fast-forwarding playback. */
   commandEndFastForward(): Promise<void>;
+  /** Begins rewinding playback. */
   commandBeginRewind(): Promise<void>;
+  /** Ends rewinding playback. */
   commandEndRewind(): Promise<void>;
+  /** Skips to the next chapter. */
   commandNextChapter(): Promise<void>;
+  /** Skips to the previous chapter. */
   commandPreviousChapter(): Promise<void>;
+  /** Marks the current track as liked. */
   commandLikeTrack(): Promise<void>;
+  /** Marks the current track as disliked. */
   commandDislikeTrack(): Promise<void>;
+  /** Bookmarks the current track. */
   commandBookmarkTrack(): Promise<void>;
+  /** Adds the currently playing item to the user's library. */
   commandAddNowPlayingItemToLibrary(): Promise<void>;
+  /**
+   * Sets the text input field to the given text, replacing any existing content.
+   *
+   * @param text - The text to set.
+   */
   textSet(text: string): Promise<void>;
+  /**
+   * Appends text to the current text input field content.
+   *
+   * @param text - The text to append.
+   */
   textAppend(text: string): Promise<void>;
+  /** Clears the text input field. */
   textClear(): Promise<void>;
+  /** Requests the current keyboard session state from the Apple TV. */
   getKeyboardSession(): Promise<void>;
+  /**
+   * Simulates a tap at the given coordinates.
+   *
+   * @param x - Horizontal position in the virtual touch area.
+   * @param y - Vertical position in the virtual touch area.
+   * @param finger - Finger index for multi-touch (defaults to 1).
+   */
   tap(x: number, y: number, finger?: number): Promise<void>;
+  /**
+   * Simulates an upward swipe gesture.
+   *
+   * @param duration - Swipe duration in milliseconds (defaults to 200).
+   */
   swipeUp(duration?: number): Promise<void>;
+  /**
+   * Simulates a downward swipe gesture.
+   *
+   * @param duration - Swipe duration in milliseconds (defaults to 200).
+   */
   swipeDown(duration?: number): Promise<void>;
+  /**
+   * Simulates a leftward swipe gesture.
+   *
+   * @param duration - Swipe duration in milliseconds (defaults to 200).
+   */
   swipeLeft(duration?: number): Promise<void>;
+  /**
+   * Simulates a rightward swipe gesture.
+   *
+   * @param duration - Swipe duration in milliseconds (defaults to 200).
+   */
   swipeRight(duration?: number): Promise<void>;
+  /**
+   * Sends a double press of a HID key (two press-and-release cycles with a 150ms gap).
+   *
+   * @param usePage - USB HID usage page (1 = Generic Desktop, 12 = Consumer).
+   * @param usage - USB HID usage code.
+   */
   doublePress(usePage: number, usage: number): Promise<void>;
+  /**
+   * Sends a long press of a HID key (hold for a configurable duration).
+   *
+   * @param usePage - USB HID usage page (1 = Generic Desktop, 12 = Consumer).
+   * @param usage - USB HID usage code.
+   * @param duration - Hold duration in milliseconds (defaults to 1000).
+   */
   longPress(usePage: number, usage: number, duration?: number): Promise<void>;
+  /**
+   * Sends a single press-and-release of a HID key with a 25ms hold.
+   *
+   * @param usePage - USB HID usage page (1 = Generic Desktop, 12 = Consumer).
+   * @param usage - USB HID usage code.
+   */
   pressAndRelease(usePage: number, usage: number): Promise<void>;
 }
 //#endregion
 //#region src/airplay/state.d.ts
-type EventMap$4 = {
+/**
+ * Events emitted by AirPlayState.
+ *
+ * Low-level events mirror DataStream protocol messages 1:1.
+ * High-level events (activePlayerChanged, artworkChanged, etc.) provide
+ * pre-resolved Client/Player references for convenience.
+ */
+type EventMap$5 = {
   readonly clients: [Record<string, Client>];
+  readonly configureConnection: [Proto.ConfigureConnectionMessage];
   readonly deviceInfo: [Proto.DeviceInfoMessage];
   readonly deviceInfoUpdate: [Proto.DeviceInfoMessage];
   readonly keyboard: [Proto.KeyboardMessage];
@@ -191,230 +546,1027 @@ type EventMap$4 = {
   readonly volumeControlAvailability: [boolean, Proto.VolumeCapabilities_Enum];
   readonly volumeControlCapabilitiesDidChange: [boolean, Proto.VolumeCapabilities_Enum];
   readonly volumeDidChange: [number];
+  readonly volumeMutedDidChange: [boolean];
+  readonly activePlayerChanged: [client: Client | null, player: Player | null];
+  readonly artworkChanged: [client: Client, player: Player];
+  readonly lyricsEvent: [event: Proto.LyricsEvent, playerPath: Proto.PlayerPath | undefined];
+  readonly playbackQueueChanged: [client: Client, player: Player];
+  readonly playbackStateChanged: [client: Client, player: Player, oldState: Proto.PlaybackState_Enum, newState: Proto.PlaybackState_Enum];
+  readonly supportedCommandsChanged: [client: Client, player: Player, commands: Proto.CommandInfo[]];
 };
-declare class export_default$2 extends EventEmitter<EventMap$4> {
+/**
+ * Tracks the complete state of an AirPlay device: clients, players, now-playing,
+ * volume, keyboard, output devices, and cluster info.
+ * Listens to DataStream protocol messages and emits both low-level (1:1 with protocol)
+ * and high-level (deduplicated, resolved) events.
+ */
+declare class export_default$2 extends EventEmitter<EventMap$5> {
   #private;
+  /** All known clients (apps) keyed by bundle identifier. */
   get clients(): Record<string, Client>;
+  /** Whether a keyboard/text input session is currently active on the Apple TV. */
   get isKeyboardActive(): boolean;
+  /** Text editing attributes for the active keyboard session, or null. */
   get keyboardAttributes(): Proto.TextEditingAttributes | null;
+  /** Current keyboard state enum value. */
   get keyboardState(): Proto.KeyboardState_Enum;
+  /** The currently active now-playing client, or null if nothing is playing. */
   get nowPlayingClient(): Client | null;
+  /** UID of the primary output device (used for volume control and multi-room). */
   get outputDeviceUID(): string | null;
+  /** List of all output device descriptors in the current AirPlay group. */
   get outputDevices(): Proto.AVOutputDeviceDescriptor[];
+  /** Cluster identifier for multi-room groups, or null. */
   get clusterID(): string | null;
+  /** Cluster type code (0 if not clustered). */
   get clusterType(): number;
+  /** Whether this device is aware of multi-room clusters. */
   get isClusterAware(): boolean;
+  /** Whether this device is the leader of its multi-room cluster. */
+  get isClusterLeader(): boolean;
+  /** Current volume level (0.0 - 1.0). */
   get volume(): number;
+  /** Whether volume control is available on this device. */
   get volumeAvailable(): boolean;
+  /** Volume capabilities (absolute, relative, both, or none). */
   get volumeCapabilities(): Proto.VolumeCapabilities_Enum;
+  /** Whether the device is currently muted. */
+  get volumeMuted(): boolean;
+  /**
+   * Creates a new AirPlayState tracker.
+   *
+   * @param device - The AirPlay device to track state for.
+   */
   constructor(device: export_default);
+  /** Subscribes to all DataStream events to track device state. Called internally via symbol. */
   [STATE_SUBSCRIBE_SYMBOL](): void;
+  /** Unsubscribes from all DataStream events. Called internally via symbol. */
   [STATE_UNSUBSCRIBE_SYMBOL](): void;
+  /** Resets all state to initial/default values. Called on connect and reconnect. */
   clear(): void;
+  /**
+   * Handles a ConfigureConnection message from the Apple TV.
+   *
+   * @param message - The configure connection message.
+   */
+  onConfigureConnection(message: Proto.ConfigureConnectionMessage): void;
+  /**
+   * Handles keyboard state changes. Updates internal state and emits 'keyboard'.
+   *
+   * @param message - The keyboard message with state and attributes.
+   */
   onKeyboard(message: Proto.KeyboardMessage): void;
+  /**
+   * Handles initial device info. Updates output device UID and cluster info.
+   *
+   * @param message - The device info message.
+   */
   onDeviceInfo(message: Proto.DeviceInfoMessage): void;
+  /**
+   * Handles device info updates (e.g. cluster changes). Updates output device UID and cluster info.
+   *
+   * @param message - The device info update message.
+   */
   onDeviceInfoUpdate(message: Proto.DeviceInfoMessage): void;
+  /**
+   * Handles origin client properties updates.
+   *
+   * @param message - The origin client properties message.
+   */
   onOriginClientProperties(message: Proto.OriginClientPropertiesMessage): void;
+  /**
+   * Handles player client properties updates.
+   *
+   * @param message - The player client properties message.
+   */
   onPlayerClientProperties(message: Proto.PlayerClientPropertiesMessage): void;
+  /**
+   * Handles removal of a client (app). Clears the now-playing reference if
+   * the removed client was the active one.
+   *
+   * @param message - The remove client message.
+   */
   onRemoveClient(message: Proto.RemoveClientMessage): void;
+  /**
+   * Handles command result notifications from the Apple TV.
+   *
+   * @param message - The send command result message.
+   */
   onSendCommandResult(message: Proto.SendCommandResultMessage): void;
+  /**
+   * Handles lyrics events (time-synced lyrics updates).
+   *
+   * @param message - The lyrics event message.
+   */
+  onSendLyricsEvent(message: Proto.SendLyricsEventMessage): void;
+  /**
+   * Handles artwork set notifications.
+   *
+   * @param message - The set artwork message.
+   */
   onSetArtwork(message: Proto.SetArtworkMessage): void;
+  /**
+   * Handles default supported commands for a client. These serve as fallback
+   * commands when a player has no commands of its own.
+   *
+   * @param message - The set default supported commands message.
+   */
   onSetDefaultSupportedCommands(message: Proto.SetDefaultSupportedCommandsMessage): void;
+  /**
+   * Handles the now-playing client changing (e.g. user switches app).
+   * Updates the active client reference and emits change events.
+   *
+   * @param message - The set now-playing client message.
+   */
   onSetNowPlayingClient(message: Proto.SetNowPlayingClientMessage): void;
+  /**
+   * Handles the active player changing within a client (e.g. PiP player becomes active).
+   * Creates the player if needed and sets it as the active player.
+   *
+   * @param message - The set now-playing player message.
+   */
   onSetNowPlayingPlayer(message: Proto.SetNowPlayingPlayerMessage): void;
+  /**
+   * Handles comprehensive state updates. Processes playback state, now-playing info,
+   * supported commands, and playback queue in a single message.
+   * Emits granular events for each changed aspect.
+   *
+   * @param message - The set state message.
+   */
   onSetState(message: Proto.SetStateMessage): void;
+  /**
+   * Handles content item updates (metadata, artwork, lyrics changes for existing items).
+   *
+   * @param message - The update content item message.
+   */
   onUpdateContentItem(message: Proto.UpdateContentItemMessage): void;
+  /**
+   * Handles artwork updates for content items. Emits 'artworkChanged' if a client and player are active.
+   *
+   * @param message - The update content item artwork message.
+   */
   onUpdateContentItemArtwork(message: Proto.UpdateContentItemArtworkMessage): void;
+  /**
+   * Handles player registration or update. Creates the player if it does not exist.
+   *
+   * @param message - The update player message.
+   */
   onUpdatePlayer(message: Proto.UpdatePlayerMessage): void;
+  /**
+   * Handles player removal. Removes the player from its client and emits
+   * active player changed events if the removed player was active.
+   *
+   * @param message - The remove player message.
+   */
   onRemovePlayer(message: Proto.RemovePlayerMessage): void;
+  /**
+   * Handles client (app) registration or display name update.
+   *
+   * @param message - The update client message.
+   */
   onUpdateClient(message: Proto.UpdateClientMessage): void;
+  /**
+   * Handles output device list updates. Prefers cluster-aware devices when available.
+   *
+   * @param message - The update output device message.
+   */
   onUpdateOutputDevice(message: Proto.UpdateOutputDeviceMessage): void;
+  /**
+   * Handles volume control availability changes.
+   *
+   * @param message - The volume control availability message.
+   */
   onVolumeControlAvailability(message: Proto.VolumeControlAvailabilityMessage): void;
+  /**
+   * Handles volume capabilities changes (e.g. device gains or loses absolute volume support).
+   *
+   * @param message - The volume capabilities change message.
+   */
   onVolumeControlCapabilitiesDidChange(message: Proto.VolumeControlCapabilitiesDidChangeMessage): void;
+  /**
+   * Handles volume level changes.
+   *
+   * @param message - The volume change message.
+   */
   onVolumeDidChange(message: Proto.VolumeDidChangeMessage): void;
+  /**
+   * Handles mute state changes.
+   *
+   * @param message - The volume muted change message.
+   */
+  onVolumeMutedDidChange(message: Proto.VolumeMutedDidChangeMessage): void;
 }
 //#endregion
 //#region src/airplay/volume.d.ts
+/**
+ * Smart volume controller for an AirPlay device.
+ * Automatically chooses between absolute volume (set a specific level) and
+ * relative volume (HID volume up/down keys) based on the device's reported capabilities.
+ */
 declare class export_default$3 {
   #private;
+  /**
+   * Creates a new Volume controller.
+   *
+   * @param device - The AirPlay device to control volume for.
+   */
   constructor(device: export_default);
+  /**
+   * Decreases the volume by one step. Uses absolute volume when available,
+   * falls back to HID relative volume keys otherwise.
+   *
+   * @throws CommandError when volume control is not available.
+   */
   down(): Promise<void>;
+  /**
+   * Increases the volume by one step. Uses absolute volume when available,
+   * falls back to HID relative volume keys otherwise.
+   *
+   * @throws CommandError when volume control is not available.
+   */
   up(): Promise<void>;
+  /**
+   * Fetches the current volume level from the device.
+   *
+   * @returns The volume level as a float between 0.0 and 1.0.
+   * @throws CommandError when no output device is active or the request fails.
+   */
   get(): Promise<number>;
+  /**
+   * Sets the volume to an absolute level.
+   *
+   * @param volume - The desired volume level (clamped to 0.0 - 1.0).
+   * @throws CommandError when no output device is active or absolute volume is not supported.
+   */
   set(volume: number): Promise<void>;
 }
 //#endregion
 //#region src/airplay/device.d.ts
-type EventMap$3 = {
+/**
+ * Events emitted by AirPlayDevice.
+ * - `connected` — emitted after the full protocol setup completes.
+ * - `disconnected` — emitted when the connection is lost or explicitly closed.
+ */
+type EventMap$4 = {
   connected: [];
   disconnected: [unexpected: boolean];
 };
-declare class export_default extends EventEmitter<EventMap$3> {
+/**
+ * High-level abstraction for an AirPlay device (Apple TV or HomePod).
+ * Manages the full lifecycle: connect, pair/verify, set up control/data/event streams,
+ * and provides access to Remote, State, and Volume controllers.
+ * Supports both transient (PIN-less) and credential-based pairing.
+ */
+declare class export_default extends EventEmitter<EventMap$4> {
   #private;
+  /** @returns The underlying AirPlay Protocol instance (accessed via symbol for internal use). */
   get [PROTOCOL](): Protocol;
+  /** The mDNS discovery result used to connect to this device. */
   get discoveryResult(): DiscoveryResult;
+  /** Updates the discovery result, e.g. when the device's address changes. */
   set discoveryResult(discoveryResult: DiscoveryResult);
+  /**
+   * Device capabilities derived from the AirPlay feature flags.
+   * Indicates which protocols and features the receiver supports.
+   */
+  get capabilities(): {
+    supportsAudio: boolean;
+    supportsBufferedAudio: boolean;
+    supportsPTP: boolean;
+    supportsRFC2198Redundancy: boolean;
+    supportsHangdogRemoteControl: boolean;
+    supportsUnifiedMediaControl: boolean;
+    supportsTransientPairing: boolean;
+    supportsSystemPairing: boolean;
+    supportsCoreUtilsPairing: boolean;
+  };
+  /** Whether the control stream TCP connection is currently active. */
   get isConnected(): boolean;
+  /** Raw receiver info dictionary from the /info endpoint, or undefined before connect. */
+  get receiverInfo(): Record<string, any> | undefined;
+  /** The Remote controller for HID keys, SendCommand, text input, and touch. */
   get remote(): export_default$1;
+  /** The State tracker for now-playing, volume, keyboard, and output device state. */
   get state(): export_default$2;
+  /** The Volume controller for absolute and relative volume adjustments. */
   get volume(): export_default$3;
+  /** The shared PTP timing server, if one is assigned for multi-room sync. */
   get timingServer(): TimingServer | undefined;
+  /** Assigns a PTP timing server for multi-room audio synchronization. */
   set timingServer(timingServer: TimingServer | undefined);
-  constructor(discoveryResult: DiscoveryResult);
+  /**
+   * Creates a new AirPlayDevice.
+   *
+   * @param discoveryResult - The mDNS discovery result for the target device.
+   * @param identity - Optional partial device identity to present during pairing.
+   */
+  constructor(discoveryResult: DiscoveryResult, identity?: Partial<DeviceIdentity>);
+  /**
+   * Connects to the AirPlay device, performs pairing/verification,
+   * and sets up all streams (control, data, event). Emits 'connected' on success.
+   * If credentials are set, uses pair-verify; otherwise uses transient pairing.
+   */
   connect(): Promise<void>;
+  /** Gracefully disconnects from the device, clears intervals, and tears down all streams. */
   disconnect(): void;
+  /** Disconnects gracefully, swallowing any errors during cleanup. */
   disconnectSafely(): void;
+  /**
+   * Enables or disables conversation detection on the output device (HomePod feature).
+   *
+   * @param enabled - Whether to enable conversation detection.
+   * @throws Error when no output device is active.
+   */
+  setConversationDetectionEnabled(enabled: boolean): Promise<void>;
+  /**
+   * Adds devices to the current multi-room output context.
+   *
+   * @param deviceUIDs - UIDs of the devices to add.
+   */
   addOutputDevices(deviceUIDs: string[]): Promise<void>;
+  /**
+   * Removes devices from the current multi-room output context.
+   *
+   * @param deviceUIDs - UIDs of the devices to remove.
+   */
   removeOutputDevices(deviceUIDs: string[]): Promise<void>;
+  /**
+   * Replaces the entire multi-room output context with the given devices.
+   *
+   * @param deviceUIDs - UIDs of the devices to set as the output context.
+   */
   setOutputDevices(deviceUIDs: string[]): Promise<void>;
+  /**
+   * Plays a URL on the device (the device fetches and plays the content).
+   * Creates a separate Protocol instance to avoid conflicting with the
+   * existing remote control session, following the same approach as pyatv.
+   *
+   * @param url - The media URL to play.
+   * @param position - Start position in seconds (defaults to 0).
+   * @throws Error when not connected.
+   */
   playUrl(url: string, position?: number): Promise<void>;
+  /** Waits for the current URL playback to finish, then cleans up the play URL protocol. */
   waitForPlaybackEnd(): Promise<void>;
+  /** Stops the current URL playback and cleans up the dedicated play URL protocol. */
   stopPlayUrl(): void;
+  /**
+   * Streams audio from a source to the device via RAOP/RTP.
+   *
+   * @param source - The audio source to stream (e.g. MP3, WAV, URL, live).
+   */
   streamAudio(source: AudioSource): Promise<void>;
+  /**
+   * Requests the playback queue from the device.
+   *
+   * @param length - Maximum number of queue items to retrieve.
+   */
   requestPlaybackQueue(length: number): Promise<void>;
+  /**
+   * Sends a raw MRP command to the device via the DataStream.
+   *
+   * @param command - The command to send.
+   * @param options - Optional command options.
+   */
   sendCommand(command: Proto.Command, options?: Proto.CommandOptions): Promise<void>;
+  /**
+   * Sets the pairing credentials for pair-verify authentication.
+   * Must be called before connect() if credential-based pairing is desired.
+   *
+   * @param credentials - The accessory credentials obtained from pair-setup.
+   */
   setCredentials(credentials: AccessoryCredentials): void;
+  /** Handles the control stream close event. Emits 'disconnected' with unexpected=true if not intentional. */
+  onClose(): void;
+  /**
+   * Handles stream error events by logging them.
+   *
+   * @param err - The error that occurred.
+   */
+  onError(err: Error): void;
+  /** Handles stream timeout events by destroying the control stream. */
+  onTimeout(): void;
 }
 //#endregion
 //#region src/companion-link/const.d.ts
+/** Symbol used to access the underlying Companion Link Protocol instance from a CompanionLinkDevice. */
 declare const PROTOCOL$1: unique symbol;
 //#endregion
+//#region src/companion-link/state.d.ts
+/**
+ * Events emitted by CompanionLinkState.
+ * Provides reactive state updates from the Companion Link protocol.
+ */
+type EventMap$3 = {
+  readonly attentionStateChanged: [AttentionState];
+  readonly mediaControlFlagsChanged: [flags: number, capabilities: MediaCapabilities];
+  readonly nowPlayingInfoChanged: [info: Record<string, unknown> | null];
+  readonly supportedActionsChanged: [actions: Record<string, unknown>];
+  readonly textInputChanged: [TextInputState];
+  readonly volumeAvailabilityChanged: [available: boolean];
+};
+/**
+ * Parsed media control capabilities, indicating which playback controls
+ * are currently available on the device.
+ */
+type MediaCapabilities = {
+  readonly play: boolean;
+  readonly pause: boolean;
+  readonly nextTrack: boolean;
+  readonly previousTrack: boolean;
+  readonly fastForward: boolean;
+  readonly rewind: boolean;
+  readonly volume: boolean;
+  readonly skipForward: boolean;
+  readonly skipBackward: boolean;
+};
+/**
+ * Tracks the state of a Companion Link device: attention state, media controls,
+ * now-playing info, supported actions, text input, and volume availability.
+ * Subscribes to protocol stream events and emits typed state change events.
+ */
+declare class CompanionLinkState extends EventEmitter<EventMap$3> {
+  #private;
+  /** Current attention state of the device (active, idle, screensaver, etc.). */
+  get attentionState(): AttentionState;
+  /** Parsed media capabilities indicating which controls are available. */
+  get mediaCapabilities(): MediaCapabilities;
+  /** Raw media control flags bitmask from the device. */
+  get mediaControlFlags(): number;
+  /** Current now-playing info as a key-value dictionary, or null. */
+  get nowPlayingInfo(): Record<string, unknown> | null;
+  /** Currently supported actions dictionary, or null. */
+  get supportedActions(): Record<string, unknown> | null;
+  /** Current text input session state. */
+  get textInputState(): TextInputState;
+  /** Whether volume control is currently available via the Companion Link protocol. */
+  get volumeAvailable(): boolean;
+  /**
+   * Creates a new CompanionLinkState tracker.
+   *
+   * @param protocol - The Companion Link protocol instance to observe.
+   */
+  constructor(protocol: Protocol$1);
+  /** Subscribes to protocol stream events and registers interests for push notifications. */
+  subscribe(): void;
+  /** Unsubscribes from protocol stream events and deregisters interests. */
+  unsubscribe(): void;
+  /** Fetches the initial attention state and media control status from the device. */
+  fetchInitialState(): Promise<void>;
+  /** Resets all state to initial/default values. */
+  clear(): void;
+  /**
+   * Handles media control flag updates (_iMC). Parses the flags bitmask and
+   * emits events if capabilities or volume availability changed.
+   *
+   * @param data - The raw media control payload.
+   */
+  onMediaControl(data: unknown): void;
+  /**
+   * Handles SystemStatus events (attention state changes from non-TV devices).
+   *
+   * @param data - The raw system status payload containing a state code.
+   */
+  onSystemStatus(data: unknown): void;
+  /**
+   * Handles TVSystemStatus events (attention state changes from Apple TV).
+   *
+   * @param data - The raw TV system status payload containing a state code.
+   */
+  onTVSystemStatus(data: unknown): void;
+  /**
+   * Handles NowPlayingInfo updates. Decodes the NSKeyedArchiver plist payload
+   * when present, otherwise uses the raw dictionary.
+   *
+   * @param data - The raw now-playing info payload.
+   */
+  onNowPlayingInfo(data: unknown): void;
+  /**
+   * Handles SupportedActions updates from the device.
+   *
+   * @param data - The raw supported actions payload.
+   */
+  onSupportedActions(data: unknown): void;
+  /**
+   * Handles the start of a text input session. Parses the plist payload to extract
+   * document text, security mode, keyboard type, and autocorrection settings.
+   *
+   * @param data - The raw text input started payload.
+   */
+  onTextInputStarted(data: unknown): void;
+  /**
+   * Handles the end of a text input session. Resets the text input state to defaults.
+   *
+   * @param _data - The raw text input stopped payload (unused).
+   */
+  onTextInputStopped(_data: unknown): void;
+}
+//#endregion
 //#region src/companion-link/device.d.ts
+/**
+ * Events emitted by CompanionLinkDevice.
+ * Forwards state change events from CompanionLinkState for convenience.
+ */
 type EventMap$2 = {
   connected: [];
   disconnected: [unexpected: boolean];
-  power: [AttentionState];
-  textInput: [TextInputState];
+  attentionStateChanged: [AttentionState];
+  mediaControlFlagsChanged: [flags: number, capabilities: MediaCapabilities];
+  nowPlayingInfoChanged: [info: Record<string, unknown> | null];
+  supportedActionsChanged: [actions: Record<string, unknown>];
+  textInputChanged: [TextInputState];
+  volumeAvailabilityChanged: [available: boolean];
 };
+/**
+ * High-level abstraction for a Companion Link device (Apple TV).
+ * Manages the OPack-based Companion Link protocol lifecycle: connect, pair-verify,
+ * session setup, and provides access to HID buttons, app launching, user accounts,
+ * media control, text input, touch, Siri, and system controls.
+ * Requires credentials (obtained from pair-setup) to connect.
+ */
 declare class export_default$5 extends EventEmitter<EventMap$2> {
   #private;
+  /** @returns The underlying Companion Link Protocol instance (accessed via symbol for internal use). */
   get [PROTOCOL$1](): Protocol$1;
+  /** The mDNS discovery result used to connect to this device. */
   get discoveryResult(): DiscoveryResult;
+  /** Updates the discovery result, e.g. when the device's address changes. */
   set discoveryResult(discoveryResult: DiscoveryResult);
+  /** Whether the Companion Link stream is currently connected. */
   get isConnected(): boolean;
+  /** The state tracker for attention, media controls, now-playing, and text input. */
+  get state(): CompanionLinkState;
+  /** Current text input session state (convenience accessor). */
   get textInputState(): TextInputState;
+  /**
+   * Creates a new CompanionLinkDevice.
+   *
+   * @param discoveryResult - The mDNS discovery result for the target device.
+   */
   constructor(discoveryResult: DiscoveryResult);
+  /**
+   * Connects to the Companion Link device, performs pair-verify, and sets up
+   * all protocol sessions (system info, TVRC, touch, text input).
+   * Emits 'connected' on success.
+   *
+   * @throws CredentialsError when no credentials are set.
+   */
   connect(): Promise<void>;
+  /** Gracefully disconnects from the device, clears heartbeat interval, and unsubscribes from events. */
   disconnect(): Promise<void>;
+  /** Disconnects gracefully, swallowing any errors during cleanup. */
   disconnectSafely(): Promise<void>;
+  /**
+   * Sets the pairing credentials required for pair-verify authentication.
+   * Must be called before connect().
+   *
+   * @param credentials - The accessory credentials from pair-setup.
+   */
   setCredentials(credentials: AccessoryCredentials): Promise<void>;
+  /**
+   * Fetches the current attention state of the device (active, idle, screensaver, etc.).
+   *
+   * @returns The current attention state.
+   */
   getAttentionState(): Promise<AttentionState>;
+  /**
+   * Fetches the list of apps that can be launched on the device.
+   *
+   * @returns Array of launchable app descriptors.
+   */
   getLaunchableApps(): Promise<LaunchableApp[]>;
+  /**
+   * Fetches the list of user accounts configured on the device.
+   *
+   * @returns Array of user account descriptors.
+   */
   getUserAccounts(): Promise<UserAccount[]>;
+  /**
+   * Fetches the current now-playing information from the device.
+   *
+   * @returns The now-playing info payload.
+   */
+  fetchNowPlayingInfo(): Promise<any>;
+  /**
+   * Fetches the currently supported actions from the device.
+   *
+   * @returns The supported actions payload.
+   */
+  fetchSupportedActions(): Promise<any>;
+  /**
+   * Fetches the current media control status (available controls bitmask).
+   *
+   * @returns The media control status payload.
+   */
+  fetchMediaControlStatus(): Promise<any>;
+  /**
+   * Launches an app on the device by its bundle identifier.
+   *
+   * @param bundleId - The bundle identifier of the app to launch.
+   */
   launchApp(bundleId: string): Promise<void>;
+  /**
+   * Opens a URL on the device (universal link or app-specific URL scheme).
+   *
+   * @param url - The URL to open.
+   */
   launchUrl(url: string): Promise<void>;
-  mediaControlCommand(command: MediaControlCommandKey, content?: object): Promise<void>;
+  /**
+   * Sends a media control command (play, pause, next, etc.) via the Companion Link protocol.
+   *
+   * @param command - The media control command key.
+   * @param content - Optional additional content for the command.
+   */
+  mediaControlCommand(command: MediaControlCommandKey, content?: Record<string, unknown>): Promise<void>;
+  /**
+   * Sends a HID button press via the Companion Link protocol.
+   *
+   * @param command - The HID command key (e.g. 'up', 'select', 'menu').
+   * @param type - Optional press type (short, long, double).
+   * @param holdDelayMs - Optional hold duration in milliseconds for long presses.
+   */
   pressButton(command: HidCommandKey, type?: ButtonPressType, holdDelayMs?: number): Promise<void>;
+  /**
+   * Switches to a different user account on the device.
+   *
+   * @param accountId - The ID of the user account to switch to.
+   */
   switchUserAccount(accountId: string): Promise<void>;
+  /**
+   * Sets the text input field to the given text, replacing any existing content.
+   *
+   * @param text - The text to set.
+   */
   textSet(text: string): Promise<void>;
+  /**
+   * Appends text to the current text input field content.
+   *
+   * @param text - The text to append.
+   */
   textAppend(text: string): Promise<void>;
+  /** Clears the text input field. */
   textClear(): Promise<void>;
-  onSystemStatus(data: {
-    readonly state: number;
-  }): Promise<void>;
-  onTVSystemStatus(data: {
-    readonly state: number;
-  }): Promise<void>;
+  /**
+   * Sends a raw touch event to the device.
+   *
+   * @param finger - Finger index (0-based).
+   * @param phase - Touch phase (0 = Began, 1 = Moved, 2 = Ended).
+   * @param x - Horizontal position.
+   * @param y - Vertical position.
+   */
+  sendTouchEvent(finger: number, phase: number, x: number, y: number): Promise<void>;
+  /**
+   * Simulates a tap at the given coordinates.
+   *
+   * @param x - Horizontal position (defaults to center 500).
+   * @param y - Vertical position (defaults to center 500).
+   */
+  tap(x?: number, y?: number): Promise<void>;
+  /**
+   * Simulates a swipe gesture in the given direction.
+   *
+   * @param direction - Swipe direction.
+   * @param duration - Swipe duration in milliseconds (defaults to 200).
+   */
+  swipe(direction: 'up' | 'down' | 'left' | 'right', duration?: number): Promise<void>;
+  /** Toggles closed captions on the device. */
+  toggleCaptions(): Promise<void>;
+  /**
+   * Toggles the system appearance between light and dark mode.
+   *
+   * @param light - True for light mode, false for dark mode.
+   */
+  toggleSystemAppearance(light: boolean): Promise<void>;
+  /**
+   * Enables or disables the "Reduce Loud Sounds" setting.
+   *
+   * @param enabled - Whether to enable the setting.
+   */
+  toggleReduceLoudSounds(enabled: boolean): Promise<void>;
+  /**
+   * Enables or disables finding mode (Find My integration).
+   *
+   * @param enabled - Whether to enable finding mode.
+   */
+  toggleFindingMode(enabled: boolean): Promise<void>;
+  /**
+   * Fetches the "Up Next" queue from the device.
+   *
+   * @param paginationToken - Optional token for paginated results.
+   * @returns The Up Next queue payload.
+   */
+  fetchUpNext(paginationToken?: string): Promise<any>;
+  /**
+   * Adds an item to the "Up Next" queue.
+   *
+   * @param identifier - Content item identifier.
+   * @param kind - Content kind descriptor.
+   */
+  addToUpNext(identifier: string, kind: string): Promise<void>;
+  /**
+   * Removes an item from the "Up Next" queue.
+   *
+   * @param identifier - Content item identifier.
+   * @param kind - Content kind descriptor.
+   */
+  removeFromUpNext(identifier: string, kind: string): Promise<void>;
+  /**
+   * Marks a content item as watched.
+   *
+   * @param identifier - Content item identifier.
+   * @param kind - Content kind descriptor.
+   */
+  markAsWatched(identifier: string, kind: string): Promise<void>;
+  /** Starts a Siri session on the device. */
+  siriStart(): Promise<void>;
+  /** Stops the active Siri session on the device. */
+  siriStop(): Promise<void>;
+  /** Handles the stream close event. Emits 'disconnected' with unexpected=true if not intentional. */
+  onClose(): void;
+  /**
+   * Handles stream error events by logging them.
+   *
+   * @param err - The error that occurred.
+   */
+  onError(err: Error): void;
+  /** Handles stream timeout events by destroying the stream. */
+  onTimeout(): void;
 }
 //#endregion
 //#region src/model/apple-tv.d.ts
+/**
+ * Events emitted by AppleTV.
+ * - `connected` — emitted after both AirPlay and Companion Link are connected.
+ * - `disconnected` — emitted when either connection is lost.
+ * - `power` — emitted when the device's attention state changes.
+ * - `textInput` — emitted when a text input session starts, changes, or stops.
+ */
 type EventMap$1 = {
   connected: [];
   disconnected: [unexpected: boolean];
   power: [AttentionState];
   textInput: [TextInputState];
 };
+/**
+ * High-level Apple TV device model combining AirPlay (remote control, media, streaming)
+ * and Companion Link (apps, accounts, power, text input) protocols.
+ * Provides a unified interface for controlling an Apple TV.
+ */
 declare class export_default$4 extends EventEmitter<EventMap$1> {
   #private;
+  /** The underlying AirPlay device for direct protocol access. */
   get airplay(): export_default;
+  /** The underlying Companion Link device for direct protocol access. */
   get companionLink(): export_default$5;
+  /** AirPlay remote controller for HID keys and commands. */
   get remote(): export_default$1;
+  /** AirPlay state tracker for now-playing, volume, and keyboard. */
   get state(): export_default$2;
+  /** AirPlay volume controller. */
   get volumeControl(): export_default$3;
+  /** Bundle identifier of the currently playing app, or null. */
   get bundleIdentifier(): string | null;
+  /** Display name of the currently playing app, or null. */
   get displayName(): string | null;
+  /** Whether both AirPlay and Companion Link are connected. */
   get isConnected(): boolean;
+  /** Whether the active player is currently playing. */
   get isPlaying(): boolean;
+  /** Current track title. */
   get title(): string;
+  /** Current track artist. */
   get artist(): string;
+  /** Current track album. */
   get album(): string;
+  /** Duration of the current track in seconds. */
   get duration(): number;
+  /** Extrapolated elapsed time in seconds. */
   get elapsedTime(): number;
+  /** Current playback queue from the active player. */
   get playbackQueue(): AirPlay.Proto.PlaybackQueue | null;
+  /** Current playback state. */
   get playbackState(): AirPlay.Proto.PlaybackState_Enum;
+  /** Timestamp of the last playback state update. */
   get playbackStateTimestamp(): number;
+  /** Current volume level (0.0 - 1.0). */
   get volume(): number;
+  /**
+   * Creates a new AppleTV instance.
+   *
+   * @param airplayDiscoveryResult - The mDNS discovery result for the AirPlay service.
+   * @param companionLinkDiscoveryResult - The mDNS discovery result for the Companion Link service.
+   */
   constructor(airplayDiscoveryResult: DiscoveryResult, companionLinkDiscoveryResult: DiscoveryResult);
+  /**
+   * Connects both AirPlay and Companion Link protocols.
+   * If Companion Link fails, AirPlay is disconnected to maintain consistency.
+   *
+   * @param airplayCredentials - Credentials for the AirPlay service.
+   * @param companionLinkCredentials - Optional separate credentials for Companion Link (defaults to AirPlay credentials).
+   */
   connect(airplayCredentials: AccessoryCredentials, companionLinkCredentials?: AccessoryCredentials): Promise<void>;
+  /** Disconnects both AirPlay and Companion Link protocols. */
   disconnect(): Promise<void>;
+  /** Puts the Apple TV to sleep via a suspend HID key press. */
   turnOff(): Promise<void>;
+  /** Wakes the Apple TV from sleep via a wake HID key press. */
   turnOn(): Promise<void>;
+  /** Sends a Pause command. */
   pause(): Promise<void>;
+  /** Sends a TogglePlayPause command. */
   playPause(): Promise<void>;
+  /** Sends a Play command. */
   play(): Promise<void>;
+  /** Sends a Stop command. */
   stop(): Promise<void>;
+  /** Sends a NextInContext command (next track/episode). */
   next(): Promise<void>;
+  /** Sends a PreviousInContext command (previous track/episode). */
   previous(): Promise<void>;
+  /** Decreases volume via HID volume down key. */
   volumeDown(): Promise<void>;
+  /** Toggles mute via HID mute key. */
   volumeMute(): Promise<void>;
+  /** Increases volume via HID volume up key. */
   volumeUp(): Promise<void>;
+  /**
+   * Fetches the current attention state via Companion Link.
+   *
+   * @returns The current attention state.
+   */
   getAttentionState(): Promise<AttentionState>;
+  /**
+   * Fetches the list of launchable apps via Companion Link.
+   *
+   * @returns Array of launchable app descriptors.
+   */
   getLaunchableApps(): Promise<LaunchableApp[]>;
+  /**
+   * Fetches user accounts configured on the device via Companion Link.
+   *
+   * @returns Array of user account descriptors.
+   */
   getUserAccounts(): Promise<UserAccount[]>;
+  /**
+   * Launches an app via Companion Link.
+   *
+   * @param bundleId - The bundle identifier of the app to launch.
+   */
   launchApp(bundleId: string): Promise<void>;
+  /**
+   * Switches user account via Companion Link.
+   *
+   * @param accountId - The ID of the user account to switch to.
+   */
   switchUserAccount(accountId: string): Promise<void>;
+  /**
+   * Sets the text input field to the given text via Companion Link.
+   *
+   * @param text - The text to set.
+   */
   textSet(text: string): Promise<void>;
+  /**
+   * Appends text to the text input field via Companion Link.
+   *
+   * @param text - The text to append.
+   */
   textAppend(text: string): Promise<void>;
+  /** Clears the text input field via Companion Link. */
   textClear(): Promise<void>;
+  /**
+   * Gets the CommandInfo for a specific command from the active player.
+   *
+   * @param command - The command to look up.
+   * @returns The command info, or null if no client is active or command not found.
+   */
   getCommandInfo(command: AirPlay.Proto.Command): Promise<AirPlay.Proto.CommandInfo | null>;
+  /**
+   * Checks whether a command is supported and enabled by the active player.
+   *
+   * @param command - The command to check.
+   * @returns True if supported and enabled, false otherwise.
+   */
   isCommandSupported(command: AirPlay.Proto.Command): Promise<boolean>;
 }
 //#endregion
 //#region src/model/homepod-base.d.ts
+/**
+ * Events emitted by HomePod models.
+ * - `connected` — emitted after the AirPlay connection is established.
+ * - `disconnected` — emitted when the connection is lost.
+ */
 type EventMap = {
   connected: [];
   disconnected: [unexpected: boolean];
 };
+/**
+ * Abstract base class for HomePod models (HomePod and HomePod Mini).
+ * Uses AirPlay only (no Companion Link). Supports transient pairing, media control,
+ * URL playback, and audio streaming.
+ */
 declare abstract class export_default$8 extends EventEmitter<EventMap> {
   #private;
+  /** The underlying AirPlay device for direct protocol access. */
   get airplay(): export_default;
+  /** AirPlay remote controller for HID keys and commands. */
   get remote(): export_default$1;
+  /** AirPlay state tracker for now-playing and volume. */
   get state(): export_default$2;
+  /** AirPlay volume controller. */
   get volumeControl(): export_default$3;
+  /** Bundle identifier of the currently playing app, or null. */
   get bundleIdentifier(): string | null;
+  /** Display name of the currently playing app, or null. */
   get displayName(): string | null;
+  /** Whether the AirPlay connection is active. */
   get isConnected(): boolean;
+  /** Whether the active player is currently playing. */
   get isPlaying(): boolean;
+  /** Current track title. */
   get title(): string;
+  /** Current track artist. */
   get artist(): string;
+  /** Current track album. */
   get album(): string;
+  /** Duration of the current track in seconds. */
   get duration(): number;
+  /** Extrapolated elapsed time in seconds. */
   get elapsedTime(): number;
+  /** Current playback queue from the active player. */
   get playbackQueue(): AirPlay.Proto.PlaybackQueue | null;
+  /** Current playback state. */
   get playbackState(): AirPlay.Proto.PlaybackState_Enum;
+  /** Timestamp of the last playback state update. */
   get playbackStateTimestamp(): number;
+  /** Current volume level (0.0 - 1.0). */
   get volume(): number;
+  /**
+   * Creates a new HomePod base instance.
+   *
+   * @param discoveryResult - The mDNS discovery result for the AirPlay service.
+   */
   constructor(discoveryResult: DiscoveryResult);
+  /** Connects to the HomePod via AirPlay (transient pairing). */
   connect(): Promise<void>;
+  /** Disconnects from the HomePod. */
   disconnect(): Promise<void>;
+  /** Sends a Pause command. */
   pause(): Promise<void>;
+  /** Sends a TogglePlayPause command. */
   playPause(): Promise<void>;
+  /** Sends a Play command. */
   play(): Promise<void>;
+  /** Sends a Stop command. */
   stop(): Promise<void>;
+  /** Sends a NextInContext command (next track). */
   next(): Promise<void>;
+  /** Sends a PreviousInContext command (previous track). */
   previous(): Promise<void>;
+  /**
+   * Plays a URL on the HomePod (the device fetches and plays the content).
+   *
+   * @param url - The media URL to play.
+   * @param position - Start position in seconds (defaults to 0).
+   */
   playUrl(url: string, position?: number): Promise<void>;
+  /** Waits for the current URL playback to finish. */
   waitForPlaybackEnd(): Promise<void>;
+  /** Stops the current URL playback and cleans up. */
   stopPlayUrl(): void;
+  /**
+   * Streams audio from a source to the HomePod via RAOP/RTP.
+   *
+   * @param source - The audio source to stream.
+   */
   streamAudio(source: AudioSource): Promise<void>;
+  /**
+   * Gets the CommandInfo for a specific command from the active player.
+   *
+   * @param command - The command to look up.
+   * @returns The command info, or null if no client is active or command not found.
+   */
   getCommandInfo(command: AirPlay.Proto.Command): Promise<AirPlay.Proto.CommandInfo | null>;
+  /**
+   * Checks whether a command is supported and enabled by the active player.
+   *
+   * @param command - The command to check.
+   * @returns True if supported and enabled, false otherwise.
+   */
   isCommandSupported(command: AirPlay.Proto.Command): Promise<boolean>;
 }
 //#endregion
 //#region src/model/homepod.d.ts
+/**
+ * HomePod device model. AirPlay only (no Companion Link).
+ * Supports media control, URL playback, audio streaming, and volume control.
+ */
 declare class export_default$6 extends export_default$8 {}
 //#endregion
 //#region src/model/homepod-mini.d.ts
+/**
+ * HomePod Mini device model. AirPlay only (no Companion Link).
+ * Identical feature set to HomePod, distinguished for device model identification.
+ */
 declare class export_default$7 extends export_default$8 {}
 //#endregion
 export { PROTOCOL as AIRPLAY, Client as AirPlayClient, export_default as AirPlayDevice, Player as AirPlayPlayer, export_default$1 as AirPlayRemote, export_default$2 as AirPlayState, export_default$3 as AirPlayVolume, export_default$4 as AppleTV, PROTOCOL$1 as COMPANION_LINK, export_default$5 as CompanionLinkDevice, export_default$6 as HomePod, export_default$7 as HomePodMini, SendCommandError };