From 15b1ec65c58f59b729834bdebed0f067c1f02181 Mon Sep 17 00:00:00 2001 From: zhifu gao Date: Sun, 15 Nov 2026 00:57:04 +0800 Subject: [PATCH] docs(site): explain WAV input checks with executable PCM16 examples Publish one dated bilingual source-configuration tutorial with an executable read-only example and explicit test limits. Signed-off-by: LauraGPT --- .../product-site/content/legacy-manifest.json | 4 +- web-pages/product-site/data/blog.json | 13 ++ .../legacy/blog/wav-pcm-input-checklist.html | 118 ++++++++++++++++++ .../en/blog/wav-pcm-input-checklist.html | 118 ++++++++++++++++++ .../tests/test_wav_input_article.py | 109 ++++++++++++++++ 5 files changed, 361 insertions(+), 1 deletion(-) create mode 100644 web-pages/product-site/legacy/blog/wav-pcm-input-checklist.html create mode 100644 web-pages/product-site/legacy/en/blog/wav-pcm-input-checklist.html create mode 100644 web-pages/product-site/tests/test_wav_input_article.py diff --git a/web-pages/product-site/content/legacy-manifest.json b/web-pages/product-site/content/legacy-manifest.json index 9d03c9583..c98d8395f 100644 --- a/web-pages/product-site/content/legacy-manifest.json +++ b/web-pages/product-site/content/legacy-manifest.json @@ -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" } } diff --git a/web-pages/product-site/data/blog.json b/web-pages/product-site/data/blog.json index 8ae38ebd9..7cc95ac6e 100644 --- a/web-pages/product-site/data/blog.json +++ b/web-pages/product-site/data/blog.json @@ -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", diff --git a/web-pages/product-site/legacy/blog/wav-pcm-input-checklist.html b/web-pages/product-site/legacy/blog/wav-pcm-input-checklist.html new file mode 100644 index 000000000..445b2ebbc --- /dev/null +++ b/web-pages/product-site/legacy/blog/wav-pcm-input-checklist.html @@ -0,0 +1,118 @@ + + + +先检查音频输入:WAV、裸 PCM 与采样率 | FunASR + + + + + + + +

先检查音频输入:WAV、裸 PCM 与采样率

+ +

同一段录音,文件路径输入正常,换成数组或字节后却出现异常?在调整模型、热词或 VAD 之前,先核对输入的格式、采样率、声道与数值范围。一个短小、只读的文件检查器,就能帮助你排除“空文件”“截断数据”和“把声道数算进时长”等基础问题。

+

例如,一个 16 kHz 双声道文件有 32000 个采样帧,时长是 2 秒,不是 4 秒。每帧含两个声道的采样值;把左右声道直接展平成单声道序列,会改变时间关系。另一个常见误区是把原本 8 kHz 的数据标记为 16 kHz:修改采样率标签没有生成新的采样点,不能代替重采样。

+

本文检查器仅面向本地、未压缩、16 位整数 PCM WAV,使用 Python 标准库,不加载 FunASR 或模型、不联网、不修改文件。它不是通用音频解码器,不支持 MP3、浮点 WAV 或任意裸 PCM,也不验证语音内容、识别准确率或生产服务。测试中的音频是人工构造的二进制样本,不是真实语音质量评测。

+

1. 先区分容器、字节与数组

+

WAV 是容器。文件包含格式信息与音频数据,不能把整个文件的字节都当作采样值。下面的示例使用 wave 解析容器,再读取数据帧。

+

裸 PCM 没有自描述的完整容器。处理前需要从数据来源确认采样率、声道数、位宽、符号和字节序。仅凭扩展名或字节长度不能可靠推断这些信息。不要把未知 PCM 强行加一个 WAV 头就认定修复完成。

+

数组有形状和数值范围。有符号 PCM16 的范围是 -32768 到 32767;转换成浮点 dtype 不等于缩放幅度。按 32768 归一化后,负端可到 -1,正端略小于 1。二维数组还需要明确哪一维是声道,不能只靠 reshape。具体支持方式应以所用版本的输入实现为准。

+

2. 运行只读的 PCM16 WAV 检查器

+

将下面代码作为独立的 inspect_wav.py 脚本运行,传入本地 WAV 路径。它逐块读取数据,报告采样帧数、时长和所有声道的绝对峰值,同时拒绝空数据、非 PCM16 和截断文件。

+
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 < 1 or rate < 1 or declared < 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("<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))
+
python inspect_wav.py /path/to/input.wav
+

duration_seconds 使用帧数除以采样率,不再除以或乘以声道数。peak_abs 是全部声道上的最大绝对采样值,不是响度、信噪比或语音概率。非空的全零文件会返回 0;这和没有任何数据帧的空文件不同。峰值达到 1 值得检查,但单个极值本身不能证明整段录音发生了削波。

+

3. 怎样使用检查结果

+
    +
  • 时长与播放器或采集记录不符时,先核对数据来源的真实采样率和声道布局,不要通过修改标签让数字“看起来正确”。
  • +
  • 文件被拒绝时,先检查导出或传输是否完整。对 MP3、24 位或浮点 WAV,使用明确支持该格式的解码工具,而不是删除验证条件。
  • +
  • 双声道需要转单声道时,按所用前端的声道策略处理;需要重采样时,使用真实的重采样器,并保留转换前后的文件与参数。
  • +
  • 峰值合理只说明幅度检查没有暴露这一类问题,不能证明录音中有可识别语音,也不能替代转录验收。
  • +
+

4. 版本与测试边界

+

#3899 的输入修复集成保留了原作者的提交,修复 NumPy PCM16 的缩放和二维浮点输入的声道处理。可核对固定提交的输入加载实现。截至本文发布,修复已合入 main;已验收的根包仍是 FunASR 1.4.26,不能据此宣称安装 1.4.26 已包含这次 main 修复。本文检查器不依赖该修复,也不会修改你的安装。

+

随文测试直接执行中英文正文及构建页面里的同一段代码,覆盖单/双声道、8/16 kHz、PCM16 正负边界、非空静音、空文件、8 位输入、截断采样、截断整帧、非 WAV、跨读取块的末尾峰值和命令行入口。它检查已覆盖的输入契约,不是任意损坏文件的安全审计,也不涵盖所有 WAV 编码扩展。

+

文件检查之后,再用有权处理的真实录音检查文字、时间戳、漏句和说话人结果。分享问题时附上脱敏的格式信息、版本与最小复现,避免公开私有音频、转录或绝对路径。

+

下一步使用会议转录验收清单,把输入检查与实际转录结果对应起来。

+
+
FunASR · 通义实验室开源语音识别 · GitHub
+ + diff --git a/web-pages/product-site/legacy/en/blog/wav-pcm-input-checklist.html b/web-pages/product-site/legacy/en/blog/wav-pcm-input-checklist.html new file mode 100644 index 000000000..fe9cea55d --- /dev/null +++ b/web-pages/product-site/legacy/en/blog/wav-pcm-input-checklist.html @@ -0,0 +1,118 @@ + + + +Check the audio input first: WAV, raw PCM and sample rate | FunASR + + + + + + + +

Check the audio input first: WAV, raw PCM and sample rate

+ +

Does a recording work as a file path but behave differently after conversion to an array or bytes? Before changing the model, hotwords or VAD, check the input format, sample rate, channels and numeric range. A small read-only inspector can expose empty files, truncated payloads and incorrect duration calculations without loading a model.

+

A stereo file with 32000 sample frames at 16 kHz lasts two seconds, not four. Each frame contains one sample per channel. Flattening the two channels into a mono sequence changes their temporal relationship. Similarly, labelling 8 kHz samples as 16 kHz does not generate new samples and is not resampling.

+

This inspector supports local, uncompressed, signed 16-bit PCM WAV only. It uses the Python standard library, makes no network requests, loads no FunASR package or model, and leaves files unchanged. It is not a general audio decoder and does not support MP3, floating-point WAV or arbitrary raw PCM. The binary test fixtures verify input handling, not speech recognition quality or a production service.

+

1. Separate containers, bytes and arrays

+

WAV is a container. Its bytes include format information as well as audio. Treating the complete file as samples also treats header bytes as sound. The example uses wave to parse the container before reading audio frames.

+

Raw PCM needs external format information. Confirm the sample rate, channel count, bit depth, signedness and byte order at the source. A filename extension or byte count cannot reliably establish those properties. Adding a guessed WAV header does not prove that the input has been repaired.

+

Arrays have both shape and amplitude conventions. Signed PCM16 spans -32768 through 32767. Changing its dtype to floating point does not scale the amplitude. Division by 32768 maps the negative endpoint to -1 and the positive endpoint to slightly less than 1. For two-dimensional arrays, identify the channel axis rather than simply reshaping. Check the input implementation in the package version you actually use.

+

2. Run a read-only PCM16 WAV inspector

+

Run the following as a separate inspect_wav.py script with a local WAV path. It reads in bounded chunks, reports frames, duration and the absolute peak across channels, and rejects empty audio, non-PCM16 input and truncated data.

+
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 < 1 or rate < 1 or declared < 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("<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))
+
python inspect_wav.py /path/to/input.wav
+

duration_seconds is frames divided by sample rate; channel count is not another multiplier or divisor. peak_abs is the maximum absolute sample value across all channels, not loudness, signal-to-noise ratio or speech probability. A nonempty all-zero file reports zero, whereas a file with no data frames is rejected. A peak of 1 deserves inspection but one extreme sample does not establish clipping throughout a recording.

+

3. Act on the result without hiding the problem

+
    +
  • If the duration differs from your player or capture record, verify the original sample rate and channel layout. Do not change metadata just to make the number look right.
  • +
  • If a file is rejected, check export and transfer completeness. For MP3, 24-bit or floating-point WAV, use a decoder that explicitly supports the format instead of removing these validation checks.
  • +
  • For stereo-to-mono conversion, follow the frontend's channel policy. If resampling is needed, use an actual resampler and retain both the original and converted files with the conversion parameters.
  • +
  • A plausible peak only means this amplitude check found no obvious problem. It does not prove the presence of intelligible speech or replace transcript acceptance.
  • +
+

4. Know the version and verification boundary

+

Input-fix integration #3899 preserves its contributors' history and addresses NumPy PCM16 scaling and channel handling for two-dimensional floating-point input. Inspect the loader at the pinned source commit. At publication, these changes are merged into main; the accepted root package is still FunASR 1.4.26. Installing 1.4.26 must not be described as installing this newer main fix. This inspector does not depend on that fix or change your installation.

+

The article tests execute the actual code from both language sources and their built pages. Cases cover mono and stereo, 8 and 16 kHz, positive and negative PCM16 endpoints, nonempty silence, empty input, 8-bit input, truncated samples and whole frames, non-WAV input, a peak beyond the first chunk, and the command-line entry point. This is a bounded input-contract test, not a security audit of arbitrary damaged files or coverage of every WAV encoding extension.

+

After checking the file, evaluate text, timestamps, omitted speech and speaker results on recordings you are authorized to process. For an issue report, provide redacted format information, versions and a shareable minimal reproduction. Do not expose private audio, transcripts or absolute paths.

+

Continue with the meeting-transcript acceptance checklist to connect input checks with actual transcription results.

+
+ + + diff --git a/web-pages/product-site/tests/test_wav_input_article.py b/web-pages/product-site/tests/test_wav_input_article.py new file mode 100644 index 000000000..6de2fb8fe --- /dev/null +++ b/web-pages/product-site/tests/test_wav_input_article.py @@ -0,0 +1,109 @@ +"""Execute the published WAV inspector on real, hand-checked binary fixtures.""" +import contextlib +import io +import json +from pathlib import Path +import struct +import sys +import wave + +from bs4 import BeautifulSoup +import pytest + +SITE=Path(__file__).resolve().parents[1] +sys.path.insert(0,str(SITE)) +from build import build + +SLUG='wav-pcm-input-checklist' +SOURCE='https://github.com/modelscope/FunASR/blob/173cbee304836dae94079c8f600272f3637451a4/funasr/utils/load_utils.py' + +def test_catalogue_discovers_input_article_once(): + data=json.loads((SITE/'data/blog.json').read_text()) + rows=[row for row in data['articles'] if row['slug']==SLUG] + assert len(rows)==1 + assert rows[0]['reviewed'] and rows[0]['category']=='explanations' + assert SLUG not in data['selected'] + +@pytest.fixture(scope='module',params=['source','built']) +def tree(request,tmp_path_factory): + if request.param=='source':return SITE/'legacy' + dest=tmp_path_factory.mktemp('wav-inspector-article') + build(dest) + return dest + +@pytest.fixture(params=['','en/']) +def article(request,tree): + prefix=request.param + return prefix,BeautifulSoup((tree/prefix/'blog'/(SLUG+'.html')).read_text(),'html.parser') + +@pytest.fixture +def inspector(article): + _,soup=article + namespace={'__name__':'article_example'} + exec(compile(soup.select_one('code[data-language="python"]').get_text(),'article-wav-inspector','exec'),namespace) + return namespace['inspect_pcm16_wav'] + +def write_wav(path,samples,channels=1,rate=16000,width=2): + with wave.open(str(path),'wb') as out: + out.setnchannels(channels);out.setsampwidth(width);out.setframerate(rate) + raw=bytes(samples) if width==1 else struct.pack('<'+'h'*len(samples),*samples) + out.writeframes(raw) + +def test_metadata_and_source_links(article): + prefix,soup=article + meta=json.loads(soup.select_one('script[type="application/ld+json"]').get_text()) + assert meta['datePublished']==meta['dateModified']=='2026-11-15' + assert meta['headline']==soup.select_one('article h1').get_text() + assert soup.select_one('link[rel="canonical"]')['href']==f'https://www.funasr.com/{prefix}blog/{SLUG}.html' + links={a['href'] for a in soup.select('article a[href]')} + assert SOURCE in links and 'https://github.com/modelscope/FunASR/pull/3899' in links + assert 'https://github.com/modelscope/FunASR/releases/tag/v1.4.26' in links + assert soup.select_one('[data-editorial="boundary"]') + assert len(soup.select('[data-editorial="next-step"] a'))==1 + +@pytest.mark.parametrize('samples,channels,rate,frames,duration,peak',[ + ([-32768,-16384,0,32767],1,8000,4,0.0005,1.0), + ([32767,0,0,0],1,16000,4,0.00025,0.999969482421875), + ([-16384,16384,0,8192],2,16000,2,0.000125,0.5), + ([0,0,0,0],2,8000,2,0.00025,0.0), +]) +def test_real_wav_reports_frames_not_scalar_samples(inspector,tmp_path,samples,channels,rate,frames,duration,peak): + path=tmp_path/'audio.wav';write_wav(path,samples,channels,rate) + before=path.read_bytes() + assert inspector(path)==dict(channels=channels,sample_rate=rate,frames=frames,duration_seconds=duration,peak_abs=peak) + assert path.read_bytes()==before + +@pytest.mark.parametrize('problem',['empty','8bit','truncated-sample','truncated-frame','not-wav']) +def test_invalid_or_unsupported_input_is_not_accepted(inspector,tmp_path,problem): + path=tmp_path/'bad.wav' + if problem=='empty':write_wav(path,[]) + elif problem=='8bit':write_wav(path,[0,128,255],width=1) + elif problem=='not-wav':path.write_bytes(b'not an audio container') + else: + write_wav(path,[1,2,3,4],channels=2) + path.write_bytes(path.read_bytes()[:(-1 if problem=='truncated-sample' else -4)]) + before=path.read_bytes() + with pytest.raises((ValueError,wave.Error,EOFError)): + inspector(path) + assert path.read_bytes()==before + +def test_inspector_reads_past_first_chunk(inspector,tmp_path): + path=tmp_path/'long.wav' + write_wav(path,[0]*40000+[-32768],rate=16000) + assert inspector(path)==dict(channels=1,sample_rate=16000,frames=40001,duration_seconds=2.5000625,peak_abs=1.0) + +def test_cli_example_executes(article,tmp_path,monkeypatch): + _,soup=article + path=tmp_path/'input.wav';write_wav(path,[0,16384],rate=8000) + monkeypatch.setattr(sys,'argv',['inspect_wav.py',str(path)]) + with contextlib.redirect_stdout(io.StringIO()) as out: + exec(compile(soup.select_one('code[data-language="python"]').get_text(),'article-wav-cli','exec'),{'__name__':'__main__'}) + assert json.loads(out.getvalue())==dict(channels=1,sample_rate=8000,frames=2,duration_seconds=0.00025,peak_abs=0.5) + +@pytest.mark.parametrize('prefix',['','en/']) +def test_archive_and_category_link_to_article(prefix,tmp_path): + build(tmp_path) + for category in ['archive','explanations']: + soup=BeautifulSoup((tmp_path/prefix/'blog'/category/'index.html').read_text(),'html.parser') + cards=soup.select(f'a[href="/{prefix}blog/{SLUG}.html"]') + assert len(cards)==1 and cards[0].select_one('time[datetime="2026-11-15"]')