@absolutejs/voice 0.0.22-beta.306 → 0.0.22-beta.307

package/README.md

@@ -3471,15 +3471,16 @@ app.use(
 
 Client state now exposes `assistantAudio` on the stream/controller helpers, so apps can buffer or play synthesized chunks without inventing a second transport.
 
-## OpenAI Realtime
+## Realtime Adapter Packages
 
-Use `createOpenAIRealtimeAdapter(...)` when you want a direct OpenAI Realtime speech-to-speech output path for live smoke tests, duplex benchmarks, or custom realtime orchestration. It implements the same `RealtimeAdapter` contract used by the benchmark harness, so the provider can stream `response.output_audio.delta` audio chunks into AbsoluteJS voice events while still emitting normalized transcript, error, and close events.
+Use realtime adapter packages when you want direct speech-to-speech output paths for live smoke tests, duplex benchmarks, or custom realtime orchestration. Core owns the `RealtimeAdapter` contract and `voice({ realtime })` orchestration path; provider protocol code lives in adapter packages such as `@absolutejs/voice-openai` and `@absolutejs/voice-gemini`.
 
 ```ts
-import { createOpenAIRealtimeAdapter } from '@absolutejs/voice';
+import { voice } from '@absolutejs/voice';
+import { openai } from '@absolutejs/voice-openai';
 import { runTTSAdapterFixture } from '@absolutejs/voice/testing';
 
-const realtime = createOpenAIRealtimeAdapter({
+const realtime = openai({
 	apiKey: process.env.OPENAI_API_KEY!,
 	instructions: 'Answer in one concise sentence.',
 	model: 'gpt-realtime',
@@ -3522,7 +3523,33 @@ const report = await runTTSAdapterFixture(
 );
 ```
 
-For server-to-server use, the adapter opens a WebSocket to OpenAI, sends `session.update`, streams text or base64 PCM input, and emits raw 24kHz mono `pcm_s16le` assistant audio. It requires raw 24kHz mono PCM input because that is the OpenAI Realtime PCM format. The main `voice(...)` route can now run in cascaded mode with `stt` plus optional `tts`, or direct realtime mode with `realtime`. Browser demos should make sure the captured PCM format matches `realtimeInputFormat` or resample before sending audio.
+For server-to-server use, realtime adapters open provider-specific streaming connections, send session configuration, stream text or PCM input, and emit normalized transcript/audio/error/close events. OpenAI Realtime uses raw 24kHz mono `pcm_s16le` audio. The main `voice(...)` route can run in cascaded mode with `stt` plus optional `tts`, or direct realtime mode with `realtime`. Browser demos should make sure the captured PCM format matches `realtimeInputFormat` or resample before sending audio.
+
+Use `createVoiceRealtimeProviderContractMatrixPreset(...)` to prove which realtime providers are production-ready. Pipecat is represented as an explicit bridge seam by default, not core-owned media infrastructure:
+
+```ts
+import {
+	createVoiceRealtimeProviderContractMatrixPreset,
+	createVoiceRealtimeProviderContractRoutes
+} from '@absolutejs/voice';
+
+app.use(
+	createVoiceRealtimeProviderContractRoutes({
+		matrix: createVoiceRealtimeProviderContractMatrixPreset({
+			env: process.env,
+			fallbackProviders: {
+				'gemini-live': ['openai-realtime'],
+				'openai-realtime': ['gemini-live']
+			},
+			latencyBudgets: {
+				'gemini-live': 900,
+				'openai-realtime': 800
+			},
+			selected: 'openai-realtime'
+		})
+	})
+);
+```
 
 If you want a minimal browser playback path, use the client audio player:
 

package/dist/index.d.ts

@@ -12,8 +12,8 @@ export { createVoiceBargeInRoutes, renderVoiceBargeInHTML, summarizeVoiceBargeIn
 export { createVoiceReconnectContractRoutes, renderVoiceReconnectContractHTML, summarizeVoiceReconnectContractSnapshots, runVoiceReconnectContract } from './reconnectContract';
 export { assertVoiceRealtimeChannelEvidence, buildVoiceRealtimeChannelRuntimeSamplesFromTrace, buildVoiceRealtimeChannelReport, createVoiceRealtimeChannelRoutes, evaluateVoiceRealtimeChannelEvidence, renderVoiceRealtimeChannelHTML, renderVoiceRealtimeChannelMarkdown } from './realtimeChannel';
 export type { VoiceRealtimeChannelAssertionInput, VoiceRealtimeChannelAssertionReport, VoiceRealtimeChannelBrowserCapture, VoiceRealtimeChannelIssue, VoiceRealtimeChannelReport, VoiceRealtimeChannelReportOptions, VoiceRealtimeChannelRoutesOptions, VoiceRealtimeChannelRuntimeSample, VoiceRealtimeChannelStatus } from './realtimeChannel';
-export { assertVoiceRealtimeProviderContractEvidence, buildVoiceRealtimeProviderContractMatrix, createVoiceRealtimeProviderContractRoutes, evaluateVoiceRealtimeProviderContractEvidence, renderVoiceRealtimeProviderContractHTML } from './realtimeProviderContracts';
-export type { VoiceRealtimeProviderContractAssertionInput, VoiceRealtimeProviderContractAssertionReport, VoiceRealtimeProviderContractCapability, VoiceRealtimeProviderContractCheck, VoiceRealtimeProviderContractDefinition, VoiceRealtimeProviderContractMatrixInput, VoiceRealtimeProviderContractMatrixReport, VoiceRealtimeProviderContractRoutesOptions, VoiceRealtimeProviderContractRow, VoiceRealtimeProviderContractStatus } from './realtimeProviderContracts';
+export { assertVoiceRealtimeProviderContractEvidence, buildVoiceRealtimeProviderContractMatrix, createVoiceRealtimeProviderContractMatrixPreset, createVoiceRealtimeProviderContractRoutes, evaluateVoiceRealtimeProviderContractEvidence, renderVoiceRealtimeProviderContractHTML } from './realtimeProviderContracts';
+export type { VoiceRealtimeProviderContractAssertionInput, VoiceRealtimeProviderContractAssertionReport, VoiceRealtimeProviderContractCapability, VoiceRealtimeProviderContractCheck, VoiceRealtimeProviderContractDefinition, VoiceRealtimeProviderContractMatrixPresetOptions, VoiceRealtimeProviderContractMatrixInput, VoiceRealtimeProviderContractMatrixReport, VoiceRealtimeProviderContractRoutesOptions, VoiceRealtimeProviderContractRow, VoiceRealtimeProviderPresetProvider, VoiceRealtimeProviderContractStatus } from './realtimeProviderContracts';
 export { buildVoiceDiagnosticsMarkdown, createVoiceDiagnosticsRoutes, resolveVoiceDiagnosticsTraceFilter } from './diagnosticsRoutes';
 export { buildVoiceDemoReadyReport, createVoiceDemoReadyRoutes, renderVoiceDemoReadyHTML } from './demoReadyRoutes';
 export { buildVoiceDeliverySinkReport, createVoiceDeliverySinkDescriptor, createVoiceDeliverySinkPair, createVoiceDeliverySinkRoutes, createVoiceFileDeliverySink, createVoicePostgresDeliverySink, createVoiceS3DeliverySink, createVoiceSQLiteDeliverySink, createVoiceWebhookDeliverySink, renderVoiceDeliverySinkHTML } from './deliverySinkRoutes';

package/dist/index.js

@@ -11256,6 +11256,11 @@ var defaultProviderEnv = {
   "openai-realtime": ["OPENAI_API_KEY"],
   "pipecat-bridge": []
 };
+var defaultRealtimeProviders = [
+  "openai-realtime",
+  "gemini-live",
+  "pipecat-bridge"
+];
 var statusRank = {
   pass: 0,
   warn: 1,
@@ -11264,6 +11269,34 @@ var statusRank = {
 var statusExceeds = (actual, max) => statusRank[actual] > statusRank[max];
 var rollupStatus = (checks) => checks.some((check) => check.status === "fail") ? "fail" : checks.some((check) => check.status === "warn") ? "warn" : "pass";
 var escapeHtml13 = (value) => String(value).replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll('"', "&quot;").replaceAll("'", "&#39;");
+var resolveProviderHref = (value, provider) => typeof value === "string" ? value : value?.[provider];
+var createVoiceRealtimeProviderContractMatrixPreset = (options = {}) => {
+  const providers = options.providers ?? defaultRealtimeProviders;
+  const selected = options.selected ?? providers[0];
+  return {
+    contracts: providers.map((provider) => {
+      const providerKey = String(provider);
+      const requiredEnv = options.requiredEnv?.[providerKey] ?? defaultProviderEnv[providerKey] ?? [];
+      const implementationStatus = options.implementationStatus?.[providerKey] ?? (providerKey === "pipecat-bridge" ? "planned" : "available");
+      const configured = options.configured?.[providerKey] ?? (implementationStatus === "planned" ? false : requiredEnv.every((name) => Boolean(options.env?.[name])));
+      return {
+        capabilities: options.capabilities?.[providerKey] ?? defaultRequiredCapabilities,
+        configured,
+        env: options.env,
+        fallbackProviders: options.fallbackProviders?.[providerKey],
+        implementationStatus,
+        latencyBudgetMs: options.latencyBudgets?.[providerKey],
+        provider,
+        readinessHref: resolveProviderHref(options.readinessHref, provider),
+        realtimeChannel: options.realtimeChannels?.[providerKey],
+        requiredCapabilities: options.requiredCapabilities?.[providerKey] ?? defaultRequiredCapabilities,
+        requiredEnv,
+        selected: provider === selected,
+        traceHref: resolveProviderHref(options.traceHref, provider)
+      };
+    })
+  };
+};
 var buildVoiceRealtimeProviderContractMatrix = (input) => {
   const rows = input.contracts.map((contract) => {
     const configured = contract.configured !== false;
@@ -34271,6 +34304,7 @@ export {
   createVoiceRedisIdempotencyStore,
   createVoiceReconnectContractRoutes,
   createVoiceRealtimeProviderContractRoutes,
+  createVoiceRealtimeProviderContractMatrixPreset,
   createVoiceRealtimeChannelRoutes,
   createVoiceReadinessProfile,
   createVoiceQualityRoutes,

package/dist/realtimeProviderContracts.d.ts

@@ -17,6 +17,22 @@ export type VoiceRealtimeProviderContractDefinition<TProvider extends string = s
     selected?: boolean;
     traceHref?: string;
 };
+export type VoiceRealtimeProviderPresetProvider = 'gemini-live' | 'openai-realtime' | 'pipecat-bridge' | (string & {});
+export type VoiceRealtimeProviderContractMatrixPresetOptions<TProvider extends string = VoiceRealtimeProviderPresetProvider> = {
+    capabilities?: Record<string, readonly VoiceRealtimeProviderContractCapability[]>;
+    configured?: Record<string, boolean>;
+    env?: Record<string, string | undefined>;
+    fallbackProviders?: Record<string, readonly TProvider[]>;
+    implementationStatus?: Record<string, 'available' | 'planned'>;
+    latencyBudgets?: Record<string, number>;
+    providers?: readonly TProvider[];
+    readinessHref?: string | Record<string, string | undefined>;
+    realtimeChannels?: Record<string, VoiceRealtimeChannelReport | undefined>;
+    requiredCapabilities?: Record<string, readonly VoiceRealtimeProviderContractCapability[]>;
+    requiredEnv?: Record<string, readonly string[]>;
+    selected?: TProvider;
+    traceHref?: string | Record<string, string | undefined>;
+};
 export type VoiceRealtimeProviderContractCheck = {
     detail?: string;
     key: string;
@@ -70,6 +86,7 @@ export type VoiceRealtimeProviderContractRoutesOptions<TProvider extends string
     render?: (report: VoiceRealtimeProviderContractMatrixReport<TProvider>) => Promise<string> | string;
     title?: string;
 };
+export declare const createVoiceRealtimeProviderContractMatrixPreset: <TProvider extends string = VoiceRealtimeProviderPresetProvider>(options?: VoiceRealtimeProviderContractMatrixPresetOptions<TProvider>) => VoiceRealtimeProviderContractMatrixInput<TProvider>;
 export declare const buildVoiceRealtimeProviderContractMatrix: <TProvider extends string = string>(input: VoiceRealtimeProviderContractMatrixInput<TProvider>) => VoiceRealtimeProviderContractMatrixReport<TProvider>;
 export declare const evaluateVoiceRealtimeProviderContractEvidence: <TProvider extends string = string>(report: VoiceRealtimeProviderContractMatrixReport<TProvider>, input?: VoiceRealtimeProviderContractAssertionInput<TProvider>) => VoiceRealtimeProviderContractAssertionReport<TProvider>;
 export declare const assertVoiceRealtimeProviderContractEvidence: <TProvider extends string = string>(report: VoiceRealtimeProviderContractMatrixReport<TProvider>, input?: VoiceRealtimeProviderContractAssertionInput<TProvider>) => VoiceRealtimeProviderContractAssertionReport<TProvider>;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@absolutejs/voice",
-	"version": "0.0.22-beta.306",
+	"version": "0.0.22-beta.307",
 	"description": "Voice primitives and Elysia plugin for AbsoluteJS",
 	"repository": {
 		"type": "git",