Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 3 additions & 1 deletion web-pages/product-site/content/legacy-manifest.json
Original file line number Diff line number Diff line change
Expand Up @@ -142,6 +142,8 @@
"blog/hotwords-package-boundaries.html": "be0aaad687d18fc9387fb35ed10f44272bd47e161ae3e489cb68ca4c860d4307",
"en/blog/hotwords-package-boundaries.html": "4eae4e3f485e5fd8c7ab1b64d6e2fb28e0e529d821b02e87f040a0a73bbd3085",
"blog/websocket-offline-model-options.html": "9be8d17aaf2b99829442c0294568e00b49b9328b1480eba1d3d525cb65d7c1b1",
"en/blog/websocket-offline-model-options.html": "bfd261068359bc529ae15e7830d518d26ecf4887d59312aad0f2e88b88805139"
"en/blog/websocket-offline-model-options.html": "bfd261068359bc529ae15e7830d518d26ecf4887d59312aad0f2e88b88805139",
"blog/wav-pcm-input-checklist.html": "178ea5555257b9d3e0e7e4078f6616c0e2faf836fdd4bbfb269d934a5ffaa436",
"en/blog/wav-pcm-input-checklist.html": "3df930106634f89309db79c42abc352eace9c319556baac207938850d7cb8973"
}
}
13 changes: 13 additions & 0 deletions web-pages/product-site/data/blog.json
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,19 @@
],
"lead_image": "/img/funclip-v2-1-0-interface.jpg",
"articles": [
{
"slug": "wav-pcm-input-checklist",
"category": "explanations",
"reviewed": true,
"zh": {
"title": "先检查音频输入:WAV、裸 PCM 与采样率",
"summary": "用可直接运行的 PCM16 WAV 检查器核对帧数、时长与峰值,区分文件检查、重采样和真实识别验收。"
},
"en": {
"title": "Check the audio input first: WAV, raw PCM and sample rate",
"summary": "Run a PCM16 WAV inspector to verify frames, duration and peak amplitude, while keeping file checks separate from resampling and ASR acceptance."
}
},
{
"slug": "websocket-offline-model-options",
"category": "explanations",
Expand Down
118 changes: 118 additions & 0 deletions web-pages/product-site/legacy/blog/wav-pcm-input-checklist.html
Original file line number Diff line number Diff line change
@@ -0,0 +1,118 @@
<!DOCTYPE html>

<html lang="zh"><head><meta charset="utf-8"/><meta content="width=device-width,initial-scale=1" name="viewport"/>
<title>先检查音频输入:WAV、裸 PCM 与采样率 | FunASR</title><meta content="用可直接运行的 PCM16 WAV 检查器核对帧数、时长与峰值,区分文件检查、重采样和真实识别验收。" name="description"/>
<link href="/logo.png" rel="icon"/><meta content="先检查音频输入:WAV、裸 PCM 与采样率" property="og:title"/><meta content="用可直接运行的 PCM16 WAV 检查器核对帧数、时长与峰值,区分文件检查、重采样和真实识别验收。" property="og:description"/>
<meta content="article" property="og:type"/><meta content="https://www.funasr.com/blog/wav-pcm-input-checklist.html" property="og:url"/><meta content="https://www.funasr.com/logo.png" property="og:image"/>
<link href="https://www.funasr.com/blog/wav-pcm-input-checklist.html" rel="canonical"/><link href="https://www.funasr.com/en/blog/wav-pcm-input-checklist.html" hreflang="en" rel="alternate"/><link href="https://www.funasr.com/blog/wav-pcm-input-checklist.html" hreflang="zh" rel="alternate"/><link href="https://www.funasr.com/en/blog/wav-pcm-input-checklist.html" hreflang="x-default" rel="alternate"/>
<link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700;800&amp;display=swap" rel="stylesheet"/>
<script type="application/ld+json">{"@context":"https://schema.org","@type":"BlogPosting","headline":"先检查音频输入:WAV、裸 PCM 与采样率","description":"用可直接运行的 PCM16 WAV 检查器核对帧数、时长与峰值,区分文件检查、重采样和真实识别验收。","datePublished":"2026-11-15","dateModified":"2026-11-15","author":{"@type":"Organization","name":"FunASR / Tongyi Lab"},"publisher":{"@type":"Organization","name":"FunASR","logo":{"@type":"ImageObject","url":"https://www.funasr.com/logo.png"}},"mainEntityOfPage":{"@type":"WebPage","@id":"https://www.funasr.com/blog/wav-pcm-input-checklist.html"},"image":"https://www.funasr.com/logo.png"}</script>
<style>:root{--primary:#2563eb;--primary-dark:#1d4ed8;--bg:#fff;--surface:#f8fafc;--border:#e2e8f0;--text:#0f172a;--text-soft:#475569;--text-muted:#94a3b8;--radius:12px}
*{margin:0;padding:0;box-sizing:border-box}
body{font-family:'Inter',-apple-system,sans-serif;color:var(--text);line-height:1.7}
a{color:var(--primary);text-decoration:none}a:hover{text-decoration:underline}
.container{max-width:800px;margin:0 auto;padding:0 24px}
.nav{position:fixed;top:0;left:0;right:0;z-index:100;background:rgba(255,255,255,0.9);backdrop-filter:blur(12px);border-bottom:1px solid var(--border);padding:14px 0}
.nav .container{max-width:1120px;display:flex;align-items:center;gap:24px}
.nav-logo{font-size:1.2rem;font-weight:800;color:var(--text)}.nav-logo span{color:var(--primary)}
.nav-links{display:flex;gap:20px;margin-left:auto;flex-wrap:wrap}
.nav-links a{font-size:0.85rem;font-weight:500;color:var(--text-soft)}
.nav-btn{padding:7px 16px;background:var(--primary);color:#fff;border-radius:7px;font-size:0.83rem;font-weight:600}
article{padding:120px 0 80px}
h1{font-size:2rem;font-weight:800;line-height:1.3;margin-bottom:14px}
h2{font-size:1.3rem;font-weight:700;margin:36px 0 14px;padding-top:16px;border-top:1px solid var(--border)}
h3{font-size:1.05rem;font-weight:700;margin:22px 0 10px}
p{margin-bottom:14px;color:var(--text-soft)}
ul,ol{margin:0 0 14px 22px;color:var(--text-soft)}li{margin-bottom:6px}
table{width:100%;border-collapse:collapse;margin:16px 0;font-size:0.86rem}
th,td{padding:10px 12px;text-align:left;border-bottom:1px solid var(--border)}
th{font-weight:600;background:var(--surface);font-size:0.78rem;color:var(--text-muted)}
pre{background:#1e293b;color:#e2e8f0;padding:18px;border-radius:10px;overflow-x:auto;font-size:0.82rem;line-height:1.7;margin:14px 0}
code{font-family:ui-monospace,Menlo,monospace}
p code,li code{background:var(--surface);padding:2px 6px;border-radius:5px;font-size:0.85em;color:var(--primary-dark)}
.post-meta{color:var(--text-muted);font-size:0.85rem;margin-bottom:24px}
.cta{background:var(--surface);border:1px solid var(--border);border-radius:var(--radius);padding:24px;margin:28px 0;text-align:center}
.cta a.btn{display:inline-block;padding:10px 24px;background:var(--primary);color:#fff;border-radius:8px;font-weight:600}
.post-list{list-style:none;margin:0;padding:0}
.post-list li{margin:0 0 8px}
.post-card{display:block;border:1px solid var(--border);border-radius:var(--radius);padding:20px 22px;margin-bottom:14px}
.post-card:hover{border-color:var(--primary);text-decoration:none}
.post-card h2{border:none;padding:0;margin:0 0 6px;font-size:1.15rem;color:var(--text)}
.post-card p{margin:0;color:var(--text-soft);font-size:0.9rem}
.post-card .date{color:var(--text-muted);font-size:0.8rem}
footer{background:#0f172a;color:#94a3b8;padding:28px 0;text-align:center;font-size:0.8rem}
footer a{color:#94a3b8}
@media(max-width:900px){.nav-links{display:none}.nav .container{gap:16px}.nav-logo{margin-right:auto}h1{font-size:1.75rem}table{table-layout:fixed;font-size:0.78rem}th,td{padding:8px 4px;overflow-wrap:anywhere}p code,li code{overflow-wrap:anywhere;word-break:break-word}}
article p a,article li a{color:#006a57;text-decoration:underline;text-underline-offset:.15em}
</style></head><body>
<nav class="nav"><div class="container"><a class="nav-logo" href="/">Fun<span>ASR</span></a><div class="nav-links"><a href="/#capabilities">核心能力</a><a href="/#usage">如何使用</a><a href="/#benchmark">性能</a><a href="/#demo">演示</a><a href="https://modelscope.github.io/FunASR/zh/" target="_blank">文档</a><a href="/quickstart.html">快速上手</a><a href="/models.html">模型</a><a href="/ecosystem.html">生态</a><a href="/blog/">技术博客</a><a href="/vs-whisper.html">对比 Whisper</a><a href="/donors.html">功德榜</a></div><a href="https://www.funasr.com/en/blog/wav-pcm-input-checklist.html" style="font-size:0.83rem;font-weight:600;color:var(--text-soft)">EN</a><a class="nav-btn" href="/go/github" target="_blank">GitHub ★</a></div></nav>
<article><div class="container"><h1>先检查音频输入:WAV、裸 PCM 与采样率</h1>
<p class="post-meta">FunASR Blog · 2026-11-15</p>
<p class="lead" data-editorial="opening">同一段录音,文件路径输入正常,换成数组或字节后却出现异常?在调整模型、热词或 VAD 之前,先核对输入的格式、采样率、声道与数值范围。一个短小、只读的文件检查器,就能帮助你排除“空文件”“截断数据”和“把声道数算进时长”等基础问题。</p>
<p data-editorial="example">例如,一个 16 kHz 双声道文件有 32000 个采样帧,时长是 2 秒,不是 4 秒。每帧含两个声道的采样值;把左右声道直接展平成单声道序列,会改变时间关系。另一个常见误区是把原本 8 kHz 的数据标记为 16 kHz:修改采样率标签没有生成新的采样点,不能代替重采样。</p>
<p data-editorial="boundary">本文检查器仅面向本地、未压缩、16 位整数 PCM WAV,使用 Python 标准库,不加载 FunASR 或模型、不联网、不修改文件。它不是通用音频解码器,不支持 MP3、浮点 WAV 或任意裸 PCM,也不验证语音内容、识别准确率或生产服务。测试中的音频是人工构造的二进制样本,不是真实语音质量评测。</p>
<h2>1. 先区分容器、字节与数组</h2>
<p><strong>WAV 是容器。</strong>文件包含格式信息与音频数据,不能把整个文件的字节都当作采样值。下面的示例使用 <code>wave</code> 解析容器,再读取数据帧。</p>
<p><strong>裸 PCM 没有自描述的完整容器。</strong>处理前需要从数据来源确认采样率、声道数、位宽、符号和字节序。仅凭扩展名或字节长度不能可靠推断这些信息。不要把未知 PCM 强行加一个 WAV 头就认定修复完成。</p>
<p><strong>数组有形状和数值范围。</strong>有符号 PCM16 的范围是 -32768 到 32767;转换成浮点 dtype 不等于缩放幅度。按 32768 归一化后,负端可到 -1,正端略小于 1。二维数组还需要明确哪一维是声道,不能只靠 reshape。具体支持方式应以所用版本的输入实现为准。</p>
<h2>2. 运行只读的 PCM16 WAV 检查器</h2>
<p>将下面代码作为独立的 <code>inspect_wav.py</code> 脚本运行,传入本地 WAV 路径。它逐块读取数据,报告采样帧数、时长和所有声道的绝对峰值,同时拒绝空数据、非 PCM16 和截断文件。</p>
<pre><code data-language="python">import json
import struct
import sys
import wave


def inspect_pcm16_wav(path):
with wave.open(str(path), "rb") as audio:
channels = audio.getnchannels()
rate = audio.getframerate()
declared = audio.getnframes()
if audio.getcomptype() != "NONE" or audio.getsampwidth() != 2:
raise ValueError("Expected uncompressed PCM16 WAV")
if channels &lt; 1 or rate &lt; 1 or declared &lt; 1:
raise ValueError("Empty or invalid audio")
frame_bytes = channels * 2
chunk_frames = max(1, 65536 // frame_bytes)
frames = 0
peak = 0
while True:
raw = audio.readframes(chunk_frames)
if not raw:
break
if len(raw) % frame_bytes:
raise ValueError("Truncated sample or channel frame")
frames += len(raw) // frame_bytes
peak = max(peak, max(abs(value[0])
for value in struct.iter_unpack("&lt;h", raw)))
if frames != declared:
raise ValueError("Audio data is shorter than its WAV header")
return {
"channels": channels,
"sample_rate": rate,
"frames": frames,
"duration_seconds": frames / rate,
"peak_abs": peak / 32768.0,
}


if __name__ == "__main__":
print(json.dumps(inspect_pcm16_wav(sys.argv[1]), indent=2))</code></pre>
<pre><code data-language="shell">python inspect_wav.py /path/to/input.wav</code></pre>
<p><code>duration_seconds</code> 使用帧数除以采样率,不再除以或乘以声道数。<code>peak_abs</code> 是全部声道上的最大绝对采样值,不是响度、信噪比或语音概率。非空的全零文件会返回 0;这和没有任何数据帧的空文件不同。峰值达到 1 值得检查,但单个极值本身不能证明整段录音发生了削波。</p>
<h2>3. 怎样使用检查结果</h2>
<ul>
<li>时长与播放器或采集记录不符时,先核对数据来源的真实采样率和声道布局,不要通过修改标签让数字“看起来正确”。</li>
<li>文件被拒绝时,先检查导出或传输是否完整。对 MP3、24 位或浮点 WAV,使用明确支持该格式的解码工具,而不是删除验证条件。</li>
<li>双声道需要转单声道时,按所用前端的声道策略处理;需要重采样时,使用真实的重采样器,并保留转换前后的文件与参数。</li>
<li>峰值合理只说明幅度检查没有暴露这一类问题,不能证明录音中有可识别语音,也不能替代转录验收。</li>
</ul>
<h2>4. 版本与测试边界</h2>
<p><a href="https://github.com/modelscope/FunASR/pull/3899">#3899 的输入修复集成</a>保留了原作者的提交,修复 NumPy PCM16 的缩放和二维浮点输入的声道处理。可核对<a href="https://github.com/modelscope/FunASR/blob/173cbee304836dae94079c8f600272f3637451a4/funasr/utils/load_utils.py">固定提交的输入加载实现</a>。截至本文发布,修复已合入 main;已验收的根包仍是 <a href="https://github.com/modelscope/FunASR/releases/tag/v1.4.26">FunASR 1.4.26</a>,不能据此宣称安装 1.4.26 已包含这次 main 修复。本文检查器不依赖该修复,也不会修改你的安装。</p>
<p>随文测试直接执行中英文正文及构建页面里的同一段代码,覆盖单/双声道、8/16 kHz、PCM16 正负边界、非空静音、空文件、8 位输入、截断采样、截断整帧、非 WAV、跨读取块的末尾峰值和命令行入口。它检查已覆盖的输入契约,不是任意损坏文件的安全审计,也不涵盖所有 WAV 编码扩展。</p>
<p>文件检查之后,再用有权处理的真实录音检查文字、时间戳、漏句和说话人结果。分享问题时附上脱敏的格式信息、版本与最小复现,避免公开私有音频、转录或绝对路径。</p>
<p data-editorial="next-step">下一步使用<a href="/blog/meeting-transcript-acceptance.html">会议转录验收清单</a>,把输入检查与实际转录结果对应起来。</p>
</div></article>
<footer><div class="container">FunASR · 通义实验室开源语音识别 · <a href="/go/github">GitHub</a></div></footer>
</body></html>

Loading
Loading