@ai-ecoverse/pi-audio 0.0.0-stage → 1.0.0

package/LICENSE

@@ -0,0 +1,191 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to the Licensor for inclusion in the Work by the copyright
+      owner or by an individual or Legal Entity authorized to submit on
+      behalf of the copyright owner. For the purposes of this definition,
+      "submitted" means any form of electronic, verbal, or written
+      communication sent to the Licensor or its representatives, including
+      but not limited to communication on electronic mailing lists, source
+      code control systems, and issue tracking systems that are managed by,
+      or on behalf of, the Licensor for the purpose of discussing and
+      improving the Work, but excluding communication that is conspicuously
+      marked or otherwise designated in writing by the copyright owner as
+      "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   Copyright 2025 ai-ecoverse
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,3 +1,31 @@
-# Temporary Holding Version
+# pi-audio
 
-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.
+Voice bindings for [pi](https://github.com/earendil-works/pi): speech-to-text, text-to-speech and realtime speech, for pi-coding-agent plugins and [slicc-agent](https://github.com/ai-ecoverse/slicc-agent).
+
+```sh
+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.
+
+## Development
+
+```sh
+npm ci
+npm run lint
+npm test
+```
+
+- `npm run lint` runs [slicc-lint](https://github.com/ai-ecoverse/slicc-shared-web): Biome, the type check, the no-comments rule, no unit tests in git, and the AGENTS.md limit. lefthook runs the same checks before each commit.
+- `npm test` builds `dist/` and runs the integration tests in `test/integration/`.
+- Unit tests live in the gitignored `test/unit/` and run with `npm run test:unit`.
+
+## Releases
+
+Every push to `main` runs semantic-release, which reads the conventional commit messages, tags the version and writes the GitHub release. A second job then publishes the tag to npm through trusted publishing (OIDC), with provenance, from GitHub-hosted runners. Nothing is published from a branch or from a laptop.
+
+## License
+
+Apache-2.0

package/dist/audio.js

@@ -0,0 +1 @@
+//# sourceMappingURL=audio.js.map

package/dist/audio.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": [],
+  "sourcesContent": [],
+  "mappings": "",
+  "names": []
+}

package/dist/auth.js

@@ -0,0 +1,7 @@
+function resolveVoiceAuth(models, model, overrides) {
+  return models.getAuth(model, overrides);
+}
+export {
+  resolveVoiceAuth
+};
+//# sourceMappingURL=auth.js.map

package/dist/auth.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../src/auth.ts"],
+  "sourcesContent": ["import type { AuthResult, Models } from '@earendil-works/pi-ai';\nimport type { VoiceModel } from './models.ts';\n\nexport function resolveVoiceAuth(\n  models: Models,\n  model: VoiceModel,\n  overrides?: Parameters<Models['getAuth']>[1]\n): Promise<AuthResult | undefined> {\n  return models.getAuth(model, overrides);\n}\n"],
+  "mappings": "AAGO,SAAS,iBACd,QACA,OACA,WACiC;AACjC,SAAO,OAAO,QAAQ,OAAO,SAAS;AACxC;",
+  "names": []
+}

package/dist/blank-usage.js

@@ -0,0 +1,14 @@
+function blankUsage() {
+  return {
+    input: 0,
+    output: 0,
+    cacheRead: 0,
+    cacheWrite: 0,
+    totalTokens: 0,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 }
+  };
+}
+export {
+  blankUsage
+};
+//# sourceMappingURL=blank-usage.js.map

package/dist/blank-usage.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../src/blank-usage.ts"],
+  "sourcesContent": ["import type { Usage } from '@earendil-works/pi-ai';\n\nexport function blankUsage(): Usage {\n  return {\n    input: 0,\n    output: 0,\n    cacheRead: 0,\n    cacheWrite: 0,\n    totalTokens: 0,\n    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },\n  };\n}\n"],
+  "mappings": "AAEO,SAAS,aAAoB;AAClC,SAAO;AAAA,IACL,OAAO;AAAA,IACP,QAAQ;AAAA,IACR,WAAW;AAAA,IACX,YAAY;AAAA,IACZ,aAAa;AAAA,IACb,MAAM,EAAE,OAAO,GAAG,QAAQ,GAAG,WAAW,GAAG,YAAY,GAAG,OAAO,EAAE;AAAA,EACrE;AACF;",
+  "names": []
+}

package/dist/errors.js

@@ -0,0 +1,12 @@
+class VoiceRequestError extends Error {
+  reason;
+  constructor(reason, message) {
+    super(message);
+    this.name = "VoiceRequestError";
+    this.reason = reason;
+  }
+}
+export {
+  VoiceRequestError
+};
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../src/errors.ts"],
+  "sourcesContent": ["export class VoiceRequestError extends Error {\n  readonly reason: 'aborted' | 'error';\n\n  constructor(reason: 'aborted' | 'error', message: string) {\n    super(message);\n    this.name = 'VoiceRequestError';\n    this.reason = reason;\n  }\n}\n"],
+  "mappings": "AAAO,MAAM,0BAA0B,MAAM;AAAA,EAClC;AAAA,EAET,YAAY,QAA6B,SAAiB;AACxD,UAAM,OAAO;AACb,SAAK,OAAO;AACZ,SAAK,SAAS;AAAA,EAChB;AACF;",
+  "names": []
+}

package/dist/index.js

@@ -0,0 +1,37 @@
+import { resolveVoiceAuth } from "./auth.js";
+import { blankUsage } from "./blank-usage.js";
+import { VoiceRequestError } from "./errors.js";
+import {
+  getVoiceModel,
+  listVoiceModels,
+  registerVoiceModel
+} from "./models.js";
+import {
+  connectRealtime,
+  listen,
+  registerRealtimeApiProvider,
+  registerSpeechApiProvider,
+  registerTranscriptionApiProvider,
+  speak,
+  transcribe
+} from "./registry.js";
+import { SpeechEventStream } from "./speech.js";
+import { TranscriptionEventStream } from "./transcription.js";
+export {
+  SpeechEventStream,
+  TranscriptionEventStream,
+  VoiceRequestError,
+  blankUsage,
+  connectRealtime,
+  getVoiceModel,
+  listVoiceModels,
+  listen,
+  registerRealtimeApiProvider,
+  registerSpeechApiProvider,
+  registerTranscriptionApiProvider,
+  registerVoiceModel,
+  resolveVoiceAuth,
+  speak,
+  transcribe
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../src/index.ts"],
+  "sourcesContent": ["export type {\n  AudioChunk,\n  AudioEncoding,\n  AudioFormat,\n  AudioSink,\n  AudioSource,\n  AudioTag,\n  CharAlignment,\n  TextSpan,\n} from './audio.ts';\nexport { resolveVoiceAuth } from './auth.ts';\nexport { blankUsage } from './blank-usage.ts';\nexport { VoiceRequestError } from './errors.ts';\nexport type {\n  Delivery,\n  DeliverySupport,\n  KnownRealtimeApi,\n  KnownSpeechApi,\n  KnownTranscriptionApi,\n  RealtimeApi,\n  RealtimeModel,\n  SpeechApi,\n  SpeechModel,\n  TranscriptionApi,\n  TranscriptionModel,\n  VoiceInfo,\n  VoiceModel,\n  VoiceModelType,\n} from './models.ts';\nexport {\n  getVoiceModel,\n  listVoiceModels,\n  registerVoiceModel,\n} from './models.ts';\nexport type {\n  RealtimeApiProvider,\n  RealtimeContext,\n  RealtimeEvent,\n  RealtimeOptions,\n  RealtimeSession,\n  RealtimeToken,\n} from './realtime.ts';\nexport {\n  connectRealtime,\n  listen,\n  registerRealtimeApiProvider,\n  registerSpeechApiProvider,\n  registerTranscriptionApiProvider,\n  speak,\n  transcribe,\n} from './registry.ts';\nexport type { SpeechApiProvider, SpeechEvent, SpeechInput } from './speech.ts';\nexport { SpeechEventStream } from './speech.ts';\nexport type {\n  AudioInput,\n  ListenOptions,\n  Transcript,\n  TranscriptionApiProvider,\n  TranscriptionEvent,\n  TranscriptSegment,\n} from './transcription.ts';\nexport { TranscriptionEventStream } from './transcription.ts';\n"],
+  "mappings": "AAUA,SAAS,wBAAwB;AACjC,SAAS,kBAAkB;AAC3B,SAAS,yBAAyB;AAiBlC;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,OACK;AASP;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,OACK;AAEP,SAAS,yBAAyB;AASlC,SAAS,gCAAgC;",
+  "names": []
+}

package/dist/models.js

@@ -0,0 +1,29 @@
+const catalog = /* @__PURE__ */ new Map();
+function catalogKey(type, provider, id) {
+  return `${type}\0${provider}\0${id}`;
+}
+function registerVoiceModel(model) {
+  const key = catalogKey(model.type, model.provider, model.id);
+  catalog.set(key, model);
+  return () => {
+    if (catalog.get(key) === model) catalog.delete(key);
+  };
+}
+function getVoiceModel(type, provider, id) {
+  return catalog.get(catalogKey(type, provider, id));
+}
+function listVoiceModels(type, provider) {
+  const found = [];
+  for (const model of catalog.values()) {
+    if (model.type !== type) continue;
+    if (provider !== void 0 && model.provider !== provider) continue;
+    found.push(model);
+  }
+  return found;
+}
+export {
+  getVoiceModel,
+  listVoiceModels,
+  registerVoiceModel
+};
+//# sourceMappingURL=models.js.map

package/dist/models.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../src/models.ts"],
+  "sourcesContent": ["import type { BaseModel } from '@earendil-works/pi-ai';\nimport type { AudioFormat } from './audio.ts';\n\nexport type KnownTranscriptionApi =\n  | 'openai-transcriptions'\n  | 'openai-realtime-transcription'\n  | 'xai-stt'\n  | 'elevenlabs-scribe'\n  | 'mistral-transcriptions'\n  | 'fish-asr'\n  | 'cloudflare-ai-run';\n\nexport type TranscriptionApi = KnownTranscriptionApi | (string & {});\n\nexport type KnownSpeechApi =\n  | 'openai-speech'\n  | 'xai-tts'\n  | 'elevenlabs-tts'\n  | 'mistral-speech'\n  | 'fish-tts'\n  | 'google-tts'\n  | 'cloudflare-ai-run'\n  | 'wavespeed';\n\nexport type SpeechApi = KnownSpeechApi | (string & {});\n\nexport type KnownRealtimeApi =\n  | 'openai-realtime'\n  | 'xai-realtime'\n  | 'gemini-live'\n  | 'elevenlabs-agents'\n  | 'fish-agents';\n\nexport type RealtimeApi = KnownRealtimeApi | (string & {});\n\nexport type Delivery = 'interrupt' | 'when_idle' | 'silent';\n\nexport type DeliverySupport = 'native' | 'approximate' | 'unsupported';\n\nexport interface VoiceInfo {\n  id: string;\n  name: string;\n  languages?: string[];\n}\n\nexport interface TranscriptionModel<TApi extends TranscriptionApi>\n  extends Omit<BaseModel<TApi>, 'input'> {\n  type: 'transcription';\n  streaming: boolean;\n  turnDetection: 'none' | 'vad' | 'semantic';\n  inputFormats: AudioFormat[];\n  languages?: string[];\n  diarization?: boolean;\n}\n\nexport interface SpeechModel<TApi extends SpeechApi> extends Omit<BaseModel<TApi>, 'input'> {\n  type: 'speech';\n  textStreaming: boolean;\n  outputFormats: AudioFormat[];\n  voices?: VoiceInfo[];\n  cloning?: boolean;\n}\n\nexport interface RealtimeModel<TApi extends RealtimeApi> extends Omit<BaseModel<TApi>, 'input'> {\n  type: 'realtime';\n  transports: ('websocket' | 'webrtc')[];\n  toolCalls: 'blocking' | 'async';\n  inputFormat: AudioFormat;\n  outputFormat: AudioFormat;\n  video?: { maxFps: number };\n  maxSessionMs?: number;\n  resumable: boolean;\n  ephemeralAuth: boolean;\n  voices: VoiceInfo[];\n  cascade?: { stt: string; llm: string; tts: string };\n  provisioning: 'none' | 'agent';\n  delivery: Record<Delivery, DeliverySupport>;\n  truncation: 'client' | 'server' | 'none';\n  liveToolUpdate: boolean;\n  toolTimeoutMs?: { min: number; max: number };\n}\n\ndeclare module '@earendil-works/pi-ai' {\n  interface ModelTypeMap {\n    transcription: TranscriptionModel<TranscriptionApi>;\n    speech: SpeechModel<SpeechApi>;\n    realtime: RealtimeModel<RealtimeApi>;\n  }\n}\n\nexport type VoiceModel =\n  | TranscriptionModel<TranscriptionApi>\n  | SpeechModel<SpeechApi>\n  | RealtimeModel<RealtimeApi>;\n\nexport type VoiceModelType = VoiceModel['type'];\n\nconst catalog = new Map<string, VoiceModel>();\n\nfunction catalogKey(type: string, provider: string, id: string): string {\n  return `${type}\\0${provider}\\0${id}`;\n}\n\nexport function registerVoiceModel(model: VoiceModel): () => void {\n  const key = catalogKey(model.type, model.provider, model.id);\n  catalog.set(key, model);\n  return () => {\n    if (catalog.get(key) === model) catalog.delete(key);\n  };\n}\n\nexport function getVoiceModel<TType extends VoiceModelType>(\n  type: TType,\n  provider: string,\n  id: string\n): Extract<VoiceModel, { type: TType }> | undefined {\n  return catalog.get(catalogKey(type, provider, id)) as\n    | Extract<VoiceModel, { type: TType }>\n    | undefined;\n}\n\nexport function listVoiceModels<TType extends VoiceModelType>(\n  type: TType,\n  provider?: string\n): Extract<VoiceModel, { type: TType }>[] {\n  const found: Extract<VoiceModel, { type: TType }>[] = [];\n  for (const model of catalog.values()) {\n    if (model.type !== type) continue;\n    if (provider !== undefined && model.provider !== provider) continue;\n    found.push(model as Extract<VoiceModel, { type: TType }>);\n  }\n  return found;\n}\n"],
+  "mappings": "AAiGA,MAAM,UAAU,oBAAI,IAAwB;AAE5C,SAAS,WAAW,MAAc,UAAkB,IAAoB;AACtE,SAAO,GAAG,IAAI,KAAK,QAAQ,KAAK,EAAE;AACpC;AAEO,SAAS,mBAAmB,OAA+B;AAChE,QAAM,MAAM,WAAW,MAAM,MAAM,MAAM,UAAU,MAAM,EAAE;AAC3D,UAAQ,IAAI,KAAK,KAAK;AACtB,SAAO,MAAM;AACX,QAAI,QAAQ,IAAI,GAAG,MAAM,MAAO,SAAQ,OAAO,GAAG;AAAA,EACpD;AACF;AAEO,SAAS,cACd,MACA,UACA,IACkD;AAClD,SAAO,QAAQ,IAAI,WAAW,MAAM,UAAU,EAAE,CAAC;AAGnD;AAEO,SAAS,gBACd,MACA,UACwC;AACxC,QAAM,QAAgD,CAAC;AACvD,aAAW,SAAS,QAAQ,OAAO,GAAG;AACpC,QAAI,MAAM,SAAS,KAAM;AACzB,QAAI,aAAa,UAAa,MAAM,aAAa,SAAU;AAC3D,UAAM,KAAK,KAA6C;AAAA,EAC1D;AACA,SAAO;AACT;",
+  "names": []
+}

package/dist/realtime.js

@@ -0,0 +1 @@
+//# sourceMappingURL=realtime.js.map

package/dist/realtime.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": [],
+  "sourcesContent": [],
+  "mappings": "",
+  "names": []
+}

package/dist/registry.js

@@ -0,0 +1,57 @@
+const transcriptionApis = /* @__PURE__ */ new Map();
+const speechApis = /* @__PURE__ */ new Map();
+const realtimeApis = /* @__PURE__ */ new Map();
+function missing(api) {
+  return new Error(`No API provider registered for api: ${api}`);
+}
+function registerTranscriptionApiProvider(provider) {
+  const entry = { provider };
+  transcriptionApis.set(provider.api, entry);
+  return () => {
+    if (transcriptionApis.get(provider.api) === entry) transcriptionApis.delete(provider.api);
+  };
+}
+function registerSpeechApiProvider(provider) {
+  const entry = { provider };
+  speechApis.set(provider.api, entry);
+  return () => {
+    if (speechApis.get(provider.api) === entry) speechApis.delete(provider.api);
+  };
+}
+function registerRealtimeApiProvider(provider) {
+  const entry = { provider };
+  realtimeApis.set(provider.api, entry);
+  return () => {
+    if (realtimeApis.get(provider.api) === entry) realtimeApis.delete(provider.api);
+  };
+}
+function transcribe(model, input, options) {
+  const transcribeModel = transcriptionApis.get(model.api)?.provider.transcribe;
+  if (!transcribeModel) return Promise.reject(missing(model.api));
+  return transcribeModel(model, input, options);
+}
+function listen(model, audio, options) {
+  const listenModel = transcriptionApis.get(model.api)?.provider.listen;
+  if (!listenModel) throw missing(model.api);
+  return listenModel(model, audio, options);
+}
+function speak(model, input, options) {
+  const speakModel = speechApis.get(model.api)?.provider.speak;
+  if (!speakModel) throw missing(model.api);
+  return speakModel(model, input, options);
+}
+function connectRealtime(model, context, options) {
+  const connect = realtimeApis.get(model.api)?.provider.connect;
+  if (!connect) return Promise.reject(missing(model.api));
+  return connect(model, context, options);
+}
+export {
+  connectRealtime,
+  listen,
+  registerRealtimeApiProvider,
+  registerSpeechApiProvider,
+  registerTranscriptionApiProvider,
+  speak,
+  transcribe
+};
+//# sourceMappingURL=registry.js.map

package/dist/registry.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../src/registry.ts"],
+  "sourcesContent": ["import type { ProviderRequestOptions } from '@earendil-works/pi-ai';\nimport type { AudioSource } from './audio.ts';\nimport type { RealtimeModel, SpeechModel, TranscriptionModel } from './models.ts';\nimport type {\n  RealtimeApiProvider,\n  RealtimeContext,\n  RealtimeOptions,\n  RealtimeSession,\n} from './realtime.ts';\nimport type { SpeechApiProvider, SpeechEventStream, SpeechInput } from './speech.ts';\nimport type {\n  AudioInput,\n  ListenOptions,\n  Transcript,\n  TranscriptionApiProvider,\n  TranscriptionEventStream,\n} from './transcription.ts';\n\ninterface TranscriptionEntry {\n  provider: TranscriptionApiProvider;\n}\n\ninterface SpeechEntry {\n  provider: SpeechApiProvider;\n}\n\ninterface RealtimeEntry {\n  provider: RealtimeApiProvider;\n}\n\nconst transcriptionApis = new Map<string, TranscriptionEntry>();\nconst speechApis = new Map<string, SpeechEntry>();\nconst realtimeApis = new Map<string, RealtimeEntry>();\n\nfunction missing(api: string): Error {\n  return new Error(`No API provider registered for api: ${api}`);\n}\n\nexport function registerTranscriptionApiProvider(provider: TranscriptionApiProvider): () => void {\n  const entry = { provider };\n  transcriptionApis.set(provider.api, entry);\n  return () => {\n    if (transcriptionApis.get(provider.api) === entry) transcriptionApis.delete(provider.api);\n  };\n}\n\nexport function registerSpeechApiProvider(provider: SpeechApiProvider): () => void {\n  const entry = { provider };\n  speechApis.set(provider.api, entry);\n  return () => {\n    if (speechApis.get(provider.api) === entry) speechApis.delete(provider.api);\n  };\n}\n\nexport function registerRealtimeApiProvider(provider: RealtimeApiProvider): () => void {\n  const entry = { provider };\n  realtimeApis.set(provider.api, entry);\n  return () => {\n    if (realtimeApis.get(provider.api) === entry) realtimeApis.delete(provider.api);\n  };\n}\n\nexport function transcribe(\n  model: TranscriptionModel<string>,\n  input: AudioInput,\n  options?: ProviderRequestOptions\n): Promise<Transcript> {\n  const transcribeModel = transcriptionApis.get(model.api)?.provider.transcribe;\n  if (!transcribeModel) return Promise.reject(missing(model.api));\n  return transcribeModel(model, input, options);\n}\n\nexport function listen(\n  model: TranscriptionModel<string>,\n  audio: AudioSource,\n  options?: ListenOptions\n): TranscriptionEventStream {\n  const listenModel = transcriptionApis.get(model.api)?.provider.listen;\n  if (!listenModel) throw missing(model.api);\n  return listenModel(model, audio, options);\n}\n\nexport function speak(\n  model: SpeechModel<string>,\n  input: SpeechInput,\n  options?: ProviderRequestOptions\n): SpeechEventStream {\n  const speakModel = speechApis.get(model.api)?.provider.speak;\n  if (!speakModel) throw missing(model.api);\n  return speakModel(model, input, options);\n}\n\nexport function connectRealtime(\n  model: RealtimeModel<string>,\n  context: RealtimeContext,\n  options?: RealtimeOptions\n): Promise<RealtimeSession> {\n  const connect = realtimeApis.get(model.api)?.provider.connect;\n  if (!connect) return Promise.reject(missing(model.api));\n  return connect(model, context, options);\n}\n"],
+  "mappings": "AA8BA,MAAM,oBAAoB,oBAAI,IAAgC;AAC9D,MAAM,aAAa,oBAAI,IAAyB;AAChD,MAAM,eAAe,oBAAI,IAA2B;AAEpD,SAAS,QAAQ,KAAoB;AACnC,SAAO,IAAI,MAAM,uCAAuC,GAAG,EAAE;AAC/D;AAEO,SAAS,iCAAiC,UAAgD;AAC/F,QAAM,QAAQ,EAAE,SAAS;AACzB,oBAAkB,IAAI,SAAS,KAAK,KAAK;AACzC,SAAO,MAAM;AACX,QAAI,kBAAkB,IAAI,SAAS,GAAG,MAAM,MAAO,mBAAkB,OAAO,SAAS,GAAG;AAAA,EAC1F;AACF;AAEO,SAAS,0BAA0B,UAAyC;AACjF,QAAM,QAAQ,EAAE,SAAS;AACzB,aAAW,IAAI,SAAS,KAAK,KAAK;AAClC,SAAO,MAAM;AACX,QAAI,WAAW,IAAI,SAAS,GAAG,MAAM,MAAO,YAAW,OAAO,SAAS,GAAG;AAAA,EAC5E;AACF;AAEO,SAAS,4BAA4B,UAA2C;AACrF,QAAM,QAAQ,EAAE,SAAS;AACzB,eAAa,IAAI,SAAS,KAAK,KAAK;AACpC,SAAO,MAAM;AACX,QAAI,aAAa,IAAI,SAAS,GAAG,MAAM,MAAO,cAAa,OAAO,SAAS,GAAG;AAAA,EAChF;AACF;AAEO,SAAS,WACd,OACA,OACA,SACqB;AACrB,QAAM,kBAAkB,kBAAkB,IAAI,MAAM,GAAG,GAAG,SAAS;AACnE,MAAI,CAAC,gBAAiB,QAAO,QAAQ,OAAO,QAAQ,MAAM,GAAG,CAAC;AAC9D,SAAO,gBAAgB,OAAO,OAAO,OAAO;AAC9C;AAEO,SAAS,OACd,OACA,OACA,SAC0B;AAC1B,QAAM,cAAc,kBAAkB,IAAI,MAAM,GAAG,GAAG,SAAS;AAC/D,MAAI,CAAC,YAAa,OAAM,QAAQ,MAAM,GAAG;AACzC,SAAO,YAAY,OAAO,OAAO,OAAO;AAC1C;AAEO,SAAS,MACd,OACA,OACA,SACmB;AACnB,QAAM,aAAa,WAAW,IAAI,MAAM,GAAG,GAAG,SAAS;AACvD,MAAI,CAAC,WAAY,OAAM,QAAQ,MAAM,GAAG;AACxC,SAAO,WAAW,OAAO,OAAO,OAAO;AACzC;AAEO,SAAS,gBACd,OACA,SACA,SAC0B;AAC1B,QAAM,UAAU,aAAa,IAAI,MAAM,GAAG,GAAG,SAAS;AACtD,MAAI,CAAC,QAAS,QAAO,QAAQ,OAAO,QAAQ,MAAM,GAAG,CAAC;AACtD,SAAO,QAAQ,OAAO,SAAS,OAAO;AACxC;",
+  "names": []
+}

package/dist/speech.js

@@ -0,0 +1,31 @@
+import { EventStream } from "@earendil-works/pi-ai";
+import { blankUsage } from "./blank-usage.js";
+import { VoiceRequestError } from "./errors.js";
+import { streamResult } from "./stream-result.js";
+class SpeechEventStream extends EventStream {
+  #settled = streamResult();
+  constructor() {
+    super(
+      (event) => event.type === "done" || event.type === "error",
+      (event) => event.type === "done" ? event.usage : blankUsage()
+    );
+  }
+  push(event) {
+    super.push(event);
+    if (event.type === "done") this.#settled.finish(event.usage);
+    else if (event.type === "error")
+      this.#settled.fail(new VoiceRequestError(event.reason, event.error));
+  }
+  end(result) {
+    super.end(result);
+    if (result !== void 0) this.#settled.finish(result);
+    else this.#settled.fail(new VoiceRequestError("error", "Speech ended without usage"));
+  }
+  result() {
+    return this.#settled.result;
+  }
+}
+export {
+  SpeechEventStream
+};
+//# sourceMappingURL=speech.js.map

package/dist/speech.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../src/speech.ts"],
+  "sourcesContent": ["import type { ProviderRequestOptions, Usage } from '@earendil-works/pi-ai';\nimport { EventStream } from '@earendil-works/pi-ai';\nimport type { AudioChunk, AudioFormat, CharAlignment, TextSpan } from './audio.ts';\nimport { blankUsage } from './blank-usage.ts';\nimport { VoiceRequestError } from './errors.ts';\nimport type { SpeechModel } from './models.ts';\nimport { streamResult } from './stream-result.ts';\n\nexport interface SpeechInput {\n  text: string | AsyncIterable<string>;\n  voice: string;\n  language?: string;\n  instructions?: string;\n  format?: AudioFormat;\n}\n\nexport type SpeechEvent =\n  | { type: 'start'; format: AudioFormat }\n  | { type: 'audio'; chunk: AudioChunk; span: TextSpan; alignment?: CharAlignment }\n  | { type: 'done'; usage: Usage }\n  | { type: 'error'; reason: 'aborted' | 'error'; error: string };\n\nexport class SpeechEventStream extends EventStream<SpeechEvent, Usage> {\n  readonly #settled = streamResult<Usage>();\n\n  constructor() {\n    super(\n      (event) => event.type === 'done' || event.type === 'error',\n      (event) => (event.type === 'done' ? event.usage : blankUsage())\n    );\n  }\n\n  override push(event: SpeechEvent): void {\n    super.push(event);\n    if (event.type === 'done') this.#settled.finish(event.usage);\n    else if (event.type === 'error')\n      this.#settled.fail(new VoiceRequestError(event.reason, event.error));\n  }\n\n  override end(result?: Usage): void {\n    super.end(result);\n    if (result !== undefined) this.#settled.finish(result);\n    else this.#settled.fail(new VoiceRequestError('error', 'Speech ended without usage'));\n  }\n\n  override result(): Promise<Usage> {\n    return this.#settled.result;\n  }\n}\n\nexport interface SpeechApiProvider<TApi extends string = string> {\n  api: TApi;\n  speak: (\n    model: SpeechModel<TApi>,\n    input: SpeechInput,\n    options?: ProviderRequestOptions\n  ) => SpeechEventStream;\n}\n"],
+  "mappings": "AACA,SAAS,mBAAmB;AAE5B,SAAS,kBAAkB;AAC3B,SAAS,yBAAyB;AAElC,SAAS,oBAAoB;AAgBtB,MAAM,0BAA0B,YAAgC;AAAA,EAC5D,WAAW,aAAoB;AAAA,EAExC,cAAc;AACZ;AAAA,MACE,CAAC,UAAU,MAAM,SAAS,UAAU,MAAM,SAAS;AAAA,MACnD,CAAC,UAAW,MAAM,SAAS,SAAS,MAAM,QAAQ,WAAW;AAAA,IAC/D;AAAA,EACF;AAAA,EAES,KAAK,OAA0B;AACtC,UAAM,KAAK,KAAK;AAChB,QAAI,MAAM,SAAS,OAAQ,MAAK,SAAS,OAAO,MAAM,KAAK;AAAA,aAClD,MAAM,SAAS;AACtB,WAAK,SAAS,KAAK,IAAI,kBAAkB,MAAM,QAAQ,MAAM,KAAK,CAAC;AAAA,EACvE;AAAA,EAES,IAAI,QAAsB;AACjC,UAAM,IAAI,MAAM;AAChB,QAAI,WAAW,OAAW,MAAK,SAAS,OAAO,MAAM;AAAA,QAChD,MAAK,SAAS,KAAK,IAAI,kBAAkB,SAAS,4BAA4B,CAAC;AAAA,EACtF;AAAA,EAES,SAAyB;AAChC,WAAO,KAAK,SAAS;AAAA,EACvB;AACF;",
+  "names": []
+}

package/dist/stream-result.js

@@ -0,0 +1,28 @@
+function streamResult() {
+  let settled = false;
+  let resolve;
+  let reject;
+  const result = new Promise((res, rej) => {
+    resolve = res;
+    reject = rej;
+  });
+  void result.catch(() => {
+  });
+  return {
+    result,
+    finish(value) {
+      if (settled) return;
+      settled = true;
+      resolve(value);
+    },
+    fail(error) {
+      if (settled) return;
+      settled = true;
+      reject(error);
+    }
+  };
+}
+export {
+  streamResult
+};
+//# sourceMappingURL=stream-result.js.map

package/dist/stream-result.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../src/stream-result.ts"],
+  "sourcesContent": ["export interface StreamResult<T> {\n  readonly result: Promise<T>;\n  finish(value: T): void;\n  fail(error: Error): void;\n}\n\nexport function streamResult<T>(): StreamResult<T> {\n  let settled = false;\n  let resolve!: (value: T) => void;\n  let reject!: (error: Error) => void;\n  const result = new Promise<T>((res, rej) => {\n    resolve = res;\n    reject = rej;\n  });\n  void result.catch(() => {});\n  return {\n    result,\n    finish(value) {\n      if (settled) return;\n      settled = true;\n      resolve(value);\n    },\n    fail(error) {\n      if (settled) return;\n      settled = true;\n      reject(error);\n    },\n  };\n}\n"],
+  "mappings": "AAMO,SAAS,eAAmC;AACjD,MAAI,UAAU;AACd,MAAI;AACJ,MAAI;AACJ,QAAM,SAAS,IAAI,QAAW,CAAC,KAAK,QAAQ;AAC1C,cAAU;AACV,aAAS;AAAA,EACX,CAAC;AACD,OAAK,OAAO,MAAM,MAAM;AAAA,EAAC,CAAC;AAC1B,SAAO;AAAA,IACL;AAAA,IACA,OAAO,OAAO;AACZ,UAAI,QAAS;AACb,gBAAU;AACV,cAAQ,KAAK;AAAA,IACf;AAAA,IACA,KAAK,OAAO;AACV,UAAI,QAAS;AACb,gBAAU;AACV,aAAO,KAAK;AAAA,IACd;AAAA,EACF;AACF;",
+  "names": []
+}

package/dist/transcription.js

@@ -0,0 +1,37 @@
+import { EventStream } from "@earendil-works/pi-ai";
+import { blankUsage } from "./blank-usage.js";
+import { VoiceRequestError } from "./errors.js";
+import { streamResult } from "./stream-result.js";
+function blankTranscript() {
+  return { text: "", usage: blankUsage() };
+}
+class TranscriptionEventStream extends EventStream {
+  #settled = streamResult();
+  constructor() {
+    super(
+      (event) => event.type === "done" || event.type === "error",
+      (event) => event.type === "done" ? event.transcript : blankTranscript()
+    );
+  }
+  push(event) {
+    super.push(event);
+    if (event.type === "done") this.#settled.finish(event.transcript);
+    else if (event.type === "error")
+      this.#settled.fail(new VoiceRequestError(event.reason, event.error));
+  }
+  end(result) {
+    super.end(result);
+    if (result !== void 0) this.#settled.finish(result);
+    else
+      this.#settled.fail(
+        new VoiceRequestError("error", "Transcription ended without a transcript")
+      );
+  }
+  result() {
+    return this.#settled.result;
+  }
+}
+export {
+  TranscriptionEventStream
+};
+//# sourceMappingURL=transcription.js.map

package/dist/transcription.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../src/transcription.ts"],
+  "sourcesContent": ["import type { ProviderRequestOptions, Usage } from '@earendil-works/pi-ai';\nimport { EventStream } from '@earendil-works/pi-ai';\nimport type { AudioSource } from './audio.ts';\nimport { blankUsage } from './blank-usage.ts';\nimport { VoiceRequestError } from './errors.ts';\nimport type { TranscriptionModel } from './models.ts';\nimport { streamResult } from './stream-result.ts';\n\nexport type AudioInput = { data: Uint8Array; mimeType: string } | { url: string };\n\nexport interface TranscriptSegment {\n  text: string;\n  start: number;\n  end: number;\n  speaker?: string;\n}\n\nexport interface Transcript {\n  text: string;\n  language?: string;\n  segments?: TranscriptSegment[];\n  usage: Usage;\n}\n\nexport type TranscriptionEvent =\n  | { type: 'speech_start'; at: number }\n  | { type: 'partial'; segmentId: string; text: string }\n  | { type: 'final'; segmentId: string; text: string; confidence?: number }\n  | { type: 'turn_end'; text: string; at: number }\n  | { type: 'done'; transcript: Transcript }\n  | { type: 'error'; reason: 'aborted' | 'error'; error: string };\n\nexport interface ListenOptions extends ProviderRequestOptions {\n  language?: string;\n  vocabulary?: string[];\n}\n\nfunction blankTranscript(): Transcript {\n  return { text: '', usage: blankUsage() };\n}\n\nexport class TranscriptionEventStream extends EventStream<TranscriptionEvent, Transcript> {\n  readonly #settled = streamResult<Transcript>();\n\n  constructor() {\n    super(\n      (event) => event.type === 'done' || event.type === 'error',\n      (event) => (event.type === 'done' ? event.transcript : blankTranscript())\n    );\n  }\n\n  override push(event: TranscriptionEvent): void {\n    super.push(event);\n    if (event.type === 'done') this.#settled.finish(event.transcript);\n    else if (event.type === 'error')\n      this.#settled.fail(new VoiceRequestError(event.reason, event.error));\n  }\n\n  override end(result?: Transcript): void {\n    super.end(result);\n    if (result !== undefined) this.#settled.finish(result);\n    else\n      this.#settled.fail(\n        new VoiceRequestError('error', 'Transcription ended without a transcript')\n      );\n  }\n\n  override result(): Promise<Transcript> {\n    return this.#settled.result;\n  }\n}\n\nexport interface TranscriptionApiProvider<TApi extends string = string> {\n  api: TApi;\n  transcribe?: (\n    model: TranscriptionModel<TApi>,\n    input: AudioInput,\n    options?: ProviderRequestOptions\n  ) => Promise<Transcript>;\n  listen?: (\n    model: TranscriptionModel<TApi>,\n    audio: AudioSource,\n    options?: ListenOptions\n  ) => TranscriptionEventStream;\n}\n"],
+  "mappings": "AACA,SAAS,mBAAmB;AAE5B,SAAS,kBAAkB;AAC3B,SAAS,yBAAyB;AAElC,SAAS,oBAAoB;AA+B7B,SAAS,kBAA8B;AACrC,SAAO,EAAE,MAAM,IAAI,OAAO,WAAW,EAAE;AACzC;AAEO,MAAM,iCAAiC,YAA4C;AAAA,EAC/E,WAAW,aAAyB;AAAA,EAE7C,cAAc;AACZ;AAAA,MACE,CAAC,UAAU,MAAM,SAAS,UAAU,MAAM,SAAS;AAAA,MACnD,CAAC,UAAW,MAAM,SAAS,SAAS,MAAM,aAAa,gBAAgB;AAAA,IACzE;AAAA,EACF;AAAA,EAES,KAAK,OAAiC;AAC7C,UAAM,KAAK,KAAK;AAChB,QAAI,MAAM,SAAS,OAAQ,MAAK,SAAS,OAAO,MAAM,UAAU;AAAA,aACvD,MAAM,SAAS;AACtB,WAAK,SAAS,KAAK,IAAI,kBAAkB,MAAM,QAAQ,MAAM,KAAK,CAAC;AAAA,EACvE;AAAA,EAES,IAAI,QAA2B;AACtC,UAAM,IAAI,MAAM;AAChB,QAAI,WAAW,OAAW,MAAK,SAAS,OAAO,MAAM;AAAA;AAEnD,WAAK,SAAS;AAAA,QACZ,IAAI,kBAAkB,SAAS,0CAA0C;AAAA,MAC3E;AAAA,EACJ;AAAA,EAES,SAA8B;AACrC,WAAO,KAAK,SAAS;AAAA,EACvB;AACF;",
+  "names": []
+}

package/dist/types/audio.d.ts

@@ -0,0 +1,36 @@
+export type AudioEncoding = 'pcm16' | 'pcmf32' | 'mulaw' | 'alaw' | 'opus' | 'mp3' | 'wav' | 'flac';
+export interface AudioFormat {
+    encoding: AudioEncoding;
+    sampleRate: number;
+    channels: 1 | 2;
+}
+export interface AudioChunk {
+    data: Uint8Array;
+    format: AudioFormat;
+    timestamp: number;
+}
+export type AudioSource = AsyncIterable<AudioChunk>;
+export type TextSpan = {
+    entryId: string;
+    contentIndex: number;
+    start: number;
+    end: number;
+} | {
+    itemId: string;
+    start: number;
+    end: number;
+};
+export interface CharAlignment {
+    startMs: number[];
+    durationMs: number[];
+}
+export interface AudioTag {
+    span: TextSpan;
+    alignment?: CharAlignment;
+}
+export interface AudioSink {
+    write(chunk: AudioChunk, tag?: AudioTag): void;
+    flush(): void;
+    readonly playedMs: number;
+    onPlayback(listener: (tag: AudioTag, offsetMs: number) => void): () => void;
+}

package/dist/types/auth.d.ts

@@ -0,0 +1,3 @@
+import type { AuthResult, Models } from '@earendil-works/pi-ai';
+import type { VoiceModel } from './models.ts';
+export declare function resolveVoiceAuth(models: Models, model: VoiceModel, overrides?: Parameters<Models['getAuth']>[1]): Promise<AuthResult | undefined>;

package/dist/types/blank-usage.d.ts

@@ -0,0 +1,2 @@
+import type { Usage } from '@earendil-works/pi-ai';
+export declare function blankUsage(): Usage;

package/dist/types/errors.d.ts

@@ -0,0 +1,4 @@
+export declare class VoiceRequestError extends Error {
+    readonly reason: 'aborted' | 'error';
+    constructor(reason: 'aborted' | 'error', message: string);
+}

package/dist/types/index.d.ts

@@ -0,0 +1,12 @@
+export type { AudioChunk, AudioEncoding, AudioFormat, AudioSink, AudioSource, AudioTag, CharAlignment, TextSpan, } from './audio.ts';
+export { resolveVoiceAuth } from './auth.ts';
+export { blankUsage } from './blank-usage.ts';
+export { VoiceRequestError } from './errors.ts';
+export type { Delivery, DeliverySupport, KnownRealtimeApi, KnownSpeechApi, KnownTranscriptionApi, RealtimeApi, RealtimeModel, SpeechApi, SpeechModel, TranscriptionApi, TranscriptionModel, VoiceInfo, VoiceModel, VoiceModelType, } from './models.ts';
+export { getVoiceModel, listVoiceModels, registerVoiceModel, } from './models.ts';
+export type { RealtimeApiProvider, RealtimeContext, RealtimeEvent, RealtimeOptions, RealtimeSession, RealtimeToken, } from './realtime.ts';
+export { connectRealtime, listen, registerRealtimeApiProvider, registerSpeechApiProvider, registerTranscriptionApiProvider, speak, transcribe, } from './registry.ts';
+export type { SpeechApiProvider, SpeechEvent, SpeechInput } from './speech.ts';
+export { SpeechEventStream } from './speech.ts';
+export type { AudioInput, ListenOptions, Transcript, TranscriptionApiProvider, TranscriptionEvent, TranscriptSegment, } from './transcription.ts';
+export { TranscriptionEventStream } from './transcription.ts';

package/dist/types/models.d.ts

@@ -0,0 +1,73 @@
+import type { BaseModel } from '@earendil-works/pi-ai';
+import type { AudioFormat } from './audio.ts';
+export type KnownTranscriptionApi = 'openai-transcriptions' | 'openai-realtime-transcription' | 'xai-stt' | 'elevenlabs-scribe' | 'mistral-transcriptions' | 'fish-asr' | 'cloudflare-ai-run';
+export type TranscriptionApi = KnownTranscriptionApi | (string & {});
+export type KnownSpeechApi = 'openai-speech' | 'xai-tts' | 'elevenlabs-tts' | 'mistral-speech' | 'fish-tts' | 'google-tts' | 'cloudflare-ai-run' | 'wavespeed';
+export type SpeechApi = KnownSpeechApi | (string & {});
+export type KnownRealtimeApi = 'openai-realtime' | 'xai-realtime' | 'gemini-live' | 'elevenlabs-agents' | 'fish-agents';
+export type RealtimeApi = KnownRealtimeApi | (string & {});
+export type Delivery = 'interrupt' | 'when_idle' | 'silent';
+export type DeliverySupport = 'native' | 'approximate' | 'unsupported';
+export interface VoiceInfo {
+    id: string;
+    name: string;
+    languages?: string[];
+}
+export interface TranscriptionModel<TApi extends TranscriptionApi> extends Omit<BaseModel<TApi>, 'input'> {
+    type: 'transcription';
+    streaming: boolean;
+    turnDetection: 'none' | 'vad' | 'semantic';
+    inputFormats: AudioFormat[];
+    languages?: string[];
+    diarization?: boolean;
+}
+export interface SpeechModel<TApi extends SpeechApi> extends Omit<BaseModel<TApi>, 'input'> {
+    type: 'speech';
+    textStreaming: boolean;
+    outputFormats: AudioFormat[];
+    voices?: VoiceInfo[];
+    cloning?: boolean;
+}
+export interface RealtimeModel<TApi extends RealtimeApi> extends Omit<BaseModel<TApi>, 'input'> {
+    type: 'realtime';
+    transports: ('websocket' | 'webrtc')[];
+    toolCalls: 'blocking' | 'async';
+    inputFormat: AudioFormat;
+    outputFormat: AudioFormat;
+    video?: {
+        maxFps: number;
+    };
+    maxSessionMs?: number;
+    resumable: boolean;
+    ephemeralAuth: boolean;
+    voices: VoiceInfo[];
+    cascade?: {
+        stt: string;
+        llm: string;
+        tts: string;
+    };
+    provisioning: 'none' | 'agent';
+    delivery: Record<Delivery, DeliverySupport>;
+    truncation: 'client' | 'server' | 'none';
+    liveToolUpdate: boolean;
+    toolTimeoutMs?: {
+        min: number;
+        max: number;
+    };
+}
+declare module '@earendil-works/pi-ai' {
+    interface ModelTypeMap {
+        transcription: TranscriptionModel<TranscriptionApi>;
+        speech: SpeechModel<SpeechApi>;
+        realtime: RealtimeModel<RealtimeApi>;
+    }
+}
+export type VoiceModel = TranscriptionModel<TranscriptionApi> | SpeechModel<SpeechApi> | RealtimeModel<RealtimeApi>;
+export type VoiceModelType = VoiceModel['type'];
+export declare function registerVoiceModel(model: VoiceModel): () => void;
+export declare function getVoiceModel<TType extends VoiceModelType>(type: TType, provider: string, id: string): Extract<VoiceModel, {
+    type: TType;
+}> | undefined;
+export declare function listVoiceModels<TType extends VoiceModelType>(type: TType, provider?: string): Extract<VoiceModel, {
+    type: TType;
+}>[];

package/dist/types/realtime.d.ts

@@ -0,0 +1,87 @@
+import type { Message, ProviderRequestOptions, Tool, ToolCall, ToolResultMessage, Usage } from '@earendil-works/pi-ai';
+import type { AudioChunk, CharAlignment, TextSpan } from './audio.ts';
+import type { Delivery, RealtimeModel } from './models.ts';
+export interface RealtimeContext {
+    instructions: string;
+    tools: Tool[];
+    voice: string;
+    history?: Message[];
+}
+export interface RealtimeToken {
+    value: string;
+    expiresAt: number;
+    model: string;
+}
+export interface RealtimeOptions extends ProviderRequestOptions {
+    token?: RealtimeToken;
+    transport?: 'websocket' | 'webrtc';
+    gateway?: {
+        url: string;
+        token: string;
+    };
+    resumeHandle?: string;
+}
+export type RealtimeEvent = {
+    type: 'session_start';
+    sessionId: string;
+} | {
+    type: 'input_speech_start';
+} | {
+    type: 'input_transcript';
+    itemId: string;
+    text: string;
+    final: boolean;
+} | {
+    type: 'output_audio';
+    itemId: string;
+    chunk: AudioChunk;
+    span?: TextSpan;
+    alignment?: CharAlignment;
+} | {
+    type: 'output_transcript';
+    itemId: string;
+    text: string;
+    final: boolean;
+} | {
+    type: 'tool_call';
+    call: ToolCall;
+    blocking: boolean;
+} | {
+    type: 'tool_call_cancelled';
+    callId: string;
+} | {
+    type: 'response_done';
+    itemId: string;
+    interrupted: boolean;
+    usage: Usage;
+} | {
+    type: 'go_away';
+    timeLeftMs: number;
+} | {
+    type: 'resumption';
+    handle: string;
+} | {
+    type: 'error';
+    error: string;
+    fatal: boolean;
+};
+export interface RealtimeSession extends AsyncIterable<RealtimeEvent> {
+    readonly model: RealtimeModel<string>;
+    appendAudio(chunk: AudioChunk): void;
+    appendVideoFrame?(jpeg: Uint8Array): void;
+    sendText(text: string): void;
+    inject(text: string, delivery: Delivery): void;
+    respond(callId: string, result: ToolResultMessage, delivery?: Delivery): void;
+    interrupt(heard?: {
+        itemId: string;
+        heardMs: number;
+    }): void;
+    update(patch: Partial<Pick<RealtimeContext, 'instructions' | 'tools' | 'voice'>>): void;
+    close(): Promise<{
+        usage: Usage;
+    }>;
+}
+export interface RealtimeApiProvider<TApi extends string = string> {
+    api: TApi;
+    connect: (model: RealtimeModel<TApi>, context: RealtimeContext, options?: RealtimeOptions) => Promise<RealtimeSession>;
+}

package/dist/types/registry.d.ts

@@ -0,0 +1,13 @@
+import type { ProviderRequestOptions } from '@earendil-works/pi-ai';
+import type { AudioSource } from './audio.ts';
+import type { RealtimeModel, SpeechModel, TranscriptionModel } from './models.ts';
+import type { RealtimeApiProvider, RealtimeContext, RealtimeOptions, RealtimeSession } from './realtime.ts';
+import type { SpeechApiProvider, SpeechEventStream, SpeechInput } from './speech.ts';
+import type { AudioInput, ListenOptions, Transcript, TranscriptionApiProvider, TranscriptionEventStream } from './transcription.ts';
+export declare function registerTranscriptionApiProvider(provider: TranscriptionApiProvider): () => void;
+export declare function registerSpeechApiProvider(provider: SpeechApiProvider): () => void;
+export declare function registerRealtimeApiProvider(provider: RealtimeApiProvider): () => void;
+export declare function transcribe(model: TranscriptionModel<string>, input: AudioInput, options?: ProviderRequestOptions): Promise<Transcript>;
+export declare function listen(model: TranscriptionModel<string>, audio: AudioSource, options?: ListenOptions): TranscriptionEventStream;
+export declare function speak(model: SpeechModel<string>, input: SpeechInput, options?: ProviderRequestOptions): SpeechEventStream;
+export declare function connectRealtime(model: RealtimeModel<string>, context: RealtimeContext, options?: RealtimeOptions): Promise<RealtimeSession>;

package/dist/types/speech.d.ts

@@ -0,0 +1,38 @@
+import type { ProviderRequestOptions, Usage } from '@earendil-works/pi-ai';
+import { EventStream } from '@earendil-works/pi-ai';
+import type { AudioChunk, AudioFormat, CharAlignment, TextSpan } from './audio.ts';
+import type { SpeechModel } from './models.ts';
+export interface SpeechInput {
+    text: string | AsyncIterable<string>;
+    voice: string;
+    language?: string;
+    instructions?: string;
+    format?: AudioFormat;
+}
+export type SpeechEvent = {
+    type: 'start';
+    format: AudioFormat;
+} | {
+    type: 'audio';
+    chunk: AudioChunk;
+    span: TextSpan;
+    alignment?: CharAlignment;
+} | {
+    type: 'done';
+    usage: Usage;
+} | {
+    type: 'error';
+    reason: 'aborted' | 'error';
+    error: string;
+};
+export declare class SpeechEventStream extends EventStream<SpeechEvent, Usage> {
+    #private;
+    constructor();
+    push(event: SpeechEvent): void;
+    end(result?: Usage): void;
+    result(): Promise<Usage>;
+}
+export interface SpeechApiProvider<TApi extends string = string> {
+    api: TApi;
+    speak: (model: SpeechModel<TApi>, input: SpeechInput, options?: ProviderRequestOptions) => SpeechEventStream;
+}

package/dist/types/stream-result.d.ts

@@ -0,0 +1,6 @@
+export interface StreamResult<T> {
+    readonly result: Promise<T>;
+    finish(value: T): void;
+    fail(error: Error): void;
+}
+export declare function streamResult<T>(): StreamResult<T>;

package/dist/types/transcription.d.ts

@@ -0,0 +1,62 @@
+import type { ProviderRequestOptions, Usage } from '@earendil-works/pi-ai';
+import { EventStream } from '@earendil-works/pi-ai';
+import type { AudioSource } from './audio.ts';
+import type { TranscriptionModel } from './models.ts';
+export type AudioInput = {
+    data: Uint8Array;
+    mimeType: string;
+} | {
+    url: string;
+};
+export interface TranscriptSegment {
+    text: string;
+    start: number;
+    end: number;
+    speaker?: string;
+}
+export interface Transcript {
+    text: string;
+    language?: string;
+    segments?: TranscriptSegment[];
+    usage: Usage;
+}
+export type TranscriptionEvent = {
+    type: 'speech_start';
+    at: number;
+} | {
+    type: 'partial';
+    segmentId: string;
+    text: string;
+} | {
+    type: 'final';
+    segmentId: string;
+    text: string;
+    confidence?: number;
+} | {
+    type: 'turn_end';
+    text: string;
+    at: number;
+} | {
+    type: 'done';
+    transcript: Transcript;
+} | {
+    type: 'error';
+    reason: 'aborted' | 'error';
+    error: string;
+};
+export interface ListenOptions extends ProviderRequestOptions {
+    language?: string;
+    vocabulary?: string[];
+}
+export declare class TranscriptionEventStream extends EventStream<TranscriptionEvent, Transcript> {
+    #private;
+    constructor();
+    push(event: TranscriptionEvent): void;
+    end(result?: Transcript): void;
+    result(): Promise<Transcript>;
+}
+export interface TranscriptionApiProvider<TApi extends string = string> {
+    api: TApi;
+    transcribe?: (model: TranscriptionModel<TApi>, input: AudioInput, options?: ProviderRequestOptions) => Promise<Transcript>;
+    listen?: (model: TranscriptionModel<TApi>, audio: AudioSource, options?: ListenOptions) => TranscriptionEventStream;
+}

package/package.json

@@ -1,6 +1,61 @@
 {
   "name": "@ai-ecoverse/pi-audio",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.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",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ai-ecoverse/pi-audio.git"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "fledgling": {
+    "provider": "github",
+    "workflow": "release.yml",
+    "repo": "ai-ecoverse/pi-audio",
+    "publish": true
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/types/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "prepare": "lefthook install",
+    "build": "node build.mjs && tsc -p tsconfig.build.json",
+    "prepack": "npm run build",
+    "pretest": "npm run build",
+    "test": "node --test 'test/integration/*.test.mjs'",
+    "test:unit": "NODE_NO_WARNINGS=1 mcr -c node_modules/@ai-ecoverse/slicc-shared-web/mcr.config.mjs node --test 'test/unit/**/*.test.mjs'",
+    "typecheck": "tsc",
+    "lint": "slicc-lint",
+    "format": "biome check --write .",
+    "trust": "npx fledgling sync -y --skip-publish",
+    "trust:dry": "npx fledgling sync --dry-run -y --skip-publish",
+    "release": "semantic-release"
+  },
+  "devDependencies": {
+    "@ai-ecoverse/slicc-shared-web": "1.21.0",
+    "@biomejs/biome": "2.5.15",
+    "@earendil-works/pi-ai": "1.0.4",
+    "@types/node": "24.19.1",
+    "esbuild": "0.28.2",
+    "lefthook": "2.2.1",
+    "monocart-coverage-reports": "2.13.2",
+    "semantic-release": "25.0.9",
+    "typescript": "7.0.2"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-ai": "1.0.4"
+  }
+}