Add an Apple Music integration on iOS

This commit is contained in:
James Babcock committed 2026-10-23 23:05:49 -07:00
1 parent 1780057f3c
commit e36fb14a34
21 files changed
+1323 -129

No files matched your search

+70
View File
@@ -0,0 +1,70 @@
import {
APPLE_MUSIC_APP_NAME,
APPLE_MUSIC_PACKAGE,
parseMediaBrowseItems,
type MediaBrowseItem,
type MediaBrowserApp,
type MediaBrowserBridge,
} from "./media-types";
export type { MediaBrowseItem, MediaBrowserApp } from "./media-types";
declare const FaceclawAppleMusic: any;
const APPLE_MUSIC_APP: MediaBrowserApp = { packageName: APPLE_MUSIC_PACKAGE, serviceClass: "", appName: APPLE_MUSIC_APP_NAME };
/**
* The Apple Music library (playlists, artists, albums, songs in the
* on-device / iCloud music library) as a browse tree, through
* FaceclawAppleMusic's MediaPlayer queries. Playing an item queues its
* collection on the system Music player.
*/
export class AppleMusicBrowserBridge implements MediaBrowserBridge {
private connected = false;
/** Bumped on every connect/disconnect; answers to older requests are dropped. */
private generation = 0;
listBrowsableApps(): MediaBrowserApp[] {
return FaceclawAppleMusic.shared().hasPermission() ? [APPLE_MUSIC_APP] : [];
}
connect(app: MediaBrowserApp): Promise<string> {
this.disconnect();
if (app.packageName !== APPLE_MUSIC_PACKAGE) return Promise.reject(new Error("Only Apple Music can be browsed on iOS"));
if (!FaceclawAppleMusic.shared().hasPermission()) return Promise.reject(new Error("Apple Music access is not allowed"));
this.connected = true;
return Promise.resolve("root");
}
browse(parentId: string): Promise<MediaBrowseItem[]> {
if (!this.connected) return Promise.reject(new Error("Not connected"));
const generation = this.generation;
return new Promise<MediaBrowseItem[]>((resolve, reject) => {
FaceclawAppleMusic.shared().browseCompletion(parentId, (json: string | null, error: string | null) => {
if (generation !== this.generation) reject(new Error("Disconnected"));
else if (error || json == null) reject(new Error(String(error || "Browse failed")));
else {
try {
resolve(parseMediaBrowseItems(String(json)));
} catch (parseError) {
reject(new Error(`Browse result parse failed: ${parseError}`));
}
}
});
});
}
playFromMediaId(mediaId: string): void {
if (!this.connected) return;
FaceclawAppleMusic.shared().playCompletion(mediaId, (error: string | null) => {
if (error) console.warn(`[apple-music] play ${mediaId} failed: ${error}`);
});
}
disconnect(): void {
this.connected = false;
this.generation++;
}
}
export const mediaBrowserBridge: MediaBrowserBridge = new AppleMusicBrowserBridge();
+5 -31
View File
@@ -1,22 +1,11 @@
import { Utils } from "@nativescript/core";
import { ignoredMediaPackages, isMediaAppEnabled, MEDIA_APPS_KEY, rememberMediaApps } from "./media-apps";
import { onSettingsStoreChanged } from "./settings-store";
import { parseMediaBrowseItems, type MediaBrowseItem, type MediaBrowserApp, type MediaBrowserBridge } from "./media-types";
declare const com: any;
export type MediaBrowserApp = {
packageName: string;
serviceClass: string;
appName: string;
};
export type MediaBrowseItem = {
mediaId: string;
title: string;
subtitle: string;
browsable: boolean;
playable: boolean;
};
export type { MediaBrowseItem, MediaBrowserApp } from "./media-types";
type PendingRequest<T> = {
resolve: (value: T) => void;
@@ -29,7 +18,7 @@ type PendingRequest<T> = {
* start playback, including starting a player that is not currently running.
* Holds at most one connection at a time.
*/
export class FaceclawMediaBrowserBridge {
export class FaceclawMediaBrowserBridge implements MediaBrowserBridge {
private browser: any = null;
private listenerProxy: any = null;
private nextRequestId = 1;
@@ -155,22 +144,7 @@ export class FaceclawMediaBrowserBridge {
return;
}
try {
const raw = JSON.parse(json) as Array<{
mediaId?: string;
title?: string;
subtitle?: string;
browsable?: boolean;
playable?: boolean;
}>;
pending.resolve(
raw.map((item) => ({
mediaId: String(item.mediaId ?? ""),
title: String(item.title ?? ""),
subtitle: String(item.subtitle ?? ""),
browsable: Boolean(item.browsable),
playable: Boolean(item.playable),
})),
);
pending.resolve(parseMediaBrowseItems(json));
} catch (parseError) {
pending.reject(new Error(`Browse result parse failed: ${parseError}`));
}
@@ -183,4 +157,4 @@ export class FaceclawMediaBrowserBridge {
}
}
export const mediaBrowserBridge = new FaceclawMediaBrowserBridge();
export const mediaBrowserBridge: MediaBrowserBridge = new FaceclawMediaBrowserBridge();
+231
View File
@@ -0,0 +1,231 @@
import { Dialogs, Utils } from "@nativescript/core";
import type { GrayImage } from "../graphics/image";
import { grayImageFromPacket, PHOTO_TONE } from "./image-files";
import { fromData } from "./kotlin-data";
import {
APPLE_MUSIC_APP_NAME,
APPLE_MUSIC_PACKAGE,
DEFAULT_MEDIA_STATE,
type MediaControllerBridge,
type MediaControllerState,
type MediaPlaybackState,
type MediaQueueItem,
} from "./media-types";
export type { MediaControllerState, MediaPlaybackState, MediaQueueItem } from "./media-types";
declare const FaceclawAppleMusic: any;
declare const FaceclawKitIosProtocol: any;
/**
* Re-read the system player this often while something listens: its change
* notifications are not delivered while Faceclaw is suspended, so a track
* change in the background would otherwise wait for the next one.
*/
const POLL_MS = 2_000;
/** Normalize FaceclawAppleMusic.stateJson()'s object. */
export function appleMusicState(raw: any): MediaControllerState {
if (!raw || raw.access !== true) {
return { ...DEFAULT_MEDIA_STATE, status: "Apple Music access is required." };
}
const hasItem = Boolean(raw.hasItem);
const playbackState: MediaPlaybackState = !hasItem
? "idle"
: raw.state === "playing" || raw.state === "paused" || raw.state === "stopped" ? raw.state : "unknown";
const rate = Number(raw.rate);
return {
available: hasItem,
accessEnabled: true,
packageName: APPLE_MUSIC_PACKAGE,
appName: APPLE_MUSIC_APP_NAME,
playbackState,
title: String(raw.title ?? ""),
artist: String(raw.artist ?? ""),
album: String(raw.album ?? ""),
positionMs: finiteOr(raw.positionMs, -1),
durationMs: finiteOr(raw.durationMs, -1),
// The system player reports a zero rate while it is still starting up.
playbackSpeed: playbackState === "playing" ? (rate > 0 ? rate : 1) : 0,
status: hasItem ? "" : "Nothing is playing in Apple Music.",
canPlayPause: hasItem,
canSkipNext: hasItem,
canSkipPrevious: hasItem,
artVersion: finiteOr(raw.artVersion, 0),
};
}
function finiteOr(value: unknown, fallback: number): number {
const number = Number(value);
return typeof value === "number" && Number.isFinite(number) ? number : fallback;
}
/** Everything a listener would redraw for; the position advances on its own. */
function stateSignature(state: MediaControllerState): string {
return JSON.stringify({ ...state, positionMs: 0 });
}
/**
* Apple Music through FaceclawAppleMusic (MediaPlayer's system player): iOS
* gives other apps' players no shared session API, so the system Music app is
* the only player Faceclaw can follow and control. Snapshots read the player
* directly (cheap property reads), so they are current even when a change
* notification was missed.
*/
export class AppleMusicControllerBridge implements MediaControllerBridge {
readonly accessPrompt = "Faceclaw needs access to Apple Music to show and control what's playing. Tap, then allow access on your phone.";
readonly accessLabel = "Apple Music access needed";
readonly accessAction = "allow access";
readonly skipRebuildsQueue = false;
private readonly stateListeners = new Set<(state: MediaControllerState) => void>();
private bound = false;
private started = false;
private pollTimer: ReturnType<typeof setInterval> | null = null;
private lastSignature = "";
private pendingAccess: Promise<boolean> | null = null;
private protocol: any = null;
onStateChange(listener: (state: MediaControllerState) => void): () => void {
void this.start();
this.stateListeners.add(listener);
this.pollTimer ??= setInterval(() => this.refresh(), POLL_MS);
listener(this.snapshot());
return () => {
this.stateListeners.delete(listener);
if (!this.stateListeners.size && this.pollTimer !== null) {
clearInterval(this.pollTimer);
this.pollTimer = null;
}
};
}
snapshot(): MediaControllerState {
let raw: unknown = null;
try {
raw = JSON.parse(String(this.native().stateJson()));
} catch (error) {
console.warn(`[apple-music] state read failed: ${error}`);
}
return appleMusicState(raw);
}
async start(): Promise<void> {
if (this.started) return;
this.started = true;
this.native().start();
}
async stop(): Promise<void> {
if (!this.started) return;
this.started = false;
this.native().stop();
}
async playPause(): Promise<void> {
this.native().playPause();
}
async skipNext(): Promise<void> {
this.native().skipNext();
}
async skipPrevious(): Promise<void> {
this.native().skipPrevious();
}
hasAccess(): boolean {
return Boolean(this.native().hasPermission());
}
/** Concurrent requests (glasses tap, phone Permissions card) share one prompt. */
requestAccess(): Promise<boolean> {
if (this.hasAccess()) return Promise.resolve(true);
this.pendingAccess ??= this.askForAccess().finally(() => {
this.pendingAccess = null;
this.refresh();
});
return this.pendingAccess;
}
async skipToQueueItem(id: number): Promise<void> {
this.native().skipToQueueIndex(Math.round(id));
}
getMediaVolumePercent(): number {
const volume = Number(this.native().volumePercent());
return Number.isFinite(volume) ? Math.max(-1, Math.min(100, Math.round(volume))) : -1;
}
setMediaVolumePercent(volumePercent: number): void {
this.native().setVolumePercent(Math.max(0, Math.min(100, Math.round(volumePercent))));
}
getAlbumArt(maxSize: number): GrayImage | null {
const packet = this.native().albumArt(Math.round(maxSize));
if (!packet) return null;
// The shared Kotlin tone curve and dither, as on Android.
this.protocol ??= FaceclawKitIosProtocol.new();
return grayImageFromPacket(fromData(this.protocol.grayPacketBgraGammaDither(packet, PHOTO_TONE.gamma, PHOTO_TONE.dither)));
}
getQueue(): MediaQueueItem[] {
try {
const raw = JSON.parse(String(this.native().queueJson()));
if (!Array.isArray(raw)) return [];
return raw.map((item: { id?: number; title?: string; active?: boolean }) => ({
id: Number(item?.id ?? -1),
title: String(item?.title ?? ""),
active: Boolean(item?.active),
}));
} catch (error) {
console.warn(`[apple-music] queue parse failed: ${error}`);
return [];
}
}
private native(): any {
const music = FaceclawAppleMusic.shared();
if (!this.bound) {
this.bound = true;
music.changeHandler = () => this.refresh();
}
return music;
}
private refresh(): void {
if (!this.stateListeners.size) return;
const state = this.snapshot();
const signature = stateSignature(state);
if (signature === this.lastSignature) return;
this.lastSignature = signature;
for (const listener of this.stateListeners) listener(state);
}
private async askForAccess(): Promise<boolean> {
const music = this.native();
const status = String(music.permissionStatus());
if (status === "denied") {
const open = await Dialogs.confirm({
title: "Apple Music Access",
message: "Allow Media & Apple Music access in Settings to show and control Apple Music on your glasses.",
okButtonText: "Open Settings",
cancelButtonText: "Cancel",
});
if (open) Utils.openUrl("app-settings:");
return false;
}
if (status === "restricted") {
await Dialogs.alert({
title: "Apple Music Access Restricted",
message: "Media library access is restricted on this iPhone. Check Screen Time or device management settings.",
okButtonText: "OK",
});
return false;
}
return new Promise<boolean>((resolve) => {
music.requestPermission((granted: boolean) => resolve(Boolean(granted)));
});
}
}
export const mediaControllerBridge: MediaControllerBridge = new AppleMusicControllerBridge();
+24 -66
View File
@@ -3,68 +3,25 @@ import { GrayImage } from "../graphics/image";
import { grayImageFromPacket, PHOTO_TONE } from "./image-files";
import { ignoredMediaPackages, MEDIA_APPS_KEY, rememberMediaApps } from "./media-apps";
import { onSettingsStoreChanged } from "./settings-store";
import { isNotificationListenerEnabled } from "./notification-access";
import {
DEFAULT_MEDIA_STATE,
interpolateMediaState,
type MediaControllerBridge,
type MediaControllerState,
type MediaPlaybackState,
type MediaQueueItem,
} from "./media-types";
declare const com: any;
export type MediaQueueItem = {
id: number;
title: string;
active: boolean;
};
export type { MediaControllerState, MediaPlaybackState, MediaQueueItem } from "./media-types";
export type MediaPlaybackState =
| "notification-access-required"
| "idle"
| "playing"
| "paused"
| "buffering"
| "stopped"
| "unknown";
export type MediaControllerState = {
available: boolean;
accessEnabled: boolean;
packageName: string;
appName: string;
playbackState: MediaPlaybackState;
title: string;
artist: string;
album: string;
positionMs: number;
durationMs: number;
playbackSpeed: number;
status: string;
canPlayPause: boolean;
canSkipNext: boolean;
canSkipPrevious: boolean;
/**
* Changes whenever getAlbumArt's result may have changed (any metadata
* update or session switch). Key cached art on this, not the title:
* players re-publish the same strings with a different bitmap.
*/
artVersion: number;
};
const DEFAULT_MEDIA_STATE: MediaControllerState = {
available: false,
accessEnabled: false,
packageName: "",
appName: "",
playbackState: "idle",
title: "",
artist: "",
album: "",
positionMs: -1,
durationMs: -1,
playbackSpeed: 0,
status: "Media controller unavailable.",
canPlayPause: false,
canSkipNext: false,
canSkipPrevious: false,
artVersion: 0,
};
export class FaceclawMediaControllerBridge {
export class FaceclawMediaControllerBridge implements MediaControllerBridge {
readonly accessPrompt = "Notification access is required to control Android media sessions. Tap to open settings.";
readonly accessLabel = "Notification access needed";
readonly accessAction = "open settings";
readonly skipRebuildsQueue = true;
private readonly stateListeners = new Set<(state: MediaControllerState) => void>();
private controller: any = null;
private listenerProxy: any = null;
@@ -79,12 +36,7 @@ export class FaceclawMediaControllerBridge {
}
snapshot(): MediaControllerState {
const state = { ...this.state };
if (state.playbackState === "playing" && state.positionMs >= 0 && state.playbackSpeed !== 0) {
state.positionMs += (Date.now() - this.stateUpdatedAtMs) * state.playbackSpeed;
state.positionMs = Math.max(0, state.durationMs > 0 ? Math.min(state.positionMs, state.durationMs) : state.positionMs);
}
return state;
return interpolateMediaState(this.state, this.stateUpdatedAtMs, Date.now());
}
async start(): Promise<void> {
@@ -115,9 +67,15 @@ export class FaceclawMediaControllerBridge {
this.controller?.skipPrevious();
}
openNotificationAccessSettings(): void {
hasAccess(): boolean {
return isNotificationListenerEnabled();
}
/** Opens the notification-access settings screen; the grant is only visible once the app resumes. */
async requestAccess(): Promise<boolean> {
this.ensureController();
this.controller?.openNotificationAccessSettings();
return false;
}
/** Jump playback to a queue item (see getQueue). */
@@ -257,4 +215,4 @@ function normalizePlaybackState(value: string): MediaPlaybackState {
}
}
export const mediaControllerBridge = new FaceclawMediaControllerBridge();
export const mediaControllerBridge: MediaControllerBridge = new FaceclawMediaControllerBridge();
+161
View File
@@ -0,0 +1,161 @@
import type { GrayImage } from "../graphics/image";
/**
* Shapes shared by the media bridges: media-controller.ts / media-browser.ts
* drive Android media sessions and MediaBrowserServices; their .ios.ts
* counterparts drive Apple Music through the MediaPlayer framework.
*/
/** The player behind the iOS bridges: the system Music app. */
export const APPLE_MUSIC_APP_NAME = "Apple Music";
export const APPLE_MUSIC_PACKAGE = "com.apple.Music";
export type MediaQueueItem = {
id: number;
title: string;
active: boolean;
};
export type MediaPlaybackState =
| "notification-access-required"
| "idle"
| "playing"
| "paused"
| "buffering"
| "stopped"
| "unknown";
export type MediaControllerState = {
available: boolean;
accessEnabled: boolean;
packageName: string;
appName: string;
playbackState: MediaPlaybackState;
title: string;
artist: string;
album: string;
positionMs: number;
durationMs: number;
playbackSpeed: number;
status: string;
canPlayPause: boolean;
canSkipNext: boolean;
canSkipPrevious: boolean;
/**
* Changes whenever getAlbumArt's result may have changed (any metadata
* update or session switch). Key cached art on this, not the title:
* players re-publish the same strings with a different bitmap.
*/
artVersion: number;
};
export const DEFAULT_MEDIA_STATE: MediaControllerState = {
available: false,
accessEnabled: false,
packageName: "",
appName: "",
playbackState: "idle",
title: "",
artist: "",
album: "",
positionMs: -1,
durationMs: -1,
playbackSpeed: 0,
status: "Media controller unavailable.",
canPlayPause: false,
canSkipNext: false,
canSkipPrevious: false,
artVersion: 0,
};
/** Interpolate the position of a playing item from the last state update. */
export function interpolateMediaState(state: MediaControllerState, updatedAtMs: number, nowMs: number): MediaControllerState {
const result = { ...state };
if (result.playbackState === "playing" && result.positionMs >= 0 && result.playbackSpeed !== 0) {
result.positionMs += (nowMs - updatedAtMs) * result.playbackSpeed;
result.positionMs = Math.max(0, result.durationMs > 0 ? Math.min(result.positionMs, result.durationMs) : result.positionMs);
}
return result;
}
export interface MediaControllerBridge {
/** Explains, on the glasses, what access is missing and that a tap asks for it. */
readonly accessPrompt: string;
/** The missing access as a short card label. */
readonly accessLabel: string;
/** What clicking the access prompt does, for its gesture hint. */
readonly accessAction: string;
/**
* Whether jumping to a queue item rebuilds the queue with that item first
* (Android players do); otherwise the queue keeps its order.
*/
readonly skipRebuildsQueue: boolean;
onStateChange(listener: (state: MediaControllerState) => void): () => void;
snapshot(): MediaControllerState;
start(): Promise<void>;
stop(): Promise<void>;
playPause(): Promise<void>;
skipNext(): Promise<void>;
skipPrevious(): Promise<void>;
hasAccess(): boolean;
/** Show the grant UI: a system settings screen or a permission prompt on the phone. */
requestAccess(): Promise<boolean>;
/** Jump playback to a queue item (see getQueue). */
skipToQueueItem(id: number): Promise<void>;
/** Media volume normalized to 0..100; -1 when unavailable. */
getMediaVolumePercent(): number;
setMediaVolumePercent(volumePercent: number): void;
/**
* Album art for the current item, grayscale with the shared photo tone
* (gamma-corrected and dithered onto the display's 16 levels), scaled to
* fit maxSize; null when the player provides none.
*/
getAlbumArt(maxSize: number): GrayImage | null;
/** The player's queue (playlist), empty when the player exposes none. */
getQueue(): MediaQueueItem[];
}
export type MediaBrowserApp = {
packageName: string;
serviceClass: string;
appName: string;
};
export type MediaBrowseItem = {
mediaId: string;
title: string;
subtitle: string;
browsable: boolean;
playable: boolean;
};
export interface MediaBrowserBridge {
/** Apps whose library can be browsed; cached after the first call. */
listBrowsableApps(refresh?: boolean): MediaBrowserApp[];
/** Connect to an app's library, replacing any existing connection. Resolves to the browse-tree root id. */
connect(app: MediaBrowserApp): Promise<string>;
/** Fetch one level of the connected library's tree. */
browse(parentId: string): Promise<MediaBrowseItem[]>;
/** Start playback of a browsed item. */
playFromMediaId(mediaId: string): void;
/** Drop the connection; in-flight requests are rejected. */
disconnect(): void;
}
/** Parse a browse listing's JSON rows. */
export function parseMediaBrowseItems(json: string): MediaBrowseItem[] {
const raw = JSON.parse(json) as Array<{
mediaId?: string;
title?: string;
subtitle?: string;
browsable?: boolean;
playable?: boolean;
}>;
return raw.map((item) => ({
mediaId: String(item.mediaId ?? ""),
title: String(item.title ?? ""),
subtitle: String(item.subtitle ?? ""),
browsable: Boolean(item.browsable),
playable: Boolean(item.playable),
}));
}