react-native-queue-player 1.0.0

package/app.plugin.js

@@ -0,0 +1,466 @@
+/* eslint-disable */
+const fs = require('fs');
+const path = require('path');
+const {
+  withDangerousMod,
+  withEntitlementsPlist,
+  withInfoPlist,
+} = require('@expo/config-plugins');
+
+/**
+ * react-native-queue-player Expo config plugin.
+ *
+ * Always-on:
+ *  - `AVInitialRouteSharingPolicy = LongFormAudio` so a cold-start
+ *    (Siri, CarPlay launch, lock-screen widget) routes to the user's
+ *    last-active long-form output (AirPods, AirPlay 2, CarPlay)
+ *    BEFORE the lib's Swift code runs. Without this, the first
+ *    ~150ms route to the device speaker.
+ *  - `UIBackgroundModes` includes `audio` so playback continues when
+ *    the app is backgrounded / the screen locks (required for any
+ *    background audio). Enabled by default; opt out with
+ *    `{ enableIosBGAudio: false }` if your app declares it elsewhere.
+ *
+ * Opt-in CarPlay (`{ carplay: true }`):
+ *  - Adds the `com.apple.developer.carplay-audio` entitlement.
+ *  - Adds `UIApplicationSceneManifest` declaring BOTH the phone
+ *    window scene (`UIWindowSceneSessionRoleApplication`) and the
+ *    CarPlay scene (`CPTemplateApplicationSceneSessionRoleApplication`).
+ *
+ * Opt-in Siri (`{ siri: true }`):
+ *  - Adds the `com.apple.developer.siri` entitlement.
+ *  - Declares SiriKit `INPlayMediaIntent` support via Info.plist
+ *    (`INIntentsSupported`, `INSupportedMediaCategories`,
+ *    `NSUserActivityTypes`).
+ *  - Adds the music-domain `LSApplicationCategoryType` + a default
+ *    `NSSiriUsageDescription` placeholder.
+ *  - Injects an `application(_:handlerFor:)` override into the
+ *    AppDelegate that routes `INPlayMediaIntent` through the lib's
+ *    `QueuePlayerMediaIntents.handler(forIntent:)` selector. Free-text
+ *    "Hey Siri play X on MyApp" lands in the JS resolver wired via
+ *    `onPlayFromSearchRequest`. The lib stays opinion-free about which
+ *    music search results to play; the consumer's JS does its own
+ *    catalog search + setQueue + play.
+ *  - Siri is a self-serve capability on developer.apple.com — EAS
+ *    Build auto-toggles the App ID flag; local Xcode builds need a
+ *    one-time Capabilities-pane toggle if running without automatic
+ *    signing.
+ *
+ * Usage in app.json:
+ *
+ *     "plugins": [
+ *       ["react-native-queue-player", { "carplay": true, "siri": true }]
+ *     ]
+ */
+
+const PHONE_SCENE_DELEGATE = 'WindowApplicationSceneDelegate';
+const CARPLAY_SCENE_DELEGATE = 'CarPlaySceneDelegate';
+const CARPLAY_CONFIG_NAME = 'CarPlay';
+const PHONE_CONFIG_NAME = 'Default Configuration';
+
+const withCarPlayInfoPlist = (config) =>
+  withInfoPlist(config, (cfg) => {
+    cfg.modResults.UIApplicationSupportsMultipleScenes = true;
+    cfg.modResults.UIApplicationSceneManifest = {
+      UIApplicationSupportsMultipleScenes: true,
+      UISceneConfigurations: {
+        UIWindowSceneSessionRoleApplication: [
+          {
+            UISceneConfigurationName: PHONE_CONFIG_NAME,
+            UISceneDelegateClassName: PHONE_SCENE_DELEGATE,
+          },
+        ],
+        CPTemplateApplicationSceneSessionRoleApplication: [
+          {
+            UISceneClassName: 'CPTemplateApplicationScene',
+            UISceneConfigurationName: CARPLAY_CONFIG_NAME,
+            UISceneDelegateClassName: CARPLAY_SCENE_DELEGATE,
+          },
+        ],
+      },
+    };
+    return cfg;
+  });
+
+const withCarPlayEntitlement = (config) =>
+  withEntitlementsPlist(config, (cfg) => {
+    cfg.modResults['com.apple.developer.carplay-audio'] = true;
+    return cfg;
+  });
+
+const withSiriEntitlement = (config) =>
+  withEntitlementsPlist(config, (cfg) => {
+    cfg.modResults['com.apple.developer.siri'] = true;
+    return cfg;
+  });
+
+const withSiriInfoPlist = (config) =>
+  withInfoPlist(config, (cfg) => {
+    // App Store category — Apple recommends setting it for any
+    // music-domain app and Siri's audio routing heuristics read it.
+    if (!cfg.modResults.LSApplicationCategoryType) {
+      cfg.modResults.LSApplicationCategoryType = 'public.app-category.music';
+    }
+    // App Store Review historically rejects builds that hold the
+    // `com.apple.developer.siri` entitlement without a usage-
+    // description string. Defensive placeholder; consumers should
+    // override with their own user-facing copy.
+    if (!cfg.modResults.NSSiriUsageDescription) {
+      cfg.modResults.NSSiriUsageDescription =
+        'Voice playback uses Siri to find and play music in this app.';
+    }
+    // iOS rejects `INPlayMediaIntent` dispatch to a third-party
+    // `application(_:handlerFor:)` when `NSAppleMusicUsageDescription`
+    // is absent, even when the app never touches the Apple Music
+    // library. Defensive placeholder; consumers should override with
+    // their own user-facing copy.
+    if (!cfg.modResults.NSAppleMusicUsageDescription) {
+      cfg.modResults.NSAppleMusicUsageDescription =
+        'Voice playback resolves search queries through this app to play music.';
+    }
+    // Declares the SiriKit intents the app handles. INPlayMediaIntent
+    // is the music-domain intent that backs "Hey Siri play X on
+    // MyApp" — Siri parses the user's free-text utterance into a
+    // structured `INMediaSearch` and routes it to our handler.
+    const ensureInArray = (key, value) => {
+      const existing = Array.isArray(cfg.modResults[key])
+        ? cfg.modResults[key]
+        : [];
+      if (!existing.includes(value)) {
+        cfg.modResults[key] = [...existing, value];
+      }
+    };
+    ensureInArray('INIntentsSupported', 'INPlayMediaIntent');
+    ensureInArray('NSUserActivityTypes', 'INPlayMediaIntent');
+    // INSupportedMediaCategories declares which SiriKit media-domain
+    // taxonomies the app's INPlayMediaIntent handler can serve. The
+    // string values are the exact `INMediaCategory…` enum case names;
+    // lowercased keywords are silently rejected. `INMediaCategoryMusic`
+    // is the primary library category; `INMediaCategoryGeneral` is the
+    // catch-all that lets Siri route any audio-domain "play X on
+    // MyApp" utterance through our handler.
+    if (!cfg.modResults.INSupportedMediaCategories) {
+      cfg.modResults.INSupportedMediaCategories = [
+        'INMediaCategoryMusic',
+        'INMediaCategoryGeneral',
+      ];
+    }
+    return cfg;
+  });
+
+/**
+ * Inject `application(_:handlerFor:)` into the consumer's AppDelegate
+ * so SiriKit `INPlayMediaIntent` dispatches route to the lib's
+ * `QueuePlayerMediaIntents.handler(forIntent:)`. Idempotent — re-running
+ * `expo prebuild` replaces the existing block in-place rather than
+ * appending duplicates.
+ */
+const SIRI_HANDLER_MARKER = '// react-native-queue-player: SiriKit INPlayMediaIntent handler';
+const SIRI_HANDLER_BLOCK = `  ${SIRI_HANDLER_MARKER} (auto-generated, do not edit; see react-native-queue-player/app.plugin.js)
+  @objc(application:handlerForIntent:)
+  public func application(
+    _ application: UIApplication,
+    handlerFor intent: INIntent
+  ) -> Any? {
+    guard let cls = NSClassFromString("QueuePlayerMediaIntents") else {
+      return nil
+    }
+    let selector = NSSelectorFromString("handlerForIntent:")
+    let meta: AnyClass? = object_getClass(cls)
+    guard meta?.instancesRespond(to: selector) ?? false else {
+      return nil
+    }
+    return (cls as AnyObject).perform(selector, with: intent)?.takeUnretainedValue()
+  }
+`;
+
+const SIRI_IMPORT_MARKER = '// react-native-queue-player: Intents import';
+const SIRI_IMPORT_LINE = `${SIRI_IMPORT_MARKER}\nimport Intents`;
+
+const withSiriAppDelegate = (config) =>
+  withDangerousMod(config, [
+    'ios',
+    async (cfg) => {
+      const appDelegatePath = path.join(
+        cfg.modRequest.platformProjectRoot,
+        cfg.modRequest.projectName,
+        'AppDelegate.swift'
+      );
+      let contents = fs.readFileSync(appDelegatePath, 'utf8');
+
+      // Ensure `import Intents` near the top.
+      if (!contents.includes(SIRI_IMPORT_MARKER)) {
+        contents = contents.replace(
+          /^(internal import Expo)/m,
+          `${SIRI_IMPORT_LINE}\n$1`
+        );
+      }
+
+      // Strip every prior generated block before re-inserting. Global
+      // flag so a manually-duplicated marker doesn't leave orphans.
+      const priorBlock = new RegExp(
+        `\\n\\s*${escapeRegex(SIRI_HANDLER_MARKER)}[\\s\\S]*?\\n\\s*\\}\\n`,
+        'gm'
+      );
+      contents = contents.replace(priorBlock, '\n');
+
+      // Insert the block just before the AppDelegate class's closing
+      // brace. The location is found via a balanced-brace scan starting
+      // from the `class AppDelegate { … }` header so reordering or
+      // adding sibling classes doesn't push the insertion into the
+      // wrong class body.
+      const insertionPoint = findAppDelegateClosingBraceIndex(contents);
+      if (insertionPoint === -1) {
+        throw new Error(
+          '[react-native-queue-player] Failed to locate AppDelegate class body — Expo template likely changed; update with-siri-app-delegate logic.'
+        );
+      }
+      contents =
+        contents.slice(0, insertionPoint) +
+        '\n' +
+        SIRI_HANDLER_BLOCK +
+        contents.slice(insertionPoint);
+
+      fs.writeFileSync(appDelegatePath, contents);
+      return cfg;
+    },
+  ]);
+
+function escapeRegex(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+/**
+ * Locate the closing `}` of the `class AppDelegate { … }` declaration
+ * via a balanced-brace scan that skips Swift string literals and
+ * line / block comments. Returns the index of the closing brace, or
+ * -1 if no AppDelegate class header is found or the braces are
+ * unbalanced.
+ */
+function findAppDelegateClosingBraceIndex(contents) {
+  const headerMatch = contents.match(/^class\s+AppDelegate\b[^{]*\{/m);
+  if (!headerMatch || headerMatch.index === undefined) return -1;
+  let depth = 1;
+  let inString = false;
+  let inLineComment = false;
+  let inBlockComment = false;
+  for (let i = headerMatch.index + headerMatch[0].length; i < contents.length; i++) {
+    const ch = contents[i];
+    const next = contents[i + 1];
+    if (inLineComment) {
+      if (ch === '\n') inLineComment = false;
+      continue;
+    }
+    if (inBlockComment) {
+      if (ch === '*' && next === '/') { inBlockComment = false; i++; }
+      continue;
+    }
+    if (inString) {
+      if (ch === '\\') { i++; continue; }
+      if (ch === '"') inString = false;
+      continue;
+    }
+    if (ch === '"') { inString = true; continue; }
+    if (ch === '/' && next === '/') { inLineComment = true; i++; continue; }
+    if (ch === '/' && next === '*') { inBlockComment = true; i++; continue; }
+    if (ch === '{') depth++;
+    else if (ch === '}') {
+      depth--;
+      if (depth === 0) return i;
+    }
+  }
+  return -1;
+}
+
+/**
+ * Opt-in Chromecast support. Adds the `QueuePlayer/Chromecast` subspec
+ * to the consumer Podfile (pulls in `google-cast-sdk ~> 4.8.4`), plus
+ * the Info.plist keys Cast SDK 4.8.4+ requires:
+ *
+ *  - `NSBonjourServices` — both `_googlecast._tcp` (generic discovery)
+ *    and `_<receiverAppId>._googlecast._tcp` (custom receiver).
+ *  - `NSLocalNetworkUsageDescription` — iOS 14+ LNA gate copy.
+ *  - `QueuePlayerChromecastReceiverApplicationID` — receiver app ID
+ *    consumed by `ChromecastSupport.installWithDefaults()`. Defaults
+ *    to `CC1AD845` (Google Default Media Receiver).
+ *
+ * Injects an `application(_:didFinishLaunchingWithOptions:)` hook
+ * into the consumer's AppDelegate calling
+ * `ChromecastSupport.installWithDefaults()` so the Cast SDK
+ * initialises at app launch. The selector is dispatched via
+ * `NSClassFromString` so the AppDelegate doesn't directly `import
+ * QueuePlayer` (avoids static_framework + NitroModules umbrella-
+ * header issues — see NOTES.md §26).
+ */
+const withChromecastSubspecPodfile = (config) =>
+  withDangerousMod(config, [
+    'ios',
+    async (cfg) => {
+      const podfilePath = path.join(cfg.modRequest.platformProjectRoot, 'Podfile');
+      if (!fs.existsSync(podfilePath)) return cfg;
+      let contents = fs.readFileSync(podfilePath, 'utf8');
+      const marker = '# react-native-queue-player: Chromecast subspec';
+      if (contents.includes(marker)) return cfg;
+      // Resolve the lib's filesystem path the same way `node` does
+      // (`require.resolve` walks the package tree the consumer app has
+      // installed). Convert it to a path relative to the iOS Podfile
+      // so the CocoaPods `:path =>` resolution matches autolinking,
+      // regardless of monorepo layout (sibling, hoisted, pnpm, etc.).
+      const libPackagePath = path.dirname(
+        require.resolve('react-native-queue-player/package.json', {
+          paths: [cfg.modRequest.projectRoot],
+        })
+      );
+      const relLibPath = path
+        .relative(cfg.modRequest.platformProjectRoot, libPackagePath)
+        .replace(/\\/g, '/');
+      // Insert AFTER use_react_native! so autolinking has resolved
+      // the main QueuePlayer pod by the time the subspec reference
+      // is evaluated. Anchor on the closing `)` of `use_react_native!`.
+      const line = `\n  ${marker}\n  pod 'QueuePlayer/Chromecast', :path => '${relLibPath}'\n`;
+      const anchor = contents.match(/use_react_native!\([\s\S]*?\n  \)/);
+      if (anchor) {
+        const idx = anchor.index + anchor[0].length;
+        contents = contents.slice(0, idx) + line + contents.slice(idx);
+      } else {
+        // Fallback: insert before post_install.
+        contents = contents.replace(/(  post_install do)/, `${line}$1`);
+      }
+      fs.writeFileSync(podfilePath, contents);
+      return cfg;
+    },
+  ]);
+
+const withChromecastInfoPlist = (config, receiverAppId) =>
+  withInfoPlist(config, (cfg) => {
+    const appId = (receiverAppId || 'CC1AD845').toUpperCase();
+    cfg.modResults.QueuePlayerChromecastReceiverApplicationID = appId;
+
+    if (!cfg.modResults.NSLocalNetworkUsageDescription) {
+      cfg.modResults.NSLocalNetworkUsageDescription =
+        'Discover Chromecast and AirPlay receivers on your local network.';
+    }
+
+    const existingBonjour = Array.isArray(cfg.modResults.NSBonjourServices)
+      ? cfg.modResults.NSBonjourServices
+      : [];
+    const additions = ['_googlecast._tcp', `_${appId}._googlecast._tcp`];
+    for (const s of additions) {
+      if (!existingBonjour.includes(s)) existingBonjour.push(s);
+    }
+    cfg.modResults.NSBonjourServices = existingBonjour;
+    return cfg;
+  });
+
+const CHROMECAST_INSTALL_MARKER_BEGIN =
+  '// react-native-queue-player: Chromecast install begin';
+const CHROMECAST_INSTALL_MARKER_END =
+  '// react-native-queue-player: Chromecast install end';
+const CHROMECAST_INSTALL_SNIPPET = `    ${CHROMECAST_INSTALL_MARKER_BEGIN} (auto-generated, do not edit; see react-native-queue-player/app.plugin.js)
+    if let cls = NSClassFromString("ChromecastSupport") {
+      let selector = NSSelectorFromString("installWithDefaults")
+      let meta: AnyClass? = object_getClass(cls)
+      if meta?.instancesRespond(to: selector) ?? false {
+        _ = (cls as AnyObject).perform(selector)
+      }
+    }
+    ${CHROMECAST_INSTALL_MARKER_END}
+`;
+
+/**
+ * Find the `return super.application(application, didFinishLaunchingWithOptions: launchOptions)`
+ * line inside the AppDelegate's existing `didFinishLaunchingWithOptions`
+ * override and insert the Chromecast install snippet immediately before it.
+ *
+ * The Expo-Router managed AppDelegate already declares the
+ * `application(_:didFinishLaunchingWithOptions:)` override; declaring it
+ * a second time is a Swift compile error. Inlining the
+ * `ChromecastSupport.installWithDefaults()` call inside the existing
+ * method body sidesteps the conflict and runs at the same point in the
+ * launch sequence.
+ */
+const withChromecastAppDelegate = (config) =>
+  withDangerousMod(config, [
+    'ios',
+    async (cfg) => {
+      const appDelegatePath = path.join(
+        cfg.modRequest.platformProjectRoot,
+        cfg.modRequest.projectName,
+        'AppDelegate.swift'
+      );
+      if (!fs.existsSync(appDelegatePath)) return cfg;
+      let contents = fs.readFileSync(appDelegatePath, 'utf8');
+
+      // Idempotent strip of any prior begin..end block + any legacy
+      // duplicate-override block from earlier plugin versions.
+      const beginEndStrip = new RegExp(
+        `[ \\t]*${escapeRegex(CHROMECAST_INSTALL_MARKER_BEGIN)}[\\s\\S]*?${escapeRegex(CHROMECAST_INSTALL_MARKER_END)}\\n`,
+        'g'
+      );
+      contents = contents.replace(beginEndStrip, '');
+      const legacyDuplicateOverride = new RegExp(
+        `\\n\\s*// react-native-queue-player: Chromecast install[^\\n]*\\n\\s*@objc public override func application\\([\\s\\S]*?\\n\\s*\\}\\n`,
+        'g'
+      );
+      contents = contents.replace(legacyDuplicateOverride, '\n');
+
+      // Insert the install snippet on its own lines immediately before the
+      // existing `return super.application(...)` line so it runs as part of
+      // the established launch hook.
+      const returnLine =
+        /(\n[ \t]*)return super\.application\(application, didFinishLaunchingWithOptions: launchOptions\)/;
+      if (!returnLine.test(contents)) {
+        // No didFinishLaunchingWithOptions present yet; nothing to inject.
+        fs.writeFileSync(appDelegatePath, contents);
+        return cfg;
+      }
+      // `indent` is the newline + leading whitespace ahead of the return; reuse
+      // it to indent the snippet's first line, and keep the matched return
+      // statement intact after it.
+      contents = contents.replace(
+        returnLine,
+        (returnStatement, indent) =>
+          `${indent}${CHROMECAST_INSTALL_SNIPPET.trim()}${returnStatement}`
+      );
+      fs.writeFileSync(appDelegatePath, contents);
+      return cfg;
+    },
+  ]);
+
+const withQueuePlayer = (config, props = {}) => {
+  // Background audio is on by default; a consumer that manages
+  // UIBackgroundModes itself can opt out with `enableIosBGAudio: false`.
+  const enableIosBGAudio = !props || props.enableIosBGAudio !== false;
+  let next = withInfoPlist(config, (cfg) => {
+    cfg.modResults.AVInitialRouteSharingPolicy = 'LongFormAudio';
+    if (enableIosBGAudio) {
+      const modes = Array.isArray(cfg.modResults.UIBackgroundModes)
+        ? cfg.modResults.UIBackgroundModes
+        : [];
+      if (!modes.includes('audio')) modes.push('audio');
+      cfg.modResults.UIBackgroundModes = modes;
+    }
+    return cfg;
+  });
+
+  if (props && props.carplay === true) {
+    next = withCarPlayInfoPlist(next);
+    next = withCarPlayEntitlement(next);
+  }
+
+  if (props && props.siri === true) {
+    next = withSiriInfoPlist(next);
+    next = withSiriEntitlement(next);
+    next = withSiriAppDelegate(next);
+  }
+
+  if (props && props.chromecast === true) {
+    next = withChromecastSubspecPodfile(next);
+    next = withChromecastInfoPlist(next, props.chromecastReceiverAppId);
+    next = withChromecastAppDelegate(next);
+  }
+
+  return next;
+};
+
+module.exports = withQueuePlayer;

package/ios/AVPlayerItemQueueItemId.swift

@@ -0,0 +1,61 @@
+import AVFoundation
+
+/// Lib-generated unique identifier per AVPlayerItem instance.
+///
+/// Set by `AVQueueBuilder.makeItem` at construction to a fresh
+/// UUID supplied by the caller (`TrackPlayer` pre-allocates one
+/// per queue position alongside `self.tracks`). Used by
+/// `TrackPlayer.matchTrackIndex` (paired with the `queueItemIds`
+/// parallel array) to resolve `player.currentItem` back to a
+/// position in `self.tracks`.
+///
+/// **CRITICAL — never derive from consumer-supplied data.** Only
+/// `track.url` is required + reliable on `TrackItem`. Every other
+/// consumer field — `id`, `title`, `artist`, `album`, `duration`,
+/// `artworkUrl`, `extras` — may be empty / missing / duplicate /
+/// colliding. Internal identity keys must be lib-generated. The
+/// naming `queueItemId` (not `trackId`) is deliberate: it signals
+/// lib-internal-and-per-item purpose, distinguishing from the
+/// consumer-facing `track.id`.
+///
+/// Why associated-object: AVPlayerItem is an NSObject subclass
+/// with no Swift stored properties for arbitrary metadata.
+/// Subclassing is heavy + brittle (would need to route every API
+/// returning AVPlayerItem through a custom-subclass cast). The
+/// Obj-C runtime API (imported into Swift via Foundation) is the
+/// standard idiom — no `.m` / `.h` source files introduced.
+private var queueItemIdKey: UInt8 = 0
+private var sourceURLKey: UInt8 = 0
+
+extension AVPlayerItem {
+  /// Lib-internal identity for this AVPlayerItem. Set once at
+  /// construction by `AVQueueBuilder.makeItem`; never mutated
+  /// after. nil only for AVPlayerItems that did not flow through
+  /// the lib's queue construction path (e.g. raw makeItemRaw
+  /// XCTest fixtures).
+  var queueItemId: String? {
+    get { objc_getAssociatedObject(self, &queueItemIdKey) as? String }
+    set {
+      objc_setAssociatedObject(
+        self, &queueItemIdKey, newValue, .OBJC_ASSOCIATION_RETAIN_NONATOMIC)
+    }
+  }
+
+  /// The exact `track.url` string this item was built from. Stored
+  /// verbatim — `LookaheadCache` keys entries by raw URL-string
+  /// equality, so a re-resolution against the cache must use the same
+  /// string the cache was keyed with, NOT the item's `AVURLAsset.url`
+  /// (which is already a `file://` path once an item is built from a
+  /// cached local file, and is a parse/re-serialize round-trip of the
+  /// original for a remote item). Lets a later attach (crossfade
+  /// skip / fade-arm) look the track up in the cache and swap a
+  /// remote-built item for its local cache file once it finishes
+  /// downloading.
+  var sourceURL: String? {
+    get { objc_getAssociatedObject(self, &sourceURLKey) as? String }
+    set {
+      objc_setAssociatedObject(
+        self, &sourceURLKey, newValue, .OBJC_ASSOCIATION_RETAIN_NONATOMIC)
+    }
+  }
+}