ink-framework-audio 0.1.0-alpha.1 → 0.1.0-alpha.12

package/package.json

@@ -1,14 +1,14 @@
 {
   "name": "ink-framework-audio",
-  "version": "0.1.0-alpha.1",
+  "version": "0.1.0-alpha.12",
   "exports": {
     ".": "./src/index.ts",
     "./microphone": "./src/microphone.ts",
     "./recording": "./src/recording.ts"
   },
   "peerDependencies": {
-    "@ink/files": "npm:ink-framework-files@0.1.0-alpha.1",
-    "ink": "npm:ink-framework@0.1.0-alpha.1",
+    "@ink/files": "npm:ink-framework-files@0.1.0-alpha.12",
+    "ink": "npm:ink-framework@0.1.0-alpha.12",
     "react": "19.2.8"
   },
   "license": "MIT",

package/src/index.ts

@@ -14,6 +14,18 @@ export interface AudioItem {
 }
 export type SourceReplacement = { prepare?: boolean } & ({ position?: number; offset?: never } | { offset: number; position?: never });
 
+export interface PlayerOptions {
+  session?: string;
+  mode?: "attached" | "detached";
+  usage?: "music" | "speech";
+  /** Reuse HTTP(S) audio in a shared 256 MiB disc cache. Off by default. */
+  cache?: boolean;
+  /** Milliseconds to buffer for the next queued item. Off by default. */
+  preloadNext?: number;
+  /** Milliseconds of audio to buffer before streaming starts. Defaults to 1000. */
+  startupBuffer?: number;
+}
+
 export interface PlayerState {
   ready: boolean;
   playing: boolean;
@@ -21,17 +33,48 @@ export interface PlayerState {
   buffering: boolean;
   loading: boolean;
   ended: boolean;
+  queue: readonly AudioItem[];
   current: AudioItem | null;
   index: number;
   position: number;
   duration: number;
   speed: number;
+  shuffle: boolean;
+  repeat: "off" | "queue" | "track";
   skipSilence: boolean;
   voiceBoost: boolean;
   silenceSaved: number;
   error: Error | null;
 }
-const initial: PlayerState = { ready: false, playing: false, playWhenReady: false, buffering: false, loading: false, ended: false, current: null, index: -1, position: 0, duration: 0, speed: 1, skipSilence: false, voiceBoost: false, silenceSaved: 0, error: null };
+const initial: PlayerState = { ready: false, playing: false, playWhenReady: false, buffering: false, loading: false, ended: false, queue: [], current: null, index: -1, position: 0, duration: 0, speed: 1, shuffle: false, repeat: "off", skipSilence: false, voiceBoost: false, silenceSaved: 0, error: null };
+
+function decodeItem(value: unknown): AudioItem {
+  if (typeof value !== "object" || value === null) throw new NativeError("protocol", "Invalid audio queue item");
+  const text = (name: string): string => {
+    const result: unknown = Reflect.get(value, name);
+    if (typeof result !== "string") throw new NativeError("protocol", `Invalid audio item ${name}`);
+    return result;
+  };
+  const duration: unknown = Reflect.get(value, "duration");
+  if (duration !== undefined && (typeof duration !== "number" || !Number.isFinite(duration) || duration < 0)) {
+    throw new NativeError("protocol", "Invalid audio item duration");
+  }
+  return { id: text("id"), src: text("src"), title: text("title"), artist: text("artist"), album: text("album"), artwork: text("artwork"), duration };
+}
+
+function validateId(id: string) {
+  if (typeof id !== "string" || !id.trim()) throw new TypeError("Audio item IDs must not be blank");
+}
+
+function validateQueue(items: readonly AudioItem[]) {
+  if (items.length === 0) throw new RangeError("Audio queues cannot be empty");
+  const ids = new Set<string>();
+  for (const item of items) {
+    validateId(item.id);
+    if (ids.has(item.id)) throw new TypeError("Audio queue item IDs must be unique");
+    ids.add(item.id);
+  }
+}
 
 function decode(value: unknown): PlayerState {
   if (typeof value !== "object" || value === null) throw new NativeError("protocol", "Invalid player state");
@@ -64,6 +107,12 @@ function decode(value: unknown): PlayerState {
     throw new NativeError("protocol", "Invalid player queue index");
   }
   const duration = number("durationMs");
+  const queue = field("queue");
+  const repeat = field("repeat");
+  if (repeat !== "off" && repeat !== "queue" && repeat !== "track") throw new NativeError("protocol", "Invalid repeat mode");
+  const shuffle = field("shuffle");
+  if (typeof shuffle !== "boolean") throw new NativeError("protocol", "Invalid shuffle mode");
+  if (!Array.isArray(queue)) throw new NativeError("protocol", "Invalid audio queue");
   return {
     ready: field("ready") === true,
     playing: status === "playing",
@@ -71,24 +120,28 @@ function decode(value: unknown): PlayerState {
     buffering: status === "loading",
     loading: field("loading") === true,
     ended: status === "ended",
+    queue: queue.map(decodeItem),
     index,
     current: src ? { id: text("id"), src, title: text("title"), artist: text("artist"), album: text("album"), artwork: text("artwork"), duration } : null,
     position: number("positionMs"), duration, speed: number("speed"),
+    shuffle, repeat,
     skipSilence: field("skipSilence") === true, voiceBoost: field("voiceBoost") === true,
     silenceSaved: number("silenceSavedMs"), error,
   };
 }
 
-export function usePlayer(options: { session?: string; mode?: "attached" | "detached"; usage?: "music" | "speech" } = {}) {
-  const { session = "main", mode = "attached", usage = "music" } = options;
+export function usePlayer(options: PlayerOptions = {}) {
+  const { session = "main", mode = "attached", usage = "music", cache = false, preloadNext = 0, startupBuffer = 1000 } = options;
   if (!/^[A-Za-z0-9._-]{1,64}$/.test(session)) throw new TypeError("Audio session names must be 1–64 letters, numbers, dots, underscores or hyphens");
+  if (!Number.isSafeInteger(preloadNext) || preloadNext < 0 || preloadNext > 30_000) throw new RangeError("Next-item preloading must be between 0 and 30000 milliseconds");
+  if (!Number.isSafeInteger(startupBuffer) || startupBuffer < 0 || startupBuffer > 30_000) throw new RangeError("Startup buffering must be between 0 and 30000 milliseconds");
   const [state, setState] = useState(initial);
   const current = useRef(initial);
   const controller = useRef<ReturnType<typeof attachNativeController> | null>(null);
   useEffect(() => {
     const publish = (next: PlayerState) => { current.current = next; setState(next); };
     publish(initial);
-    const attachment = attachNativeController("audio", { kind: "player", config: { session, playback: mode, usage } }, value => {
+    const attachment = attachNativeController("audio", { kind: "player", config: { session, playback: mode, usage, cache, preloadNext, startupBuffer } }, value => {
       try { publish(decode(value)); }
       catch (error) { publish({ ...initial, error: error instanceof Error ? error : new Error(String(error)) }); }
     });
@@ -101,7 +154,7 @@ export function usePlayer(options: { session?: string; mode?: "attached" | "deta
       current.current = initial;
       void attachment.dispose().catch(error => console.error("Could not release audio player", error));
     };
-  }, [session, mode, usage]);
+  }, [session, mode, usage, cache, preloadNext, startupBuffer]);
   const commands = useMemo(() => {
     const call = async (operation: string, payload: unknown = {}) => {
       if (!controller.current || !current.current.ready) throw new NativeError("unavailable", "Audio player is not ready");
@@ -126,15 +179,38 @@ export function usePlayer(options: { session?: string; mode?: "attached" | "deta
         }
         return call("replaceSource", { id, src, ...options });
       },
-      setQueue(items: readonly AudioItem[], options: { startIndex?: number; startPosition?: number; prepare?: boolean } = {}) {
+      async setQueue(items: readonly AudioItem[], options: { startIndex?: number; startPosition?: number; prepare?: boolean } = {}) {
+        validateQueue(items);
         const startPosition = options.startPosition ?? 0;
-        if (!Number.isFinite(startPosition) || startPosition < 0) return Promise.reject(new RangeError("Audio position must be a non-negative number of milliseconds"));
-        return call("setQueue", { items, startIndex: options.startIndex ?? 0, startPosition, prepare: options.prepare ?? true });
+        if (!Number.isFinite(startPosition) || startPosition < 0) throw new RangeError("Audio position must be a non-negative number of milliseconds");
+        await call("setQueue", { items, startIndex: options.startIndex ?? 0, startPosition, prepare: options.prepare ?? true });
+      },
+      async add(item: AudioItem, options: { at?: number | "next" } = {}) {
+        validateId(item.id);
+        if (options.at !== undefined && options.at !== "next" && (!Number.isSafeInteger(options.at) || options.at < 0)) {
+          throw new RangeError("Audio insertion index must be a non-negative integer");
+        }
+        await call("add", { item, ...options });
+      },
+      remove: (id: string) => call("remove", { id }),
+      async move(id: string, index: number) {
+        if (!Number.isSafeInteger(index) || index < 0) throw new RangeError("Audio destination index must be a non-negative integer");
+        await call("move", { id, index });
+      },
+      async replace(id: string, item: AudioItem) {
+        validateId(item.id);
+        await call("replace", { id, item });
+      },
+      async play(id?: string) {
+        if (id !== undefined) validateId(id);
+        await call(id === undefined ? "play" : "playItem", { id });
       },
-      play: () => call("play"),
+      prepare: () => call("prepare"),
       pause: () => call("pause"),
       toggle: () => call("toggle"),
       stop: () => call("stop"),
+      setShuffle: (enabled: boolean) => call("setShuffle", { value: enabled }),
+      setRepeat: (mode: PlayerState["repeat"]) => call("setRepeat", { value: mode }),
       setSpeed(speed: number) {
         if (!Number.isFinite(speed) || speed < 0.25 || speed > 4) return Promise.reject(new RangeError("Playback speed must be between 0.25 and 4"));
         return call("setSpeed", { value: speed });