@basmilius/apple-sdk 0.11.0

package/dist/index.d.mts

@@ -0,0 +1,2583 @@
+/// <reference types="node" />
+import { EventEmitter } from "node:events";
+import * as _$_basmilius_apple_common0 from "@basmilius/apple-common";
+import { AccessoryCredentials, AccessoryCredentials as AccessoryCredentials$1, AudioSource, CommandError, DeviceIdentity, DiscoveryResult, DiscoveryResult as DiscoveryResult$1, Storage, TimingServer, TimingServer as TimingServer$1 } from "@basmilius/apple-common";
+import { Proto, Proto as Proto$1, Protocol } from "@basmilius/apple-airplay";
+import { AttentionState, AttentionState as AttentionState$1, ButtonPressType, HidCommandKey, LaunchableApp, MediaControlCommandKey, Protocol as Protocol$1, TextInputState, TextInputState as TextInputState$1, UserAccount } from "@basmilius/apple-companion-link";
+
+//#region src/internal/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$1.SendError_Enum;
+  /**
+   * The handler return status reported by the Apple TV.
+   */
+  readonly handlerReturnStatus: Proto$1.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$1.SendError_Enum, handlerReturnStatus: Proto$1.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 AirPlayRemote {
+  #private;
+  /**
+   * Creates a new Remote controller.
+   *
+   * @param device - The AirPlay device to control.
+   */
+  constructor(device: AirPlayManager);
+  /**
+   * 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$1.ShuffleMode_Enum): Promise<void>;
+  /**
+   * Sets the repeat mode.
+   *
+   * @param mode - The desired repeat mode.
+   */
+  commandSetRepeatMode(mode: Proto$1.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 a sleep timer that will stop playback after the specified duration.
+   * The timer works by attaching sleep timer options to a Pause command.
+   *
+   * @param seconds - Timer duration in seconds. Use 0 to cancel an active timer.
+   * @param stopMode - Stop mode: 0 = stop playback, 1 = pause, 2 = end of track, 3 = end of queue.
+   */
+  commandSetSleepTimer(seconds: number, stopMode?: number): 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/internal/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 AirPlayPlayer {
+  #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$1.NowPlayingInfo | null;
+  /**
+   * Current playback queue, or null if unavailable.
+   */
+  get playbackQueue(): Proto$1.PlaybackQueue | null;
+  /**
+   * Effective playback state.
+   */
+  get playbackState(): Proto$1.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$1.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$1.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$1.ShuffleMode_Enum;
+  /**
+   * Current repeat mode, derived from the ChangeRepeatMode command info.
+   */
+  get repeatMode(): Proto$1.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$1.ContentItem | null;
+  /**
+   * Metadata of the current content item, or null if no item is playing.
+   */
+  get currentItemMetadata(): Proto$1.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$1.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$1.Command): Proto$1.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$1.Command): boolean;
+  /**
+   * Updates the now-playing info for this player.
+   *
+   * @param nowPlayingInfo - The new now-playing info from the Apple TV.
+   */
+  setNowPlayingInfo(nowPlayingInfo: Proto$1.NowPlayingInfo): void;
+  /**
+   * Updates the playback queue for this player.
+   *
+   * @param playbackQueue - The new playback queue from the Apple TV.
+   */
+  setPlaybackQueue(playbackQueue: Proto$1.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$1.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$1.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$1.ContentItem): void;
+}
+//#endregion
+//#region src/internal/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 AirPlayClient {
+  #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, AirPlayPlayer>;
+  /**
+   * The currently active player, or null if none is active. Falls back to the default player.
+   */
+  get activePlayer(): AirPlayPlayer | null;
+  /**
+   * Now-playing info from the active player, or null.
+   */
+  get nowPlayingInfo(): Proto$1.NowPlayingInfo | null;
+  /**
+   * Playback queue from the active player, or null.
+   */
+  get playbackQueue(): Proto$1.PlaybackQueue | null;
+  /**
+   * Playback state from the active player, or Unknown.
+   */
+  get playbackState(): Proto$1.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$1.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$1.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$1.ShuffleMode_Enum;
+  /**
+   * Current repeat mode from the active player.
+   */
+  get repeatMode(): Proto$1.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$1.ContentItem | null;
+  /**
+   * Metadata of the current content item from the active player.
+   */
+  get currentItemMetadata(): Proto$1.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$1.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): AirPlayPlayer;
+  /**
+   * 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$1.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$1.Command): Proto$1.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$1.Command): boolean;
+  /**
+   * Updates the display name for this client.
+   *
+   * @param displayName - The new display name.
+   */
+  updateDisplayName(displayName: string): void;
+}
+//#endregion
+//#region src/internal/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;
+/**
+ * Symbol used to access the underlying Companion Link Protocol instance from a CompanionLinkManager.
+ */
+declare const COMPANION_LINK_PROTOCOL: unique symbol;
+//#endregion
+//#region src/internal/airplay-state.d.ts
+/**
+ * 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$3 = {
+  readonly clients: [Record<string, AirPlayClient>];
+  readonly configureConnection: [Proto$1.ConfigureConnectionMessage];
+  readonly deviceInfo: [Proto$1.DeviceInfoMessage];
+  readonly deviceInfoUpdate: [Proto$1.DeviceInfoMessage];
+  readonly keyboard: [Proto$1.KeyboardMessage];
+  readonly nowPlayingChanged: [client: AirPlayClient | null, player: AirPlayPlayer | null];
+  readonly originClientProperties: [Proto$1.OriginClientPropertiesMessage];
+  readonly playerClientProperties: [Proto$1.PlayerClientPropertiesMessage];
+  readonly removeClient: [Proto$1.RemoveClientMessage];
+  readonly removePlayer: [Proto$1.RemovePlayerMessage];
+  readonly sendCommandResult: [Proto$1.SendCommandResultMessage];
+  readonly setArtwork: [Proto$1.SetArtworkMessage];
+  readonly setDefaultSupportedCommands: [Proto$1.SetDefaultSupportedCommandsMessage];
+  readonly setNowPlayingClient: [Proto$1.SetNowPlayingClientMessage];
+  readonly setNowPlayingPlayer: [Proto$1.SetNowPlayingPlayerMessage];
+  readonly setState: [Proto$1.SetStateMessage];
+  readonly updateClient: [Proto$1.UpdateClientMessage];
+  readonly updateContentItem: [Proto$1.UpdateContentItemMessage];
+  readonly updateContentItemArtwork: [Proto$1.UpdateContentItemArtworkMessage];
+  readonly updatePlayer: [Proto$1.UpdatePlayerMessage];
+  readonly updateOutputDevice: [Proto$1.UpdateOutputDeviceMessage];
+  readonly volumeControlAvailability: [boolean, Proto$1.VolumeCapabilities_Enum];
+  readonly volumeControlCapabilitiesDidChange: [boolean, Proto$1.VolumeCapabilities_Enum];
+  readonly volumeDidChange: [number];
+  readonly volumeMutedDidChange: [boolean];
+  readonly activePlayerChanged: [client: AirPlayClient | null, player: AirPlayPlayer | null];
+  readonly artworkChanged: [client: AirPlayClient, player: AirPlayPlayer];
+  readonly lyricsEvent: [event: Proto$1.LyricsEvent, playerPath: Proto$1.PlayerPath | undefined];
+  readonly playbackQueueChanged: [client: AirPlayClient, player: AirPlayPlayer];
+  readonly playbackStateChanged: [client: AirPlayClient, player: AirPlayPlayer, oldState: Proto$1.PlaybackState_Enum, newState: Proto$1.PlaybackState_Enum];
+  readonly supportedCommandsChanged: [client: AirPlayClient, player: AirPlayPlayer, commands: Proto$1.CommandInfo[]];
+  readonly clusterChanged: [clusterID: string | null, isLeader: boolean];
+  readonly playerClientParticipantsUpdate: [Proto$1.PlayerClientParticipantsUpdateMessage];
+};
+/**
+ * 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 AirPlayState extends EventEmitter<EventMap$3> {
+  #private;
+  /**
+   * All known clients (apps) keyed by bundle identifier.
+   */
+  get clients(): Record<string, AirPlayClient>;
+  /**
+   * 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$1.TextEditingAttributes | null;
+  /**
+   * Current keyboard state enum value.
+   */
+  get keyboardState(): Proto$1.KeyboardState_Enum;
+  /**
+   * The currently active now-playing client, or null if nothing is playing.
+   */
+  get nowPlayingClient(): AirPlayClient | 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$1.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 playback queue participants (e.g. SharePlay users).
+   */
+  get participants(): Proto$1.PlaybackQueueParticipant[];
+  /**
+   * Raw JPEG artwork data from the last SET_ARTWORK_MESSAGE, or null.
+   */
+  get artworkJpegData(): Uint8Array | null;
+  /**
+   * 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$1.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: AirPlayManager);
+  /**
+   * 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$1.ConfigureConnectionMessage): void;
+  /**
+   * Handles keyboard state changes. Updates internal state and emits 'keyboard'.
+   *
+   * @param message - The keyboard message with state and attributes.
+   */
+  onKeyboard(message: Proto$1.KeyboardMessage): void;
+  /**
+   * Handles initial device info. Updates output device UID and cluster info.
+   *
+   * @param message - The device info message.
+   */
+  onDeviceInfo(message: Proto$1.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$1.DeviceInfoMessage): void;
+  /**
+   * Handles origin client properties updates.
+   *
+   * @param message - The origin client properties message.
+   */
+  onOriginClientProperties(message: Proto$1.OriginClientPropertiesMessage): void;
+  /**
+   * Handles player client properties updates.
+   *
+   * @param message - The player client properties message.
+   */
+  onPlayerClientProperties(message: Proto$1.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$1.RemoveClientMessage): void;
+  /**
+   * Handles command result notifications from the Apple TV.
+   *
+   * @param message - The send command result message.
+   */
+  onSendCommandResult(message: Proto$1.SendCommandResultMessage): void;
+  /**
+   * Handles lyrics events (time-synced lyrics updates).
+   *
+   * @param message - The lyrics event message.
+   */
+  onSendLyricsEvent(message: Proto$1.SendLyricsEventMessage): void;
+  /**
+   * Handles artwork set notifications.
+   *
+   * @param message - The set artwork message.
+   */
+  onSetArtwork(message: Proto$1.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$1.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$1.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$1.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$1.SetStateMessage): void;
+  /**
+   * Handles content item updates (metadata, artwork, lyrics changes for existing items).
+   *
+   * @param message - The update content item message.
+   */
+  onUpdateContentItem(message: Proto$1.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$1.UpdateContentItemArtworkMessage): void;
+  /**
+   * Handles player registration or update. Creates the player if it does not exist.
+   *
+   * @param message - The update player message.
+   */
+  onUpdatePlayer(message: Proto$1.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$1.RemovePlayerMessage): void;
+  /**
+   * Handles client (app) registration or display name update.
+   *
+   * @param message - The update client message.
+   */
+  onUpdateClient(message: Proto$1.UpdateClientMessage): void;
+  /**
+   * Handles output device list updates. Prefers cluster-aware devices when available.
+   *
+   * @param message - The update output device message.
+   */
+  /**
+   * Handles playback queue participant updates (e.g. SharePlay users).
+   *
+   * @param message - The participants update message.
+   */
+  onPlayerClientParticipantsUpdate(message: Proto$1.PlayerClientParticipantsUpdateMessage): void;
+  onUpdateOutputDevice(message: Proto$1.UpdateOutputDeviceMessage): void;
+  /**
+   * Handles volume control availability changes.
+   *
+   * @param message - The volume control availability message.
+   */
+  onVolumeControlAvailability(message: Proto$1.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$1.VolumeControlCapabilitiesDidChangeMessage): void;
+  /**
+   * Handles volume level changes.
+   *
+   * @param message - The volume change message.
+   */
+  onVolumeDidChange(message: Proto$1.VolumeDidChangeMessage): void;
+  /**
+   * Handles mute state changes.
+   *
+   * @param message - The volume muted change message.
+   */
+  onVolumeMutedDidChange(message: Proto$1.VolumeMutedDidChangeMessage): void;
+}
+//#endregion
+//#region src/internal/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 AirPlayVolume {
+  #private;
+  /**
+   * Creates a new Volume controller.
+   *
+   * @param device - The AirPlay device to control volume for.
+   */
+  constructor(device: AirPlayManager);
+  /**
+   * 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>;
+  /**
+   * Mutes the output device.
+   *
+   * @throws CommandError when no output device is active.
+   */
+  mute(): Promise<void>;
+  /**
+   * Unmutes the output device.
+   *
+   * @throws CommandError when no output device is active.
+   */
+  unmute(): Promise<void>;
+  /**
+   * Toggles the mute state of the output device.
+   *
+   * @throws CommandError when no output device is active.
+   */
+  toggleMute(): Promise<void>;
+  /**
+   * Sets the volume for a specific output device in a speaker group.
+   * Use this to control individual speakers when multiple devices are grouped.
+   *
+   * @param outputDeviceUID - The unique identifier of the target output device.
+   * @param volume - The desired volume level (clamped to 0.0 - 1.0).
+   */
+  setForDevice(outputDeviceUID: string, volume: number): Promise<void>;
+  /**
+   * Fetches the volume for a specific output device in a speaker group.
+   *
+   * @param outputDeviceUID - The unique identifier of the target output device.
+   * @returns The volume level as a float between 0.0 and 1.0.
+   */
+  getForDevice(outputDeviceUID: string): Promise<number>;
+  /**
+   * Mutes a specific output device in a speaker group.
+   *
+   * @param outputDeviceUID - The unique identifier of the target output device.
+   */
+  muteDevice(outputDeviceUID: string): Promise<void>;
+  /**
+   * Unmutes a specific output device in a speaker group.
+   *
+   * @param outputDeviceUID - The unique identifier of the target output device.
+   */
+  unmuteDevice(outputDeviceUID: string): Promise<void>;
+  /**
+   * Adjusts the volume by a relative increment/decrement on a specific output device.
+   * This is the method Apple uses internally in Music.app for volume changes.
+   *
+   * @param adjustment - The volume adjustment to apply (IncrementSmall/Medium/Large, DecrementSmall/Medium/Large).
+   * @param outputDeviceUID - Optional UID of the target output device. Defaults to the active device.
+   */
+  adjust(adjustment: Proto$1.AdjustVolumeMessage_Adjustment, outputDeviceUID?: string): Promise<void>;
+  /**
+   * Smoothly fades the volume to a target level over a given duration.
+   * Uses linear interpolation with absolute volume set calls.
+   *
+   * @param targetVolume - The target volume level (0.0 - 1.0).
+   * @param durationMs - The fade duration in milliseconds.
+   * @throws CommandError when absolute volume control is not available.
+   */
+  fade(targetVolume: number, durationMs: number): Promise<void>;
+}
+//#endregion
+//#region src/internal/airplay-manager.d.ts
+/**
+ * Events emitted by AirPlayDevice.
+ * - `connected` — emitted after the full protocol setup completes.
+ * - `disconnected` — emitted when the connection is lost or explicitly closed.
+ */
+type EventMap$2 = {
+  connected: [];
+  disconnected: [unexpected: boolean];
+};
+/**
+ * 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 AirPlayManager extends EventEmitter<EventMap$2> {
+  #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$1;
+  /**
+   * Updates the discovery result, e.g. when the device's address changes.
+   */
+  set discoveryResult(discoveryResult: DiscoveryResult$1);
+  /**
+   * 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 Artwork controller for fetching now-playing artwork from all sources.
+   */
+  get artwork(): AirPlayArtwork;
+  /**
+   * The Remote controller for HID keys, SendCommand, text input, and touch.
+   */
+  get remote(): AirPlayRemote;
+  /**
+   * The State tracker for now-playing, volume, keyboard, and output device state.
+   */
+  get state(): AirPlayState;
+  /**
+   * The Volume controller for absolute and relative volume adjustments.
+   */
+  get volume(): AirPlayVolume;
+  /**
+   * The shared PTP timing server, if one is assigned for multi-room sync.
+   */
+  get timingServer(): TimingServer$1 | undefined;
+  /**
+   * Assigns a PTP timing server for multi-room audio synchronization.
+   */
+  set timingServer(timingServer: TimingServer$1 | undefined);
+  /**
+   * 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$1, 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.
+   * Creates a separate Protocol instance to avoid conflicting with the
+   * existing remote control session, following the same approach as playUrl.
+   *
+   * @param source - The audio source to stream (e.g. MP3, WAV, URL, live).
+   */
+  streamAudio(source: AudioSource): Promise<void>;
+  /**
+   * Stops the current audio stream and cleans up the dedicated stream protocol.
+   */
+  stopStreamAudio(): void;
+  /**
+   * Sets the audio listening mode on the device (HomePod).
+   *
+   * @param mode - Listening mode string (e.g. 'Default', 'Vivid', 'LateNight').
+   */
+  setListeningMode(mode: string): Promise<void>;
+  /**
+   * Sets the audio routing mode on the receiver via the control stream.
+   *
+   * @param mode - Audio mode (e.g. 'default', 'moviePlayback', 'spoken').
+   */
+  setAudioMode(mode: string): Promise<void>;
+  /**
+   * Triggers an audio fade on the device.
+   *
+   * @param fadeType - The fade type (0 = fade out, 1 = fade in).
+   */
+  audioFade(fadeType: number): Promise<void>;
+  /**
+   * Wakes the device from sleep via the DataStream.
+   */
+  wake(): 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$1.Command, options?: Proto$1.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$1): 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 now-playing changes to auto-fetch artwork on track changes.
+   */
+  onNowPlayingChanged(_client: any, player: any): void;
+  /**
+   * Handles stream timeout events by destroying the control stream.
+   */
+  onTimeout(): void;
+}
+//#endregion
+//#region src/internal/airplay-artwork.d.ts
+/**
+ * Artwork result from the unified artwork API.
+ * Always contains at least one of `url` or `data`.
+ */
+type ArtworkResult = {
+  /**
+   * Direct URL to the artwork image (preferred for web/UI rendering).
+   */
+  readonly url: string | null;
+  /**
+   * Raw image bytes (available when artwork is embedded or fetched from playback queue).
+   */
+  readonly data: Uint8Array | null;
+  /**
+   * MIME type of the artwork (e.g. 'image/jpeg', 'image/png').
+   */
+  readonly mimeType: string;
+  /**
+   * The artwork identifier used for change detection.
+   */
+  readonly identifier: string | null;
+  /**
+   * Width of the artwork in pixels (0 if unknown).
+   */
+  readonly width: number;
+  /**
+   * Height of the artwork in pixels (0 if unknown).
+   */
+  readonly height: number;
+};
+/**
+ * Unified artwork controller for an AirPlay device.
+ *
+ * Provides a single `get()` method that resolves artwork from all available
+ * sources in priority order:
+ * 1. URL from now-playing metadata (artworkURL, remoteArtworks, template)
+ * 2. Inline binary data from the playback queue (artworkData, dataArtworks)
+ * 3. JPEG data from SET_ARTWORK_MESSAGE
+ * 4. Fetches the playback queue if artwork is expected but not yet available
+ */
+declare class AirPlayArtwork {
+  #private;
+  constructor(device: AirPlayManager);
+  /**
+   * Gets the current artwork for the active now-playing item.
+   *
+   * Tries all available sources in priority order and returns a unified result.
+   * Results are cached by artwork identifier — subsequent calls for the same
+   * track return the cached result without additional requests.
+   *
+   * @param width - Desired artwork width in pixels (default: 600).
+   * @param height - Desired artwork height in pixels (-1 for proportional).
+   * @returns The artwork result, or null if no artwork is available.
+   */
+  get(width?: number, height?: number): Promise<ArtworkResult | null>;
+  /**
+   * Clears the cached artwork, forcing a fresh fetch on the next `get()` call.
+   */
+  clear(): void;
+}
+//#endregion
+//#region src/internal/companion-link-state.d.ts
+/**
+ * Events emitted by CompanionLinkState.
+ * Provides reactive state updates from the Companion Link protocol.
+ */
+type EventMap$1 = {
+  readonly attentionStateChanged: [AttentionState$1];
+  readonly mediaControlFlagsChanged: [flags: number, capabilities: MediaCapabilities];
+  readonly nowPlayingInfoChanged: [info: Record<string, unknown> | null];
+  readonly supportedActionsChanged: [actions: Record<string, unknown>];
+  readonly textInputChanged: [TextInputState$1];
+  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$1> {
+  #private;
+  /**
+   * Current attention state of the device (active, idle, screensaver, etc.).
+   */
+  get attentionState(): AttentionState$1;
+  /**
+   * 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$1;
+  /**
+   * 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/internal/companion-link-manager.d.ts
+/**
+ * Events emitted by CompanionLinkDevice.
+ * Forwards state change events from CompanionLinkState for convenience.
+ */
+type EventMap = {
+  connected: [];
+  disconnected: [unexpected: boolean];
+  attentionStateChanged: [AttentionState$1];
+  mediaControlFlagsChanged: [flags: number, capabilities: MediaCapabilities];
+  nowPlayingInfoChanged: [info: Record<string, unknown> | null];
+  supportedActionsChanged: [actions: Record<string, unknown>];
+  textInputChanged: [TextInputState$1];
+  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 CompanionLinkManager extends EventEmitter<EventMap> {
+  #private;
+  /**
+   * @returns The underlying Companion Link Protocol instance (accessed via symbol for internal use).
+   */
+  get [COMPANION_LINK_PROTOCOL](): Protocol$1;
+  /**
+   * The mDNS discovery result used to connect to this device.
+   */
+  get discoveryResult(): DiscoveryResult$1;
+  /**
+   * Updates the discovery result, e.g. when the device's address changes.
+   */
+  set discoveryResult(discoveryResult: DiscoveryResult$1);
+  /**
+   * 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$1;
+  /**
+   * Creates a new CompanionLinkDevice.
+   *
+   * @param discoveryResult - The mDNS discovery result for the target device.
+   */
+  constructor(discoveryResult: DiscoveryResult$1);
+  /**
+   * 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$1): Promise<void>;
+  /**
+   * Fetches the current attention state of the device (active, idle, screensaver, etc.).
+   *
+   * @returns The current attention state.
+   */
+  getAttentionState(): Promise<AttentionState$1>;
+  /**
+   * 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>;
+  /**
+   * 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>;
+  /**
+   * 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/controller/accounts.d.ts
+/**
+ * User account controller for Apple TV devices.
+ * Provides user account listing and switching.
+ */
+declare class AccountsController {
+  #private;
+  constructor(companionLink: CompanionLinkManager);
+  /**
+   * Returns the list of user accounts configured on the device.
+   */
+  list(): Promise<UserAccount[]>;
+  /**
+   * Switches to a different user account.
+   *
+   * @param accountId - The account ID to switch to.
+   */
+  switch(accountId: string): Promise<void>;
+}
+//#endregion
+//#region src/controller/apps.d.ts
+/**
+ * App management controller for Apple TV devices.
+ * Provides app launching and URL opening.
+ */
+declare class AppsController {
+  #private;
+  constructor(companionLink: CompanionLinkManager);
+  /**
+   * Returns the list of apps that can be launched on the device.
+   */
+  list(): Promise<LaunchableApp[]>;
+  /**
+   * Launches an app by its bundle identifier.
+   *
+   * @param bundleId - The bundle identifier (e.g. 'com.netflix.Netflix').
+   */
+  launch(bundleId: string): Promise<void>;
+  /**
+   * Opens a URL on the device (universal link or app-specific URL scheme).
+   *
+   * @param url - The URL to open.
+   */
+  openUrl(url: string): Promise<void>;
+}
+//#endregion
+//#region src/controller/artwork.d.ts
+/**
+ * Artwork controller for Apple devices.
+ * Resolves artwork from all available sources with a 4-tier fallback.
+ */
+declare class ArtworkController {
+  #private;
+  constructor(airplay: AirPlayManager);
+  /**
+   * Gets the current artwork for the active now-playing item.
+   *
+   * @param width - Desired width in pixels (default: 600).
+   * @param height - Desired height in pixels (-1 for proportional).
+   * @returns Artwork result with url, data, or both.
+   */
+  get(width?: number, height?: number): Promise<ArtworkResult | null>;
+}
+//#endregion
+//#region src/controller/keyboard.d.ts
+/**
+ * Text input controller for Apple TV devices.
+ * Provides keyboard control when a text field is active on the device.
+ */
+declare class KeyboardController {
+  #private;
+  constructor(airplay: AirPlayManager);
+  /**
+   * Sets the text input field to the given text, replacing any existing content.
+   */
+  type(text: string): Promise<void>;
+  /**
+   * Appends text to the current text input field content.
+   */
+  append(text: string): Promise<void>;
+  /**
+   * Clears the text input field.
+   */
+  clear(): Promise<void>;
+  /**
+   * Fetches the current keyboard session state.
+   */
+  getSession(): Promise<any>;
+}
+//#endregion
+//#region src/controller/media.d.ts
+/**
+ * Media source controller for Apple devices.
+ * Provides URL playback (device fetches and plays) and audio streaming (client sends PCM via RTP).
+ */
+declare class MediaController {
+  #private;
+  constructor(airplay: AirPlayManager);
+  /**
+   * Plays a URL on the device. The device fetches and plays the content.
+   * Creates a separate protocol session to avoid conflicting with remote control.
+   *
+   * @param url - The media URL to play.
+   * @param position - Start position in seconds (default: 0).
+   */
+  playUrl(url: string, position?: number): Promise<void>;
+  /**
+   * Stops the current URL playback.
+   */
+  stopPlayUrl(): void;
+  /**
+   * Waits for the current URL playback to end naturally.
+   */
+  waitForPlaybackEnd(): Promise<void>;
+  /**
+   * Streams audio from a source to the device via RAOP/RTP.
+   * Creates a separate protocol session to avoid conflicting with remote control.
+   *
+   * @param source - The audio source to stream (MP3, OGG, WAV, PCM, FFmpeg, URL, live).
+   */
+  streamAudio(source: AudioSource): Promise<void>;
+  /**
+   * Stops the current audio stream.
+   */
+  stopStreamAudio(): void;
+  /**
+   * Requests lyrics for the current playback.
+   *
+   * @param length - Maximum number of lyrics items to retrieve.
+   */
+  requestLyrics(length?: number): Promise<void>;
+}
+//#endregion
+//#region src/controller/multiroom.d.ts
+/**
+ * Multi-room / cluster controller for Apple devices.
+ * Manages output device groups for multi-room audio.
+ */
+declare class MultiroomController {
+  #private;
+  constructor(airplay: AirPlayManager);
+  /**
+   * The cluster ID if the device is part of a multi-room group, or null.
+   */
+  get clusterId(): string | null;
+  /**
+   * Whether this device is the leader of its multi-room cluster.
+   */
+  get isLeader(): boolean;
+  /**
+   * Whether this device is aware of cluster functionality.
+   */
+  get isClusterAware(): boolean;
+  /**
+   * Adds devices to the current multi-room output context.
+   *
+   * @param deviceUIDs - UIDs of devices to add.
+   */
+  addDevice(...deviceUIDs: string[]): Promise<void>;
+  /**
+   * Removes devices from the current multi-room output context.
+   *
+   * @param deviceUIDs - UIDs of devices to remove.
+   */
+  removeDevice(...deviceUIDs: string[]): Promise<void>;
+  /**
+   * Replaces the entire multi-room output context.
+   *
+   * @param deviceUIDs - UIDs of devices to set as the output context.
+   */
+  setDevices(...deviceUIDs: string[]): Promise<void>;
+}
+//#endregion
+//#region src/controller/playback.d.ts
+/**
+ * Media playback controller for Apple devices.
+ * Provides play/pause/next/seek and other media commands via SendCommand (MRP protocol).
+ */
+declare class PlaybackController {
+  #private;
+  constructor(airplay: AirPlayManager);
+  play(): Promise<void>;
+  pause(): Promise<void>;
+  playPause(): Promise<void>;
+  stop(): Promise<void>;
+  next(): Promise<void>;
+  previous(): Promise<void>;
+  skipForward(seconds?: number): Promise<void>;
+  skipBackward(seconds?: number): Promise<void>;
+  seekTo(position: number): Promise<void>;
+  setShuffleMode(mode: Proto$1.ShuffleMode_Enum): Promise<void>;
+  setRepeatMode(mode: Proto$1.RepeatMode_Enum): Promise<void>;
+  advanceShuffleMode(): Promise<void>;
+  advanceRepeatMode(): Promise<void>;
+  setPlaybackRate(rate: number): Promise<void>;
+  setSleepTimer(seconds: number, stopMode?: number): Promise<void>;
+  beginFastForward(): Promise<void>;
+  endFastForward(): Promise<void>;
+  beginRewind(): Promise<void>;
+  endRewind(): Promise<void>;
+  nextChapter(): Promise<void>;
+  previousChapter(): Promise<void>;
+  likeTrack(): Promise<void>;
+  dislikeTrack(): Promise<void>;
+  bookmarkTrack(): Promise<void>;
+  addToLibrary(): Promise<void>;
+  /**
+   * Requests the playback queue from the device (includes artwork and metadata).
+   *
+   * @param length - Maximum number of queue items to retrieve (default: 1).
+   */
+  requestPlaybackQueue(length?: number): Promise<void>;
+  /**
+   * Checks whether a playback command is currently supported by the active media app.
+   */
+  isCommandSupported(command: Proto$1.Command): boolean;
+}
+//#endregion
+//#region src/controller/power.d.ts
+/**
+ * Power management controller for Apple TV devices.
+ * Provides power on/off and attention state queries.
+ */
+declare class PowerController {
+  #private;
+  constructor(airplay: AirPlayManager, companionLink: CompanionLinkManager);
+  /**
+   * Turns on the device (sends wake HID key).
+   */
+  on(): Promise<void>;
+  /**
+   * Turns off the device (sends suspend HID key).
+   */
+  off(): Promise<void>;
+  /**
+   * Gets the current attention state of the device.
+   *
+   * @returns The attention state ('active', 'idle', 'screensaver', etc.).
+   */
+  getState(): Promise<AttentionState$1>;
+}
+//#endregion
+//#region src/controller/remote.d.ts
+/**
+ * Remote controller for Apple devices.
+ * Provides all HID-based keys (navigation, media, volume, power),
+ * touch/swipe gestures, and low-level HID primitives.
+ */
+declare class RemoteController {
+  #private;
+  constructor(airplay: AirPlayManager);
+  up(): Promise<void>;
+  down(): Promise<void>;
+  left(): Promise<void>;
+  right(): Promise<void>;
+  select(): Promise<void>;
+  menu(): Promise<void>;
+  home(): Promise<void>;
+  topMenu(): Promise<void>;
+  play(): Promise<void>;
+  pause(): Promise<void>;
+  playPause(): Promise<void>;
+  stop(): Promise<void>;
+  next(): Promise<void>;
+  previous(): Promise<void>;
+  channelUp(): Promise<void>;
+  channelDown(): Promise<void>;
+  volumeUp(): Promise<void>;
+  volumeDown(): Promise<void>;
+  mute(): Promise<void>;
+  wake(): Promise<void>;
+  suspend(): Promise<void>;
+  tap(x: number, y: number, finger?: number): Promise<void>;
+  swipe(direction: 'up' | 'down' | 'left' | 'right', duration?: number): Promise<void>;
+  pressAndRelease(usePage: number, usage: number): Promise<void>;
+  longPress(usePage: number, usage: number, duration?: number): Promise<void>;
+  doublePress(usePage: number, usage: number): Promise<void>;
+}
+//#endregion
+//#region src/types.d.ts
+/**
+ * Device type identifier used in discovery results.
+ */
+type DeviceType = 'appletv' | 'homepod' | 'homepod-mini' | 'unknown';
+/**
+ * Device-level events shared by all device types.
+ */
+type DeviceEventMap = {
+  connected: [];
+  disconnected: [unexpected: boolean];
+  recovering: [attempt: number];
+  recoveryFailed: [];
+};
+/**
+ * Additional events emitted by Apple TV devices.
+ */
+type AppleTVEventMap = DeviceEventMap & {
+  power: [state: AttentionState$1];
+  textInput: [state: TextInputState$1];
+};
+/**
+ * Events emitted by the state controller.
+ */
+type StateEventMap = {
+  nowPlayingChanged: [client: AirPlayClient | null, player: AirPlayPlayer | null];
+  playbackStateChanged: [client: AirPlayClient, player: AirPlayPlayer, oldState: Proto$1.PlaybackState_Enum, newState: Proto$1.PlaybackState_Enum];
+  volumeChanged: [volume: number];
+  volumeMutedChanged: [muted: boolean];
+  artworkChanged: [client: AirPlayClient, player: AirPlayPlayer];
+  activeAppChanged: [bundleIdentifier: string | null, displayName: string | null];
+  supportedCommandsChanged: [client: AirPlayClient, player: AirPlayPlayer, commands: Proto$1.CommandInfo[]];
+  clusterChanged: [clusterId: string | null, isLeader: boolean];
+};
+/**
+ * Connection recovery options.
+ */
+type RecoveryOptions = {
+  /**
+   * Maximum number of reconnection attempts. Default: 3.
+   */
+  readonly maxAttempts?: number;
+  /**
+   * Base delay in milliseconds for exponential backoff. Default: 1000.
+   */
+  readonly baseDelay?: number;
+  /**
+   * Interval in milliseconds between periodic reconnection attempts. 0 = disabled. Default: 900000 (15 min).
+   */
+  readonly reconnectInterval?: number;
+};
+/**
+ * Options passed to device.connect().
+ */
+type ConnectOptions = {
+  /**
+   * Connection recovery configuration. Set to false to disable recovery.
+   */
+  readonly recovery?: RecoveryOptions | false;
+};
+/**
+ * Device construction options.
+ */
+type DeviceOptions = {
+  /**
+   * IP address of the device.
+   */
+  readonly address?: string;
+  /**
+   * Pre-discovered AirPlay service result.
+   */
+  readonly airplay?: _$_basmilius_apple_common0.DiscoveryResult;
+  /**
+   * Pre-discovered Companion Link service result (Apple TV only).
+   */
+  readonly companionLink?: _$_basmilius_apple_common0.DiscoveryResult;
+  /**
+   * Custom device identity to present during pairing.
+   */
+  readonly identity?: Partial<_$_basmilius_apple_common0.DeviceIdentity>;
+  /**
+   * Timing server for multi-room / audio streaming.
+   */
+  readonly timingServer?: _$_basmilius_apple_common0.TimingServer;
+};
+//#endregion
+//#region src/controller/state.d.ts
+/**
+ * Now-playing state controller.
+ * Provides read-only getters for the current playback state and emits
+ * typed events when state changes occur.
+ */
+declare class StateController extends EventEmitter<StateEventMap> {
+  #private;
+  constructor(airplay: AirPlayManager);
+  get title(): string;
+  get artist(): string;
+  get album(): string;
+  get genre(): string;
+  get duration(): number;
+  get elapsedTime(): number;
+  get playbackRate(): number;
+  get isPlaying(): boolean;
+  get playbackState(): Proto$1.PlaybackState_Enum | undefined;
+  get mediaType(): Proto$1.ContentItemMetadata_MediaType | undefined;
+  get shuffleMode(): Proto$1.ShuffleMode_Enum | undefined;
+  get repeatMode(): Proto$1.RepeatMode_Enum | undefined;
+  get activeApp(): {
+    bundleIdentifier: string;
+    displayName: string;
+  } | null;
+  get volume(): number;
+  get isMuted(): boolean;
+  get volumeAvailable(): boolean;
+  get isKeyboardActive(): boolean;
+  get clusterId(): string | null;
+  get isClusterLeader(): boolean;
+  get outputDevices(): Proto$1.AVOutputDeviceDescriptor[];
+  get clients(): Record<string, AirPlayClient>;
+  get activeClient(): AirPlayClient | null;
+  get activePlayer(): AirPlayPlayer | null;
+  isCommandSupported(command: Proto$1.Command): boolean;
+  getCommandInfo(command: Proto$1.Command): Proto$1.CommandInfo | null;
+  /**
+   * Subscribes to the underlying AirPlayState events and re-emits them.
+   * Called internally by the device after connection is established.
+   * @internal
+   */
+  subscribe(): void;
+  /**
+   * Removes all event listeners from this controller.
+   * @internal
+   */
+  unsubscribe(): void;
+}
+//#endregion
+//#region src/controller/system.d.ts
+/**
+ * System controller for Apple TV devices.
+ * Provides access to captions, appearance, Siri, and Up Next queue.
+ */
+declare class SystemController {
+  #private;
+  constructor(companionLink: CompanionLinkManager);
+  /**
+   * Toggles closed captions on the device.
+   */
+  toggleCaptions(): Promise<void>;
+  /**
+   * Sets the system appearance.
+   *
+   * @param mode - 'light' or 'dark'.
+   */
+  setAppearance(mode: 'light' | 'dark'): Promise<void>;
+  /**
+   * Enables or disables the "Reduce Loud Sounds" setting.
+   */
+  setReduceLoudSounds(enabled: boolean): Promise<void>;
+  /**
+   * Enables or disables Find My mode.
+   */
+  setFindingMode(enabled: boolean): Promise<void>;
+  /**
+   * Starts a Siri session.
+   */
+  siriStart(): Promise<void>;
+  /**
+   * Stops the active Siri session.
+   */
+  siriStop(): Promise<void>;
+  /**
+   * Fetches the Up Next queue.
+   *
+   * @param paginationToken - Optional token for paginated results.
+   */
+  fetchUpNext(paginationToken?: string): Promise<any>;
+  /**
+   * Adds an item to the Up Next queue.
+   */
+  addToUpNext(identifier: string, kind: string): Promise<void>;
+  /**
+   * Removes an item from the Up Next queue.
+   */
+  removeFromUpNext(identifier: string, kind: string): Promise<void>;
+}
+//#endregion
+//#region src/controller/volume.d.ts
+/**
+ * Volume controller for Apple devices.
+ * Supports absolute volume (set level), relative volume (up/down),
+ * muting, fading, and per-device volume in multi-room setups.
+ */
+declare class VolumeController {
+  #private;
+  constructor(airplay: AirPlayManager);
+  set(volume: number): Promise<void>;
+  get(): Promise<number>;
+  up(): Promise<void>;
+  down(): Promise<void>;
+  mute(): Promise<void>;
+  unmute(): Promise<void>;
+  toggleMute(): Promise<void>;
+  fade(targetVolume: number, durationMs: number): Promise<void>;
+  setForDevice(outputDeviceUID: string, volume: number): Promise<void>;
+  getForDevice(outputDeviceUID: string): Promise<number>;
+  muteDevice(outputDeviceUID: string): Promise<void>;
+  unmuteDevice(outputDeviceUID: string): Promise<void>;
+  adjust(adjustment: Proto$1.AdjustVolumeMessage_Adjustment, outputDeviceUID?: string): Promise<void>;
+}
+//#endregion
+//#region src/pairing/pairing-session.d.ts
+/**
+ * Step-based pairing session for Apple TV devices.
+ *
+ * Provides a three-phase pairing flow suitable for external UI frameworks
+ * (e.g., Homey's pairing wizard) where PIN entry happens asynchronously:
+ *
+ * ```ts
+ * const session = tv.createPairingSession();
+ * await session.start();              // Connects and triggers PIN dialog on TV
+ * await session.pin('1234');           // Submits PIN, executes M1-M6
+ * const credentials = await session.end();  // Returns credentials, cleans up
+ * ```
+ */
+declare class PairingSession {
+  #private;
+  constructor(discoveryResult: DiscoveryResult$1, identity?: Partial<DeviceIdentity>);
+  /**
+   * Connects to the device and triggers the PIN dialog.
+   * After this method returns, the Apple TV displays a 4-digit PIN on screen.
+   */
+  start(): Promise<void>;
+  /**
+   * Submits the PIN and executes the M1-M6 key exchange.
+   *
+   * @param code - The 4-digit PIN displayed on the Apple TV screen.
+   */
+  pin(code: string): Promise<void>;
+  /**
+   * Finishes the pairing session, cleans up the protocol connection,
+   * and returns the obtained credentials.
+   *
+   * @returns Long-term credentials for future connections.
+   */
+  end(): Promise<AccessoryCredentials$1>;
+  /**
+   * Aborts the pairing session and cleans up without returning credentials.
+   * Use this when the user cancels pairing.
+   */
+  abort(): void;
+}
+//#endregion
+//#region src/pairing/types.d.ts
+/**
+ * Options for the callback-based pair() convenience method.
+ */
+type PairingOptions = {
+  /**
+   * Callback invoked when the device displays a PIN code. Must return the PIN as a string.
+   */
+  readonly onPinRequired: () => Promise<string>;
+};
+/**
+ * Result of a successful pairing session.
+ */
+type PairingResult = AccessoryCredentials$1;
+//#endregion
+//#region src/device/device.d.ts
+/**
+ * Abstract base class for all Apple devices.
+ * Provides shared controllers and lifecycle management.
+ */
+declare abstract class AbstractDevice extends EventEmitter {
+  #private;
+  readonly remote: RemoteController;
+  readonly playback: PlaybackController;
+  readonly state: StateController;
+  readonly volume: VolumeController;
+  readonly artwork: ArtworkController;
+  readonly media: MediaController;
+  readonly multiroom: MultiroomController;
+  constructor(options: DeviceOptions);
+  /**
+   * The unique identifier of the device (from mDNS discovery).
+   */
+  get id(): string;
+  /**
+   * The human-readable name of the device.
+   */
+  get name(): string;
+  /**
+   * The IP address of the device.
+   */
+  get address(): string;
+  /**
+   * Whether the device is currently connected.
+   */
+  get isConnected(): boolean;
+  /**
+   * Raw receiver info from the AirPlay /info endpoint.
+   */
+  get receiverInfo(): Record<string, any> | undefined;
+  /**
+   * AirPlay device capabilities (features supported by the receiver).
+   */
+  get capabilities(): {
+    supportsAudio: boolean;
+    supportsBufferedAudio: boolean;
+    supportsPTP: boolean;
+    supportsRFC2198Redundancy: boolean;
+    supportsHangdogRemoteControl: boolean;
+    supportsUnifiedMediaControl: boolean;
+    supportsTransientPairing: boolean;
+    supportsSystemPairing: boolean;
+    supportsCoreUtilsPairing: boolean;
+  };
+  /**
+   * Updates the discovery result (e.g. when the device's IP address changes).
+   */
+  set discoveryResult(result: DiscoveryResult$1);
+  /**
+   * Updates the timing server for multi-room audio sync.
+   */
+  set timingServer(server: TimingServer$1 | undefined);
+  /**
+   * The underlying AirPlay protocol manager.
+   * Use this for low-level protocol access, raw state events, or features
+   * not covered by the high-level controllers.
+   */
+  get airplay(): AirPlayManager;
+  /**
+   * Creates a step-based pairing session for interactive PIN entry flows.
+   *
+   * ```ts
+   * const session = tv.createPairingSession();
+   * await session.start();           // Connects and triggers PIN dialog
+   * await session.pin('1234');        // Submits PIN, executes M1-M6
+   * const creds = await session.end(); // Returns credentials, cleans up
+   * ```
+   */
+  createPairingSession(): PairingSession;
+  /**
+   * Pairs with the device using a callback-based PIN flow.
+   * Convenience method that wraps createPairingSession().
+   *
+   * @param options - Pairing options with onPinRequired callback.
+   * @returns Long-term credentials for future connections.
+   */
+  pair(options: PairingOptions): Promise<AccessoryCredentials$1>;
+  /**
+   * Connects to the device.
+   *
+   * @param credentials - Pairing credentials. Required for Apple TV, ignored for HomePod.
+   */
+  abstract connect(credentials?: AccessoryCredentials$1): Promise<void>;
+  /**
+   * Disconnects from the device.
+   */
+  disconnect(): void;
+  /**
+   * Called when AirPlay connects successfully. Override for additional setup.
+   */
+  protected onAirPlayConnected(): void;
+  /**
+   * Called when AirPlay disconnects. Override for additional cleanup.
+   */
+  protected onAirPlayDisconnected(unexpected: boolean): void;
+}
+//#endregion
+//#region src/device/apple-tv.d.ts
+/**
+ * Options specific to Apple TV devices.
+ */
+type AppleTVOptions = DeviceOptions & {
+  /**
+   * Pre-discovered Companion Link service result.
+   */
+  readonly companionLink?: DiscoveryResult$1;
+};
+/**
+ * High-level Apple TV device combining AirPlay and Companion Link protocols.
+ * Provides remote control, media playback, app launching, keyboard input,
+ * power management, and system settings.
+ *
+ * ```ts
+ * const tv = new AppleTV({ airplay: result, companionLink: clResult });
+ *
+ * // First time — pair
+ * const session = tv.createPairingSession();
+ * await session.start();
+ * await session.pin('1234');
+ * const credentials = await session.end();
+ *
+ * // Connect with credentials
+ * await tv.connect(credentials);
+ * await tv.playback.play();
+ * ```
+ */
+declare class AppleTV extends AbstractDevice {
+  #private;
+  readonly accounts: AccountsController | undefined;
+  readonly apps: AppsController | undefined;
+  readonly keyboard: KeyboardController;
+  readonly power: PowerController | undefined;
+  readonly system: SystemController | undefined;
+  constructor(options: AppleTVOptions);
+  /**
+   * The underlying Companion Link protocol manager, or undefined if no
+   * Companion Link discovery result was provided.
+   * Use this for low-level protocol access or features not covered by controllers.
+   */
+  get companionLink(): CompanionLinkManager | undefined;
+  get isConnected(): boolean;
+  /**
+   * Connects to the Apple TV using AirPlay and (optionally) Companion Link.
+   *
+   * @param credentials - Pairing credentials from pair-setup.
+   */
+  connect(credentials: AccessoryCredentials$1): Promise<void>;
+  disconnect(): void;
+  protected onAirPlayConnected(): void;
+  protected onAirPlayDisconnected(unexpected: boolean): void;
+}
+//#endregion
+//#region src/device/homepod.d.ts
+/**
+ * High-level HomePod device using AirPlay only (transient pairing).
+ * Provides media playback, URL playback, audio streaming, and volume control.
+ * No credentials needed — transient pairing is handled transparently.
+ *
+ * ```ts
+ * const pod = new HomePod({ airplay: result });
+ * await pod.connect();
+ * await pod.media.playUrl('https://example.com/song.mp3');
+ * ```
+ */
+declare class HomePod extends AbstractDevice {
+  constructor(options: DeviceOptions);
+  /**
+   * Connects to the HomePod using transient pairing (no credentials needed).
+   */
+  connect(): Promise<void>;
+  protected onAirPlayConnected(): void;
+  protected onAirPlayDisconnected(unexpected: boolean): void;
+}
+//#endregion
+//#region src/device/homepod-mini.d.ts
+/**
+ * High-level HomePod Mini device.
+ * Functionally identical to HomePod, different device model.
+ */
+declare class HomePodMini extends HomePod {}
+//#endregion
+//#region src/discover.d.ts
+/**
+ * A discovered Apple device with its services and metadata.
+ */
+type DiscoveredDevice = {
+  readonly id: string;
+  readonly name: string;
+  readonly address: string;
+  readonly modelName: string;
+  readonly deviceType: DeviceType;
+  readonly services: {
+    readonly airplay?: DiscoveryResult$1;
+    readonly companionLink?: DiscoveryResult$1;
+    readonly raop?: DiscoveryResult$1;
+  };
+};
+/**
+ * Discovers Apple devices on the local network via mDNS.
+ * Returns device descriptors that can be passed to createDevice().
+ */
+declare function discover(): Promise<DiscoveredDevice[]>;
+/**
+ * Creates a typed device instance from a discovery result.
+ * Automatically selects AppleTV, HomePod, or HomePodMini based on the model.
+ */
+declare function createDevice(discovered: DiscoveredDevice): AppleTV | HomePod | HomePodMini;
+//#endregion
+//#region src/configure.d.ts
+/**
+ * Global SDK configuration options.
+ */
+type SdkConfig = {
+  /**
+   * Storage backend for credentials. Default: none (consumer manages storage).
+   */
+  readonly storage?: Storage;
+  /**
+   * Enable debug logging groups. Default: none.
+   */
+  readonly logging?: ('debug' | 'error' | 'info' | 'net' | 'raw' | 'warn')[];
+  /**
+   * Shared timing server for multi-room audio sync and RAOP streaming.
+   * When set, all devices automatically use this timing server unless
+   * overridden per device via DeviceOptions.timingServer.
+   */
+  readonly timingServer?: TimingServer$1;
+};
+/**
+ * Configures global settings for the Apple SDK.
+ * Should be called once before creating any device instances.
+ */
+declare function configure(config: SdkConfig): void;
+//#endregion
+export { PROTOCOL as AIRPLAY_PROTOCOL, AbstractDevice, type AccessoryCredentials, AccountsController, AirPlayArtwork, type AirPlayClient, AirPlayManager, type AirPlayPlayer, AirPlayRemote, AirPlayState, AirPlayVolume, AppleTV, type AppleTVEventMap, type AppleTVOptions, AppsController, ArtworkController, type ArtworkResult, type AttentionState, COMPANION_LINK_PROTOCOL, CompanionLinkManager, CompanionLinkState, type ConnectOptions, type DeviceEventMap, type DeviceOptions, type DeviceType, type DiscoveredDevice, type DiscoveryResult, HomePod, HomePodMini, KeyboardController, type MediaCapabilities, MediaController, MultiroomController, type PairingOptions, type PairingResult, PairingSession, PlaybackController, PowerController, Proto, type RecoveryOptions, RemoteController, type SdkConfig, SendCommandError, StateController, type StateEventMap, SystemController, type TextInputState, TimingServer, VolumeController, configure, createDevice, discover };