ink-framework-audio 0.0.0-stage → 0.1.0-alpha.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vandam Dinh
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/ink-native.json

@@ -0,0 +1,14 @@
+{
+  "version": 1,
+  "modules": {
+    "src/index.ts": [
+      "audio-detached"
+    ],
+    "src/microphone.ts": [
+      "audio-microphone"
+    ],
+    "src/recording.ts": [
+      "audio-recording"
+    ]
+  }
+}

package/package.json

@@ -1,6 +1,25 @@
 {
   "name": "ink-framework-audio",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0-alpha.1",
+  "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",
+    "react": "19.2.8"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/No-Scrolling/ink.git",
+    "directory": "packages/audio"
+  },
+  "files": [
+    "src",
+    "*.json",
+    "*.ts"
+  ]
+}

package/src/capture-internal.ts

@@ -0,0 +1,118 @@
+import { createElement, useEffect, useMemo, useRef, useState } from "react";
+import type { Snapshot, SnapshotSource } from "ink";
+import { NativeError } from "ink/native";
+import { attachNativeController } from "ink/native/controller";
+
+const displayController = Symbol("captureController");
+export type CaptureDisplay = { readonly [displayController]: number | null };
+
+export function captureReadout(source: { display: CaptureDisplay }, kind: "recorder" | "level" | "pitch") {
+  const controller = source.display[displayController];
+  return controller === null ? null : createElement("CaptureReadout", { controller, kind });
+}
+
+export function fields(value: unknown) {
+  if (typeof value !== "object" || value === null) throw new NativeError("protocol", "Invalid audio capture state");
+  return {
+    text(name: string) {
+      const result: unknown = Reflect.get(value, name);
+      if (typeof result !== "string") throw new NativeError("protocol", `Invalid audio capture ${name}`);
+      return result;
+    },
+    number(name: string, minimum = 0) {
+      const result: unknown = Reflect.get(value, name);
+      if (typeof result !== "number" || !Number.isFinite(result) || result < minimum) {
+        throw new NativeError("protocol", `Invalid audio capture ${name}`);
+      }
+      return result;
+    },
+    error(): Error | null {
+      if (Reflect.get(value, "status") !== "error") return null;
+      const detail: unknown = Reflect.get(value, "error");
+      if (typeof detail !== "object" || detail === null
+        || !("kind" in detail) || typeof detail.kind !== "string"
+        || !("message" in detail) || typeof detail.message !== "string") {
+        throw new NativeError("protocol", "Invalid audio capture error");
+      }
+      return new NativeError(detail.kind, detail.message, "retryable" in detail && detail.retryable === true);
+    },
+  };
+}
+
+export function useCapture<State extends { status: string; error: Error | null }, Status extends { status: string; error: Error | null }>(
+  kind: "recorder" | "level" | "pitch",
+  initial: State,
+  decode: (value: unknown) => State,
+  selectStatus: (value: State) => Status,
+  referenceHz?: number,
+) {
+  const [state, setState] = useState(() => selectStatus(initial));
+  const [id, setId] = useState<number | null>(null);
+  const controller = useRef<ReturnType<typeof attachNativeController> | null>(null);
+  const channel = useMemo(() => {
+    let snapshot: Snapshot<State> = { status: "loading" };
+    const listeners = new Set<() => void>();
+    const publish = (value: Snapshot<State>) => {
+      snapshot = value;
+      for (const listener of listeners) listener();
+    };
+    const observe = () => {
+      const active = controller.current;
+      if (!active) return;
+      void active.call("observeMeasurements", { enabled: listeners.size > 0 }).catch(error => {
+        if (controller.current === active) publish({ status: "error", error: error instanceof Error ? error : new Error(String(error)) });
+      });
+    };
+    const source: SnapshotSource<State> = {
+      getSnapshot: () => snapshot,
+      subscribe(listener) {
+        listeners.add(listener);
+        if (listeners.size === 1) observe();
+        return () => {
+          listeners.delete(listener);
+          if (!listeners.size) observe();
+        };
+      },
+    };
+    return { source, publish, observe };
+  }, []);
+  useEffect(() => {
+    setState(selectStatus(initial));
+    setId(null);
+    channel.publish({ status: "loading" });
+    let statusKey = "";
+    const publish = (value: State) => {
+      const status = selectStatus(value);
+      const key = JSON.stringify([status, status.error?.message]);
+      if (key !== statusKey) { statusKey = key; setState(status); }
+      channel.publish({ status: "ready", data: value });
+    };
+    const fail = (error: unknown) => {
+      const failure = error instanceof Error ? error : new Error(String(error));
+      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;
+      try { publish(decode(value)); }
+      catch (error) { fail(error); }
+    });
+    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]);
+  const call = useMemo(() => async (operation: string) => {
+    if (!controller.current) throw new NativeError("unavailable", "Audio capture is not attached");
+    return controller.current.call(operation);
+  }, []);
+  const display = useMemo(() => ({ [displayController]: id }), [id]);
+  return { state, ready: id !== null, call, display, measurements: channel.source };
+}

package/src/index.ts

@@ -0,0 +1,153 @@
+import { useEffect, useMemo, useRef, useState } from "react";
+import { attachNativeController } from "ink/native/controller";
+import { NativeError } from "ink/native";
+import { playbackController } from "ink/internal/playback";
+
+export interface AudioItem {
+  id: string;
+  src: string;
+  title: string;
+  artist?: string;
+  album?: string;
+  artwork?: string;
+  duration?: number;
+}
+export type SourceReplacement = { prepare?: boolean } & ({ position?: number; offset?: never } | { offset: number; position?: never });
+
+export interface PlayerState {
+  ready: boolean;
+  playing: boolean;
+  playWhenReady: boolean;
+  buffering: boolean;
+  loading: boolean;
+  ended: boolean;
+  current: AudioItem | null;
+  index: number;
+  position: number;
+  duration: number;
+  speed: number;
+  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 };
+
+function decode(value: unknown): PlayerState {
+  if (typeof value !== "object" || value === null) throw new NativeError("protocol", "Invalid player state");
+  const field = (name: string): unknown => Reflect.get(value, name);
+  const text = (name: string) => {
+    const result = field(name);
+    if (typeof result !== "string") throw new NativeError("protocol", `Invalid player ${name}`);
+    return result;
+  };
+  const number = (name: string) => {
+    const result = field(name);
+    if (typeof result !== "number" || !Number.isFinite(result) || result < 0) throw new NativeError("protocol", `Invalid player ${name}`);
+    return result;
+  };
+  const status = text("status");
+  if (!["idle", "loading", "playing", "paused", "ended", "error"].includes(status) || typeof field("ready") !== "boolean") {
+    throw new NativeError("protocol", "Invalid player status");
+  }
+  let error: Error | null = null;
+  if (status === "error") {
+    const detail = field("error");
+    if (typeof detail !== "object" || detail === null
+      || !("message" in detail) || typeof detail.message !== "string"
+      || !("kind" in detail) || typeof detail.kind !== "string") throw new NativeError("protocol", "Invalid player error");
+    error = new NativeError(detail.kind, detail.message, "retryable" in detail && detail.retryable === true);
+  }
+  const src = text("src");
+  const index = field("index");
+  if (typeof index !== "number" || !Number.isSafeInteger(index) || index < -1) {
+    throw new NativeError("protocol", "Invalid player queue index");
+  }
+  const duration = number("durationMs");
+  return {
+    ready: field("ready") === true,
+    playing: status === "playing",
+    playWhenReady: field("playWhenReady") === true,
+    buffering: status === "loading",
+    loading: field("loading") === true,
+    ended: status === "ended",
+    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"),
+    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;
+  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");
+  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 => {
+      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)) });
+    });
+    return () => {
+      controller.current = null;
+      current.current = initial;
+      void attachment.dispose().catch(error => console.error("Could not release audio player", error));
+    };
+  }, [session, mode, usage]);
+  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");
+      await controller.current.call(operation, payload);
+    };
+    return {
+      async getState(): Promise<PlayerState> {
+        const active = controller.current;
+        if (!active || !current.current.ready) throw new NativeError("unavailable", "Audio player is not ready");
+        return decode(JSON.parse(await active.call("getState")));
+      },
+      seekBy(offset: number) {
+        if (!Number.isSafeInteger(offset)) return Promise.reject(new RangeError("Seek offset must be a safe integer in milliseconds"));
+        return call("seekBy", { value: offset });
+      },
+      replaceSource(id: string, src: string, options: SourceReplacement = {}) {
+        if (options.position !== undefined && (!Number.isFinite(options.position) || options.position < 0)) {
+          return Promise.reject(new RangeError("Audio position must be non-negative milliseconds"));
+        }
+        if (options.offset !== undefined && !Number.isSafeInteger(options.offset)) {
+          return Promise.reject(new RangeError("Seek offset must be a safe integer in milliseconds"));
+        }
+        return call("replaceSource", { id, src, ...options });
+      },
+      setQueue(items: readonly AudioItem[], options: { startIndex?: number; startPosition?: number; prepare?: boolean } = {}) {
+        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 });
+      },
+      play: () => call("play"),
+      pause: () => call("pause"),
+      toggle: () => call("toggle"),
+      stop: () => call("stop"),
+      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 });
+      },
+      setVoiceBoost: (enabled: boolean) => call("setVoiceBoost", { value: enabled }),
+      setSkipSilence: (enabled: boolean) => call("setSkipSilence", { value: enabled }),
+      next: () => call("next"),
+      previous: () => call("previous"),
+      seek(position: number) {
+        if (!Number.isFinite(position) || position < 0) return Promise.reject(new RangeError("Audio position must be a non-negative number of milliseconds"));
+        return call("seekTo", { value: position });
+      },
+    };
+  }, []);
+  return { state, [playbackController]: controller.current?.id, ...commands };
+}

package/src/microphone.ts

@@ -0,0 +1,61 @@
+import { createElement, useMemo } from "react";
+import { NativeError } from "ink/native";
+import { captureReadout, fields, useCapture, type CaptureDisplay } from "./capture-internal";
+
+export interface LevelState {
+  status: "idle" | "listening" | "active" | "clipping" | "error";
+  rms: number;
+  peak: number;
+  error: Error | null;
+}
+const levelInitial: LevelState = { status: "idle", rms: 0, peak: 0, error: null };
+function decodeLevel(value: unknown): LevelState {
+  const field = fields(value);
+  const status = field.text("status");
+  if (status !== "idle" && status !== "listening" && status !== "active" && status !== "clipping" && status !== "error") {
+    throw new NativeError("protocol", "Invalid level meter status");
+  }
+  return { status, rms: field.number("rms"), peak: field.number("peak"), error: field.error() };
+}
+const levelStatus = ({ status, error }: LevelState) => ({ status, error });
+export function useLevelMeter() {
+  const { state, ready, call, display, measurements } = useCapture("level", levelInitial, decodeLevel, levelStatus);
+  const commands = useMemo(() => ({ start: async () => { await call("start"); }, stop: async () => { await call("stop"); } }), [call]);
+  return { state, ready, display, measurements, ...commands };
+}
+
+export interface PitchState {
+  status: "idle" | "listening" | "active" | "error";
+  frequency: number;
+  note: string;
+  octave: number;
+  cents: number;
+  confidence: number;
+  error: Error | null;
+}
+
+const pitchInitial: PitchState = { status: "idle", frequency: 0, note: "", octave: 0, cents: 0, confidence: 0, error: null };
+function decodePitch(value: unknown): PitchState {
+  const field = fields(value);
+  const status = field.text("status");
+  if (status !== "idle" && status !== "listening" && status !== "active" && status !== "error") {
+    throw new NativeError("protocol", "Invalid pitch detector status");
+  }
+  return { status, frequency: field.number("frequencyHz"), note: field.text("note"),
+    octave: field.number("octave", -Infinity), cents: field.number("cents", -Infinity),
+    confidence: field.number("confidence"), error: field.error() };
+}
+const pitchStatus = ({ status, error }: PitchState) => ({ status, error });
+export function usePitchDetector({ referenceHz = 440 }: { referenceHz?: number } = {}) {
+  if (!Number.isFinite(referenceHz) || referenceHz <= 0) throw new RangeError("Pitch reference must be a positive frequency");
+  const { state, ready, call, display, measurements } = useCapture("pitch", pitchInitial, decodePitch, pitchStatus, referenceHz);
+  const commands = useMemo(() => ({ start: async () => { await call("start"); }, stop: async () => { await call("stop"); } }), [call]);
+  return { state, ready, display, measurements, ...commands };
+}
+
+export function LevelReadout({ meter }: { meter: { display: CaptureDisplay } }) { return captureReadout(meter, "level"); }
+export function PitchReadout({ detector }: { detector: { display: CaptureDisplay } }) { return captureReadout(detector, "pitch"); }
+
+export function PitchIndicator({ cents }: { cents: number | null }) {
+  return createElement("PitchIndicator", { cents });
+}

package/src/recording.ts

@@ -0,0 +1,39 @@
+import { useMemo } from "react";
+import { NativeError } from "ink/native";
+import type { FileRef } from "@ink/files";
+import { captureReadout, fields, useCapture, type CaptureDisplay } from "./capture-internal";
+
+export interface RecorderState {
+  status: "idle" | "recording" | "stopping" | "ready" | "error";
+  duration: number;
+  recording: (FileRef & { duration: number }) | null;
+  error: Error | null;
+}
+const recorderInitial: RecorderState = { status: "idle", duration: 0, recording: null, error: null };
+function decodeRecorder(value: unknown): RecorderState {
+  const field = fields(value);
+  const status = field.text("status");
+  if (status !== "idle" && status !== "recording" && status !== "stopping" && status !== "ready" && status !== "error") {
+    throw new NativeError("protocol", "Invalid recorder status");
+  }
+  const id = field.text("id");
+  return { status, duration: field.number("durationMs"), error: field.error(),
+    recording: id ? { id, src: `ink-file://${id}`, name: field.text("name"), mimeType: field.text("mimeType"), size: field.number("size"), duration: field.number("recordingDurationMs") } : null };
+}
+const recorderStatus = ({ status, error, recording }: RecorderState) => ({ status, error, recording });
+export function useRecorder() {
+  const { state, ready, call, display, measurements } = useCapture("recorder", recorderInitial, decodeRecorder, recorderStatus);
+  const commands = useMemo(() => ({
+    start: async () => { await call("start"); },
+    async stop(): Promise<FileRef & { duration: number }> {
+      const completed = decodeRecorder(JSON.parse(await call("stop")));
+      if (completed.status !== "ready" || !completed.recording) throw new NativeError("protocol", "Recording did not return a saved file");
+      return completed.recording;
+    },
+    cancel: async () => { await call("cancel"); },
+    delete: async () => { await call("delete"); },
+  }), [call]);
+  return { state, ready, display, measurements, ...commands };
+}
+
+export function RecordingDuration({ recorder }: { recorder: { display: CaptureDisplay } }) { return captureReadout(recorder, "recorder"); }

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.