@lalternative/tornade-sdk-react 0.1.0

package/README.md

@@ -0,0 +1,25 @@
+# @lalternative/tornade-sdk-react
+
+Plays a tornade reading in the browser, straight from tornade, on a URL the
+application's server signed. The server never relays audio: it primes the
+opening when the text is produced, signs one URL per press, and the bytes go
+from tornade to the listener.
+
+```tsx
+import { speakSource, useVoicePlayback } from '@lalternative/tornade-sdk-react'
+
+function PlayButton({ messageId }: { messageId: string }) {
+  const resolve = useCallback(async () => {
+    const res = await fetch(`${API}/messages/${messageId}/audio`, { credentials: 'include' })
+    const { url, text } = await res.json()
+    return speakSource({ url, text, scope: 'chat-message', id: messageId })
+  }, [messageId])
+  const { state, toggle } = useVoicePlayback(resolve)
+  if (state === 'unavailable') return null
+  return <button onClick={toggle}>{state === 'playing' ? 'Pause' : 'Play'}</button>
+}
+```
+
+The server side is the Go `client` package of this module: `client.New` with
+an `AppKey` for `PrimeOpening`, and `signed.NewSigner` for the URL the
+endpoint above returns.

package/dist/index.d.ts

@@ -0,0 +1,54 @@
+/**
+ * A streamed reading is a sequence of independently decodable mp3 pieces,
+ * each length-prefixed in the response body: a big-endian uint32 byte count
+ * followed by that many bytes. Mirrors go/audioreader's FramesContentType.
+ */
+declare const FRAMES_CONTENT_TYPE = "application/x-lalter-audio-frames";
+/**
+ * Reads length-prefixed frames off a byte stream as they arrive, handing
+ * each complete frame to onFrame as soon as it is fully buffered. A frame can
+ * straddle several network chunks, or a chunk can hold several frames.
+ */
+declare function readFrames(reader: ReadableStreamDefaultReader<Uint8Array>, onFrame: (frame: Uint8Array) => void, signal: AbortSignal): Promise<void>;
+
+/** Where a reading may be fetched, and what to ask for once there. */
+type VoiceSource = {
+    url: string;
+    body: unknown;
+};
+/** The reading an application's server signed a URL for. */
+type SignedReading = {
+    /** The signed URL onto tornade's /speak, as handed out by the application. */
+    url: string;
+    /** The exact text the signature covers: what the server read aloud, not the raw content. */
+    text: string;
+    scope: string;
+    id: string;
+};
+/**
+ * Builds the request the browser sends tornade for a signed reading. Always
+ * streamed: an opening the application primed is only served on the
+ * streaming path, and only a stream starts playing before the end is read.
+ */
+declare function speakSource(reading: SignedReading): VoiceSource;
+
+type VoicePlaybackState = 'idle' | 'loading' | 'playing' | 'unavailable';
+/**
+ * Plays a reading aloud piece by piece as tornade streams it, so listening
+ * starts on the first piece instead of after the whole synthesis.
+ *
+ * Decoded with Web Audio rather than MediaSource: mp3 in a SourceBuffer is
+ * inconsistent across desktop browsers, and MediaSource is unavailable on
+ * iOS Safari and in a Tauri webview, while decodeAudioData works everywhere.
+ *
+ * resolve is called on each press rather than once: the URL it returns is
+ * signed and expires, so one resolved when the text was rendered would have
+ * gone stale by the time someone presses play.
+ */
+declare function useVoicePlayback(resolve: () => Promise<VoiceSource>): {
+    state: VoicePlaybackState;
+    toggle: () => void;
+    stop: () => void;
+};
+
+export { FRAMES_CONTENT_TYPE, type SignedReading, type VoicePlaybackState, type VoiceSource, readFrames, speakSource, useVoicePlayback };

package/dist/index.js

@@ -0,0 +1,132 @@
+// src/frames.ts
+var FRAMES_CONTENT_TYPE = "application/x-lalter-audio-frames";
+async function readFrames(reader, onFrame, signal) {
+  let buffer = new Uint8Array(0);
+  const append = (chunk) => {
+    const next = new Uint8Array(buffer.length + chunk.length);
+    next.set(buffer);
+    next.set(chunk, buffer.length);
+    buffer = next;
+  };
+  for (; ; ) {
+    if (signal.aborted) return;
+    const { done, value } = await reader.read();
+    if (value) append(value);
+    if (done) return;
+    for (; ; ) {
+      if (buffer.length < 4) break;
+      const view = new DataView(buffer.buffer, buffer.byteOffset, buffer.length);
+      const frameLength = view.getUint32(0);
+      const total = 4 + frameLength;
+      if (buffer.length < total) break;
+      onFrame(buffer.subarray(4, total));
+      buffer = buffer.subarray(total);
+    }
+  }
+}
+
+// src/speak.ts
+function speakSource(reading) {
+  return {
+    url: reading.url,
+    body: { text: reading.text, scope: reading.scope, id: reading.id, stream: true }
+  };
+}
+
+// src/useVoicePlayback.ts
+import { useCallback, useRef, useState } from "react";
+function useVoicePlayback(resolve) {
+  const [state, setState] = useState("idle");
+  const contextRef = useRef(null);
+  const abortRef = useRef(null);
+  const stopRef = useRef(null);
+  const stop = useCallback(() => {
+    stopRef.current?.();
+    stopRef.current = null;
+    abortRef.current?.abort();
+    abortRef.current = null;
+    setState((s) => s === "unavailable" ? s : "idle");
+  }, []);
+  const play = useCallback(() => {
+    setState("loading");
+    const controller = new AbortController();
+    abortRef.current = controller;
+    const audioContext = new AudioContext();
+    contextRef.current = audioContext;
+    let cancelled = false;
+    let nextStartAt = 0;
+    let scheduled = 0;
+    let sourcesDone = 0;
+    let streamDone = false;
+    const finishIfDone = () => {
+      if (streamDone && scheduled === sourcesDone) {
+        setState((s) => s === "playing" ? "idle" : s);
+      }
+    };
+    stopRef.current = () => {
+      cancelled = true;
+      audioContext.close().catch(() => {
+      });
+    };
+    (async () => {
+      try {
+        const reading = await resolve();
+        const res = await fetch(reading.url, {
+          method: "POST",
+          signal: controller.signal,
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify(reading.body)
+        });
+        if (!res.ok || !res.body || res.headers.get("Content-Type") !== FRAMES_CONTENT_TYPE) {
+          throw new Error(`unexpected response (${res.status})`);
+        }
+        await readFrames(
+          res.body.getReader(),
+          (frame) => {
+            if (cancelled) return;
+            scheduled += 1;
+            const bytes = frame.slice().buffer;
+            audioContext.decodeAudioData(bytes).then((buffer) => {
+              if (cancelled) return;
+              const source = audioContext.createBufferSource();
+              source.buffer = buffer;
+              source.connect(audioContext.destination);
+              const startAt = Math.max(nextStartAt, audioContext.currentTime);
+              source.start(startAt);
+              nextStartAt = startAt + buffer.duration;
+              source.onended = () => {
+                sourcesDone += 1;
+                finishIfDone();
+              };
+              if (scheduled === 1) setState("playing");
+            }).catch(() => {
+              sourcesDone += 1;
+              finishIfDone();
+            });
+          },
+          controller.signal
+        );
+        streamDone = true;
+        finishIfDone();
+        if (scheduled === 0) setState("unavailable");
+      } catch {
+        if (!cancelled) setState("unavailable");
+      }
+    })();
+  }, [resolve]);
+  const toggle = useCallback(() => {
+    if (state === "playing" || state === "loading") {
+      stop();
+      return;
+    }
+    play();
+  }, [state, play, stop]);
+  return { state, toggle, stop };
+}
+export {
+  FRAMES_CONTENT_TYPE,
+  readFrames,
+  speakSource,
+  useVoicePlayback
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/frames.ts","../src/speak.ts","../src/useVoicePlayback.ts"],"sourcesContent":["/**\n * A streamed reading is a sequence of independently decodable mp3 pieces,\n * each length-prefixed in the response body: a big-endian uint32 byte count\n * followed by that many bytes. Mirrors go/audioreader's FramesContentType.\n */\nexport const FRAMES_CONTENT_TYPE = 'application/x-lalter-audio-frames'\n\n/**\n * Reads length-prefixed frames off a byte stream as they arrive, handing\n * each complete frame to onFrame as soon as it is fully buffered. A frame can\n * straddle several network chunks, or a chunk can hold several frames.\n */\nexport async function readFrames(\n  reader: ReadableStreamDefaultReader<Uint8Array>,\n  onFrame: (frame: Uint8Array) => void,\n  signal: AbortSignal,\n): Promise<void> {\n  let buffer = new Uint8Array(0)\n\n  const append = (chunk: Uint8Array) => {\n    const next = new Uint8Array(buffer.length + chunk.length)\n    next.set(buffer)\n    next.set(chunk, buffer.length)\n    buffer = next\n  }\n\n  for (;;) {\n    if (signal.aborted) return\n    const { done, value } = await reader.read()\n    if (value) append(value)\n    if (done) return\n\n    for (;;) {\n      if (buffer.length < 4) break\n      const view = new DataView(buffer.buffer, buffer.byteOffset, buffer.length)\n      const frameLength = view.getUint32(0)\n      const total = 4 + frameLength\n      if (buffer.length < total) break\n      onFrame(buffer.subarray(4, total))\n      buffer = buffer.subarray(total)\n    }\n  }\n}\n","/** Where a reading may be fetched, and what to ask for once there. */\nexport type VoiceSource = {\n  url: string\n  body: unknown\n}\n\n/** The reading an application's server signed a URL for. */\nexport type SignedReading = {\n  /** The signed URL onto tornade's /speak, as handed out by the application. */\n  url: string\n  /** The exact text the signature covers: what the server read aloud, not the raw content. */\n  text: string\n  scope: string\n  id: string\n}\n\n/**\n * Builds the request the browser sends tornade for a signed reading. Always\n * streamed: an opening the application primed is only served on the\n * streaming path, and only a stream starts playing before the end is read.\n */\nexport function speakSource(reading: SignedReading): VoiceSource {\n  return {\n    url: reading.url,\n    body: { text: reading.text, scope: reading.scope, id: reading.id, stream: true },\n  }\n}\n","import { useCallback, useRef, useState } from 'react'\nimport { FRAMES_CONTENT_TYPE, readFrames } from './frames'\nimport type { VoiceSource } from './speak'\n\nexport type VoicePlaybackState = 'idle' | 'loading' | 'playing' | 'unavailable'\n\n/**\n * Plays a reading aloud piece by piece as tornade streams it, so listening\n * starts on the first piece instead of after the whole synthesis.\n *\n * Decoded with Web Audio rather than MediaSource: mp3 in a SourceBuffer is\n * inconsistent across desktop browsers, and MediaSource is unavailable on\n * iOS Safari and in a Tauri webview, while decodeAudioData works everywhere.\n *\n * resolve is called on each press rather than once: the URL it returns is\n * signed and expires, so one resolved when the text was rendered would have\n * gone stale by the time someone presses play.\n */\nexport function useVoicePlayback(resolve: () => Promise<VoiceSource>) {\n  const [state, setState] = useState<VoicePlaybackState>('idle')\n  const contextRef = useRef<AudioContext | null>(null)\n  const abortRef = useRef<AbortController | null>(null)\n  const stopRef = useRef<(() => void) | null>(null)\n\n  const stop = useCallback(() => {\n    stopRef.current?.()\n    stopRef.current = null\n    abortRef.current?.abort()\n    abortRef.current = null\n    setState((s) => (s === 'unavailable' ? s : 'idle'))\n  }, [])\n\n  const play = useCallback(() => {\n    setState('loading')\n    const controller = new AbortController()\n    abortRef.current = controller\n\n    const audioContext = new AudioContext()\n    contextRef.current = audioContext\n\n    let cancelled = false\n    let nextStartAt = 0\n    let scheduled = 0\n    let sourcesDone = 0\n    let streamDone = false\n\n    const finishIfDone = () => {\n      if (streamDone && scheduled === sourcesDone) {\n        setState((s) => (s === 'playing' ? 'idle' : s))\n      }\n    }\n\n    stopRef.current = () => {\n      cancelled = true\n      audioContext.close().catch(() => {})\n    }\n\n    ;(async () => {\n      try {\n        const reading = await resolve()\n        // No credentials: the audio comes from another origin, and what\n        // authorises the request is the signature already in the URL.\n        const res = await fetch(reading.url, {\n          method: 'POST',\n          signal: controller.signal,\n          headers: { 'Content-Type': 'application/json' },\n          body: JSON.stringify(reading.body),\n        })\n        if (!res.ok || !res.body || res.headers.get('Content-Type') !== FRAMES_CONTENT_TYPE) {\n          throw new Error(`unexpected response (${res.status})`)\n        }\n\n        await readFrames(\n          res.body.getReader(),\n          (frame) => {\n            if (cancelled) return\n            scheduled += 1\n            // decodeAudioData detaches the buffer it is given, which would\n            // corrupt later frames sharing the same backing ArrayBuffer.\n            const bytes = frame.slice().buffer\n            audioContext\n              .decodeAudioData(bytes)\n              .then((buffer) => {\n                if (cancelled) return\n                const source = audioContext.createBufferSource()\n                source.buffer = buffer\n                source.connect(audioContext.destination)\n                const startAt = Math.max(nextStartAt, audioContext.currentTime)\n                source.start(startAt)\n                nextStartAt = startAt + buffer.duration\n                source.onended = () => {\n                  sourcesDone += 1\n                  finishIfDone()\n                }\n                if (scheduled === 1) setState('playing')\n              })\n              .catch(() => {\n                sourcesDone += 1\n                finishIfDone()\n              })\n          },\n          controller.signal,\n        )\n        streamDone = true\n        finishIfDone()\n        if (scheduled === 0) setState('unavailable')\n      } catch {\n        if (!cancelled) setState('unavailable')\n      }\n    })()\n  }, [resolve])\n\n  const toggle = useCallback(() => {\n    if (state === 'playing' || state === 'loading') {\n      stop()\n      return\n    }\n    play()\n  }, [state, play, stop])\n\n  return { state, toggle, stop }\n}\n"],"mappings":"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","names":[]}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@lalternative/tornade-sdk-react",
+  "version": "0.1.0",
+  "description": "React hook that plays a tornade reading in the browser, straight from tornade on a URL the application signed",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "pnpm build",
+    "test": "node --experimental-strip-types --test \"src/**/*.test.ts\""
+  },
+  "peerDependencies": {
+    "react": ">=18"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "@types/react": "^19.0.0",
+    "react": "^19.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.7.0"
+  },
+  "keywords": [
+    "tornade",
+    "tts",
+    "audio",
+    "react"
+  ],
+  "license": "MIT",
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/lalternativefabrique/tornade.git",
+    "directory": "sdk-react"
+  }
+}