@basmilius/apple-devices 0.10.0 → 0.11.0

package/dist/index.mjs

@@ -1,16 +1,151 @@
 import * as AirPlay from "@basmilius/apple-airplay";
-import { AirPlayFeature, DataStreamMessage, Proto, Protocol } from "@basmilius/apple-airplay";
+import { DataStreamMessage, Proto, Protocol } from "@basmilius/apple-airplay";
 import { EventEmitter } from "node:events";
-import { CommandError, CredentialsError, waitFor } from "@basmilius/apple-common";
+import { AirPlayFeatureFlags, CommandError, CredentialsError, waitFor } from "@basmilius/apple-common";
 import { MediaControlFlag, Protocol as Protocol$1, convertAttentionState } from "@basmilius/apple-companion-link";
 import { NSKeyedArchiver, Plist } from "@basmilius/apple-encoding";
 
+//#region src/airplay/const.ts
+/** Interval in milliseconds between periodic feedback requests to keep the AirPlay session alive. */
+const FEEDBACK_INTERVAL = 2e3;
+/** Symbol used to access the underlying AirPlay Protocol instance from an AirPlayDevice. */
+const PROTOCOL = Symbol("com.basmilius.airplay:protocol");
+/** Symbol used to subscribe AirPlayState to DataStream events. */
+const STATE_SUBSCRIBE_SYMBOL = Symbol("com.basmilius.airplay:subscribe");
+/** Symbol used to unsubscribe AirPlayState from DataStream events. */
+const STATE_UNSUBSCRIBE_SYMBOL = Symbol("com.basmilius.airplay:unsubscribe");
+
+//#endregion
+//#region src/airplay/artwork.ts
+/**
+* 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
+*/
+var Artwork = class {
+	get #protocol() {
+		return this.#device[PROTOCOL];
+	}
+	get #state() {
+		return this.#device.state;
+	}
+	#device;
+	#lastIdentifier = null;
+	#cached = null;
+	constructor(device) {
+		this.#device = device;
+	}
+	/**
+	* 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.
+	*/
+	async get(width = 600, height = -1) {
+		const player = this.#state.nowPlayingClient?.activePlayer;
+		if (!player) return null;
+		const identifier = player.artworkId;
+		if (identifier && identifier === this.#lastIdentifier && this.#cached) return this.#cached;
+		const url = player.artworkUrl(width, height);
+		if (url) return this.#cache(identifier, {
+			url,
+			data: null,
+			mimeType: guessMimeType(url),
+			identifier,
+			width,
+			height: height < 0 ? 0 : height
+		});
+		const inlineData = player.currentItemArtwork;
+		if (inlineData && inlineData.byteLength > 0) {
+			const metadata = player.currentItemMetadata;
+			return this.#cache(identifier, {
+				url: null,
+				data: inlineData,
+				mimeType: metadata?.artworkMIMEType || "image/jpeg",
+				identifier,
+				width: 0,
+				height: 0
+			});
+		}
+		const setArtworkData = this.#state.artworkJpegData;
+		if (setArtworkData && setArtworkData.byteLength > 0) return this.#cache(identifier, {
+			url: null,
+			data: setArtworkData,
+			mimeType: "image/jpeg",
+			identifier,
+			width: 0,
+			height: 0
+		});
+		if (identifier) try {
+			await this.#protocol.dataStream.exchange(DataStreamMessage.playbackQueueRequest(0, 1, width, height < 0 ? 400 : height));
+			const fetchedData = player.currentItemArtwork;
+			if (fetchedData && fetchedData.byteLength > 0) {
+				const metadata = player.currentItemMetadata;
+				return this.#cache(identifier, {
+					url: null,
+					data: fetchedData,
+					mimeType: metadata?.artworkMIMEType || "image/jpeg",
+					identifier,
+					width: 0,
+					height: 0
+				});
+			}
+			const retryUrl = player.artworkUrl(width, height);
+			if (retryUrl) return this.#cache(identifier, {
+				url: retryUrl,
+				data: null,
+				mimeType: guessMimeType(retryUrl),
+				identifier,
+				width,
+				height: height < 0 ? 0 : height
+			});
+		} catch {}
+		this.#lastIdentifier = null;
+		this.#cached = null;
+		return null;
+	}
+	/** Clears the cached artwork, forcing a fresh fetch on the next `get()` call. */
+	clear() {
+		this.#lastIdentifier = null;
+		this.#cached = null;
+	}
+	#cache(identifier, result) {
+		this.#lastIdentifier = identifier;
+		this.#cached = result;
+		return result;
+	}
+};
+const guessMimeType = (url) => {
+	if (url.includes(".png")) return "image/png";
+	if (url.includes(".webp")) return "image/webp";
+	return "image/jpeg";
+};
+
+//#endregion
 //#region src/airplay/player.ts
 /** Offset in seconds between the Cocoa epoch (2001-01-01) and the Unix epoch (1970-01-01). */
 const COCOA_EPOCH_OFFSET = 978307200;
 /** Default player identifier used by the Apple TV when no specific player is active. */
 const DEFAULT_PLAYER_ID = "MediaRemote-DefaultPlayer";
 /**
+* Converts an artwork URL to a browser-compatible format.
+* Apple's CDN serves HEIC by default, which most browsers can't display.
+* Replacing the extension with .jpg makes the CDN return JPEG instead.
+*/
+const convertArtworkUrl = (url) => {
+	return url.replace(/\.heic(\b|$)/gi, ".jpg");
+};
+/**
 * Extrapolates the current elapsed time based on a snapshot timestamp and playback rate.
 * Compensates for the time passed since the timestamp was recorded, scaled by the playback rate.
 *
@@ -53,15 +188,9 @@ var Player = class {
 		return this.#playbackQueue;
 	}
 	/**
-	* 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() {
-		if (this.#playbackState === Proto.PlaybackState_Enum.Playing && this.playbackRate === 0) return Proto.PlaybackState_Enum.Paused;
-		return this.#playbackState;
-	}
-	/** The raw playback state as reported by the Apple TV, without corrections. */
-	get rawPlaybackState() {
 		return this.#playbackState;
 	}
 	/** Timestamp of the last playback state update, used to discard stale updates. */
@@ -177,11 +306,11 @@ var Player = class {
 	*/
 	artworkUrl(width = 600, height = -1) {
 		const metadata = this.currentItemMetadata;
-		if (metadata?.artworkURL) return metadata.artworkURL;
+		if (metadata?.artworkURL) return convertArtworkUrl(metadata.artworkURL);
 		const item = this.currentItem;
-		if (item?.remoteArtworks.length > 0 && item.remoteArtworks[0].artworkURLString) return item.remoteArtworks[0].artworkURLString;
+		if (item?.remoteArtworks.length > 0 && item.remoteArtworks[0].artworkURLString) return convertArtworkUrl(item.remoteArtworks[0].artworkURLString);
 		if (metadata?.artworkIdentifier) try {
-			const url = metadata.artworkIdentifier.replace("{w}", String(width < 1 ? 999999 : width)).replace("{h}", String(height < 1 ? 999999 : height)).replace("{c}", "bb").replace("{f}", "png");
+			const url = metadata.artworkIdentifier.replace("{w}", String(width < 1 ? 999999 : width)).replace("{h}", String(height < 1 ? 999999 : height)).replace("{c}", "bb").replace("{f}", "jpg");
 			if (url.startsWith("http://") || url.startsWith("https://")) return url;
 		} catch {}
 		return null;
@@ -532,17 +661,6 @@ var Client = class {
 	}
 };
 
-//#endregion
-//#region src/airplay/const.ts
-/** Interval in milliseconds between periodic feedback requests to keep the AirPlay session alive. */
-const FEEDBACK_INTERVAL = 2e3;
-/** Symbol used to access the underlying AirPlay Protocol instance from an AirPlayDevice. */
-const PROTOCOL = Symbol("com.basmilius.airplay:protocol");
-/** Symbol used to subscribe AirPlayState to DataStream events. */
-const STATE_SUBSCRIBE_SYMBOL = Symbol("com.basmilius.airplay:subscribe");
-/** Symbol used to unsubscribe AirPlayState from DataStream events. */
-const STATE_UNSUBSCRIBE_SYMBOL = Symbol("com.basmilius.airplay:unsubscribe");
-
 //#endregion
 //#region src/airplay/remote.ts
 /**
@@ -797,6 +915,16 @@ var remote_default = class {
 		await this.#sendCommand(Proto.Command.AddNowPlayingItemToLibrary);
 	}
 	/**
+	* 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.
+	*/
+	async commandSetSleepTimer(seconds, stopMode = 0) {
+		await this.#sendCommandRaw(DataStreamMessage.sendCommandWithSleepTimer(seconds, stopMode));
+	}
+	/**
 	* Sets the text input field to the given text, replacing any existing content.
 	*
 	* @param text - The text to set.
@@ -1035,6 +1163,14 @@ var state_default = class extends EventEmitter {
 	get isClusterLeader() {
 		return this.#isClusterLeader;
 	}
+	/** Current playback queue participants (e.g. SharePlay users). */
+	get participants() {
+		return this.#participants;
+	}
+	/** Raw JPEG artwork data from the last SET_ARTWORK_MESSAGE, or null. */
+	get artworkJpegData() {
+		return this.#artworkJpegData;
+	}
 	/** Current volume level (0.0 - 1.0). */
 	get volume() {
 		return this.#volume;
@@ -1063,6 +1199,8 @@ var state_default = class extends EventEmitter {
 	#clusterType;
 	#isClusterAware;
 	#isClusterLeader;
+	#participants;
+	#artworkJpegData;
 	#volume;
 	#volumeAvailable;
 	#volumeCapabilities;
@@ -1095,6 +1233,7 @@ var state_default = class extends EventEmitter {
 		this.onUpdateContentItem = this.onUpdateContentItem.bind(this);
 		this.onUpdateContentItemArtwork = this.onUpdateContentItemArtwork.bind(this);
 		this.onUpdatePlayer = this.onUpdatePlayer.bind(this);
+		this.onPlayerClientParticipantsUpdate = this.onPlayerClientParticipantsUpdate.bind(this);
 		this.onUpdateOutputDevice = this.onUpdateOutputDevice.bind(this);
 		this.onVolumeControlAvailability = this.onVolumeControlAvailability.bind(this);
 		this.onVolumeControlCapabilitiesDidChange = this.onVolumeControlCapabilitiesDidChange.bind(this);
@@ -1122,6 +1261,7 @@ var state_default = class extends EventEmitter {
 		this.#dataStream.on("updateContentItem", this.onUpdateContentItem);
 		this.#dataStream.on("updateContentItemArtwork", this.onUpdateContentItemArtwork);
 		this.#dataStream.on("updatePlayer", this.onUpdatePlayer);
+		this.#dataStream.on("playerClientParticipantsUpdate", this.onPlayerClientParticipantsUpdate);
 		this.#dataStream.on("updateOutputDevice", this.onUpdateOutputDevice);
 		this.#dataStream.on("volumeControlAvailability", this.onVolumeControlAvailability);
 		this.#dataStream.on("volumeControlCapabilitiesDidChange", this.onVolumeControlCapabilitiesDidChange);
@@ -1151,6 +1291,7 @@ var state_default = class extends EventEmitter {
 		dataStream.off("updateContentItem", this.onUpdateContentItem);
 		dataStream.off("updateContentItemArtwork", this.onUpdateContentItemArtwork);
 		dataStream.off("updatePlayer", this.onUpdatePlayer);
+		dataStream.off("playerClientParticipantsUpdate", this.onPlayerClientParticipantsUpdate);
 		dataStream.off("updateOutputDevice", this.onUpdateOutputDevice);
 		dataStream.off("volumeControlAvailability", this.onVolumeControlAvailability);
 		dataStream.off("volumeControlCapabilitiesDidChange", this.onVolumeControlCapabilitiesDidChange);
@@ -1170,6 +1311,8 @@ var state_default = class extends EventEmitter {
 		this.#clusterType = 0;
 		this.#isClusterAware = false;
 		this.#isClusterLeader = false;
+		this.#participants = [];
+		this.#artworkJpegData = null;
 		this.#volume = 0;
 		this.#volumeAvailable = false;
 		this.#volumeCapabilities = Proto.VolumeCapabilities_Enum.None;
@@ -1268,6 +1411,7 @@ var state_default = class extends EventEmitter {
 	* @param message - The set artwork message.
 	*/
 	onSetArtwork(message) {
+		if (message.jpegData?.byteLength > 0) this.#artworkJpegData = message.jpegData;
 		this.emit("setArtwork", message);
 	}
 	/**
@@ -1410,6 +1554,15 @@ var state_default = class extends EventEmitter {
 	*
 	* @param message - The update output device message.
 	*/
+	/**
+	* Handles playback queue participant updates (e.g. SharePlay users).
+	*
+	* @param message - The participants update message.
+	*/
+	onPlayerClientParticipantsUpdate(message) {
+		this.#participants = message.participants ?? [];
+		this.emit("playerClientParticipantsUpdate", message);
+	}
 	onUpdateOutputDevice(message) {
 		this.#outputDevices = message.clusterAwareOutputDevices?.length > 0 ? message.clusterAwareOutputDevices : message.outputDevices;
 		this.emit("updateOutputDevice", message);
@@ -1459,11 +1612,14 @@ var state_default = class extends EventEmitter {
 	* @param message - The device info message.
 	*/
 	#updateDeviceInfo(message) {
+		const previousClusterID = this.#clusterID;
+		const previousIsLeader = this.#isClusterLeader;
 		this.#outputDeviceUID = message.clusterID || message.deviceUID || message.uniqueIdentifier || null;
 		this.#clusterID = message.clusterID || null;
 		this.#clusterType = message.clusterType ?? 0;
 		this.#isClusterAware = message.isClusterAware ?? false;
 		this.#isClusterLeader = message.isClusterLeader ?? false;
+		if (this.#clusterID !== previousClusterID || this.#isClusterLeader !== previousIsLeader) this.emit("clusterChanged", this.#clusterID, this.#isClusterLeader);
 	}
 	/**
 	* Gets or creates a Client for the given bundle identifier.
@@ -1547,6 +1703,8 @@ var state_default = class extends EventEmitter {
 //#region src/airplay/volume.ts
 /** Volume adjustment step size as a fraction (0.05 = 5%). */
 const VOLUME_STEP = .05;
+/** Minimum interval between volume fade steps in milliseconds. */
+const FADE_STEP_INTERVAL = 50;
 /**
 * Smart volume controller for an AirPlay device.
 * Automatically chooses between absolute volume (set a specific level) and
@@ -1633,6 +1791,106 @@ var volume_default = class {
 		this.#protocol.context.logger.info(`Setting volume to ${volume} for device ${this.#state.outputDeviceUID}`);
 		await this.#protocol.dataStream.exchange(DataStreamMessage.setVolume(this.#state.outputDeviceUID, volume));
 	}
+	/**
+	* Mutes the output device.
+	*
+	* @throws CommandError when no output device is active.
+	*/
+	async mute() {
+		if (!this.#state.outputDeviceUID) throw new CommandError("No output device active.");
+		await this.#protocol.dataStream.exchange(DataStreamMessage.setVolumeMuted(this.#state.outputDeviceUID, true));
+	}
+	/**
+	* Unmutes the output device.
+	*
+	* @throws CommandError when no output device is active.
+	*/
+	async unmute() {
+		if (!this.#state.outputDeviceUID) throw new CommandError("No output device active.");
+		await this.#protocol.dataStream.exchange(DataStreamMessage.setVolumeMuted(this.#state.outputDeviceUID, false));
+	}
+	/**
+	* Toggles the mute state of the output device.
+	*
+	* @throws CommandError when no output device is active.
+	*/
+	async toggleMute() {
+		if (this.#state.volumeMuted) await this.unmute();
+		else await this.mute();
+	}
+	/**
+	* 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).
+	*/
+	async setForDevice(outputDeviceUID, volume) {
+		volume = Math.min(1, Math.max(0, volume));
+		this.#protocol.context.logger.info(`Setting volume to ${volume} for output device ${outputDeviceUID}`);
+		await this.#protocol.dataStream.exchange(DataStreamMessage.setVolume(outputDeviceUID, volume));
+	}
+	/**
+	* 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.
+	*/
+	async getForDevice(outputDeviceUID) {
+		const response = await this.#protocol.dataStream.exchange(DataStreamMessage.getVolume(outputDeviceUID));
+		if (response.type === Proto.ProtocolMessage_Type.GET_VOLUME_RESULT_MESSAGE) return DataStreamMessage.getExtension(response, Proto.getVolumeResultMessage).volume;
+		throw new CommandError("Failed to get volume for output device.");
+	}
+	/**
+	* Mutes a specific output device in a speaker group.
+	*
+	* @param outputDeviceUID - The unique identifier of the target output device.
+	*/
+	async muteDevice(outputDeviceUID) {
+		await this.#protocol.dataStream.exchange(DataStreamMessage.setVolumeMuted(outputDeviceUID, true));
+	}
+	/**
+	* Unmutes a specific output device in a speaker group.
+	*
+	* @param outputDeviceUID - The unique identifier of the target output device.
+	*/
+	async unmuteDevice(outputDeviceUID) {
+		await this.#protocol.dataStream.exchange(DataStreamMessage.setVolumeMuted(outputDeviceUID, false));
+	}
+	/**
+	* 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.
+	*/
+	async adjust(adjustment, outputDeviceUID) {
+		const uid = outputDeviceUID ?? this.#state.outputDeviceUID;
+		if (!uid) throw new CommandError("No output device active.");
+		await this.#protocol.dataStream.exchange(DataStreamMessage.adjustVolume(adjustment, uid));
+	}
+	/**
+	* 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.
+	*/
+	async fade(targetVolume, durationMs) {
+		if (!this.#state.outputDeviceUID) throw new CommandError("No output device active.");
+		if (![Proto.VolumeCapabilities_Enum.Absolute, Proto.VolumeCapabilities_Enum.Both].includes(this.#state.volumeCapabilities)) throw new CommandError("Absolute volume control is not available.");
+		targetVolume = Math.min(1, Math.max(0, targetVolume));
+		const startVolume = this.#state.volume;
+		const steps = Math.max(1, Math.floor(durationMs / FADE_STEP_INTERVAL));
+		const stepDuration = durationMs / steps;
+		const volumeDelta = (targetVolume - startVolume) / steps;
+		for (let i = 1; i <= steps; i++) {
+			const volume = i === steps ? targetVolume : Math.min(1, Math.max(0, startVolume + volumeDelta * i));
+			await this.set(volume);
+			if (i < steps) await waitFor(stepDuration);
+		}
+	}
 };
 
 //#endregion
@@ -1663,15 +1921,15 @@ var device_default = class extends EventEmitter {
 	get capabilities() {
 		const has = (f) => this.#protocol?.hasReceiverFeature(f) ?? false;
 		return {
-			supportsAudio: has(AirPlayFeature.SupportsAirPlayAudio),
-			supportsBufferedAudio: has(AirPlayFeature.SupportsBufferedAudio),
-			supportsPTP: has(AirPlayFeature.SupportsPTP),
-			supportsRFC2198Redundancy: has(AirPlayFeature.SupportsRFC2198Redundancy),
-			supportsHangdogRemoteControl: has(AirPlayFeature.SupportsHangdogRemoteControl),
-			supportsUnifiedMediaControl: has(AirPlayFeature.SupportsUnifiedMediaControl),
-			supportsTransientPairing: has(AirPlayFeature.SupportsHKPairingAndAccessControl),
-			supportsSystemPairing: has(AirPlayFeature.SupportsSystemPairing),
-			supportsCoreUtilsPairing: has(AirPlayFeature.SupportsCoreUtilsPairingAndEncryption)
+			supportsAudio: has(AirPlayFeatureFlags.SupportsAirPlayAudio),
+			supportsBufferedAudio: has(AirPlayFeatureFlags.SupportsBufferedAudio),
+			supportsPTP: has(AirPlayFeatureFlags.SupportsPTP),
+			supportsRFC2198Redundancy: has(AirPlayFeatureFlags.SupportsRFC2198Redundancy),
+			supportsHangdogRemoteControl: has(AirPlayFeatureFlags.SupportsHangdogRemoteControl),
+			supportsUnifiedMediaControl: has(AirPlayFeatureFlags.SupportsUnifiedMediaControl),
+			supportsTransientPairing: has(AirPlayFeatureFlags.SupportsHKPairingAndAccessControl),
+			supportsSystemPairing: has(AirPlayFeatureFlags.SupportsSystemPairing),
+			supportsCoreUtilsPairing: has(AirPlayFeatureFlags.SupportsCoreUtilsPairingAndEncryption)
 		};
 	}
 	/** Whether the control stream TCP connection is currently active. */
@@ -1682,6 +1940,10 @@ var device_default = class extends EventEmitter {
 	get receiverInfo() {
 		return this.#protocol?.receiverInfo;
 	}
+	/** The Artwork controller for fetching now-playing artwork from all sources. */
+	get artwork() {
+		return this.#artwork;
+	}
 	/** The Remote controller for HID keys, SendCommand, text input, and touch. */
 	get remote() {
 		return this.#remote;
@@ -1702,6 +1964,7 @@ var device_default = class extends EventEmitter {
 	set timingServer(timingServer) {
 		this.#timingServer = timingServer;
 	}
+	#artwork;
 	#remote;
 	#state;
 	#volume;
@@ -1711,6 +1974,7 @@ var device_default = class extends EventEmitter {
 	#identity;
 	#feedbackInterval;
 	#keys;
+	#lastArtworkId = null;
 	#playUrlProtocol;
 	#prevDataStream;
 	#prevEventStream;
@@ -1726,10 +1990,12 @@ var device_default = class extends EventEmitter {
 		super();
 		this.#discoveryResult = discoveryResult;
 		this.#identity = identity;
+		this.#artwork = new Artwork(this);
 		this.#remote = new remote_default(this);
 		this.#state = new state_default(this);
 		this.onClose = this.onClose.bind(this);
 		this.onError = this.onError.bind(this);
+		this.onNowPlayingChanged = this.onNowPlayingChanged.bind(this);
 		this.onTimeout = this.onTimeout.bind(this);
 		this.#volume = new volume_default(this);
 	}
@@ -1879,6 +2145,37 @@ var device_default = class extends EventEmitter {
 		await this.#protocol.setupAudioStream(source);
 	}
 	/**
+	* Sets the audio listening mode on the device (HomePod).
+	*
+	* @param mode - Listening mode string (e.g. 'Default', 'Vivid', 'LateNight').
+	*/
+	async setListeningMode(mode) {
+		const uid = this.state.outputDeviceUID;
+		if (uid) await this.#protocol.dataStream.send(DataStreamMessage.setListeningMode(mode, uid));
+	}
+	/**
+	* Sets the audio routing mode on the receiver via the control stream.
+	*
+	* @param mode - Audio mode (e.g. 'default', 'moviePlayback', 'spoken').
+	*/
+	async setAudioMode(mode) {
+		await this.#protocol.controlStream.setAudioMode(mode);
+	}
+	/**
+	* Triggers an audio fade on the device.
+	*
+	* @param fadeType - The fade type (0 = fade out, 1 = fade in).
+	*/
+	async audioFade(fadeType) {
+		await this.#protocol.dataStream.send(DataStreamMessage.audioFade(fadeType));
+	}
+	/**
+	* Wakes the device from sleep via the DataStream.
+	*/
+	async wake() {
+		await this.#protocol.dataStream.send(DataStreamMessage.wakeDevice());
+	}
+	/**
 	* Requests the playback queue from the device.
 	*
 	* @param length - Maximum number of queue items to retrieve.
@@ -1928,6 +2225,14 @@ var device_default = class extends EventEmitter {
 	onError(err) {
 		this.#protocol.context.logger.error("AirPlay error", err);
 	}
+	/** Handles now-playing changes to auto-fetch artwork on track changes. */
+	onNowPlayingChanged(_client, player) {
+		const artworkId = player?.artworkId ?? null;
+		if (artworkId !== this.#lastArtworkId) {
+			this.#lastArtworkId = artworkId;
+			this.requestPlaybackQueue(1).catch(() => {});
+		}
+	}
 	/** Handles stream timeout events by destroying the control stream. */
 	onTimeout() {
 		this.#protocol.context.logger.error("AirPlay timeout");
@@ -1958,9 +2263,11 @@ var device_default = class extends EventEmitter {
 			if (this.#feedbackInterval) clearInterval(this.#feedbackInterval);
 			this.#feedbackInterval = setInterval(async () => await this.#feedback(), FEEDBACK_INTERVAL);
 			await this.#protocol.dataStream.exchange(DataStreamMessage.deviceInfo(keys.pairingId, this.#protocol.context.identity));
-			await this.#protocol.dataStream.exchange(DataStreamMessage.setConnectionState());
-			await this.#protocol.dataStream.exchange(DataStreamMessage.clientUpdatesConfig(true, true, true, true, true, true));
+			this.#protocol.dataStream.send(DataStreamMessage.setConnectionState());
+			this.#protocol.dataStream.send(DataStreamMessage.clientUpdatesConfig(true, true, true, true));
 			await this.#protocol.dataStream.exchange(DataStreamMessage.getState());
+			this.#lastArtworkId = null;
+			this.#state.on("nowPlayingChanged", this.onNowPlayingChanged);
 			this.#protocol.context.logger.info("Protocol ready.");
 		} catch (err) {
 			if (this.#feedbackInterval) {
@@ -1979,6 +2286,7 @@ var device_default = class extends EventEmitter {
 	/** Unsubscribes the state tracker from DataStream events. */
 	#unsubscribe() {
 		try {
+			this.#state.off("nowPlayingChanged", this.onNowPlayingChanged);
 			this.#state[STATE_UNSUBSCRIBE_SYMBOL]();
 		} catch (err) {
 			this.#protocol.context.logger.error("State unsubscribe error", err);
@@ -2677,6 +2985,33 @@ var device_default$1 = class extends EventEmitter {
 	}
 };
 
+//#endregion
+//#region src/utils.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.
+*/
+function getCommandInfo(state, command) {
+	const client = state.nowPlayingClient;
+	if (!client) return null;
+	return client.supportedCommands.find((c) => c.command === command) ?? 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.
+*/
+function isCommandSupported(state, command) {
+	const client = state.nowPlayingClient;
+	if (!client) return false;
+	return client.isCommandSupported(command);
+}
+
 //#endregion
 //#region src/model/apple-tv.ts
 /**
@@ -2916,9 +3251,7 @@ var apple_tv_default = class extends EventEmitter {
 	* @returns The command info, or null if no client is active or command not found.
 	*/
 	async getCommandInfo(command) {
-		const client = this.#airplay.state.nowPlayingClient;
-		if (!client) return null;
-		return client.supportedCommands.find((c) => c.command === command) ?? null;
+		return getCommandInfo(this.#airplay.state, command);
 	}
 	/**
 	* Checks whether a command is supported and enabled by the active player.
@@ -2927,9 +3260,7 @@ var apple_tv_default = class extends EventEmitter {
 	* @returns True if supported and enabled, false otherwise.
 	*/
 	async isCommandSupported(command) {
-		const client = this.#airplay.state.nowPlayingClient;
-		if (!client) return false;
-		return client.isCommandSupported(command);
+		return isCommandSupported(this.#airplay.state, command);
 	}
 	/** Emits 'connected' when both AirPlay and Companion Link are connected. */
 	async #onConnected() {
@@ -3026,6 +3357,26 @@ var homepod_base_default = class extends EventEmitter {
 	get volume() {
 		return this.#airplay.state.volume ?? 0;
 	}
+	/** Whether the device is currently muted. */
+	get isMuted() {
+		return this.#airplay.state.volumeMuted;
+	}
+	/** Cluster ID when part of a speaker group, or null. */
+	get clusterID() {
+		return this.#airplay.state.clusterID;
+	}
+	/** Cluster type identifier (0 = none). */
+	get clusterType() {
+		return this.#airplay.state.clusterType;
+	}
+	/** Whether this device supports cluster-aware multi-room. */
+	get isClusterAware() {
+		return this.#airplay.state.isClusterAware;
+	}
+	/** Whether this device is the leader in a speaker cluster. */
+	get isClusterLeader() {
+		return this.#airplay.state.isClusterLeader;
+	}
 	/** @returns The currently active now-playing client, or null. */
 	get #nowPlayingClient() {
 		return this.#airplay.state.nowPlayingClient;
@@ -3102,15 +3453,23 @@ var homepod_base_default = class extends EventEmitter {
 		await this.#airplay.streamAudio(source);
 	}
 	/**
+	* 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).
+	*/
+	async requestLyrics(length = 1) {
+		await this.#airplay.requestPlaybackQueue(length);
+	}
+	/**
 	* Gets the CommandInfo for a specific command from the active player.
 	*
 	* @param command - The command to look up.
 	* @returns The command info, or null if no client is active or command not found.
 	*/
 	async getCommandInfo(command) {
-		const client = this.#airplay.state.nowPlayingClient;
-		if (!client) return null;
-		return client.supportedCommands.find((c) => c.command === command) ?? null;
+		return getCommandInfo(this.#airplay.state, command);
 	}
 	/**
 	* Checks whether a command is supported and enabled by the active player.
@@ -3119,9 +3478,7 @@ var homepod_base_default = class extends EventEmitter {
 	* @returns True if supported and enabled, false otherwise.
 	*/
 	async isCommandSupported(command) {
-		const client = this.#airplay.state.nowPlayingClient;
-		if (!client) return false;
-		return client.isCommandSupported(command);
+		return isCommandSupported(this.#airplay.state, command);
 	}
 	/** Emits 'connected' when the AirPlay connection is established. */
 	async #onConnected() {
@@ -3158,4 +3515,4 @@ var homepod_default = class extends homepod_base_default {};
 var homepod_mini_default = class extends homepod_base_default {};
 
 //#endregion
-export { PROTOCOL as AIRPLAY, Client as AirPlayClient, device_default as AirPlayDevice, Player as AirPlayPlayer, remote_default as AirPlayRemote, state_default as AirPlayState, volume_default as AirPlayVolume, apple_tv_default as AppleTV, PROTOCOL$1 as COMPANION_LINK, device_default$1 as CompanionLinkDevice, homepod_default as HomePod, homepod_mini_default as HomePodMini, SendCommandError };
+export { PROTOCOL as AIRPLAY, Artwork as AirPlayArtwork, Client as AirPlayClient, device_default as AirPlayDevice, Player as AirPlayPlayer, remote_default as AirPlayRemote, state_default as AirPlayState, volume_default as AirPlayVolume, apple_tv_default as AppleTV, PROTOCOL$1 as COMPANION_LINK, device_default$1 as CompanionLinkDevice, homepod_default as HomePod, homepod_mini_default as HomePodMini, SendCommandError, getCommandInfo, isCommandSupported };