@basmilius/apple-devices 0.10.0 → 0.11.0

package/dist/index.d.mts

@@ -5,6 +5,240 @@ import { EventEmitter } from "node:events";
 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/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 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/airplay/player.d.ts
 /**
  * Represents a single media player within an app on the Apple TV.
@@ -25,12 +259,9 @@ declare class Player {
   /** Current playback queue, or null if unavailable. */
   get playbackQueue(): Proto.PlaybackQueue | null;
   /**
-   * Effective playback state. Corrects for the edge case where the Apple TV
-   * reports Playing but the playback rate is 0 (effectively paused).
+   * 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. */
@@ -141,377 +372,151 @@ declare class Player {
    */
   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).
+   * Merges updated content item data into the existing playback queue.
+   * Updates metadata, artwork, lyrics, and info fields for the matching item.
    *
-   * @param rate - The desired playback rate (e.g. 1.0 for normal, 2.0 for double speed).
+   * @param item - The content item with updated fields.
    */
-  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>;
+  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;
   /**
-   * Sets the text input field to the given text, replacing any existing content.
-   *
-   * @param text - The text to set.
+   * Merged list of supported commands from the active player and client defaults.
+   * Player commands take precedence; default commands are appended if not already present.
    */
-  textSet(text: string): Promise<void>;
+  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;
   /**
-   * Appends text to the current text input field content.
+   * Resolves the best available artwork URL from the active player.
    *
-   * @param text - The text to append.
+   * @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.
    */
-  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>;
+  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;
   /**
-   * Simulates a tap at the given coordinates.
+   * Creates a new Client instance.
    *
-   * @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).
+   * @param bundleIdentifier - Bundle identifier of the app.
+   * @param displayName - Human-readable app name.
    */
-  tap(x: number, y: number, finger?: number): Promise<void>;
+  constructor(bundleIdentifier: string, displayName: string);
   /**
-   * Simulates an upward swipe gesture.
+   * Gets an existing player or creates a new one if it does not exist.
    *
-   * @param duration - Swipe duration in milliseconds (defaults to 200).
+   * @param identifier - Unique player identifier.
+   * @param displayName - Human-readable player name (defaults to identifier).
+   * @returns The existing or newly created Player.
    */
-  swipeUp(duration?: number): Promise<void>;
+  getOrCreatePlayer(identifier: string, displayName?: string): Player;
   /**
-   * Simulates a downward swipe gesture.
+   * Sets the active player by identifier.
    *
-   * @param duration - Swipe duration in milliseconds (defaults to 200).
+   * @param identifier - Identifier of the player to activate.
    */
-  swipeDown(duration?: number): Promise<void>;
+  setActivePlayer(identifier: string): void;
   /**
-   * Simulates a leftward swipe gesture.
+   * 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 duration - Swipe duration in milliseconds (defaults to 200).
+   * @param identifier - Identifier of the player to remove.
    */
-  swipeLeft(duration?: number): Promise<void>;
+  removePlayer(identifier: string): void;
   /**
-   * Simulates a rightward swipe gesture.
+   * Sets the default supported commands for this client. These are used as
+   * fallback when the active player has no commands of its own.
    *
-   * @param duration - Swipe duration in milliseconds (defaults to 200).
+   * @param supportedCommands - The default command list.
    */
-  swipeRight(duration?: number): Promise<void>;
+  setDefaultSupportedCommands(supportedCommands: Proto.CommandInfo[]): void;
   /**
-   * Sends a double press of a HID key (two press-and-release cycles with a 150ms gap).
+   * Finds a command by type, checking the active player first,
+   * then falling back to the default supported commands.
    *
-   * @param usePage - USB HID usage page (1 = Generic Desktop, 12 = Consumer).
-   * @param usage - USB HID usage code.
+   * @param command - The command to look up.
+   * @returns The command info, or null if not found.
    */
-  doublePress(usePage: number, usage: number): Promise<void>;
+  findCommand(command: Proto.Command): Proto.CommandInfo | null;
   /**
-   * Sends a long press of a HID key (hold for a configurable duration).
+   * Checks whether a command is supported and enabled, checking both
+   * the active player and default commands.
    *
-   * @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).
+   * @param command - The command to check.
+   * @returns True if the command is supported and enabled.
    */
-  longPress(usePage: number, usage: number, duration?: number): Promise<void>;
+  isCommandSupported(command: Proto.Command): boolean;
   /**
-   * Sends a single press-and-release of a HID key with a 25ms hold.
+   * Updates the display name for this client.
    *
-   * @param usePage - USB HID usage page (1 = Generic Desktop, 12 = Consumer).
-   * @param usage - USB HID usage code.
+   * @param displayName - The new display name.
    */
-  pressAndRelease(usePage: number, usage: number): Promise<void>;
+  updateDisplayName(displayName: string): void;
 }
 //#endregion
 //#region src/airplay/state.d.ts
@@ -554,6 +559,8 @@ type EventMap$5 = {
   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[]];
+  readonly clusterChanged: [clusterID: string | null, isLeader: boolean];
+  readonly playerClientParticipantsUpdate: [Proto.PlayerClientParticipantsUpdateMessage];
 };
 /**
  * Tracks the complete state of an AirPlay device: clients, players, now-playing,
@@ -585,6 +592,10 @@ declare class export_default$2 extends EventEmitter<EventMap$5> {
   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.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. */
@@ -731,6 +742,12 @@ declare class export_default$2 extends EventEmitter<EventMap$5> {
    *
    * @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.PlayerClientParticipantsUpdateMessage): void;
   onUpdateOutputDevice(message: Proto.UpdateOutputDeviceMessage): void;
   /**
    * Handles volume control availability changes.
@@ -800,6 +817,68 @@ declare class export_default$3 {
    * @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.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/airplay/device.d.ts
@@ -845,6 +924,8 @@ declare class export_default extends EventEmitter<EventMap$4> {
   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(): Artwork;
   /** 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. */
@@ -917,6 +998,28 @@ declare class export_default extends EventEmitter<EventMap$4> {
    * @param source - The audio source to stream (e.g. MP3, WAV, URL, live).
    */
   streamAudio(source: AudioSource): Promise<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.
    *
@@ -945,10 +1048,54 @@ declare class export_default extends EventEmitter<EventMap$4> {
    * @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/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 Artwork {
+  #private;
+  constructor(device: export_default);
+  /**
+   * 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/companion-link/const.d.ts
 /** Symbol used to access the underlying Companion Link Protocol instance from a CompanionLinkDevice. */
 declare const PROTOCOL$1: unique symbol;
@@ -1501,6 +1648,16 @@ declare abstract class export_default$8 extends EventEmitter<EventMap> {
   get playbackStateTimestamp(): number;
   /** Current volume level (0.0 - 1.0). */
   get volume(): number;
+  /** Whether the device is currently muted. */
+  get isMuted(): boolean;
+  /** Cluster ID when part of a speaker group, or null. */
+  get clusterID(): string | null;
+  /** Cluster type identifier (0 = none). */
+  get clusterType(): number;
+  /** Whether this device supports cluster-aware multi-room. */
+  get isClusterAware(): boolean;
+  /** Whether this device is the leader in a speaker cluster. */
+  get isClusterLeader(): boolean;
   /**
    * Creates a new HomePod base instance.
    *
@@ -1540,6 +1697,14 @@ declare abstract class export_default$8 extends EventEmitter<EventMap> {
    * @param source - The audio source to stream.
    */
   streamAudio(source: AudioSource): Promise<void>;
+  /**
+   * Requests the current playback queue with lyrics from the device.
+   * Lyrics are included by default in the playback queue request.
+   * Real-time lyrics timing events are emitted via the `lyricsEvent` event on state.
+   *
+   * @param length - Maximum number of queue items to retrieve (defaults to 1).
+   */
+  requestLyrics(length?: number): Promise<void>;
   /**
    * Gets the CommandInfo for a specific command from the active player.
    *
@@ -1570,4 +1735,22 @@ declare class export_default$6 extends export_default$8 {}
  */
 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 };
+//#region src/utils.d.ts
+/**
+ * Gets the CommandInfo for a specific command from the active now-playing client.
+ *
+ * @param state - The AirPlay state tracker.
+ * @param command - The command to look up.
+ * @returns The command info, or null if no client is active or command not found.
+ */
+declare function getCommandInfo(state: export_default$2, command: Proto.Command): Proto.CommandInfo | null;
+/**
+ * Checks whether a command is supported and enabled by the active now-playing client.
+ *
+ * @param state - The AirPlay state tracker.
+ * @param command - The command to check.
+ * @returns True if supported and enabled, false otherwise.
+ */
+declare function isCommandSupported(state: export_default$2, command: Proto.Command): boolean;
+//#endregion
+export { PROTOCOL as AIRPLAY, Artwork as AirPlayArtwork, 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, type ArtworkResult, PROTOCOL$1 as COMPANION_LINK, export_default$5 as CompanionLinkDevice, export_default$6 as HomePod, export_default$7 as HomePodMini, type MediaCapabilities, SendCommandError, getCommandInfo, isCommandSupported };