# 语音 SDK

实时转写（边说边出字）、录音、音量分析、音频文件转写，以及基于转写的翻译与会议纪要。

```js
import { voice } from "/developer/sdk/v1/aidc.js";
```

清单里声明：`"sdk": ["voice", "model"]`、`"permissions": { "microphone": true }`、`"models": ["gpt-live-transcribe", "deepseek-flash"]`。

## 实时转写

```js
const session = await voice.startTranscription({
  languages: ["zh", "en", "ja", "ar", "bn"],   // 预期输入语种（ISO 639-1）
  keywords: ["AIDC", "Nexus"],                // 专有名词提示
  onPartial: (id, text) => render(id, text),  // 同一句会多次回调，文字越来越长
  onFinal: (id, text) => commit(id, text),    // 这一句定稿
  onLevel: (level) => meter(level),           // 0–1 音量
  onStop: () => done(),
});
session.stop();
```

原理：平台用服务端的 key 换一张 10 分钟的短命票据（会话配置钉在票据上），浏览器经 WebRTC 直连转写模型——**音频字节不经 AIDC 平台**。断句在浏览器侧做：静音超过 `silenceMs`（缺省 600ms）就把这一句交去定稿。每场最长 5 分钟，到点自动结束，再开一场即可续上。

| 参数 | 说明 |
| --- | --- |
| `languages` | 缺省 `["zh","en"]`；支持 zh、en、ja、ar、bn、ko、fr、de、es、ru、vi、th、id |
| `prompt` / `keywords` | 场景提示与专有名词（不得含 `<`、`>`、换行）。转写会偏向这些词，只放会上真会出现的词——写死无关的词会把别的词听成它 |
| `silenceMs` / `speechRms` | 断句的静音时长与音量门限 |
| `stream` | 复用已有的麦克风流（例如录像时） |

## 录音

```js
const recorder = await voice.record({ timesliceMs: 1000, onChunk: (blob) => upload(blob) });
const audio = await recorder.stop();   // 整段 webm / mp4（Safari）
```

录音与实时转写可以同时进行：先 `voice.openMicrophone()` 拿到流，分别传给 `record({ stream })` 和 `startTranscription({ stream })`。

## 音量

```js
const stopMeter = voice.levelMeter(stream, (level) => bar.style.width = `${level * 100}%`);
```

## 文件转写

```js
const { text, language, duration } = await voice.transcribe(audioBlob, { language: "zh" });
```

单次 ≤ 4 MB（约 15 分钟 24 kbps opus）。更长的录音在服务端或命令行处理：`aidc voice transcribe meeting.m4a`（ffmpeg 自动转码、分段）。

## 翻译

```js
const out = await voice.translate("下周一上线新版本", ["ja", "en", "ar-EG", "bn"]);
// → { ja: "来週の月曜日に…", en: "…", "ar-EG": "…", bn: "…" }
```

一次请求同时译成多种语言，缺省用 `deepseek-flash`（最快）。`ar-EG` 是埃及阿拉伯语（埃及方言），`ar` 是现代标准阿拉伯语。可以传 `context`（上文，只帮助理解、不翻译）。

## 会议纪要

```js
const m = await voice.minutes(transcript, { meetingTitle: "周例会" });
// → { title, summary, decisions, actionItems: [{owner, task, due}], topics, markdown }
```

`markdown` 可以直接发给智能体归档（见 [连接 SDK](connect.md)）。

## 命令行

```bash
aidc voice transcribe meeting.m4a --language zh
aidc voice translate "下周一上线" --to ja,en,ar-EG,bn
aidc voice minutes transcript.txt --title 周例会
```

## 错误

`microphone_denied`、`microphone_not_found`、`microphone_unsupported`、`transcription_rejected`、`transcription_disconnected`；API 的 `quota_exhausted`（应用当日实时转写场次用完）。