# @ai-matrx/browser-audio 中文文档

规范地址：https://npmcn.com/package/%40ai-matrx/browser-audio/

版本：0\.5\.17
npm 元数据更新时间：2026-10-28T12:15:59.833Z
中文译文更新时间：2026-11-05T18:44:42.267Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40ai-matrx/browser-audio
原文对照：https://npmcn.com/package/%40ai-matrx/browser-audio/?lang=original
项目主页：https://github.com/AI-Matrix-Engine/aidream/tree/main/apps/shared/browser-audio#readme
源码仓库：https://github.com/AI-Matrix-Engine/aidream

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：733 kB，20 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=20
- 运行依赖：0 个
- peer 依赖：react \>=18\.0\.0
- 首次发布：2026-08-22T20:43:37.442Z
- 最新版本发布：2026-10-28T12:15:59.614Z
- 近 30 天下载量：56830（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：38（近 12 个月 38 个）

## 中文简介

持久,框架光浏览器语音输入,并带有索引DB恢复,可插件转录,以及可选反应控制.

## 安装

```sh
npm install @ai-matrx/browser-audio
```

也可以使用：`pnpm add @ai-matrx/browser-audio`、`yarn add @ai-matrx/browser-audio`、`bun add @ai-matrx/browser-audio`

## README

# @ai-matrx/浏览器-音频

持久浏览器语音输入,带有框架光芯,索引DB恢复, 可插件复制,可选的 AI Matrx 适配器和可选反应 控制系统.

软件包拥有困难浏览器生命周期: 麦克风权限, `MediaRecorder`音频形式的谈判, 块旋转, 本地安全写道, 命令现场抄录 完整记录回落 页面后恢复 关闭或网络呼叫失败 .

## 安装

```bash
pnpm add @ai-matrx/browser-audio
```

反应控制是可选的 。 应用程序导入 `/react` 还必须安装 反应18或更新.

## 无框架核心

```ts
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),
});
```

每个应用程序创建一个内核 。 输入订阅内核并识别 他们用马厩录音 `ownerId`。 。 。 .

## AI Matrx 适配器

```ts
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,
});
```

适配器接收来自主机的API基础URL和访问-token解析器. 它不进口应用程序代码,也不储存证书。 用于耐用 Matrx 它发送一个明确的操作 `X-Organization-Id`: 主机可能注入 解析器,否则适配器通过 `/auth/whoami` 和缓存 只用于当前访问符号.

## 反应

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

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

`VoiceInputButton` 样式中立, 接受 `className` 财务报告和审定财务报表 `style`,并允许 要替换其图标的主机 `renderIcon`。 。 。 . `useVoiceInput` 当 产品需要完全自定义的演示.

## 运行时间支持

-   现代浏览器应用程序,包括Vite和客户端侧Next.js代码.
-   提供的网络视图 `MediaRecorder`, (中文(简体) ), `MediaDevices`,索引数据库、网络音频, `Blob`, (中文(简体) ), `File`获取.
-   在 DOM/offscreen 文档中抓取时浏览器扩展名 。 示意图V3 服务人员需要一个主机消息适配器.
-   反应本地和本地进程需要媒体/存储适配器;浏览器 抓取 API 不存在 .

导入软件包是安全的。 构造并启动内核 客户端运行时间 .

## 可靠性合同

-   每个完整的音频块在网络工作前都会被写入安全商店.
-   每个显示的活性记录片段都写在索引数据库之前 发布给主机UI.
-   前3和6秒迅速可见;在10秒 在解剖学上, 取而代之的是开口的更高级的文字记录.
-   AI Matrx 远程恢复使用有索引的、所有者范围化的日记并拒绝 不完整块集而不是将部分音频转录为完整 .
-   失败的活块触发了全记录的复制.
-   部分笔录在倒计时失败后从未作为最后记录交付.
-   关闭页面留下可恢复的记录.
-   转录和坚持合同;核心从未假定 aPI、认证系统、数据库或框架.
-   背景失败已达 `onDiagnostic`; 影响用户的失败到达 记录请求和反应 `onError` 召回电话.

## 出口

-   `@ai-matrx/browser-audio` ——无框架核心.
-   `@ai-matrx/browser-audio/core` 明确的核心切入点.
-   `@ai-matrx/browser-audio/matrx` ——AI Matrx HTTP和耐久性适配器.
-   `@ai-matrx/browser-audio/react` ——反应钩与控制.

## 发展

```bash
pnpm typecheck
pnpm test
pnpm check:package
```

`check:package` 建立无害环境管理 JavaScript 和声明,验证 npm 表面 与Publint, 包装出版的文物, 验证焦油球的申报 将它安装到空项目中, 并导入每个 公共入境点.

永远不要跑 `npm publish` 工作空间开发用途 pnpm 替换为 `dist/` 包装时输出。 释放 已核实 `.tgz` 生产 `pnpm pack`· ; `prepublishOnly` 封锁不安全路径.

自动门不能取而代之的是已部署的经认证的麦克风 金丝雀. 0.2.0版本仅在匹配的 AI Dream 之后发布 录音-记者路线已经部署,金丝雀经过。 每个未来 释放必须在登记册公布前重复已部署的金丝雀.

## 常见问题

### @ai-matrx/browser-audio 是什么？

持久,框架光浏览器语音输入,并带有索引DB恢复,可插件转录,以及可选反应控制\.

### 如何安装 @ai-matrx/browser-audio？

在项目目录运行 npm install @ai-matrx/browser-audio，或使用 pnpm add / yarn add / bun add。

### @ai-matrx/browser-audio 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @ai-matrx/browser-audio 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @ai-matrx/browser-audio 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=20。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @ai-matrx/browser-audio 可以商用吗？

@ai-matrx/browser-audio 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @ai-matrx/browser-audio 的下载量有多少？

根据 npm 官方下载统计，@ai-matrx/browser-audio 在 2026/10/05 – 2026/11/03 这 30 天内被下载 56,830 次，日均约 1,894 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @ai-matrx/browser-audio 还在维护吗？

最新版本 0\.5\.17 发布于 2026/10/28（8 天前）；至今共发布 38 个版本，其中过去 12 个月发布了 38 个；首次发布于 2026/08/23。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。