ink-framework-audio 0.1.0-alpha.10 → 0.1.0-alpha.13

package/package.json

@@ -1,14 +1,14 @@
 {
   "name": "ink-framework-audio",
-  "version": "0.1.0-alpha.10",
+  "version": "0.1.0-alpha.13",
   "exports": {
     ".": "./src/index.ts",
     "./microphone": "./src/microphone.ts",
     "./recording": "./src/recording.ts"
   },
   "peerDependencies": {
-    "@ink/files": "npm:ink-framework-files@0.1.0-alpha.10",
-    "ink": "npm:ink-framework@0.1.0-alpha.10",
+    "@ink/files": "npm:ink-framework-files@0.1.0-alpha.13",
+    "ink": "npm:ink-framework@0.1.0-alpha.13",
     "react": "19.2.8"
   },
   "license": "MIT",
@@ -20,6 +20,7 @@
   "files": [
     "src",
     "*.json",
-    "*.ts"
+    "*.ts",
+    "*.md"
   ]
 }

package/src/capture-internal.ts

@@ -1,7 +1,7 @@
-import { createElement, useEffect, useMemo, useRef, useState } from "react";
+import { createElement, useEffect, useMemo, useState } from "ink/internal/react";
 import type { Snapshot, SnapshotSource } from "ink";
 import { NativeError } from "ink/native";
-import { attachNativeController } from "ink/native/controller";
+import { useNativeController } from "ink/internal/controller";
 
 const displayController = Symbol("captureController");
 export type CaptureDisplay = { readonly [displayController]: number | null };
@@ -48,7 +48,7 @@ export function useCapture<State extends { status: string; error: Error | null }
 ) {
   const [state, setState] = useState(() => selectStatus(initial));
   const [id, setId] = useState<number | null>(null);
-  const controller = useRef<ReturnType<typeof attachNativeController> | null>(null);
+  const controller = useNativeController("audio", "audio capture");
   const channel = useMemo(() => {
     let snapshot: Snapshot<State> = { status: "loading" };
     const listeners = new Set<() => void>();
@@ -75,7 +75,7 @@ export function useCapture<State extends { status: string; error: Error | null }
       },
     };
     return { source, publish, observe };
-  }, []);
+  }, [controller]);
   useEffect(() => {
     setState(selectStatus(initial));
     setId(null);
@@ -92,27 +92,18 @@ export function useCapture<State extends { status: string; error: Error | null }
       setState({ ...selectStatus(initial), status: "error", error: failure });
       channel.publish({ status: "error", error: failure });
     };
-    const attachment = attachNativeController("audio", { kind, config: referenceHz === undefined ? {} : { referenceHz } }, value => {
-      if (controller.current !== attachment) return;
+    return controller.attach({ kind, config: referenceHz === undefined ? {} : { referenceHz } }, value => {
       try { publish(decode(value)); }
       catch (error) { fail(error); }
+    }, fail, id => {
+      setId(id);
+      channel.observe();
     });
-    controller.current = attachment;
-    void attachment.ready.then(() => {
-      if (controller.current === attachment) {
-        setId(attachment.id);
-        channel.observe();
-      }
-    }, error => { if (controller.current === attachment) fail(error); });
-    return () => {
-      controller.current = null;
-      void attachment.dispose().catch(error => console.error("Could not release audio capture", error));
-    };
-  }, [kind, initial, decode, selectStatus, referenceHz, channel]);
+  }, [kind, initial, decode, selectStatus, referenceHz, channel, controller]);
   const call = useMemo(() => async (operation: string) => {
     if (!controller.current) throw new NativeError("unavailable", "Audio capture is not attached");
     return controller.current.call(operation);
-  }, []);
+  }, [controller]);
   const display = useMemo(() => ({ [displayController]: id }), [id]);
   return { state, ready: id !== null, call, display, measurements: channel.source };
 }

package/src/index.ts

@@ -1,5 +1,5 @@
-import { useEffect, useMemo, useRef, useState } from "react";
-import { attachNativeController } from "ink/native/controller";
+import { useEffect, useMemo, useRef, useState } from "ink/internal/react";
+import { useNativeController } from "ink/internal/controller";
 import { NativeError } from "ink/native";
 import { playbackController } from "ink/internal/playback";
 
@@ -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,37 +120,38 @@ 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);
+  const controller = useNativeController("audio", "audio player");
   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 detach = controller.attach({ 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)) }); }
-    });
-    controller.current = attachment;
-    void attachment.ready.catch(error => {
-      if (controller.current === attachment) publish({ ...initial, error: error instanceof Error ? error : new Error(String(error)) });
+    }, error => {
+      publish({ ...initial, error: error instanceof Error ? error : new Error(String(error)) });
     });
     return () => {
-      controller.current = null;
+      detach();
       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, controller]);
   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 +176,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 });
@@ -148,6 +221,6 @@ export function usePlayer(options: { session?: string; mode?: "attached" | "deta
         return call("seekTo", { value: position });
       },
     };
-  }, []);
+  }, [controller]);
   return { state, [playbackController]: controller.current?.id, ...commands };
 }

package/src/microphone.ts

@@ -1,4 +1,4 @@
-import { createElement, useMemo } from "react";
+import { createElement, useMemo } from "ink/internal/react";
 import { NativeError } from "ink/native";
 import { captureReadout, fields, useCapture, type CaptureDisplay } from "./capture-internal";
 

package/src/recording.ts

@@ -1,4 +1,4 @@
-import { useMemo } from "react";
+import { useMemo } from "ink/internal/react";
 import { NativeError } from "ink/native";
 import type { FileRef } from "@ink/files";
 import { captureReadout, fields, useCapture, type CaptureDisplay } from "./capture-internal";