@ai-matrx/browser-audio

Durable browser voice input with a framework-light core, IndexedDB recovery, pluggable transcription, an optional AI Matrx adapter, and optional React controls.

The package owns the difficult browser lifecycle: microphone permission, MediaRecorder, audio-format negotiation, chunk rotation, local safety writes, ordered live transcription, whole-recording fallback, and recovery after a page closes or a network call fails.

Install

pnpm add @ai-matrx/browser-audio

React controls are optional. Applications importing /react must also install React 18 or newer.

Framework-free core

import {
  BrowserAudioKernel,
  type TranscriptionTransport,
} from "@ai-matrx/browser-audio/core";

const transport: TranscriptionTransport = {
  async transcribe(file, signal) {
    const form = new FormData();
    form.append("file", file);
    const response = await fetch("/api/transcribe", {
      method: "POST",
      body: form,
      signal,
    });
    if (!response.ok) throw new Error("Transcription failed");
    return response.json();
  },
};

export const audio = new BrowserAudioKernel({
  transport,
  onDiagnostic: (diagnostic) => reportDiagnostic(diagnostic),
});

Create one kernel per application. Inputs subscribe to the kernel and identify their recording with a stable ownerId.

AI Matrx adapter

import { BrowserAudioKernel } from "@ai-matrx/browser-audio/core";
import { createMatrxAudioClient } from "@ai-matrx/browser-audio/matrx";

const client = createMatrxAudioClient({
  baseUrl: "https://server.example.com/api",
  getAccessToken: () => auth.getAccessToken(),
  // Optional when /auth/whoami returns organization_id. Supply this when the
  // host already owns an explicit active-organization selector.
  getOrganizationId: () => auth.getActiveOrganizationId(),
});

export const audio = new BrowserAudioKernel({
  transport: client,
  persistence: client,
});

The adapter receives the API base URL and access-token resolver from the host. It imports no application code and stores no credentials. For durable Matrx operations it sends an explicit X-Organization-Id: the host may inject the resolver, otherwise the adapter resolves it through /auth/whoami and caches it only for the current access token.

React

import { VoiceInputButton } from "@ai-matrx/browser-audio/react";

<VoiceInputButton
  kernel={audio}
  ownerId="message-composer"
  value={draft}
  onValueChange={setDraft}
  append
  onBusyChange={setVoiceBusy}
  onError={showVoiceError}
/>

VoiceInputButton is style-neutral, accepts className and style, and allows hosts to replace its icon with renderIcon. useVoiceInput is available when a product needs completely custom presentation.

Runtime support

• Modern browser applications, including Vite and client-side Next.js code.
• WebViews that provide MediaRecorder, MediaDevices, IndexedDB, Web Audio, Blob, File, and Fetch.
• Browser extensions when capture runs in a DOM/offscreen document. Manifest V3 service workers require a host messaging adapter.
• React Native and native processes require a media/storage adapter; browser capture APIs do not exist there.

Importing the package is SSR-safe. Construct and start the browser kernel in a client runtime.

Reliability contract

• Every complete audio chunk is written to the safety store before network work.
• Every displayed live transcript fragment is written to IndexedDB before it is published to the host UI.
• The first three and six seconds become visible quickly; at ten seconds they are atomically replaced by one higher-context transcription of the opening.
• AI Matrx remote recovery uses an indexed, owner-scoped journal and rejects incomplete chunk sets instead of transcribing partial audio as complete.
• Failed live chunks trigger whole-recording transcription.
• A partial transcript is never delivered as final after a failed fallback.
• Closing the page leaves a recoverable record.
• Transcription and persistence are injected contracts; the core never assumes an API, authentication system, database, or framework.
• Background failures reach onDiagnostic; user-affecting failures reach the recording request and React onError callbacks.

Exports

• @ai-matrx/browser-audio — framework-free core.
• @ai-matrx/browser-audio/core — explicit core entry point.
• @ai-matrx/browser-audio/matrx — AI Matrx HTTP and durability adapter.
• @ai-matrx/browser-audio/react — React hook and controls.

Development

pnpm typecheck
pnpm test
pnpm check:package

check:package builds ESM JavaScript and declarations, validates the npm surface with Publint, packs the publish artifact, validates that tarball's declarations with Are the Types Wrong, installs it into an empty project, and imports every public entry point.

Never run npm publish from this working directory: workspace development uses source exports that pnpm replaces with dist/ exports while packing. Release the verified .tgz produced by pnpm pack; prepublishOnly blocks the unsafe path.

Automated gates do not substitute for a deployed authenticated microphone canary. Version 0.2.0 was published only after the matching AI Dream recording-journal routes were deployed and that canary passed. Every future release must repeat the deployed canary before registry publication.