AI 录音设备 · 开放协议与云端 AI 接口 AI Recorder · Open Protocol & Cloud AI API

文件列表Files on device

Offset  Len   Field   Endian   Note
0       1B    MAGIC   -        0x5A
1       1B    SEQ     -        0..255 rolling
2       2B    CRC     LE       CRC-16/XMODEM over LEN(2B) + DATA
4       2B    LEN     LE       byte length of DATA
6       LEN   DATA    -        [TYPE:1B][CMD:1B][PARAMS...]

CRC-16/XMODEM   poly 0x1021  init 0x0000  no reflect  xorout 0x0000
Check vector    "123456789" -> 0x31C3

time  4B  BE   时长（秒）；个别固件为 unix 时间戳duration in seconds; some firmware sends a unix timestamp
size  4B  BE   设备内压缩体积（Byte）compressed size on device (bytes)
name  20B      NUL 填充。注意只有 20BNUL-padded. Note: only 20 bytes

KEY 只存在你自己浏览器的 localStorage 里，只会作为 Bearer 令牌发给 API。没有 KEY？ The key is kept in your own browser's localStorage and only ever sent as a Bearer token. No key yet? 申请试用Request a trial

问答Ask

其他端点Other endpoints

从一段 opus 到带说话人的逐句文本，中间有五步。每一步都有个「为什么必须这样」， 下面按顺序讲。这套跑在阿里云百炼 paraformer-v2 上，换别的引擎见下一节。 Five steps take an opus file to speaker-labelled sentences. Each has a reason it must be done that way. This describes the Alibaba Bailian paraformer-v2 path; see the next section to swap in another engine.

opus/wav  →  解码 PCM  →  音量归一化  →  上传对象存储拿公网 URL  →  提交转写  →  轮询取 JSON
                            normalize      object storage URL        submit         poll

文件转写接口只收公网可访问的 URL，不收字节流。 所以本地那份音频必须先落到一个能被对方服务器拉到的地方。我们用阿里云 OSS， 但换成任何一个能出公网 URL 的存储都一样 —— S3、R2、甚至你自己的 nginx 静态目录都行。 The file-transcription endpoint takes a public URL, not raw bytes. So the audio has to land somewhere the vendor's servers can fetch. We use Alibaba OSS, but anything that yields a public URL works — S3, R2, even your own nginx static dir.

🔑 OSS V1 签名只签 /{bucket}/{key}，host 不参与签名。 所以同一个签名换任意 endpoint 都有效 —— 我们据此让 PUT 走传输加速端点（国内各地就近接入，实测 0.27~0.6s）， GET 走标准端点（服务端回源同速，不产生加速流量费）。 🔑 The OSS V1 signature covers only /{bucket}/{key} — the host is not signed. So one signature works against any endpoint: we PUT via the transfer-acceleration endpoint (nearest PoP, measured 0.27–0.6 s) and GET via the standard one (same speed to the vendor, no acceleration traffic billed).

PUT  https://<bucket>.oss-accelerate.aliyuncs.com/<key>      # 就近上传 / nearest PoP
GET  https://<bucket>.oss-<region>.aliyuncs.com/<key>        # 引擎回源 / vendor fetches
Authorization: OSS <AccessKeyId>:<base64(hmac-sha1(secret, StringToSign))>

StringToSign = VERB + "\n" + Content-MD5 + "\n" + Content-Type + "\n" + Date + "\n"
             + CanonicalizedResource        # = /<bucket>/<key>   ← host 不在里面

⚠️ 音频落在存储上就是一份可下载的个人数据。 生产环境请给这个 bucket 配生命周期规则自动过期，别让它无限堆积 （我们这台试用机是 24 小时清一次，见「隐私与保留期」）。 ⚠️ Once uploaded, that audio is downloadable personal data. Set a lifecycle expiry rule on the bucket in production. Our trial host wipes after 24 h.

这是这类产品最值钱的一段，也最容易做错。先看声道数，再决定走哪条。 The most valuable part, and the easiest to get wrong. Branch on channel count first.

🔴 双声道两路必须用【同一个】增益，绝不能各自归一化。 两路的相对能量正是「这句话是谁说的」的判据，分别归一化会把这个信息直接抹掉，串音就分不掉了。 取两路各自所需增益里较小的那个：响的那路不削顶，比例也原样保留。 🔴 Apply one shared gain to both channels, never normalise them separately. Their relative energy is the attribution signal; separate normalisation erases it and crosstalk becomes unseparable. Use the smaller of the two required gains — the louder channel stays unclipped and the ratio is preserved.

const gain = Math.min(peakGain(left), peakGain(right));   // ✅
// const L = normalize(left), R = normalize(right);       // ❌ 相对能量没了 / ratio destroyed

POST /api/v1/services/audio/asr/transcription
X-DashScope-Async: enable
{ "model": "paraformer-v2",
  "input":  { "file_urls": ["https://<bucket>.oss-<region>.aliyuncs.com/<key>"] },
  "parameters": { "language_hints": ["zh"], "diarization_enabled": true } }

→ { "output": { "task_id": "..." } }
GET /api/v1/tasks/<task_id>      # 轮询到 SUCCEEDED，再去拉结果 JSON

⚠️ 任务成功 ≠ 有内容。见过 SUCCESS_WITH_NO_VALID_FRAGMENT（已计费但一个字没有）。 判成功要看有没有拿到句子，不能只看状态码，否则会把空结果当正常结果写进库。 ⚠️ Success ≠ content. SUCCESS_WITH_NO_VALID_FRAGMENT is billed but empty. Check that sentences came back, not just the status, or you will store empty results as good ones.

转写引擎是可插拔的。你只要提供一个函数，把音频变成统一格式的句子数组， 其余（归一化、说话人归属、摘要、检索、下载）全部不用动。 The engine is pluggable. Provide one function that turns audio into a normalised array of sentences; normalisation, attribution, summarisation, search and export all stay as they are.

/**
 * @param wavBuf  Buffer   16k/16bit PCM 的 WAV（已归一化）/ normalised WAV
 * @param tag     string   日志用的 id / id for logs
 * @param opts    { diarization: boolean, speakerCount: number }
 * @returns Promise<Segment[]>
 *
 * Segment = {
 *   start:   number,   // 秒 / seconds
 *   end:     number,
 *   text:    string,
 *   speaker: string|null   // "说话人A" 之类；引擎不支持就给 null
 * }
 */
async function asrMyEngine(wavBuf, tag, { diarization = true, speakerCount = 0 } = {}) {
  // 1) 你的引擎要 URL 就先传对象存储；要字节流就直接 POST
  // 2) 把返回结构映射成上面的 Segment[]
  // 3) 失败【抛异常】，不要 return [] —— 见下面第 2 条
  return segments;
}

然后在路由处加一档。现有逻辑是：需要说话人分离 → 走支持它的引擎； 短音频 → 走边际成本为零的那条；都不满足 → 走默认。 Then add a branch in the router. Current logic: needs diarization → engine that supports it; short audio → the zero-marginal-cost one; otherwise → default.

let provider = item.asrProvider || CFG.asrDefault || 'auto';
if (needSpeakers && MY_KEY) provider = 'myengine';
// ...
if (provider === 'myengine') segs = await asrMyEngine(wav, id, { diarization, speakerCount });

网页端完整流程是这五步。BLE 那半段的命令细节在上面「BLE 协议」一节， 这里讲的是把它接到云端并把结果显示出来的部分。 Five steps end to end. The BLE command details are in the protocol section above; this covers wiring it to the cloud and showing the result.

requestDevice  →  2-0 列目录  →  2-2 下载文件  →  POST /rec/v1/upload  →  轮询 /rec/v1/item/<id>
  连接              list           download          upload                 poll until done

// 蓝牙下下来的 blob 直接送走，元信息走 header（比 multipart 简单）
const r = await fetch('/rec/v1/upload', {
  method : 'POST',
  headers: { 'Authorization': 'Bearer ' + KEY,
             'X-Filename'   : encodeURIComponent(name),   // ← 见下面的中文乱码坑
             'Content-Type' : 'application/octet-stream' },
  body   : blob
});
const { id } = await r.json();     // → 拿到 id 就开始轮询

🔴 header 里的中文必然乱码。 Node 和 Python 的 http 层都按 latin-1 解 header，裸 UTF-8 会变成 名片.png → åç.png。发送端 encodeURIComponent， 接收端先 URL 解码再尝试还原 UTF-8。 文件名不是装饰 —— call / note 前缀要靠它判断录音模式， 而且设备不返回录制时间戳，文件名是唯一的时间来源。 🔴 Non-ASCII in headers will mojibake. Both Node's and Python's HTTP layers decode headers as latin-1. Percent-encode on send, URL-decode then re-interpret as UTF-8 on receive. The filename matters: the call/note prefix determines recording mode, and the device returns no timestamp — the filename is the only source of time.

// 转写是异步的（排队 → ASR → 摘要），几秒到几十秒，所以轮询而不是傻等
function watch(id, key) {                 // key = 设备上的文件名，见下面第 1 条
  clearInterval(timers[key]);
  results[key] = { id, status: 'queued' };
  render();
  const t0 = Date.now();
  timers[key] = setInterval(async () => {
    const it = await api('/item/' + id);
    results[key] = it;  render();
    if (it.status === 'done' || it.status === 'failed') clearInterval(timers[key]);
    else if (Date.now() - t0 > 180000) { clearInterval(timers[key]); note('还在转，稍后再看'); }
  }, 2500);
}

别做成「一个全局结果块显示在列表下方」—— 同步第二条就会把第一条顶掉， 而客户在现场最常做的动作恰恰是一条条点开来看。按文件名存成一个字典，渲染时挂到对应行下面。 Don't render one global result block below the list — syncing a second recording replaces the first, and clicking through them one by one is exactly what people do. Key the results by filename and render each under its own row.

var results = {};      // 设备文件名 → 转写结果 / filename → result
var open    = {};      // 设备文件名 → 是否展开 / filename → expanded

rows.forEach(f => {
  html += renderRow(f);                    // 时间 / 时长 / 大小 / 同步按钮
  html += renderResult(results[f.raw], f.raw);   // ← 就挂在它下面
});

// ✅ 带认证取音频 / fetch with auth
async function authBlob(path) {
  const r = await fetch(API + path, { headers: { Authorization: 'Bearer ' + KEY } });
  if (!r.ok) throw new Error('HTTP ' + r.status);
  return r.blob();
}
authBlob('/file/' + id).then(b => { audioEl.src = URL.createObjectURL(b); });

// 下载：同一条路，再触发一次 <a download>
function saveAs(blob, name) {
  const u = URL.createObjectURL(blob), a = document.createElement('a');
  a.href = u; a.download = name; document.body.appendChild(a); a.click();
  setTimeout(() => { URL.revokeObjectURL(u); a.remove(); }, 1500);
}

试用场景下客户传的是他自己的真实通话录音。 不清理就等于无限期持有别人的个人数据，客户还不知道 —— 欧洲客户直接踩 GDPR。 这台机器的做法： In a trial, people upload their own real phone calls. Keeping them forever means holding someone else's personal data indefinitely without them knowing — a direct GDPR problem for EU customers. What this host does:

🔴 删文件要按 id 前缀扫目录，不要枚举后缀。 一条记录散在 audio / text / files / thumbs / preview 五个目录，后缀还不止一种 （.txt .chunks.json .segments.json .wav .opus…）。 枚举漏一个就留下孤儿文件 —— 列表里已经看不见了，磁盘却一直在涨，没人会发现。 🔴 Delete by scanning directories for the id prefix, not by enumerating extensions. One record spans five directories with several suffixes each. Miss one and you leave orphan files: gone from the list, still growing on disk, and nobody notices.

开源许可（全部核过，可商用打包）Licensing (all verified, safe to ship commercially)

自己动手会踩到的四个坑Four things that will bite you