@legendapp/spark 0.0.1-next.2 → 0.0.1-next.4

package/vendor/node_modules/@legendapp/spark-audio/macos/RNSparkAudio.mm

@@ -1,6 +1,52 @@
 #import "RNSparkAudio.h"
 #import <AVFoundation/AVFoundation.h>
 #import <MediaPlayer/MediaPlayer.h>
+/** Native observation exists only while the corresponding public status stream is observed. */
+@interface SparkAudioObservation : NSObject
+@property AVPlayer *player;
+@property id timeObserver;
+@property id endObserver;
+@property NSArray<NSString *> *keys;
+@property (copy) void (^notify)(void);
+@property BOOL stopped;
+- (instancetype)initWithPlayer:(AVPlayer *)player notify:(void (^)(void))notify;
+- (instancetype)initWithPlayer:(AVPlayer *)player positionUpdates:(BOOL)positionUpdates notify:(void (^)(void))notify;
+- (void)remove;
+@end
+@implementation SparkAudioObservation
+- (instancetype)initWithPlayer:(AVPlayer *)player notify:(void (^)(void))notify {
+  return [self initWithPlayer:player positionUpdates:YES notify:notify];
+}
+- (instancetype)initWithPlayer:(AVPlayer *)player positionUpdates:(BOOL)positionUpdates notify:(void (^)(void))notify {
+  if (self = [super init]) {
+    self.player = player; self.notify = notify;
+    self.keys = positionUpdates ? @[@"status", @"timeControlStatus", @"volume", @"currentItem.status", @"currentItem.duration"] : @[@"status", @"currentItem.status"];
+    for (NSString *key in self.keys)
+      [player addObserver:self forKeyPath:key options:NSKeyValueObservingOptionNew context:nil];
+    __weak SparkAudioObservation *weakSelf = self;
+    if (positionUpdates) self.timeObserver = [player addPeriodicTimeObserverForInterval:CMTimeMake(1, 4) queue:dispatch_get_main_queue() usingBlock:^(CMTime time) {
+      SparkAudioObservation *owner = weakSelf; if (owner && !owner.stopped) owner.notify();
+    }];
+    if (positionUpdates) self.endObserver = [NSNotificationCenter.defaultCenter addObserverForName:AVPlayerItemDidPlayToEndTimeNotification object:player.currentItem queue:NSOperationQueue.mainQueue usingBlock:^(NSNotification *event) {
+      SparkAudioObservation *owner = weakSelf; if (owner && !owner.stopped) owner.notify();
+    }];
+  }
+  return self;
+}
+- (void)observeValueForKeyPath:(NSString *)key ofObject:(id)object change:(NSDictionary *)change context:(void *)context {
+  if (NSThread.isMainThread) { if (!self.stopped) self.notify(); }
+  else { __weak SparkAudioObservation *weakSelf = self; dispatch_async(dispatch_get_main_queue(), ^{ SparkAudioObservation *owner = weakSelf; if (owner && !owner.stopped) owner.notify(); }); }
+}
+- (void)remove {
+  if (self.stopped) return;
+  self.stopped = YES;
+  for (NSString *key in self.keys) [self.player removeObserver:self forKeyPath:key];
+  if (self.timeObserver) [self.player removeTimeObserver:self.timeObserver];
+  if (self.endObserver) [NSNotificationCenter.defaultCenter removeObserver:self.endObserver];
+  self.timeObserver = nil; self.endObserver = nil; self.notify = nil;
+}
+- (void)dealloc { [self remove]; }
+@end
 @interface RNSparkAudio ()
 @property NSMutableDictionary<NSString *, AVPlayer *> *players;
 @property NSString *activeID;
@@ -8,7 +54,11 @@
 @property NSMutableDictionary<NSString *, id> *targets;
 @property NSString *sessionID;
 @property NSMutableDictionary *session;
-@property NSMutableArray *commands;
+@property NSMutableDictionary<NSString *, SparkAudioObservation *> *observations;
+@property NSMutableDictionary<NSString *, NSDictionary *> *lastStatuses;
+@property NSMutableDictionary<NSString *, id> *endObservers;
+@property NSMutableDictionary<NSString *, SparkAudioObservation *> *readiness;
+@property NSMutableDictionary *readyRejects;
 @property NSUInteger artworkGeneration;
 @end
 static NSDictionary *MediaInfo(NSDictionary *metadata) {
@@ -28,9 +78,12 @@ static NSDictionary<NSString *, MPRemoteCommand *> *RemoteCommands() {
 @implementation RNSparkAudio
 RCT_EXPORT_MODULE(NativeSparkAudio)
 + (BOOL)requiresMainQueueSetup { return YES; }
+- (NSArray<NSString *> *)supportedEvents { return @[@"sparkMediaCommand", @"sparkAudioStatus"]; }
 - (instancetype)init { if (self = [super init]) {
   _players = [NSMutableDictionary new];
-  _metadata = [NSMutableDictionary new]; _targets = [NSMutableDictionary new]; _commands = [NSMutableArray new];
+  _metadata = [NSMutableDictionary new]; _targets = [NSMutableDictionary new];
+  _observations = [NSMutableDictionary new]; _lastStatuses = [NSMutableDictionary new]; _endObservers = [NSMutableDictionary new];
+  _readiness = [NSMutableDictionary new]; _readyRejects = [NSMutableDictionary new];
   __weak RNSparkAudio *weakSelf = self;
   [RemoteCommands() enumerateKeysAndObjectsUsingBlock:^(NSString *name, MPRemoteCommand *command, BOOL *stop) {
     command.enabled = [@[@"play", @"pause", @"seekTo"] containsObject:name];
@@ -43,18 +96,41 @@ RCT_EXPORT_MODULE(NativeSparkAudio)
           if (![owner.session[@"commands"] containsObject:name]) return;
           NSMutableDictionary *value = [@{@"command": name} mutableCopy];
           if ([event isKindOfClass:MPChangePlaybackPositionCommandEvent.class]) value[@"position"] = @(((MPChangePlaybackPositionCommandEvent *)event).positionTime);
-          if (owner.commands.count < 128) [owner.commands addObject:value];
+          [owner sendEventWithName:@"sparkMediaCommand" body:@{@"id": owner.sessionID, @"value": value}];
         } else {
           AVPlayer *player = owner.players[owner.activeID ?: @""];
           if ([name isEqual:@"play"]) [player play];
           else if ([name isEqual:@"pause"]) [player pause];
           else if ([event isKindOfClass:MPChangePlaybackPositionCommandEvent.class]) [player seekToTime:CMTimeMakeWithSeconds(((MPChangePlaybackPositionCommandEvent *)event).positionTime, 600)];
+          [owner publishPlayer:owner.activeID];
         }
       });
       return MPRemoteCommandHandlerStatusSuccess;
     }];
   }];
 } return self; }
+- (NSDictionary *)statusForPlayer:(AVPlayer *)player {
+  double position = CMTimeGetSeconds(player.currentTime), duration = CMTimeGetSeconds(player.currentItem.duration);
+  if (!isfinite(position)) position = 0; if (!isfinite(duration)) duration = 0;
+  NSError *error = player.error ?: player.currentItem.error;
+  return @{ @"volume": @(player.volume), @"playing": @(player.timeControlStatus == AVPlayerTimeControlStatusPlaying), @"currentTime": @(position), @"duration": @(duration), @"didJustFinish": @(duration > 0 && position >= duration && player.rate == 0), @"error": error.localizedDescription ?: NSNull.null };
+}
+- (void)emitStatus:(NSString *)identifier {
+  AVPlayer *player = self.players[identifier]; if (!player || !self.observations[identifier]) return;
+  NSDictionary *status = [self statusForPlayer:player];
+  if ([self.lastStatuses[identifier] isEqual:status]) return;
+  self.lastStatuses[identifier] = status;
+  [self sendEventWithName:@"sparkAudioStatus" body:@{@"id": identifier, @"value": status}];
+}
+- (void)publishPlayer:(NSString *)identifier {
+  if (!identifier || self.sessionID || ![self.activeID isEqual:identifier]) return;
+  AVPlayer *player = self.players[identifier]; if (!player) return;
+  NSDictionary *status = [self statusForPlayer:player];
+  NSMutableDictionary *info = [MPNowPlayingInfoCenter.defaultCenter.nowPlayingInfo mutableCopy] ?: [NSMutableDictionary new];
+  info[MPMediaItemPropertyPlaybackDuration] = status[@"duration"]; info[MPNowPlayingInfoPropertyElapsedPlaybackTime] = status[@"currentTime"]; info[MPNowPlayingInfoPropertyPlaybackRate] = @(player.rate);
+  MPNowPlayingInfoCenter.defaultCenter.nowPlayingInfo = info;
+  MPNowPlayingInfoCenter.defaultCenter.playbackState = [status[@"playing"] boolValue] ? MPNowPlayingPlaybackStatePlaying : MPNowPlayingPlaybackStatePaused;
+}
 - (void)publishMetadata:(NSDictionary *)metadata {
   NSMutableDictionary *info = [MediaInfo(metadata) mutableCopy];
   MPNowPlayingInfoCenter.defaultCenter.nowPlayingInfo = info;
@@ -92,16 +168,16 @@ RCT_EXPORT_MODULE(NativeSparkAudio)
     AVPlayer *player = self.players[identifier]; id result = NSNull.null;
     if ([method hasPrefix:@"session"]) {
       if ([method isEqual:@"sessionCreate"]) {
-        self.sessionID = identifier; self.session = [@{@"commands": @[@"play", @"pause"]} mutableCopy]; [self.commands removeAllObjects];
+        self.sessionID = identifier; self.session = [@{@"commands": @[@"play", @"pause"]} mutableCopy];
         [self publishMetadata:args[@"metadata"] ?: @{}];
-      } else if (![self.sessionID isEqual:identifier]) { reject(@"E_SESSION_REPLACED", @"Media session has been replaced", nil); return; }
+      } else if (![self.sessionID isEqual:identifier] && [method isEqual:@"sessionRemove"]) { resolve(@"null"); return; }
+      else if (![self.sessionID isEqual:identifier]) { reject(@"E_CLOSED", @"Media session has been replaced", nil); return; }
       if ([method isEqual:@"sessionCreate"] || [method isEqual:@"sessionUpdate"]) {
         [self.session addEntriesFromDictionary:args];
         if (args[@"metadata"]) [self publishMetadata:args[@"metadata"]];
         [self publishSession];
-      } else if ([method isEqual:@"sessionCommands"]) { result = [self.commands copy]; [self.commands removeAllObjects]; }
-      else if ([method isEqual:@"sessionRemove"]) {
-        self.sessionID = nil; self.session = nil; self.activeID = nil; ++self.artworkGeneration; [self.commands removeAllObjects];
+      } else if ([method isEqual:@"sessionRemove"]) {
+        self.sessionID = nil; self.session = nil; self.activeID = nil; ++self.artworkGeneration;
         MPNowPlayingInfoCenter.defaultCenter.nowPlayingInfo = nil; MPNowPlayingInfoCenter.defaultCenter.playbackState = MPNowPlayingPlaybackStateStopped;
         for (MPRemoteCommand *command in RemoteCommands().allValues) command.enabled = NO;
       } else { reject(@"E_AUDIO", @"Unknown session operation", nil); return; }
@@ -110,12 +186,29 @@ RCT_EXPORT_MODULE(NativeSparkAudio)
       if (!url || (!url.isFileURL && ![@[@"https", @"http"] containsObject:url.scheme])) { reject(@"E_AUDIO", @"Expected a local file or HTTP audio URL", nil); return; }
       if (url.isFileURL && ![NSFileManager.defaultManager isReadableFileAtPath:url.path]) { reject(@"E_NOT_FOUND", @"Audio file is not readable", nil); return; }
       self.players[identifier] = [AVPlayer playerWithURL:url]; self.metadata[identifier] = @{@"title": args[@"title"] ?: @"Music"};
+      __weak RNSparkAudio *weakSelf = self;
+      self.endObservers[identifier] = [NSNotificationCenter.defaultCenter addObserverForName:AVPlayerItemDidPlayToEndTimeNotification object:self.players[identifier].currentItem queue:NSOperationQueue.mainQueue usingBlock:^(NSNotification *event) { [weakSelf publishPlayer:identifier]; }];
       if (!self.sessionID) { self.activeID = identifier; [self publishMetadata:self.metadata[identifier]]; }
-    } else if (!player) { reject(@"E_AUDIO", @"Audio player is not available", nil); return; }
-    else if ([method isEqual:@"ready"]) {
+    } else if (!player && [method isEqual:@"remove"]) { resolve(@"null"); return; }
+    else if (!player) { reject(@"E_AUDIO", @"Audio player is not available", nil); return; }
+    else if ([method isEqual:@"awaitReady"]) {
       NSError *error = player.error ?: player.currentItem.error;
       if (error) { reject(@"E_AUDIO", error.localizedDescription, error); return; }
-      result = @(player.currentItem.status == AVPlayerItemStatusReadyToPlay);
+      if (player.currentItem.status == AVPlayerItemStatusReadyToPlay) { [self publishPlayer:identifier]; resolve(@"true"); return; }
+      if (self.readiness[identifier]) { reject(@"E_BUSY", @"Audio readiness is already pending", nil); return; }
+      __weak RNSparkAudio *weakSelf = self;
+      self.readyRejects[identifier] = reject;
+      self.readiness[identifier] = [[SparkAudioObservation alloc] initWithPlayer:player positionUpdates:NO notify:^{
+        RNSparkAudio *owner = weakSelf; AVPlayer *current = owner.players[identifier];
+        NSError *error = current.error ?: current.currentItem.error;
+        if (!owner || !current || (!error && current.currentItem.status != AVPlayerItemStatusReadyToPlay)) return;
+        [owner.readiness[identifier] remove]; [owner.readiness removeObjectForKey:identifier]; [owner.readyRejects removeObjectForKey:identifier];
+        if (error) reject(@"E_AUDIO", error.localizedDescription, error);
+        else { [owner publishPlayer:identifier]; resolve(@"true"); }
+      }];
+      // Readiness may have changed between the first check and installing KVO.
+      self.readiness[identifier].notify();
+      return;
     }
     else if ([method isEqual:@"volume"]) { double volume = [args[@"volume"] doubleValue]; if (!isfinite(volume) || volume < 0 || volume > 1) { reject(@"E_AUDIO", @"Invalid volume", nil); return; } player.volume = volume; }
     else if ([method isEqual:@"metadata"]) { self.metadata[identifier] = args[@"metadata"]; if (!self.sessionID && [self.activeID isEqual:identifier]) [self publishMetadata:self.metadata[identifier]]; }
@@ -127,28 +220,37 @@ RCT_EXPORT_MODULE(NativeSparkAudio)
     else if ([method isEqual:@"seek"]) {
       double seconds = [args[@"seconds"] doubleValue];
       if (!isfinite(seconds) || seconds < 0) { reject(@"E_AUDIO", @"Invalid seek position", nil); return; }
-      [player seekToTime:CMTimeMakeWithSeconds(seconds, 600) toleranceBefore:kCMTimeZero toleranceAfter:kCMTimeZero completionHandler:^(BOOL finished) { if (finished) resolve(@"null"); else reject(@"E_AUDIO", @"Seek was interrupted", nil); }]; return;
+      [player seekToTime:CMTimeMakeWithSeconds(seconds, 600) toleranceBefore:kCMTimeZero toleranceAfter:kCMTimeZero completionHandler:^(BOOL finished) { dispatch_async(dispatch_get_main_queue(), ^{ if (finished) { [self publishPlayer:identifier]; [self emitStatus:identifier]; resolve(@"null"); } else reject(@"E_AUDIO", @"Seek was interrupted", nil); }); }]; return;
     } else if ([method isEqual:@"status"]) {
-      double position = CMTimeGetSeconds(player.currentTime), duration = CMTimeGetSeconds(player.currentItem.duration);
-      if (!isfinite(position)) position = 0; if (!isfinite(duration)) duration = 0;
-      NSError *error = player.error ?: player.currentItem.error;
-      BOOL playing = player.timeControlStatus == AVPlayerTimeControlStatusPlaying;
-      result = @{ @"volume": @(player.volume), @"playing": @(playing), @"currentTime": @(position), @"duration": @(duration), @"didJustFinish": @(duration > 0 && position >= duration && player.rate == 0), @"error": error.localizedDescription ?: NSNull.null };
-      if (!self.sessionID && [self.activeID isEqual:identifier]) {
-        NSMutableDictionary *info = [MPNowPlayingInfoCenter.defaultCenter.nowPlayingInfo mutableCopy] ?: [NSMutableDictionary new];
-        info[MPMediaItemPropertyPlaybackDuration] = @(duration); info[MPNowPlayingInfoPropertyElapsedPlaybackTime] = @(position); info[MPNowPlayingInfoPropertyPlaybackRate] = @(player.rate); MPNowPlayingInfoCenter.defaultCenter.nowPlayingInfo = info;
-        MPNowPlayingInfoCenter.defaultCenter.playbackState = playing ? MPNowPlayingPlaybackStatePlaying : MPNowPlayingPlaybackStatePaused;
-      }
-    } else if ([method isEqual:@"remove"]) { [player pause]; [self.players removeObjectForKey:identifier]; [self.metadata removeObjectForKey:identifier]; if (!self.sessionID && [self.activeID isEqual:identifier]) { self.activeID = nil; ++self.artworkGeneration; MPNowPlayingInfoCenter.defaultCenter.nowPlayingInfo = nil; } }
+      result = [self statusForPlayer:player];
+    } else if ([method isEqual:@"statusUpdates"]) {
+      if ([args[@"enabled"] boolValue] && !self.observations[identifier]) {
+        __weak RNSparkAudio *weakSelf = self;
+        self.observations[identifier] = [[SparkAudioObservation alloc] initWithPlayer:player notify:^{ [weakSelf emitStatus:identifier]; }];
+        [self emitStatus:identifier];
+      } else if (![args[@"enabled"] boolValue]) { [self.observations[identifier] remove]; [self.observations removeObjectForKey:identifier]; [self.lastStatuses removeObjectForKey:identifier]; }
+    } else if ([method isEqual:@"remove"]) {
+      RCTPromiseRejectBlock cancelReady = self.readyRejects[identifier];
+      [self.readiness[identifier] remove]; [self.readiness removeObjectForKey:identifier]; [self.readyRejects removeObjectForKey:identifier];
+      if (cancelReady) cancelReady(@"E_CLOSED", @"Audio player was removed during loading", nil);
+      [self.observations[identifier] remove]; [self.observations removeObjectForKey:identifier]; [self.lastStatuses removeObjectForKey:identifier];
+      if (self.endObservers[identifier]) [NSNotificationCenter.defaultCenter removeObserver:self.endObservers[identifier]]; [self.endObservers removeObjectForKey:identifier];
+      [player pause]; [self.players removeObjectForKey:identifier]; [self.metadata removeObjectForKey:identifier]; if (!self.sessionID && [self.activeID isEqual:identifier]) { self.activeID = nil; ++self.artworkGeneration; MPNowPlayingInfoCenter.defaultCenter.nowPlayingInfo = nil; }
+    }
     else { reject(@"E_AUDIO", @"Unknown audio operation", nil); return; }
+    if ([method isEqual:@"play"] || [method isEqual:@"pause"]) [self publishPlayer:identifier];
     NSData *data = [NSJSONSerialization dataWithJSONObject:result options:NSJSONWritingFragmentsAllowed error:nil]; resolve([[NSString alloc] initWithData:data encoding:NSUTF8StringEncoding]);
   });
 }
 - (void)invalidate { dispatch_async(dispatch_get_main_queue(), ^{
+  for (SparkAudioObservation *observation in self.readiness.allValues) [observation remove]; [self.readiness removeAllObjects];
+  for (RCTPromiseRejectBlock reject in self.readyRejects.allValues) reject(@"E_CLOSED", @"Audio module was invalidated during loading", nil); [self.readyRejects removeAllObjects];
+  for (SparkAudioObservation *observation in self.observations.allValues) [observation remove]; [self.observations removeAllObjects]; [self.lastStatuses removeAllObjects];
+  for (id token in self.endObservers.allValues) [NSNotificationCenter.defaultCenter removeObserver:token]; [self.endObservers removeAllObjects];
   for (AVPlayer *player in self.players.allValues) [player pause];
   [self.players removeAllObjects]; [self.metadata removeAllObjects]; ++self.artworkGeneration;
   for (NSString *key in self.targets) [RemoteCommands()[key] removeTarget:self.targets[key]];
   [self.targets removeAllObjects]; self.sessionID = nil; MPNowPlayingInfoCenter.defaultCenter.nowPlayingInfo = nil;
-}); }
+}); [super invalidate]; }
 - (std::shared_ptr<facebook::react::TurboModule>)getTurboModule:(const facebook::react::ObjCTurboModule::InitParams &)params { return std::make_shared<facebook::react::NativeSparkAudioSpecJSI>(params); }
 @end

package/vendor/node_modules/@legendapp/spark-audio/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@legendapp/spark-audio",
-  "version": "0.0.1-next.2",
+  "version": "0.0.1-next.4",
   "license": "MIT",
   "main": "src/index",
   "react-native": "src/index",
@@ -45,5 +45,8 @@
     ],
     "requires": []
   },
-  "private": true
+  "private": true,
+  "dependencies": {
+    "@legendapp/spark-desktop-app": "0.0.1-next.4"
+  }
 }

package/vendor/node_modules/@legendapp/spark-audio/src/NativeSparkAudio.ts

@@ -1,3 +1,7 @@
 import { TurboModuleRegistry, type TurboModule } from "react-native";
-export interface Spec extends TurboModule { call(method: string, args: string): Promise<string> }
+export interface Spec extends TurboModule {
+  call(method: string, args: string): Promise<string>;
+  addListener(eventName: string): void;
+  removeListeners(count: number): void;
+}
 export default TurboModuleRegistry.get<Spec>("NativeSparkAudio");

package/vendor/node_modules/@legendapp/spark-audio/src/desktop.ts

@@ -1,39 +1,43 @@
-import { statusListeners } from "./status-listeners";
-import { validateVolume, validateMetadata } from "./media-types";
+import { SparkError, invokeNative, parseNativeResult } from "@legendapp/spark-desktop-app/src/contracts";
+import { playerHandle, validatePlayerOptions, waitForAudio } from "./player";
 export { createMediaSession } from "./media-session";
 export type * from "./media-types";
 import Native from "./NativeSparkAudio";
-import { validateSource, validateTime, type AudioPlayer, type AudioSource, type AudioStatus } from "./types";
-export type { AudioPlayer, AudioSource, AudioStatus } from "./types";
+import { onAudioEvent } from "./events";
+import { validateSource, type AudioPlayer, type AudioSource, type AudioPlayerOptions, type AudioStatus } from "./types";
+export type { AudioPlayer, AudioSource, AudioStatus, AudioPlayerOptions, Subscription } from "./types";
 let sequence = 0;
-export async function createAudioPlayer(source: AudioSource): Promise<AudioPlayer> {
-  validateSource(source);
-  if (!Native) throw Object.assign(new Error("Audio playback is unavailable. Build a client with @legendapp/spark-audio."), { code: "E_UNAVAILABLE" });
+export async function createAudioPlayer(source: AudioSource, options: AudioPlayerOptions = {}): Promise<AudioPlayer> {
+  validateSource(source); validatePlayerOptions(options);
+  options = { ...options };
+  source = { ...source };
+  if (!Native) throw new SparkError("E_MODULE_UNAVAILABLE", "Audio requires a client with @legendapp/spark-audio");
   const native = Native, id = `audio-${Date.now()}-${++sequence}`;
-  let removed = false;
-  const call = async <T = void>(method: string, args = {}): Promise<T> => {
-    if (removed) throw new Error("Audio player has been removed");
-    return JSON.parse(await native.call(method, JSON.stringify({ id, ...args })));
-  };
-  await call("create", source);
-  let timer: ReturnType<typeof setTimeout> | undefined;
-  let cancelled = false;
+  const call = async (method: string, args = {}): Promise<unknown> => parseNativeResult(await invokeNative(() => native.call(method, JSON.stringify({ id, ...args }))), (value): value is unknown => true);
+  const command = async (method: string, args = {}) => { if (await call(method, args) !== null) throw new SparkError("E_INVALID_DATA", "Invalid audio command result"); };
   try {
-    await Promise.race([
-      (async () => { while (!cancelled && !await call<boolean>("ready")) await new Promise(resolve => setTimeout(resolve, 50)); })(),
-      new Promise<never>((_, reject) => { timer = setTimeout(() => reject(new Error("Audio loading timed out")), 15_000); }),
-    ]);
-  } catch (error) { void call("remove").catch(() => {}); throw error; }
-  finally { cancelled = true; clearTimeout(timer); }
-  const read = () => call<AudioStatus>("status");
-  const listeners = statusListeners(read);
-  return {
-    setVolume: volume => { validateVolume(volume); return call("volume", { volume }); },
-    setMetadata: metadata => { validateMetadata(metadata); return call("metadata", { metadata }); },
-    addListener: (event, listener) => { if (event !== "playbackStatusUpdate") throw new TypeError("Unknown audio event"); return listeners.add(listener); },
-    play: () => call("play"), pause: () => call("pause"),
-    seekTo: seconds => { validateTime(seconds); return call("seek", { seconds }); },
-    getStatus: read,
-    async remove() { if (!removed) { await call("remove"); removed = true; listeners.close(); } },
-  };
+    await command("create", source);
+    // The native promise settles on AVPlayer/MediaPlayer readiness; no JS polling.
+    await waitForAudio(async () => { const ready = await call("awaitReady"); if (ready !== true) throw new SparkError("E_INVALID_DATA", "Invalid audio readiness"); return true; }, options);
+  } catch (cause) {
+    try { await command("remove"); } catch (cleanup) { throw new SparkError("E_NATIVE", "Audio loading and cleanup failed", { cause: new AggregateError([cause, cleanup]) }); }
+    throw cause;
+  }
+  return playerHandle({
+    setVolume: volume => command("volume", { volume }),
+    setMetadata: metadata => command("metadata", { metadata: metadata ?? {} }),
+    play: () => command("play"), pause: () => command("pause"),
+    seekTo: seconds => command("seek", { seconds }),
+    getStatus: async () => await call("status") as AudioStatus,
+    addStatusListener(listener) {
+      let active = true;
+      const subscription = onAudioEvent("sparkAudioStatus", id, value => { if (active) listener(value as AudioStatus); });
+      void command("statusUpdates", { enabled: true }).catch(error => { if (active) console.error(error); });
+      return { remove() { active = false; subscription.remove(); void command("statusUpdates", { enabled: false }).catch(console.error); } };
+    },
+    remove: () => command("remove"),
+  });
 }
+
+export { useAudioPlayer } from "./hooks";
+export type { AudioPlayerState, AudioPlayerHookOptions } from "./hooks";

package/vendor/node_modules/@legendapp/spark-audio/src/events.ts

@@ -0,0 +1,11 @@
+import { NativeEventEmitter } from "react-native";
+import { SparkError, type Subscription } from "@legendapp/spark-desktop-app/src/contracts";
+import Native from "./NativeSparkAudio";
+
+/** Private audio transport. Install before native setup so readiness cannot lose events. */
+export function onAudioEvent(name: "sparkAudioStatus" | "sparkMediaCommand", id: string, listener: (value: unknown) => void): Subscription {
+  if (!Native) throw new SparkError("E_MODULE_UNAVAILABLE", "The audio module is unavailable");
+  return new NativeEventEmitter(Native).addListener(name, (event: unknown) => {
+    if (event && typeof event === "object" && (event as { id?: unknown }).id === id) listener((event as { value?: unknown }).value);
+  });
+}

package/vendor/node_modules/@legendapp/spark-audio/src/hooks.ts

@@ -0,0 +1,65 @@
+import { useEffect, useLayoutEffect, useRef, useState } from "react";
+import { createAudioPlayer } from "./index";
+import type { AudioPlayer, AudioPlayerOptions, AudioSource } from "./types";
+
+export type AudioPlayerState = { status: "loading" } | { status: "ready"; player: AudioPlayer } | { status: "error"; error: unknown };
+export interface AudioPlayerHookOptions extends AudioPlayerOptions {
+  /** Cleanup failures cannot update an unmounted component. The player permits retry. */
+  onCleanupError?(error: unknown, player: AudioPlayer): void;
+}
+type OwnedPlayer = { player: AudioPlayer; removing?: Promise<void> };
+type Lifecycle = { tail: Promise<void>; owner?: OwnedPlayer };
+/** Owns one player for this source. Creation occurs in an effect, never during render. */
+export function useAudioPlayer(source: AudioSource, options: AudioPlayerHookOptions = {}): AudioPlayerState {
+  const { uri, title } = source;
+  const { loadTimeoutMs, signal, onCleanupError } = options;
+  const cleanupError = useRef(onCleanupError);
+  const lifecycleRef = useRef<Lifecycle | null>(null);
+  if (!lifecycleRef.current) lifecycleRef.current = { tail: Promise.resolve() };
+  const lifecycle = lifecycleRef.current;
+  useLayoutEffect(() => { cleanupError.current = onCleanupError; }, [onCleanupError]);
+  const [current, setCurrent] = useState<{ uri: string; title?: string; loadTimeoutMs?: number; signal?: AbortSignal; state: AudioPlayerState }>();
+  useEffect(() => {
+    const controller = new AbortController();
+    let disposed = false, owned: OwnedPlayer | undefined;
+    const abort = () => controller.abort();
+    signal?.addEventListener("abort", abort, { once: true });
+    if (signal?.aborted) abort();
+    const set = (state: AudioPlayerState) => { if (!disposed) setCurrent({ uri, title, loadTimeoutMs, signal, state }); };
+    set({ status: "loading" });
+    const remove = (owner: OwnedPlayer) => {
+      if (!owner.removing) owner.removing = owner.player.remove().then(() => {
+        if (lifecycle.owner === owner) lifecycle.owner = undefined;
+      }).catch(error => {
+        try {
+          if (cleanupError.current) cleanupError.current(error, owner.player);
+          else console.error(error, owner.player);
+        } catch (callbackError) { console.error(callbackError); }
+        throw error;
+      }).finally(() => { owner.removing = undefined; });
+      return owner.removing;
+    };
+    const creation = lifecycle.tail.then(async () => {
+      if (disposed) return;
+      try {
+        if (lifecycle.owner) await remove(lifecycle.owner);
+      } catch (error) { set({ status: "error", error }); return; }
+      if (disposed) return;
+      try {
+        const player = await createAudioPlayer({ uri, title }, { loadTimeoutMs, signal: controller.signal });
+        owned = { player };
+        lifecycle.owner = owned;
+        if (!disposed) set({ status: "ready", player });
+      } catch (error) { set({ status: "error", error }); }
+    });
+    lifecycle.tail = creation;
+    return () => {
+      disposed = true;
+      controller.abort();
+      signal?.removeEventListener("abort", abort);
+      const cleanup = creation.then(async () => { if (owned) await remove(owned).catch(() => {}); });
+      lifecycle.tail = cleanup;
+    };
+  }, [uri, title, loadTimeoutMs, signal]);
+  return current && current.uri === uri && current.title === title && current.loadTimeoutMs === loadTimeoutMs && current.signal === signal ? current.state : { status: "loading" };
+}

package/vendor/node_modules/@legendapp/spark-audio/src/index.web.ts

@@ -1,42 +1,101 @@
-import { validateVolume, validateMetadata } from "./media-types";
-import { statusListeners } from "./status-listeners";
+import { SparkError } from "@legendapp/spark-desktop-app/src/contracts";
+import { playerHandle, validatePlayerOptions, waitForAudio } from "./player";
 import { hasExplicitMediaSession, claimPlayerMediaSession, ownsPlayerMediaSession, releasePlayerMediaSession } from "./media-session.web";
 export { createMediaSession } from "./media-session.web";
 export type * from "./media-types";
-import { validateSource, validateTime, type AudioPlayer, type AudioSource } from "./types";
-export type { AudioPlayer, AudioSource, AudioStatus } from "./types";
+import { validateSource, type AudioPlayer, type AudioSource, type AudioPlayerOptions, type AudioStatus } from "./types";
+export type { AudioPlayer, AudioSource, AudioStatus, AudioPlayerOptions, Subscription } from "./types";
+export { useAudioPlayer } from "./hooks";
+export type { AudioPlayerState, AudioPlayerHookOptions } from "./hooks";
 
-export async function createAudioPlayer(source: AudioSource): Promise<AudioPlayer> {
-  validateSource(source);
+const SEEK_TIMEOUT_MS = 10_000;
+
+export async function createAudioPlayer(source: AudioSource, options: AudioPlayerOptions = {}): Promise<AudioPlayer> {
+  validateSource(source); validatePlayerOptions(options);
+  options = { ...options };
+  source = { ...source };
+  if (typeof Audio === "undefined") throw new SparkError("E_UNSUPPORTED_PLATFORM", "Browser audio is unavailable");
   const audio = new Audio(source.uri);
-  audio.preload = "metadata";
-  let removed = false;
-  const pending = new Set<() => void>();
-  const alive = () => { if (removed) throw new Error("Audio player has been removed"); };
-  const media = navigator.mediaSession;
-  if (media && !hasExplicitMediaSession()) {
-    claimPlayerMediaSession(audio);
-    media.metadata = new MediaMetadata({ title: source.title ?? "Music" });
-    media.setActionHandler("play", () => { void audio.play().catch(console.error); });
-    media.setActionHandler("pause", () => audio.pause());
-    media.setActionHandler("seekto", event => { if (event.seekTime !== undefined) audio.currentTime = event.seekTime; });
+  audio.preload = "auto";
+  const media = typeof navigator === "undefined" ? undefined : navigator.mediaSession;
+  let cancelPendingSeek: ((error: SparkError) => void) | undefined;
+  let removeRequested = false;
+  const statusValue = (): AudioStatus => ({ playing: !audio.paused, currentTime: audio.currentTime, duration: Number.isFinite(audio.duration) ? audio.duration : 0, didJustFinish: audio.ended, error: audio.error?.message ?? null, volume: audio.volume });
+  async function dispose() {
+    audio.pause(); audio.removeAttribute("src"); audio.load();
+    if (media && ownsPlayerMediaSession(audio)) {
+      for (const action of ["play", "pause", "seekto"] as const) media.setActionHandler(action, null);
+      media.metadata = null; releasePlayerMediaSession(audio);
+    }
+  }
+  try {
+    await waitForAudio(async () => { if (audio.error) throw new SparkError("E_NATIVE", audio.error.message || "Could not load audio"); return audio.readyState >= 1; }, options, notify => {
+      audio.addEventListener("loadedmetadata", notify); audio.addEventListener("error", notify);
+      return { remove() { audio.removeEventListener("loadedmetadata", notify); audio.removeEventListener("error", notify); } };
+    });
+    if (media && !hasExplicitMediaSession()) {
+      claimPlayerMediaSession(audio);
+      media.metadata = new MediaMetadata({ title: source.title ?? "Music" });
+      media.setActionHandler("play", () => { void audio.play().catch(console.error); });
+      media.setActionHandler("pause", () => audio.pause());
+      media.setActionHandler("seekto", event => { if (event.seekTime !== undefined) audio.currentTime = event.seekTime; });
+    }
+  } catch (cause) {
+    try { await dispose(); } catch (cleanup) { throw new SparkError("E_NATIVE", "Audio loading and cleanup failed", { cause: new AggregateError([cause, cleanup]) }); }
+    throw cause;
   }
-  const read = async () => { alive(); return { playing: !audio.paused, currentTime: audio.currentTime, duration: Number.isFinite(audio.duration) ? audio.duration : 0, didJustFinish: audio.ended, error: audio.error?.message ?? null, volume: audio.volume }; };
-  const listeners = statusListeners(read);
+  const player = playerHandle({
+    async setVolume(volume) { audio.volume = volume; },
+    async setMetadata(metadata) {
+      const value = metadata ?? {};
+      if (media && ownsPlayerMediaSession(audio)) media.metadata = new MediaMetadata({ title: value.title, artist: value.artist, album: value.albumTitle, artwork: value.artworkUrl ? [{ src: value.artworkUrl }] : [] });
+    },
+    async play() { await audio.play(); }, async pause() { audio.pause(); },
+    async seekTo(seconds) {
+      if (removeRequested) throw new SparkError("E_CLOSED", "Audio player was removed during seek");
+      if (audio.error) throw new SparkError("E_NATIVE", audio.error.message || "Could not seek audio", { cause: audio.error });
+      if (!audio.seeking && audio.currentTime === seconds) return;
+      await new Promise<void>((resolve, reject) => {
+        let settled = false;
+        const finish = (error?: SparkError) => {
+          if (settled) return;
+          settled = true;
+          clearTimeout(timeout);
+          audio.removeEventListener("seeked", onSeeked);
+          audio.removeEventListener("error", onError);
+          audio.removeEventListener("emptied", onEmptied);
+          if (cancelPendingSeek === cancel) cancelPendingSeek = undefined;
+          if (error) reject(error); else resolve();
+        };
+        const onSeeked = () => { if (!audio.seeking) finish(); };
+        const onError = () => finish(new SparkError("E_NATIVE", audio.error?.message || "Could not seek audio", { cause: audio.error }));
+        const onEmptied = () => finish(new SparkError("E_CLOSED", "Audio source was removed during seek"));
+        const cancel = (error: SparkError) => finish(error);
+        const timeout = setTimeout(() => finish(new SparkError("E_TIMEOUT", "Browser audio seek did not complete before timeout")), SEEK_TIMEOUT_MS);
+        audio.addEventListener("seeked", onSeeked);
+        audio.addEventListener("error", onError);
+        audio.addEventListener("emptied", onEmptied);
+        cancelPendingSeek = cancel;
+        try { audio.currentTime = seconds; }
+        catch (cause) { finish(new SparkError("E_NATIVE", "Failed to seek browser audio", { cause })); }
+      });
+    },
+    async getStatus() { return statusValue(); },
+    addStatusListener(listener) {
+      const events = ["playing", "pause", "timeupdate", "ended", "durationchange", "volumechange", "error", "seeked"];
+      const notify = () => listener(statusValue());
+      for (const event of events) audio.addEventListener(event, notify);
+      notify();
+      return { remove() { for (const event of events) audio.removeEventListener(event, notify); } };
+    },
+    remove: dispose,
+  });
   return {
-    async setVolume(volume) { alive(); validateVolume(volume); audio.volume = volume; },
-    async setMetadata(metadata) { alive(); validateMetadata(metadata); if (media && ownsPlayerMediaSession(audio)) media.metadata = new MediaMetadata({ title: metadata.title, artist: metadata.artist, album: metadata.albumTitle, artwork: metadata.artworkUrl ? [{ src: metadata.artworkUrl }] : [] }); },
-    addListener(event, listener) { if (event !== "playbackStatusUpdate") throw new TypeError("Unknown audio event"); return listeners.add(listener); },
-    async play() { alive(); await audio.play(); }, async pause() { alive(); audio.pause(); },
-    async seekTo(seconds) { alive(); validateTime(seconds); if (audio.readyState === 0) await new Promise<void>((resolve, reject) => {
-      const clear = () => { clearTimeout(timer); pending.delete(cancel); audio.removeEventListener("loadedmetadata", loaded); audio.removeEventListener("error", failed); };
-      const loaded = () => { clear(); resolve(); }; const failed = () => { clear(); reject(new Error("Could not load audio")); };
-      const cancel = () => { clear(); reject(new Error("Audio player has been removed")); };
-      const timer = setTimeout(() => { clear(); reject(new Error("Audio loading timed out")); }, 15_000);
-      pending.add(cancel);
-      audio.addEventListener("loadedmetadata", loaded); audio.addEventListener("error", failed);
-    }); alive(); audio.currentTime = seconds; },
-    getStatus: read,
-    async remove() { if (!removed) { removed = true; listeners.close(); for (const cancel of pending) cancel(); audio.pause(); audio.removeAttribute("src"); audio.load(); if (media && ownsPlayerMediaSession(audio)) { for (const action of ["play", "pause", "seekto"] as const) media.setActionHandler(action, null); media.metadata = null; releasePlayerMediaSession(audio); } } },
+    ...player,
+    remove() {
+      removeRequested = true;
+      cancelPendingSeek?.(new SparkError("E_CLOSED", "Audio player was removed during seek"));
+      return player.remove();
+    },
   };
 }

package/vendor/node_modules/@legendapp/spark-audio/src/media-session-unavailable.ts

@@ -1,5 +1,7 @@
-import type { MediaCommand, MediaSession, MediaSessionOptions } from "./media-types";
-/** Expo Audio owns mobile transport controls; it cannot attach an external engine. */
-export async function createMediaSession(_options: MediaSessionOptions, _onCommand: (command: MediaCommand) => void): Promise<MediaSession> {
-  throw Object.assign(new Error("Standalone media sessions support desktop and web. On mobile use the audio player's Expo-backed controls."), { code: "E_UNAVAILABLE" });
+import { SparkError } from "@legendapp/spark-desktop-app/src/contracts";
+import { sessionOptions, type MediaSession, type MediaSessionOptions } from "./media-types";
+/** Expo Audio cannot attach an external playback engine to its transport controls. */
+export async function createMediaSession(options: MediaSessionOptions): Promise<MediaSession> {
+  sessionOptions(options);
+  throw new SparkError("E_UNSUPPORTED_PLATFORM", "Standalone media sessions require desktop or web; mobile uses the player's controls");
 }