@ai-ecoverse/pi-audio 1.0.0 → 1.1.0

package/README.md

@@ -8,7 +8,7 @@ npm install @ai-ecoverse/pi-audio
 
 The package is a TypeScript ES module library for Node 24 and newer. It peers `@earendil-works/pi-ai`.
 
-Transcription, speech, and realtime models are added to pi-ai's `ModelTypeMap` by declaration merging. They are not chat models: `Models.getAllModels()` does not list them. Register them with `registerVoiceModel` and look them up with `getVoiceModel` / `listVoiceModels`. Operations dispatch on `model.api` through `registerTranscriptionApiProvider`, `registerSpeechApiProvider`, and `registerRealtimeApiProvider`. A stored chat credential is reused with `resolveVoiceAuth(models, voiceModel)`, which calls `Models.getAuth` for that provider. Provider adapters ship as their own subpath exports (`@ai-ecoverse/pi-audio/openai`, and the rest) so a host loads only the ones it uses.
+Transcription, speech, and realtime models are added to pi-ai's `ModelTypeMap` by declaration merging. They are not chat models: `Models.getAllModels()` does not list them. Register them with `registerVoiceModel` and look them up with `getVoiceModel` / `listVoiceModels`. Operations dispatch on `model.api` through `registerTranscriptionApiProvider`, `registerSpeechApiProvider`, and `registerRealtimeApiProvider`. A stored chat credential is reused with `resolveVoiceAuth(models, voiceModel)`, which calls `Models.getAuth` for that provider. Provider adapters ship as their own subpath exports (`@ai-ecoverse/pi-audio/openai`, and the rest) so a host loads only the ones it uses. `@ai-ecoverse/pi-audio/faux` registers scripted transcription, speech, and realtime adapters for tests.
 
 ## Development
 

package/dist/faux/index.js

@@ -0,0 +1,15 @@
+import {
+  registerFauxRealtime
+} from "./realtime.js";
+import {
+  registerFauxSpeech
+} from "./speech.js";
+import {
+  registerFauxTranscription
+} from "./transcription.js";
+export {
+  registerFauxRealtime,
+  registerFauxSpeech,
+  registerFauxTranscription
+};
+//# sourceMappingURL=index.js.map

package/dist/faux/index.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/faux/index.ts"],
+  "sourcesContent": ["export {\n  type FauxRealtime,\n  type FauxRealtimeCall,\n  type FauxRealtimeFlags,\n  type FauxRealtimeOptions,\n  registerFauxRealtime,\n} from './realtime.ts';\nexport {\n  type FauxSpeech,\n  type FauxSpeechOptions,\n  registerFauxSpeech,\n} from './speech.ts';\nexport {\n  type FauxTranscription,\n  type FauxTranscriptionCall,\n  type FauxTranscriptionCue,\n  type FauxTranscriptionOptions,\n  registerFauxTranscription,\n} from './transcription.ts';\n"],
+  "mappings": "AAAA;AAAA,EAKE;AAAA,OACK;AACP;AAAA,EAGE;AAAA,OACK;AACP;AAAA,EAKE;AAAA,OACK;",
+  "names": []
+}

package/dist/faux/realtime.js

@@ -0,0 +1,137 @@
+import { blankUsage } from "../blank-usage.js";
+import {
+  registerVoiceModel
+} from "../models.js";
+import { registerRealtimeApiProvider } from "../registry.js";
+import { modelKey, pcm, shareApi, zeroCost } from "./shared.js";
+class FauxSession {
+  model;
+  #calls;
+  #queue = [];
+  #waiters = [];
+  #closed = false;
+  #usage = blankUsage();
+  constructor(model, calls) {
+    this.model = model;
+    this.#calls = calls;
+  }
+  get closed() {
+    return this.#closed;
+  }
+  push(event) {
+    if (this.#closed) return;
+    const waiter = this.#waiters.shift();
+    if (waiter) waiter({ value: event, done: false });
+    else this.#queue.push(event);
+  }
+  appendAudio(chunk) {
+    this.#calls.push({ method: "appendAudio", chunk });
+  }
+  appendVideoFrame(jpeg) {
+    this.#calls.push({ method: "appendVideoFrame", jpeg });
+  }
+  sendText(text) {
+    this.#calls.push({ method: "sendText", text });
+  }
+  inject(text, delivery) {
+    this.#calls.push({ method: "inject", text, delivery });
+  }
+  respond(callId, result, delivery) {
+    this.#calls.push({ method: "respond", callId, result, delivery });
+  }
+  interrupt(heard) {
+    this.#calls.push({ method: "interrupt", heard });
+  }
+  update(patch) {
+    this.#calls.push({ method: "update", patch });
+  }
+  async close() {
+    this.#calls.push({ method: "close" });
+    this.#closed = true;
+    while (this.#waiters.length > 0) this.#waiters.shift()?.({ done: true });
+    return { usage: this.#usage };
+  }
+  async *[Symbol.asyncIterator]() {
+    while (true) {
+      const queued = this.#queue.shift();
+      if (queued) {
+        yield queued;
+        continue;
+      }
+      if (this.#closed) return;
+      const next = await new Promise((resolve) => this.#waiters.push(resolve));
+      if (next.done || next.value === void 0) return;
+      yield next.value;
+    }
+  }
+}
+const states = /* @__PURE__ */ new Map();
+const apis = /* @__PURE__ */ new Map();
+const nativeDelivery = {
+  interrupt: "native",
+  when_idle: "native",
+  silent: "native"
+};
+function registerFauxRealtime(options = {}) {
+  const model = {
+    id: options.id ?? "faux-realtime",
+    name: options.name ?? "Faux realtime",
+    api: options.api ?? "faux-realtime",
+    provider: options.provider ?? "faux",
+    baseUrl: "http://localhost:0",
+    type: "realtime",
+    transports: ["websocket"],
+    toolCalls: options.toolCalls ?? "blocking",
+    inputFormat: pcm(24e3),
+    outputFormat: pcm(24e3),
+    resumable: false,
+    ephemeralAuth: false,
+    voices: [{ id: "faux", name: "Faux" }],
+    provisioning: "none",
+    delivery: options.delivery ?? nativeDelivery,
+    truncation: options.truncation ?? "client",
+    liveToolUpdate: true,
+    cost: zeroCost
+  };
+  const state = { model, calls: [], events: options.events ?? [], pending: [] };
+  states.set(modelKey(model), state);
+  const unregisterModel = registerVoiceModel(model);
+  const release = shareApi(
+    apis,
+    model.api,
+    () => registerRealtimeApiProvider({ api: model.api, connect: connectFaux }),
+    () => [...states.values()].some((entry) => entry.model.api === model.api)
+  );
+  return {
+    model,
+    calls: state.calls,
+    emit(event) {
+      if (state.session) state.session.push(event);
+      if (!state.session || state.session.closed) state.pending.push(event);
+    },
+    setFlags(flags) {
+      if (flags.toolCalls) state.model.toolCalls = flags.toolCalls;
+      if (flags.delivery) state.model.delivery = flags.delivery;
+      if (flags.truncation) state.model.truncation = flags.truncation;
+    },
+    unregister() {
+      if (states.get(modelKey(model)) === state) states.delete(modelKey(model));
+      unregisterModel();
+      release();
+    }
+  };
+}
+async function connectFaux(model, _context, _options) {
+  const state = states.get(modelKey(model));
+  if (!state) throw new Error(`Unknown faux realtime model ${model.provider}/${model.id}`);
+  const session = new FauxSession(state.model, state.calls);
+  state.session = session;
+  for (const event of state.pending) session.push(event);
+  state.pending = [];
+  for (const event of state.events) session.push(event);
+  return session;
+}
+export {
+  registerFauxRealtime
+};
+//# sourceMappingURL=realtime.js.map

package/dist/faux/realtime.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/faux/realtime.ts"],
+  "sourcesContent": ["import type { Usage } from '@earendil-works/pi-ai';\nimport type { AudioChunk } from '../audio.ts';\nimport { blankUsage } from '../blank-usage.ts';\nimport {\n  type Delivery,\n  type DeliverySupport,\n  type RealtimeModel,\n  registerVoiceModel,\n} from '../models.ts';\nimport type {\n  RealtimeContext,\n  RealtimeEvent,\n  RealtimeOptions,\n  RealtimeSession,\n} from '../realtime.ts';\nimport { registerRealtimeApiProvider } from '../registry.ts';\nimport { modelKey, pcm, shareApi, zeroCost } from './shared.ts';\n\nexport type FauxRealtimeCall =\n  | { method: 'appendAudio'; chunk: AudioChunk }\n  | { method: 'appendVideoFrame'; jpeg: Uint8Array }\n  | { method: 'sendText'; text: string }\n  | { method: 'inject'; text: string; delivery: Delivery }\n  | {\n      method: 'respond';\n      callId: string;\n      result: Parameters<RealtimeSession['respond']>[1];\n      delivery?: Delivery;\n    }\n  | { method: 'interrupt'; heard?: { itemId: string; heardMs: number } }\n  | { method: 'update'; patch: Parameters<RealtimeSession['update']>[0] }\n  | { method: 'close' };\n\nexport interface FauxRealtimeFlags {\n  toolCalls?: RealtimeModel<string>['toolCalls'];\n  delivery?: Record<Delivery, DeliverySupport>;\n  truncation?: RealtimeModel<string>['truncation'];\n}\n\nexport interface FauxRealtimeOptions extends FauxRealtimeFlags {\n  api?: string;\n  provider?: string;\n  id?: string;\n  name?: string;\n  events?: RealtimeEvent[];\n}\n\nexport interface FauxRealtime {\n  model: RealtimeModel<string>;\n  calls: FauxRealtimeCall[];\n  emit(event: RealtimeEvent): void;\n  setFlags(flags: FauxRealtimeFlags): void;\n  unregister(): void;\n}\n\ninterface IteratorResultEvent {\n  value?: RealtimeEvent;\n  done: boolean;\n}\n\nclass FauxSession implements RealtimeSession {\n  readonly model: RealtimeModel<string>;\n  readonly #calls: FauxRealtimeCall[];\n  readonly #queue: RealtimeEvent[] = [];\n  readonly #waiters: Array<(result: IteratorResultEvent) => void> = [];\n  #closed = false;\n  readonly #usage: Usage = blankUsage();\n\n  constructor(model: RealtimeModel<string>, calls: FauxRealtimeCall[]) {\n    this.model = model;\n    this.#calls = calls;\n  }\n\n  get closed(): boolean {\n    return this.#closed;\n  }\n\n  push(event: RealtimeEvent): void {\n    if (this.#closed) return;\n    const waiter = this.#waiters.shift();\n    if (waiter) waiter({ value: event, done: false });\n    else this.#queue.push(event);\n  }\n\n  appendAudio(chunk: AudioChunk): void {\n    this.#calls.push({ method: 'appendAudio', chunk });\n  }\n\n  appendVideoFrame(jpeg: Uint8Array): void {\n    this.#calls.push({ method: 'appendVideoFrame', jpeg });\n  }\n\n  sendText(text: string): void {\n    this.#calls.push({ method: 'sendText', text });\n  }\n\n  inject(text: string, delivery: Delivery): void {\n    this.#calls.push({ method: 'inject', text, delivery });\n  }\n\n  respond(\n    callId: string,\n    result: Parameters<RealtimeSession['respond']>[1],\n    delivery?: Delivery\n  ): void {\n    this.#calls.push({ method: 'respond', callId, result, delivery });\n  }\n\n  interrupt(heard?: { itemId: string; heardMs: number }): void {\n    this.#calls.push({ method: 'interrupt', heard });\n  }\n\n  update(patch: Parameters<RealtimeSession['update']>[0]): void {\n    this.#calls.push({ method: 'update', patch });\n  }\n\n  async close(): Promise<{ usage: Usage }> {\n    this.#calls.push({ method: 'close' });\n    this.#closed = true;\n    while (this.#waiters.length > 0) this.#waiters.shift()?.({ done: true });\n    return { usage: this.#usage };\n  }\n\n  async *[Symbol.asyncIterator](): AsyncIterator<RealtimeEvent> {\n    while (true) {\n      const queued = this.#queue.shift();\n      if (queued) {\n        yield queued;\n        continue;\n      }\n      if (this.#closed) return;\n      const next = await new Promise<IteratorResultEvent>((resolve) => this.#waiters.push(resolve));\n      if (next.done || next.value === undefined) return;\n      yield next.value;\n    }\n  }\n}\n\ninterface RealtimeState {\n  model: RealtimeModel<string>;\n  calls: FauxRealtimeCall[];\n  events: RealtimeEvent[];\n  pending: RealtimeEvent[];\n  session?: FauxSession;\n}\n\nconst states = new Map<string, RealtimeState>();\nconst apis = new Map<string, () => void>();\n\nconst nativeDelivery: Record<Delivery, DeliverySupport> = {\n  interrupt: 'native',\n  when_idle: 'native',\n  silent: 'native',\n};\n\nexport function registerFauxRealtime(options: FauxRealtimeOptions = {}): FauxRealtime {\n  const model: RealtimeModel<string> = {\n    id: options.id ?? 'faux-realtime',\n    name: options.name ?? 'Faux realtime',\n    api: options.api ?? 'faux-realtime',\n    provider: options.provider ?? 'faux',\n    baseUrl: 'http://localhost:0',\n    type: 'realtime',\n    transports: ['websocket'],\n    toolCalls: options.toolCalls ?? 'blocking',\n    inputFormat: pcm(24000),\n    outputFormat: pcm(24000),\n    resumable: false,\n    ephemeralAuth: false,\n    voices: [{ id: 'faux', name: 'Faux' }],\n    provisioning: 'none',\n    delivery: options.delivery ?? nativeDelivery,\n    truncation: options.truncation ?? 'client',\n    liveToolUpdate: true,\n    cost: zeroCost,\n  };\n  const state: RealtimeState = { model, calls: [], events: options.events ?? [], pending: [] };\n  states.set(modelKey(model), state);\n  const unregisterModel = registerVoiceModel(model);\n  const release = shareApi(\n    apis,\n    model.api,\n    () => registerRealtimeApiProvider({ api: model.api, connect: connectFaux }),\n    () => [...states.values()].some((entry) => entry.model.api === model.api)\n  );\n  return {\n    model,\n    calls: state.calls,\n    emit(event) {\n      if (state.session) state.session.push(event);\n      if (!state.session || state.session.closed) state.pending.push(event);\n    },\n    setFlags(flags) {\n      if (flags.toolCalls) state.model.toolCalls = flags.toolCalls;\n      if (flags.delivery) state.model.delivery = flags.delivery;\n      if (flags.truncation) state.model.truncation = flags.truncation;\n    },\n    unregister() {\n      if (states.get(modelKey(model)) === state) states.delete(modelKey(model));\n      unregisterModel();\n      release();\n    },\n  };\n}\n\nasync function connectFaux(\n  model: RealtimeModel<string>,\n  _context: RealtimeContext,\n  _options?: RealtimeOptions\n): Promise<RealtimeSession> {\n  const state = states.get(modelKey(model));\n  if (!state) throw new Error(`Unknown faux realtime model ${model.provider}/${model.id}`);\n  const session = new FauxSession(state.model, state.calls);\n  state.session = session;\n  for (const event of state.pending) session.push(event);\n  state.pending = [];\n  for (const event of state.events) session.push(event);\n  return session;\n}\n"],
+  "mappings": "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",
+  "names": []
+}

package/dist/faux/shared.js

@@ -0,0 +1,37 @@
+const zeroCost = { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 };
+function pcm(sampleRate = 24e3) {
+  return { encoding: "pcm16", sampleRate, channels: 1 };
+}
+function modelKey(model) {
+  return `${model.provider}\0${model.id}`;
+}
+function decodeBytes(data) {
+  return new TextDecoder().decode(data);
+}
+function encodeChars(text) {
+  const bytes = new Uint8Array(text.length);
+  for (let index = 0; index < text.length; index++) bytes[index] = text.charCodeAt(index) & 255;
+  return bytes;
+}
+function errorMessage(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+function shareApi(registrations, api, register, stillUsed) {
+  if (!registrations.has(api)) registrations.set(api, register());
+  return () => {
+    if (stillUsed()) return;
+    const unregister = registrations.get(api);
+    registrations.delete(api);
+    if (unregister) unregister();
+  };
+}
+export {
+  decodeBytes,
+  encodeChars,
+  errorMessage,
+  modelKey,
+  pcm,
+  shareApi,
+  zeroCost
+};
+//# sourceMappingURL=shared.js.map

package/dist/faux/shared.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/faux/shared.ts"],
+  "sourcesContent": ["import type { AudioFormat } from '../audio.ts';\n\nexport const zeroCost = { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 };\n\nexport function pcm(sampleRate = 24000): AudioFormat {\n  return { encoding: 'pcm16', sampleRate, channels: 1 };\n}\n\nexport function modelKey(model: { provider: string; id: string }): string {\n  return `${model.provider}\\0${model.id}`;\n}\n\nexport function decodeBytes(data: Uint8Array): string {\n  return new TextDecoder().decode(data);\n}\n\nexport function encodeChars(text: string): Uint8Array {\n  const bytes = new Uint8Array(text.length);\n  for (let index = 0; index < text.length; index++) bytes[index] = text.charCodeAt(index) & 0xff;\n  return bytes;\n}\n\nexport function errorMessage(error: unknown): string {\n  return error instanceof Error ? error.message : String(error);\n}\n\nexport function shareApi(\n  registrations: Map<string, () => void>,\n  api: string,\n  register: () => () => void,\n  stillUsed: () => boolean\n): () => void {\n  if (!registrations.has(api)) registrations.set(api, register());\n  return () => {\n    if (stillUsed()) return;\n    const unregister = registrations.get(api);\n    registrations.delete(api);\n    if (unregister) unregister();\n  };\n}\n"],
+  "mappings": "AAEO,MAAM,WAAW,EAAE,OAAO,GAAG,QAAQ,GAAG,WAAW,GAAG,YAAY,EAAE;AAEpE,SAAS,IAAI,aAAa,MAAoB;AACnD,SAAO,EAAE,UAAU,SAAS,YAAY,UAAU,EAAE;AACtD;AAEO,SAAS,SAAS,OAAiD;AACxE,SAAO,GAAG,MAAM,QAAQ,KAAK,MAAM,EAAE;AACvC;AAEO,SAAS,YAAY,MAA0B;AACpD,SAAO,IAAI,YAAY,EAAE,OAAO,IAAI;AACtC;AAEO,SAAS,YAAY,MAA0B;AACpD,QAAM,QAAQ,IAAI,WAAW,KAAK,MAAM;AACxC,WAAS,QAAQ,GAAG,QAAQ,KAAK,QAAQ,QAAS,OAAM,KAAK,IAAI,KAAK,WAAW,KAAK,IAAI;AAC1F,SAAO;AACT;AAEO,SAAS,aAAa,OAAwB;AACnD,SAAO,iBAAiB,QAAQ,MAAM,UAAU,OAAO,KAAK;AAC9D;AAEO,SAAS,SACd,eACA,KACA,UACA,WACY;AACZ,MAAI,CAAC,cAAc,IAAI,GAAG,EAAG,eAAc,IAAI,KAAK,SAAS,CAAC;AAC9D,SAAO,MAAM;AACX,QAAI,UAAU,EAAG;AACjB,UAAM,aAAa,cAAc,IAAI,GAAG;AACxC,kBAAc,OAAO,GAAG;AACxB,QAAI,WAAY,YAAW;AAAA,EAC7B;AACF;",
+  "names": []
+}

package/dist/faux/speech.js

@@ -0,0 +1,108 @@
+import { blankUsage } from "../blank-usage.js";
+import { VoiceRequestError } from "../errors.js";
+import { registerVoiceModel } from "../models.js";
+import { registerSpeechApiProvider } from "../registry.js";
+import { SpeechEventStream } from "../speech.js";
+import { encodeChars, errorMessage, modelKey, pcm, shareApi, zeroCost } from "./shared.js";
+const states = /* @__PURE__ */ new Map();
+const apis = /* @__PURE__ */ new Map();
+function registerFauxSpeech(options = {}) {
+  const model = {
+    id: options.id ?? "faux-speech",
+    name: options.name ?? "Faux speech",
+    api: options.api ?? "faux-speech",
+    provider: options.provider ?? "faux",
+    baseUrl: "http://localhost:0",
+    type: "speech",
+    textStreaming: options.textStreaming ?? true,
+    outputFormats: [pcm()],
+    voices: [{ id: "faux", name: "Faux", languages: ["en"] }],
+    cloning: false,
+    cost: zeroCost
+  };
+  const state = {
+    model,
+    alignment: options.alignment ?? false,
+    chunkChars: Math.max(1, options.chunkChars ?? 4),
+    calls: []
+  };
+  states.set(modelKey(model), state);
+  const unregisterModel = registerVoiceModel(model);
+  const release = shareApi(
+    apis,
+    model.api,
+    () => registerSpeechApiProvider({ api: model.api, speak: speakFaux }),
+    () => [...states.values()].some((entry) => entry.model.api === model.api)
+  );
+  return {
+    model,
+    calls: state.calls,
+    setAlignment(alignment) {
+      state.alignment = alignment;
+    },
+    unregister() {
+      if (states.get(modelKey(model)) === state) states.delete(modelKey(model));
+      unregisterModel();
+      release();
+    }
+  };
+}
+function speakFaux(model, input, options) {
+  const stream = new SpeechEventStream();
+  const state = states.get(modelKey(model));
+  if (!state) {
+    stream.push({
+      type: "error",
+      reason: "error",
+      error: `Unknown faux speech model ${model.provider}/${model.id}`
+    });
+    return stream;
+  }
+  state.calls.push(input);
+  void pumpSpeech(state, input, options, stream);
+  return stream;
+}
+async function readText(input, signal) {
+  if (typeof input.text === "string") return input.text;
+  let text = "";
+  for await (const part of input.text) {
+    if (signal?.aborted) throw new VoiceRequestError("aborted", "aborted");
+    text += part;
+  }
+  return text;
+}
+function alignmentFor(start, length) {
+  const startMs = [];
+  const durationMs = [];
+  for (let offset = 0; offset < length; offset++) {
+    startMs.push((start + offset) * 20);
+    durationMs.push(20);
+  }
+  return { startMs, durationMs };
+}
+async function pumpSpeech(state, input, options, stream) {
+  try {
+    if (options?.signal?.aborted) throw new VoiceRequestError("aborted", "aborted");
+    const text = await readText(input, options?.signal);
+    const format = input.format ?? state.model.outputFormats[0];
+    if (!format) throw new Error("No output format");
+    stream.push({ type: "start", format });
+    for (let start = 0; start < text.length; start += state.chunkChars) {
+      const slice = text.slice(start, start + state.chunkChars);
+      stream.push({
+        type: "audio",
+        chunk: { data: encodeChars(slice), format, timestamp: start * 20 },
+        span: { itemId: state.model.id, start, end: start + slice.length },
+        ...state.alignment ? { alignment: alignmentFor(start, slice.length) } : {}
+      });
+    }
+    stream.push({ type: "done", usage: blankUsage() });
+  } catch (error) {
+    const reason = error instanceof VoiceRequestError ? error.reason : "error";
+    stream.push({ type: "error", reason, error: errorMessage(error) });
+  }
+}
+export {
+  registerFauxSpeech
+};
+//# sourceMappingURL=speech.js.map

package/dist/faux/speech.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/faux/speech.ts"],
+  "sourcesContent": ["import type { ProviderRequestOptions } from '@earendil-works/pi-ai';\nimport type { AudioFormat, CharAlignment } from '../audio.ts';\nimport { blankUsage } from '../blank-usage.ts';\nimport { VoiceRequestError } from '../errors.ts';\nimport { registerVoiceModel, type SpeechModel } from '../models.ts';\nimport { registerSpeechApiProvider } from '../registry.ts';\nimport { SpeechEventStream, type SpeechInput } from '../speech.ts';\nimport { encodeChars, errorMessage, modelKey, pcm, shareApi, zeroCost } from './shared.ts';\n\nexport interface FauxSpeechOptions {\n  api?: string;\n  provider?: string;\n  id?: string;\n  name?: string;\n  alignment?: boolean;\n  chunkChars?: number;\n  textStreaming?: boolean;\n}\n\nexport interface FauxSpeech {\n  model: SpeechModel<string>;\n  calls: SpeechInput[];\n  setAlignment(alignment: boolean): void;\n  unregister(): void;\n}\n\ninterface SpeechState {\n  model: SpeechModel<string>;\n  alignment: boolean;\n  chunkChars: number;\n  calls: SpeechInput[];\n}\n\nconst states = new Map<string, SpeechState>();\nconst apis = new Map<string, () => void>();\n\nexport function registerFauxSpeech(options: FauxSpeechOptions = {}): FauxSpeech {\n  const model: SpeechModel<string> = {\n    id: options.id ?? 'faux-speech',\n    name: options.name ?? 'Faux speech',\n    api: options.api ?? 'faux-speech',\n    provider: options.provider ?? 'faux',\n    baseUrl: 'http://localhost:0',\n    type: 'speech',\n    textStreaming: options.textStreaming ?? true,\n    outputFormats: [pcm()],\n    voices: [{ id: 'faux', name: 'Faux', languages: ['en'] }],\n    cloning: false,\n    cost: zeroCost,\n  };\n  const state: SpeechState = {\n    model,\n    alignment: options.alignment ?? false,\n    chunkChars: Math.max(1, options.chunkChars ?? 4),\n    calls: [],\n  };\n  states.set(modelKey(model), state);\n  const unregisterModel = registerVoiceModel(model);\n  const release = shareApi(\n    apis,\n    model.api,\n    () => registerSpeechApiProvider({ api: model.api, speak: speakFaux }),\n    () => [...states.values()].some((entry) => entry.model.api === model.api)\n  );\n  return {\n    model,\n    calls: state.calls,\n    setAlignment(alignment) {\n      state.alignment = alignment;\n    },\n    unregister() {\n      if (states.get(modelKey(model)) === state) states.delete(modelKey(model));\n      unregisterModel();\n      release();\n    },\n  };\n}\n\nfunction speakFaux(\n  model: SpeechModel<string>,\n  input: SpeechInput,\n  options?: ProviderRequestOptions\n): SpeechEventStream {\n  const stream = new SpeechEventStream();\n  const state = states.get(modelKey(model));\n  if (!state) {\n    stream.push({\n      type: 'error',\n      reason: 'error',\n      error: `Unknown faux speech model ${model.provider}/${model.id}`,\n    });\n    return stream;\n  }\n  state.calls.push(input);\n  void pumpSpeech(state, input, options, stream);\n  return stream;\n}\n\nasync function readText(input: SpeechInput, signal: AbortSignal | undefined): Promise<string> {\n  if (typeof input.text === 'string') return input.text;\n  let text = '';\n  for await (const part of input.text) {\n    if (signal?.aborted) throw new VoiceRequestError('aborted', 'aborted');\n    text += part;\n  }\n  return text;\n}\n\nfunction alignmentFor(start: number, length: number): CharAlignment {\n  const startMs = [];\n  const durationMs = [];\n  for (let offset = 0; offset < length; offset++) {\n    startMs.push((start + offset) * 20);\n    durationMs.push(20);\n  }\n  return { startMs, durationMs };\n}\n\nasync function pumpSpeech(\n  state: SpeechState,\n  input: SpeechInput,\n  options: ProviderRequestOptions | undefined,\n  stream: SpeechEventStream\n) {\n  try {\n    if (options?.signal?.aborted) throw new VoiceRequestError('aborted', 'aborted');\n    const text = await readText(input, options?.signal);\n    const format: AudioFormat | undefined = input.format ?? state.model.outputFormats[0];\n    if (!format) throw new Error('No output format');\n    stream.push({ type: 'start', format });\n    for (let start = 0; start < text.length; start += state.chunkChars) {\n      const slice = text.slice(start, start + state.chunkChars);\n      stream.push({\n        type: 'audio',\n        chunk: { data: encodeChars(slice), format, timestamp: start * 20 },\n        span: { itemId: state.model.id, start, end: start + slice.length },\n        ...(state.alignment ? { alignment: alignmentFor(start, slice.length) } : {}),\n      });\n    }\n    stream.push({ type: 'done', usage: blankUsage() });\n  } catch (error) {\n    const reason = error instanceof VoiceRequestError ? error.reason : 'error';\n    stream.push({ type: 'error', reason, error: errorMessage(error) });\n  }\n}\n"],
+  "mappings": "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",
+  "names": []
+}

package/dist/faux/transcription.js

@@ -0,0 +1,152 @@
+import { blankUsage } from "../blank-usage.js";
+import { VoiceRequestError } from "../errors.js";
+import { registerVoiceModel } from "../models.js";
+import { registerTranscriptionApiProvider } from "../registry.js";
+import {
+  TranscriptionEventStream
+} from "../transcription.js";
+import { decodeBytes, errorMessage, modelKey, pcm, shareApi, zeroCost } from "./shared.js";
+const states = /* @__PURE__ */ new Map();
+const apis = /* @__PURE__ */ new Map();
+function requireState(model) {
+  const state = states.get(modelKey(model));
+  if (!state) throw new Error(`Unknown faux transcription model ${model.provider}/${model.id}`);
+  return state;
+}
+function registerFauxTranscription(options = {}) {
+  const model = {
+    id: options.id ?? "faux-transcription",
+    name: options.name ?? "Faux transcription",
+    api: options.api ?? "faux-transcription",
+    provider: options.provider ?? "faux",
+    baseUrl: "http://localhost:0",
+    type: "transcription",
+    streaming: true,
+    turnDetection: options.turnDetection ?? "vad",
+    inputFormats: [pcm(16e3)],
+    languages: ["en"],
+    diarization: false,
+    cost: zeroCost
+  };
+  const state = { model, cues: options.cues, calls: [] };
+  states.set(modelKey(model), state);
+  const unregisterModel = registerVoiceModel(model);
+  const release = shareApi(
+    apis,
+    model.api,
+    () => registerTranscriptionApiProvider({
+      api: model.api,
+      transcribe: transcribeFaux,
+      listen: listenFaux
+    }),
+    () => [...states.values()].some((entry) => entry.model.api === model.api)
+  );
+  return {
+    model,
+    calls: state.calls,
+    setCues(cues) {
+      state.cues = cues;
+    },
+    unregister() {
+      if (states.get(modelKey(model)) === state) states.delete(modelKey(model));
+      unregisterModel();
+      release();
+    }
+  };
+}
+async function transcribeFaux(model, input, options) {
+  if (options?.signal?.aborted) throw new VoiceRequestError("aborted", "aborted");
+  const state = requireState(model);
+  state.calls.push({ kind: "transcribe", input, chunks: [] });
+  const text = "url" in input ? input.url : decodeBytes(input.data);
+  return { text, usage: blankUsage() };
+}
+function listenFaux(model, audio, options) {
+  const stream = new TranscriptionEventStream();
+  let state;
+  try {
+    state = requireState(model);
+  } catch (error) {
+    stream.push({ type: "error", reason: "error", error: errorMessage(error) });
+    return stream;
+  }
+  void pumpListen(state, audio, options, stream);
+  return stream;
+}
+function createPump(stream) {
+  const pump = {
+    stream,
+    finished: false,
+    push(event) {
+      if (pump.finished) return;
+      if (event.type === "turn_end") pump.turnText = event.text;
+      stream.push(event);
+      if (event.type === "done" || event.type === "error") pump.finished = true;
+    }
+  };
+  return pump;
+}
+function cuesAt(cues, at) {
+  return cues.filter((cue) => cue.at === at).flatMap((cue) => cue.events);
+}
+function endCues(cues, count) {
+  return cues.filter((cue) => cue.at === "end" || typeof cue.at === "number" && cue.at > count).flatMap((cue) => cue.events);
+}
+function finishScript(pump, cues, text, at, count) {
+  if (pump.finished) return;
+  if (cues) for (const event of endCues(cues, count)) pump.push(event);
+  else {
+    pump.push({ type: "final", segmentId: "0", text });
+    pump.push({ type: "turn_end", text, at });
+  }
+  if (!pump.finished) {
+    pump.push({
+      type: "done",
+      transcript: { text: pump.turnText ?? text, usage: blankUsage() }
+    });
+  }
+}
+async function pumpListen(state, audio, options, stream) {
+  const pump = createPump(stream);
+  const call = { kind: "listen", chunks: [] };
+  state.calls.push(call);
+  let text = "";
+  let at = 0;
+  let count = 0;
+  try {
+    if (options?.signal?.aborted) {
+      pump.push({ type: "error", reason: "aborted", error: "aborted" });
+      return;
+    }
+    for (const event of cuesAt(state.cues ?? [], 0)) pump.push(event);
+    if (!pump.finished) {
+      for await (const chunk of audio) {
+        if (pump.finished || options?.signal?.aborted) break;
+        call.chunks.push(chunk);
+        count += 1;
+        at = chunk.timestamp;
+        text += decodeBytes(chunk.data);
+        deliverChunk(pump, state.cues, chunk, count, text);
+      }
+    }
+    if (options?.signal?.aborted && !pump.finished) {
+      pump.push({ type: "error", reason: "aborted", error: "aborted" });
+      return;
+    }
+    finishScript(pump, state.cues, text, at, count);
+  } catch (error) {
+    pump.push({ type: "error", reason: "error", error: errorMessage(error) });
+  }
+}
+function deliverChunk(pump, cues, chunk, count, text) {
+  if (cues) {
+    for (const event of cuesAt(cues, count)) pump.push(event);
+    return;
+  }
+  if (count === 1) pump.push({ type: "speech_start", at: chunk.timestamp });
+  pump.push({ type: "partial", segmentId: "0", text });
+}
+export {
+  registerFauxTranscription
+};
+//# sourceMappingURL=transcription.js.map

package/dist/faux/transcription.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/faux/transcription.ts"],
+  "sourcesContent": ["import type { ProviderRequestOptions } from '@earendil-works/pi-ai';\nimport type { AudioChunk, AudioSource } from '../audio.ts';\nimport { blankUsage } from '../blank-usage.ts';\nimport { VoiceRequestError } from '../errors.ts';\nimport { registerVoiceModel, type TranscriptionModel } from '../models.ts';\nimport { registerTranscriptionApiProvider } from '../registry.ts';\nimport {\n  type AudioInput,\n  type ListenOptions,\n  type TranscriptionEvent,\n  TranscriptionEventStream,\n} from '../transcription.ts';\nimport { decodeBytes, errorMessage, modelKey, pcm, shareApi, zeroCost } from './shared.ts';\n\nexport interface FauxTranscriptionCue {\n  at: number | 'end';\n  events: TranscriptionEvent[];\n}\n\nexport interface FauxTranscriptionOptions {\n  api?: string;\n  provider?: string;\n  id?: string;\n  name?: string;\n  turnDetection?: TranscriptionModel<string>['turnDetection'];\n  cues?: FauxTranscriptionCue[];\n}\n\nexport interface FauxTranscriptionCall {\n  kind: 'transcribe' | 'listen';\n  input?: AudioInput;\n  chunks: AudioChunk[];\n}\n\nexport interface FauxTranscription {\n  model: TranscriptionModel<string>;\n  calls: FauxTranscriptionCall[];\n  setCues(cues: FauxTranscriptionCue[] | undefined): void;\n  unregister(): void;\n}\n\ninterface TranscriptionState {\n  model: TranscriptionModel<string>;\n  cues?: FauxTranscriptionCue[];\n  calls: FauxTranscriptionCall[];\n}\n\nconst states = new Map<string, TranscriptionState>();\nconst apis = new Map<string, () => void>();\n\nfunction requireState(model: TranscriptionModel<string>): TranscriptionState {\n  const state = states.get(modelKey(model));\n  if (!state) throw new Error(`Unknown faux transcription model ${model.provider}/${model.id}`);\n  return state;\n}\n\nexport function registerFauxTranscription(\n  options: FauxTranscriptionOptions = {}\n): FauxTranscription {\n  const model: TranscriptionModel<string> = {\n    id: options.id ?? 'faux-transcription',\n    name: options.name ?? 'Faux transcription',\n    api: options.api ?? 'faux-transcription',\n    provider: options.provider ?? 'faux',\n    baseUrl: 'http://localhost:0',\n    type: 'transcription',\n    streaming: true,\n    turnDetection: options.turnDetection ?? 'vad',\n    inputFormats: [pcm(16000)],\n    languages: ['en'],\n    diarization: false,\n    cost: zeroCost,\n  };\n  const state: TranscriptionState = { model, cues: options.cues, calls: [] };\n  states.set(modelKey(model), state);\n  const unregisterModel = registerVoiceModel(model);\n  const release = shareApi(\n    apis,\n    model.api,\n    () =>\n      registerTranscriptionApiProvider({\n        api: model.api,\n        transcribe: transcribeFaux,\n        listen: listenFaux,\n      }),\n    () => [...states.values()].some((entry) => entry.model.api === model.api)\n  );\n  return {\n    model,\n    calls: state.calls,\n    setCues(cues) {\n      state.cues = cues;\n    },\n    unregister() {\n      if (states.get(modelKey(model)) === state) states.delete(modelKey(model));\n      unregisterModel();\n      release();\n    },\n  };\n}\n\nasync function transcribeFaux(\n  model: TranscriptionModel<string>,\n  input: AudioInput,\n  options?: ProviderRequestOptions\n) {\n  if (options?.signal?.aborted) throw new VoiceRequestError('aborted', 'aborted');\n  const state = requireState(model);\n  state.calls.push({ kind: 'transcribe', input, chunks: [] });\n  const text = 'url' in input ? input.url : decodeBytes(input.data);\n  return { text, usage: blankUsage() };\n}\n\nfunction listenFaux(\n  model: TranscriptionModel<string>,\n  audio: AudioSource,\n  options?: ListenOptions\n): TranscriptionEventStream {\n  const stream = new TranscriptionEventStream();\n  let state: TranscriptionState;\n  try {\n    state = requireState(model);\n  } catch (error) {\n    stream.push({ type: 'error', reason: 'error', error: errorMessage(error) });\n    return stream;\n  }\n  void pumpListen(state, audio, options, stream);\n  return stream;\n}\n\ninterface Pump {\n  stream: TranscriptionEventStream;\n  finished: boolean;\n  turnText?: string;\n  push(event: TranscriptionEvent): void;\n}\n\nfunction createPump(stream: TranscriptionEventStream): Pump {\n  const pump: Pump = {\n    stream,\n    finished: false,\n    push(event) {\n      if (pump.finished) return;\n      if (event.type === 'turn_end') pump.turnText = event.text;\n      stream.push(event);\n      if (event.type === 'done' || event.type === 'error') pump.finished = true;\n    },\n  };\n  return pump;\n}\n\nfunction cuesAt(cues: FauxTranscriptionCue[], at: number | 'end'): TranscriptionEvent[] {\n  return cues.filter((cue) => cue.at === at).flatMap((cue) => cue.events);\n}\n\nfunction endCues(cues: FauxTranscriptionCue[], count: number): TranscriptionEvent[] {\n  return cues\n    .filter((cue) => cue.at === 'end' || (typeof cue.at === 'number' && cue.at > count))\n    .flatMap((cue) => cue.events);\n}\n\nfunction finishScript(\n  pump: Pump,\n  cues: FauxTranscriptionCue[] | undefined,\n  text: string,\n  at: number,\n  count: number\n) {\n  if (pump.finished) return;\n  if (cues) for (const event of endCues(cues, count)) pump.push(event);\n  else {\n    pump.push({ type: 'final', segmentId: '0', text });\n    pump.push({ type: 'turn_end', text, at });\n  }\n  if (!pump.finished) {\n    pump.push({\n      type: 'done',\n      transcript: { text: pump.turnText ?? text, usage: blankUsage() },\n    });\n  }\n}\n\nasync function pumpListen(\n  state: TranscriptionState,\n  audio: AudioSource,\n  options: ListenOptions | undefined,\n  stream: TranscriptionEventStream\n) {\n  const pump = createPump(stream);\n  const call: FauxTranscriptionCall = { kind: 'listen', chunks: [] };\n  state.calls.push(call);\n  let text = '';\n  let at = 0;\n  let count = 0;\n  try {\n    if (options?.signal?.aborted) {\n      pump.push({ type: 'error', reason: 'aborted', error: 'aborted' });\n      return;\n    }\n    for (const event of cuesAt(state.cues ?? [], 0)) pump.push(event);\n    if (!pump.finished) {\n      for await (const chunk of audio) {\n        if (pump.finished || options?.signal?.aborted) break;\n        call.chunks.push(chunk);\n        count += 1;\n        at = chunk.timestamp;\n        text += decodeBytes(chunk.data);\n        deliverChunk(pump, state.cues, chunk, count, text);\n      }\n    }\n    if (options?.signal?.aborted && !pump.finished) {\n      pump.push({ type: 'error', reason: 'aborted', error: 'aborted' });\n      return;\n    }\n    finishScript(pump, state.cues, text, at, count);\n  } catch (error) {\n    pump.push({ type: 'error', reason: 'error', error: errorMessage(error) });\n  }\n}\n\nfunction deliverChunk(\n  pump: Pump,\n  cues: FauxTranscriptionCue[] | undefined,\n  chunk: AudioChunk,\n  count: number,\n  text: string\n) {\n  if (cues) {\n    for (const event of cuesAt(cues, count)) pump.push(event);\n    return;\n  }\n  if (count === 1) pump.push({ type: 'speech_start', at: chunk.timestamp });\n  pump.push({ type: 'partial', segmentId: '0', text });\n}\n"],
+  "mappings": "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",
+  "names": []
+}

package/dist/types/faux/index.d.ts

@@ -0,0 +1,3 @@
+export { type FauxRealtime, type FauxRealtimeCall, type FauxRealtimeFlags, type FauxRealtimeOptions, registerFauxRealtime, } from './realtime.ts';
+export { type FauxSpeech, type FauxSpeechOptions, registerFauxSpeech, } from './speech.ts';
+export { type FauxTranscription, type FauxTranscriptionCall, type FauxTranscriptionCue, type FauxTranscriptionOptions, registerFauxTranscription, } from './transcription.ts';

package/dist/types/faux/realtime.d.ts

@@ -0,0 +1,53 @@
+import type { AudioChunk } from '../audio.ts';
+import { type Delivery, type DeliverySupport, type RealtimeModel } from '../models.ts';
+import type { RealtimeEvent, RealtimeSession } from '../realtime.ts';
+export type FauxRealtimeCall = {
+    method: 'appendAudio';
+    chunk: AudioChunk;
+} | {
+    method: 'appendVideoFrame';
+    jpeg: Uint8Array;
+} | {
+    method: 'sendText';
+    text: string;
+} | {
+    method: 'inject';
+    text: string;
+    delivery: Delivery;
+} | {
+    method: 'respond';
+    callId: string;
+    result: Parameters<RealtimeSession['respond']>[1];
+    delivery?: Delivery;
+} | {
+    method: 'interrupt';
+    heard?: {
+        itemId: string;
+        heardMs: number;
+    };
+} | {
+    method: 'update';
+    patch: Parameters<RealtimeSession['update']>[0];
+} | {
+    method: 'close';
+};
+export interface FauxRealtimeFlags {
+    toolCalls?: RealtimeModel<string>['toolCalls'];
+    delivery?: Record<Delivery, DeliverySupport>;
+    truncation?: RealtimeModel<string>['truncation'];
+}
+export interface FauxRealtimeOptions extends FauxRealtimeFlags {
+    api?: string;
+    provider?: string;
+    id?: string;
+    name?: string;
+    events?: RealtimeEvent[];
+}
+export interface FauxRealtime {
+    model: RealtimeModel<string>;
+    calls: FauxRealtimeCall[];
+    emit(event: RealtimeEvent): void;
+    setFlags(flags: FauxRealtimeFlags): void;
+    unregister(): void;
+}
+export declare function registerFauxRealtime(options?: FauxRealtimeOptions): FauxRealtime;

package/dist/types/faux/shared.d.ts

@@ -0,0 +1,16 @@
+import type { AudioFormat } from '../audio.ts';
+export declare const zeroCost: {
+    input: number;
+    output: number;
+    cacheRead: number;
+    cacheWrite: number;
+};
+export declare function pcm(sampleRate?: number): AudioFormat;
+export declare function modelKey(model: {
+    provider: string;
+    id: string;
+}): string;
+export declare function decodeBytes(data: Uint8Array): string;
+export declare function encodeChars(text: string): Uint8Array;
+export declare function errorMessage(error: unknown): string;
+export declare function shareApi(registrations: Map<string, () => void>, api: string, register: () => () => void, stillUsed: () => boolean): () => void;

package/dist/types/faux/speech.d.ts

@@ -0,0 +1,18 @@
+import { type SpeechModel } from '../models.ts';
+import { type SpeechInput } from '../speech.ts';
+export interface FauxSpeechOptions {
+    api?: string;
+    provider?: string;
+    id?: string;
+    name?: string;
+    alignment?: boolean;
+    chunkChars?: number;
+    textStreaming?: boolean;
+}
+export interface FauxSpeech {
+    model: SpeechModel<string>;
+    calls: SpeechInput[];
+    setAlignment(alignment: boolean): void;
+    unregister(): void;
+}
+export declare function registerFauxSpeech(options?: FauxSpeechOptions): FauxSpeech;

package/dist/types/faux/transcription.d.ts

@@ -0,0 +1,27 @@
+import type { AudioChunk } from '../audio.ts';
+import { type TranscriptionModel } from '../models.ts';
+import { type AudioInput, type TranscriptionEvent } from '../transcription.ts';
+export interface FauxTranscriptionCue {
+    at: number | 'end';
+    events: TranscriptionEvent[];
+}
+export interface FauxTranscriptionOptions {
+    api?: string;
+    provider?: string;
+    id?: string;
+    name?: string;
+    turnDetection?: TranscriptionModel<string>['turnDetection'];
+    cues?: FauxTranscriptionCue[];
+}
+export interface FauxTranscriptionCall {
+    kind: 'transcribe' | 'listen';
+    input?: AudioInput;
+    chunks: AudioChunk[];
+}
+export interface FauxTranscription {
+    model: TranscriptionModel<string>;
+    calls: FauxTranscriptionCall[];
+    setCues(cues: FauxTranscriptionCue[] | undefined): void;
+    unregister(): void;
+}
+export declare function registerFauxTranscription(options?: FauxTranscriptionOptions): FauxTranscription;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-ecoverse/pi-audio",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Voice bindings for pi: speech-to-text, text-to-speech and realtime speech for pi-coding-agent plugins and slicc-agent",
   "type": "module",
   "license": "Apache-2.0",
@@ -25,6 +25,10 @@
     ".": {
       "types": "./dist/types/index.d.ts",
       "default": "./dist/index.js"
+    },
+    "./faux": {
+      "types": "./dist/types/faux/index.d.ts",
+      "default": "./dist/faux/index.js"
     }
   },
   "files": [
@@ -47,7 +51,7 @@
   "devDependencies": {
     "@ai-ecoverse/slicc-shared-web": "1.21.0",
     "@biomejs/biome": "2.5.15",
-    "@earendil-works/pi-ai": "1.0.4",
+    "@earendil-works/pi-ai": "1.1.0",
     "@types/node": "24.19.1",
     "esbuild": "0.28.2",
     "lefthook": "2.2.1",
@@ -56,6 +60,6 @@
     "typescript": "7.0.2"
   },
   "peerDependencies": {
-    "@earendil-works/pi-ai": "1.0.4"
+    "@earendil-works/pi-ai": "1.1.0"
   }
 }