@quatrain/speech-api 0.0.0-stage → 0.1.1

package/LICENSE.md

@@ -0,0 +1,15 @@
+# LICENSE UPDATE NOTICE
+
+As of 01/01/2026, Quatrain Core is licensed under the **GNU Affero General Public License v3.0 (AGPL v3)**.
+Previous versions remain under the MIT License.
+
+## Why AGPL?
+
+We believe in open collaboration for the development ecosystem. The AGPL ensures that any modification or deployment of this BaaS stack, including over a network, benefits the entire community.
+
+## Commercial Services & Enterprise Usage
+
+We provide official deployment services, technical training, and certification for Quatrain Core.
+For organizations requiring a non-copyleft license (commercial license) or custom proprietary integrations, please contact the copyright holder: **Quatrain Technologies**.
+
+Copyright © 2024-2026 Quatrain Technologies. All Rights Reserved.

package/README.md

@@ -1,3 +1,13 @@
-# Temporary Holding Version
+# @quatrain/speech-api
 
-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.
+Remote speech adapter for [`@quatrain/speech`](../speech): plays the audio returned by any speech API endpoint, so the server can use the speech model of its choice.
+
+- `prepare()` starts the request immediately: with `SpeechController`, the next sentence downloads while the current one plays.
+- Endpoint contract: `POST` JSON (default body `{ text, locale, voice, style }`, customizable with `buildBody`), answering either audio bytes (`Content-Type: audio/*`) or JSON `{ audioBase64, mimeType? }`.
+- `rate` is applied at playback; `cancel()` aborts the download and stops playback.
+
+```typescript
+import { ApiSpeechSynthesizer } from '@quatrain/speech-api'
+
+const cloud = new ApiSpeechSynthesizer({ endpoint: '/api/speak', headers: { Authorization: `Bearer ${token}` } })
+```

package/dist/ApiSpeechSynthesizer.d.ts

@@ -0,0 +1,36 @@
+import type { PreparedUtteranceInterface, SpeechOptionsInterface, SpeechSynthesizerInterface } from '@quatrain/speech';
+export type FetchLike = (url: string, init: RequestInit) => Promise<Response>;
+export interface AudioLike {
+    playbackRate: number;
+    onplaying: ((event: Event) => void) | null;
+    onended: ((event: Event) => void) | null;
+    onerror: ((event: Event | string) => void) | null;
+    play(): Promise<void>;
+    pause(): void;
+}
+export interface AudioSourceInterface {
+    url: string;
+    release(): void;
+}
+export interface ApiSpeechSynthesizerOptionsInterface {
+    endpoint: string;
+    buildBody?: (text: string, options: SpeechOptionsInterface) => Record<string, unknown>;
+    headers?: Record<string, string>;
+    fetchImpl?: FetchLike;
+    createAudio?: (url: string) => AudioLike;
+    createObjectUrl?: (blob: Blob) => AudioSourceInterface;
+    isOnline?: () => boolean;
+}
+export declare function isAudioPayload(value: unknown): value is {
+    audioBase64: string;
+    mimeType?: string;
+};
+export declare class ApiSpeechSynthesizer implements SpeechSynthesizerInterface {
+    private readonly settings;
+    readonly id = "api";
+    constructor(settings: ApiSpeechSynthesizerOptionsInterface);
+    isAvailable(): Promise<boolean>;
+    private fetchAudio;
+    prepare(text: string, options: SpeechOptionsInterface): PreparedUtteranceInterface;
+}
+//# sourceMappingURL=ApiSpeechSynthesizer.d.ts.map

package/dist/ApiSpeechSynthesizer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ApiSpeechSynthesizer.d.ts","sourceRoot":"","sources":["../src/ApiSpeechSynthesizer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,0BAA0B,EAAmB,sBAAsB,EAAE,0BAA0B,EAAE,MAAM,kBAAkB,CAAA;AAGvI,MAAM,MAAM,SAAS,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAA;AAG7E,MAAM,WAAW,SAAS;IACvB,YAAY,EAAE,MAAM,CAAA;IACpB,SAAS,EAAE,CAAC,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC,GAAG,IAAI,CAAA;IAC1C,OAAO,EAAE,CAAC,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC,GAAG,IAAI,CAAA;IACxC,OAAO,EAAE,CAAC,CAAC,KAAK,EAAE,KAAK,GAAG,MAAM,KAAK,IAAI,CAAC,GAAG,IAAI,CAAA;IACjD,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;IACrB,KAAK,IAAI,IAAI,CAAA;CACf;AAGD,MAAM,WAAW,oBAAoB;IAElC,GAAG,EAAE,MAAM,CAAA;IAEX,OAAO,IAAI,IAAI,CAAA;CACjB;AAGD,MAAM,WAAW,oCAAoC;IAElD,QAAQ,EAAE,MAAM,CAAA;IAEhB,SAAS,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,sBAAsB,KAAK,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAEtF,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAEhC,SAAS,CAAC,EAAE,SAAS,CAAA;IAErB,WAAW,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,SAAS,CAAA;IAExC,eAAe,CAAC,EAAE,CAAC,IAAI,EAAE,IAAI,KAAK,oBAAoB,CAAA;IAEtD,QAAQ,CAAC,EAAE,MAAM,OAAO,CAAA;CAC1B;AAQD,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI;IAAE,WAAW,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,CASlG;AAiBD,qBAAa,oBAAqB,YAAW,0BAA0B;IAMxD,OAAO,CAAC,QAAQ,CAAC,QAAQ;IALrC,QAAQ,CAAC,EAAE,SAAQ;gBAKU,QAAQ,EAAE,oCAAoC;IAKrE,WAAW,IAAI,OAAO,CAAC,OAAO,CAAC;YAevB,UAAU;IA8BxB,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,sBAAsB,GAAG,0BAA0B;CA0CpF"}

package/dist/ApiSpeechSynthesizer.js

@@ -0,0 +1,96 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ApiSpeechSynthesizer = void 0;
+exports.isAudioPayload = isAudioPayload;
+function isAudioPayload(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        'audioBase64' in value &&
+        typeof value.audioBase64 === 'string' &&
+        value.audioBase64.length > 0 &&
+        (!('mimeType' in value) || value.mimeType === undefined || typeof value.mimeType === 'string'));
+}
+function defaultObjectUrl(blob) {
+    const url = URL.createObjectURL(blob);
+    return { url, release: () => URL.revokeObjectURL(url) };
+}
+class ApiSpeechSynthesizer {
+    settings;
+    id = 'api';
+    constructor(settings) {
+        this.settings = settings;
+    }
+    async isAvailable() {
+        if (this.settings.isOnline) {
+            return this.settings.isOnline();
+        }
+        return typeof navigator === 'undefined' || navigator.onLine !== false;
+    }
+    async fetchAudio(text, options, signal) {
+        const fetchImpl = this.settings.fetchImpl ?? ((url, init) => fetch(url, init));
+        const body = this.settings.buildBody
+            ? this.settings.buildBody(text, options)
+            : { text, locale: options.locale, voice: options.voice, style: options.style };
+        const response = await fetchImpl(this.settings.endpoint, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json', ...this.settings.headers },
+            body: JSON.stringify(body),
+            signal,
+        });
+        if (!response.ok) {
+            return null;
+        }
+        const contentType = response.headers.get('Content-Type') ?? '';
+        if (contentType.startsWith('audio/')) {
+            return (this.settings.createObjectUrl ?? defaultObjectUrl)(await response.blob());
+        }
+        const payload = await response.json();
+        if (!isAudioPayload(payload)) {
+            return null;
+        }
+        return { url: `data:${payload.mimeType ?? 'audio/wav'};base64,${payload.audioBase64}`, release: () => undefined };
+    }
+    prepare(text, options) {
+        const controller = new AbortController();
+        let cancelled = false;
+        let audio = null;
+        let finish = null;
+        const source = this.fetchAudio(text, options, controller.signal).catch(() => null);
+        return {
+            play: async (onStarted) => {
+                const ready = await source;
+                if (cancelled) {
+                    ready?.release();
+                    return 'interrupted';
+                }
+                if (!ready) {
+                    return 'failed';
+                }
+                const createAudio = this.settings.createAudio ?? ((url) => new Audio(url));
+                const element = createAudio(ready.url);
+                audio = element;
+                element.playbackRate = options.rate ?? 1;
+                return new Promise((resolve) => {
+                    finish = (reason) => {
+                        finish = null;
+                        audio = null;
+                        ready.release();
+                        resolve(reason);
+                    };
+                    element.onplaying = () => onStarted?.();
+                    element.onended = () => finish?.('completed');
+                    element.onerror = () => finish?.('failed');
+                    element.play().catch(() => finish?.(cancelled ? 'interrupted' : 'failed'));
+                });
+            },
+            cancel: () => {
+                cancelled = true;
+                controller.abort();
+                audio?.pause();
+                finish?.('interrupted');
+            },
+        };
+    }
+}
+exports.ApiSpeechSynthesizer = ApiSpeechSynthesizer;
+//# sourceMappingURL=ApiSpeechSynthesizer.js.map

package/dist/ApiSpeechSynthesizer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ApiSpeechSynthesizer.js","sourceRoot":"","sources":["../src/ApiSpeechSynthesizer.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { ApiSpeechSynthesizer, isAudioPayload } from './ApiSpeechSynthesizer';
+export type { AudioLike, AudioSourceInterface, FetchLike, ApiSpeechSynthesizerOptionsInterface } from './ApiSpeechSynthesizer';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAA;AAC7E,YAAY,EAAE,SAAS,EAAE,oBAAoB,EAAE,SAAS,EAAE,oCAAoC,EAAE,MAAM,wBAAwB,CAAA"}

package/dist/index.js

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isAudioPayload = exports.ApiSpeechSynthesizer = void 0;
+var ApiSpeechSynthesizer_1 = require("./ApiSpeechSynthesizer");
+Object.defineProperty(exports, "ApiSpeechSynthesizer", { enumerable: true, get: function () { return ApiSpeechSynthesizer_1.ApiSpeechSynthesizer; } });
+Object.defineProperty(exports, "isAudioPayload", { enumerable: true, get: function () { return ApiSpeechSynthesizer_1.isAudioPayload; } });
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;AAAA,+DAA6E;AAApE,4HAAA,oBAAoB,OAAA;AAAE,sHAAA,cAAc,OAAA"}

package/package.json

@@ -1,6 +1,42 @@
 {
   "name": "@quatrain/speech-api",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.1",
+  "license": "AGPL-3.0-only",
+  "description": "Remote speech adapter for @quatrain/speech: plays audio returned by a speech API endpoint, sentence by sentence",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bun": "src/index.ts",
+  "files": [
+    "LICENSE.md",
+    "src/",
+    "dist/",
+    "README.md",
+    "NOTICE.md"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Quatrain/Core.git",
+    "directory": "packages/speech-api"
+  },
+  "author": "Quatrain Développement SAS <developers@quatrain.com>",
+  "dependencies": {
+    "@quatrain/speech": "^0.1.1"
+  },
+  "devDependencies": {
+    "@tsconfig/recommended": "^1.0.1",
+    "@types/jest": "^29.5.12",
+    "@types/node": "^22.10.1",
+    "jest": "^29.7.0",
+    "ts-jest": "^29.4.6",
+    "typescript": "^5.1.5"
+  },
+  "scripts": {
+    "test-ci": "jest --runInBand",
+    "build": "tsc",
+    "wbuild": "tsc --watch",
+    "bump-to": "yarn version"
+  },
+  "typedoc": {
+    "entryPoint": "src/index.ts"
+  }
 }

package/src/ApiSpeechSynthesizer.test.ts

@@ -0,0 +1,146 @@
+import { ApiSpeechSynthesizer, isAudioPayload, type AudioLike, type FetchLike } from './ApiSpeechSynthesizer'
+
+/** Fake audio element, controlled by the test. */
+interface FakeAudioInterface extends AudioLike {
+   url: string
+   paused: boolean
+}
+
+/**
+ * Builds a fake audio factory.
+ *
+ * @param rejectPlay - Make `play()` reject (autoplay refused).
+ * @returns The factory and the created elements.
+ */
+function fakeAudio(rejectPlay = false): { createAudio: (url: string) => AudioLike; elements: FakeAudioInterface[] } {
+   const elements: FakeAudioInterface[] = []
+   return {
+      elements,
+      createAudio: (url) => {
+         const element: FakeAudioInterface = {
+            url,
+            paused: false,
+            playbackRate: 1,
+            onplaying: null,
+            onended: null,
+            onerror: null,
+            play: () => (rejectPlay ? Promise.reject(new Error('NotAllowedError')) : Promise.resolve()),
+            pause: () => {
+               element.paused = true
+            },
+         }
+         elements.push(element)
+         return element
+      },
+   }
+}
+
+/**
+ * Builds a fake fetch answering a JSON payload.
+ *
+ * @param status - HTTP status.
+ * @param body - JSON body.
+ * @returns The fake and its recorded calls.
+ */
+function jsonFetch(status: number, body: unknown): { fetchImpl: FetchLike; calls: RequestInit[] } {
+   const calls: RequestInit[] = []
+   return {
+      calls,
+      fetchImpl: async (_url, init) => {
+         calls.push(init)
+         return new Response(JSON.stringify(body), { status, headers: { 'Content-Type': 'application/json' } })
+      },
+   }
+}
+
+/** Lets pending promise callbacks run. */
+const flush = (): Promise<void> => new Promise((resolve) => setTimeout(resolve, 0))
+
+describe('isAudioPayload', () => {
+   it('accepts a non-empty audioBase64 with an optional mimeType', () => {
+      expect(isAudioPayload({ audioBase64: 'AAAA' })).toBe(true)
+      expect(isAudioPayload({ audioBase64: 'AAAA', mimeType: 'audio/mpeg' })).toBe(true)
+      expect(isAudioPayload({ audioBase64: '' })).toBe(false)
+      expect(isAudioPayload({ audioBase64: 'AAAA', mimeType: 3 })).toBe(false)
+      expect(isAudioPayload(null)).toBe(false)
+   })
+})
+
+describe('ApiSpeechSynthesizer', () => {
+   it('follows the network status', async () => {
+      expect(await new ApiSpeechSynthesizer({ endpoint: '/speak', isOnline: () => false }).isAvailable()).toBe(false)
+      expect(await new ApiSpeechSynthesizer({ endpoint: '/speak', isOnline: () => true }).isAvailable()).toBe(true)
+   })
+
+   it('requests the audio at prepare time and plays it with the rate', async () => {
+      const { fetchImpl, calls } = jsonFetch(200, { audioBase64: 'AAAA' })
+      const { createAudio, elements } = fakeAudio()
+      const synthesizer = new ApiSpeechSynthesizer({ endpoint: '/speak', fetchImpl, createAudio })
+      const utterance = synthesizer.prepare('Hello there.', { locale: 'en-US', voice: 'v1', style: 'warm', rate: 1.2 })
+      expect(calls).toHaveLength(1)
+      expect(calls[0].body).toBe(JSON.stringify({ text: 'Hello there.', locale: 'en-US', voice: 'v1', style: 'warm' }))
+
+      let started = false
+      const playing = utterance.play(() => {
+         started = true
+      })
+      await flush()
+      expect(elements[0].url).toBe('data:audio/wav;base64,AAAA')
+      expect(elements[0].playbackRate).toBe(1.2)
+      elements[0].onplaying?.(new Event('playing'))
+      elements[0].onended?.(new Event('ended'))
+      expect(await playing).toBe('completed')
+      expect(started).toBe(true)
+   })
+
+   it('plays binary audio responses through an object URL', async () => {
+      const released: string[] = []
+      const { createAudio, elements } = fakeAudio()
+      const synthesizer = new ApiSpeechSynthesizer({
+         endpoint: '/speak',
+         fetchImpl: async () => new Response(new Uint8Array([1, 2, 3]), { status: 200, headers: { 'Content-Type': 'audio/mpeg' } }),
+         createAudio,
+         createObjectUrl: () => ({ url: 'blob:1', release: () => released.push('blob:1') }),
+      })
+      const playing = synthesizer.prepare('Hi.', { locale: 'en-US' }).play()
+      await flush()
+      elements[0].onended?.(new Event('ended'))
+      expect(await playing).toBe('completed')
+      expect(elements[0].url).toBe('blob:1')
+      expect(released).toEqual(['blob:1'])
+   })
+
+   it('uses a custom body builder', async () => {
+      const { fetchImpl, calls } = jsonFetch(200, { audioBase64: 'AAAA' })
+      new ApiSpeechSynthesizer({ endpoint: '/speak', fetchImpl, buildBody: (text) => ({ input: text }) }).prepare('Hi.', { locale: 'en-US' })
+      expect(calls[0].body).toBe(JSON.stringify({ input: 'Hi.' }))
+   })
+
+   it('fails on HTTP errors, bad payloads and refused playback', async () => {
+      const options = { locale: 'en-US' }
+      expect(await new ApiSpeechSynthesizer({ endpoint: '/speak', fetchImpl: jsonFetch(502, {}).fetchImpl }).prepare('Hi.', options).play()).toBe('failed')
+      expect(await new ApiSpeechSynthesizer({ endpoint: '/speak', fetchImpl: jsonFetch(200, { nope: 1 }).fetchImpl }).prepare('Hi.', options).play()).toBe('failed')
+      const refused = new ApiSpeechSynthesizer({ endpoint: '/speak', fetchImpl: jsonFetch(200, { audioBase64: 'AAAA' }).fetchImpl, createAudio: fakeAudio(true).createAudio })
+      expect(await refused.prepare('Hi.', options).play()).toBe('failed')
+   })
+
+   it('aborts the download and stops playback on cancel', async () => {
+      const signals: (AbortSignal | null | undefined)[] = []
+      const { createAudio, elements } = fakeAudio()
+      const synthesizer = new ApiSpeechSynthesizer({
+         endpoint: '/speak',
+         fetchImpl: async (_url, init) => {
+            signals.push(init.signal)
+            return new Response(JSON.stringify({ audioBase64: 'AAAA' }), { status: 200 })
+         },
+         createAudio,
+      })
+      const utterance = synthesizer.prepare('Hi.', { locale: 'en-US' })
+      const playing = utterance.play()
+      await flush()
+      utterance.cancel()
+      expect(await playing).toBe('interrupted')
+      expect(signals[0]?.aborted).toBe(true)
+      expect(elements[0].paused).toBe(true)
+   })
+})

package/src/ApiSpeechSynthesizer.ts

@@ -0,0 +1,172 @@
+import type { PreparedUtteranceInterface, SpeechEndReason, SpeechOptionsInterface, SpeechSynthesizerInterface } from '@quatrain/speech'
+
+/** Minimal `fetch` signature (injectable in tests). */
+export type FetchLike = (url: string, init: RequestInit) => Promise<Response>
+
+/** Subset of `HTMLAudioElement` used by the adapter. */
+export interface AudioLike {
+   playbackRate: number
+   onplaying: ((event: Event) => void) | null
+   onended: ((event: Event) => void) | null
+   onerror: ((event: Event | string) => void) | null
+   play(): Promise<void>
+   pause(): void
+}
+
+/** Audio returned by the endpoint, ready to be played. */
+export interface AudioSourceInterface {
+   /** `data:` or `blob:` URL. */
+   url: string
+   /** Releases the URL (blob URLs). */
+   release(): void
+}
+
+/** Adapter settings. */
+export interface ApiSpeechSynthesizerOptionsInterface {
+   /** Endpoint synthesizing one text: `POST` JSON, answers audio bytes (`audio/*`) or `{ audioBase64, mimeType? }`. */
+   endpoint: string
+   /** Builds the JSON body (defaults to `{ text, locale, voice, style }`). */
+   buildBody?: (text: string, options: SpeechOptionsInterface) => Record<string, unknown>
+   /** Extra request headers. */
+   headers?: Record<string, string>
+   /** HTTP implementation (defaults to the global `fetch`). */
+   fetchImpl?: FetchLike
+   /** Audio element factory (defaults to `new Audio(url)`). */
+   createAudio?: (url: string) => AudioLike
+   /** Turns audio bytes into a playable URL (defaults to `URL.createObjectURL`). */
+   createObjectUrl?: (blob: Blob) => AudioSourceInterface
+   /** Network status (defaults to `navigator.onLine`, `true` outside browsers). */
+   isOnline?: () => boolean
+}
+
+/**
+ * Type guard for the JSON audio payload.
+ *
+ * @param value - Parsed JSON.
+ * @returns `true` when the payload carries a non-empty `audioBase64` string.
+ */
+export function isAudioPayload(value: unknown): value is { audioBase64: string; mimeType?: string } {
+   return (
+      typeof value === 'object' &&
+      value !== null &&
+      'audioBase64' in value &&
+      typeof value.audioBase64 === 'string' &&
+      value.audioBase64.length > 0 &&
+      (!('mimeType' in value) || value.mimeType === undefined || typeof value.mimeType === 'string')
+   )
+}
+
+/**
+ * Default conversion of audio bytes into a blob URL.
+ *
+ * @param blob - Audio bytes.
+ * @returns The playable URL.
+ */
+function defaultObjectUrl(blob: Blob): AudioSourceInterface {
+   const url = URL.createObjectURL(blob)
+   return { url, release: () => URL.revokeObjectURL(url) }
+}
+
+/**
+ * Cloud speech through any HTTP endpoint (the endpoint calls the speech model of its choice).
+ * `prepare` starts the request immediately, so the next sentence downloads while the current one plays.
+ */
+export class ApiSpeechSynthesizer implements SpeechSynthesizerInterface {
+   readonly id = 'api'
+
+   /**
+    * @param settings - Endpoint and injectable dependencies.
+    */
+   constructor(private readonly settings: ApiSpeechSynthesizerOptionsInterface) {}
+
+   /**
+    * @returns `true` when the device is online (the endpoint itself is only checked when speaking).
+    */
+   async isAvailable(): Promise<boolean> {
+      if (this.settings.isOnline) {
+         return this.settings.isOnline()
+      }
+      return typeof navigator === 'undefined' || navigator.onLine !== false
+   }
+
+   /**
+    * Downloads the audio of one text.
+    *
+    * @param text - Text.
+    * @param options - Speech options.
+    * @param signal - Abort signal.
+    * @returns The playable audio, or `null` when the endpoint produced none.
+    */
+   private async fetchAudio(text: string, options: SpeechOptionsInterface, signal: AbortSignal): Promise<AudioSourceInterface | null> {
+      const fetchImpl = this.settings.fetchImpl ?? ((url: string, init: RequestInit) => fetch(url, init))
+      const body = this.settings.buildBody
+         ? this.settings.buildBody(text, options)
+         : { text, locale: options.locale, voice: options.voice, style: options.style }
+      const response = await fetchImpl(this.settings.endpoint, {
+         method: 'POST',
+         headers: { 'Content-Type': 'application/json', ...this.settings.headers },
+         body: JSON.stringify(body),
+         signal,
+      })
+      if (!response.ok) {
+         return null
+      }
+      const contentType = response.headers.get('Content-Type') ?? ''
+      if (contentType.startsWith('audio/')) {
+         return (this.settings.createObjectUrl ?? defaultObjectUrl)(await response.blob())
+      }
+      const payload: unknown = await response.json()
+      if (!isAudioPayload(payload)) {
+         return null
+      }
+      return { url: `data:${payload.mimeType ?? 'audio/wav'};base64,${payload.audioBase64}`, release: () => undefined }
+   }
+
+   /**
+    * @param text - Text to speak.
+    * @param options - Speech options (`rate` is applied at playback).
+    * @returns The prepared utterance; its audio starts downloading now.
+    */
+   prepare(text: string, options: SpeechOptionsInterface): PreparedUtteranceInterface {
+      const controller = new AbortController()
+      let cancelled = false
+      let audio: AudioLike | null = null
+      let finish: ((reason: SpeechEndReason) => void) | null = null
+      const source = this.fetchAudio(text, options, controller.signal).catch(() => null)
+
+      return {
+         play: async (onStarted) => {
+            const ready = await source
+            if (cancelled) {
+               ready?.release()
+               return 'interrupted'
+            }
+            if (!ready) {
+               return 'failed'
+            }
+            const createAudio = this.settings.createAudio ?? ((url: string): AudioLike => new Audio(url))
+            const element = createAudio(ready.url)
+            audio = element
+            element.playbackRate = options.rate ?? 1
+            return new Promise<SpeechEndReason>((resolve) => {
+               finish = (reason) => {
+                  finish = null
+                  audio = null
+                  ready.release()
+                  resolve(reason)
+               }
+               element.onplaying = () => onStarted?.()
+               element.onended = () => finish?.('completed')
+               element.onerror = () => finish?.('failed')
+               element.play().catch(() => finish?.(cancelled ? 'interrupted' : 'failed'))
+            })
+         },
+         cancel: () => {
+            cancelled = true
+            controller.abort()
+            audio?.pause()
+            finish?.('interrupted')
+         },
+      }
+   }
+}

package/src/index.ts

@@ -0,0 +1,2 @@
+export { ApiSpeechSynthesizer, isAudioPayload } from './ApiSpeechSynthesizer'
+export type { AudioLike, AudioSourceInterface, FetchLike, ApiSpeechSynthesizerOptionsInterface } from './ApiSpeechSynthesizer'