Feat/hzjh-AudioOps

[starlight6336]

Audio Operators Final Overview

本文档说明最终版本新增并保留的音频算子。仅描述算子职责、预期输入输出、模型调用和运行依赖边界；不包含测试步骤，也不解释中间曾加入后删除的实现。

通用约定

• 算子均为 DataMate Mapper 算子，运行时处理单个输入样本并返回单个输出样本。
• 音频处理类算子优先读取上游写入的 sample["data"] 音频字节；没有上游字节时读取 sample["filePath"]。
• 标注类算子会把标签或结构化结果写入 sample["ext_params"]，同时尽量保留当前音频，便于后续算子继续处理。
• 文本类算子写入 sample["text"]，通常导出为 .txt。
• 第三方依赖由 DataMate 运行环境提供，不在算子目录内自带 local_libs、bin、lib、site-packages。
• 模型权重作为外部模型资产部署在 /models/AudioOperations/...，不作为 Python 包打包进算子。

音频转文本链路相关算子

AudioFormatConvert

• 注册名：AudioFormatConvert
• 作用：音频格式转换、重采样、声道转换。
• 预期输入：音频文件路径或上游 sample["data"] 音频字节。
• 预期输出：转换后的音频字节写入 sample["data"]，目标格式写入 sample["target_type"]，用于后续 LID/ASR。
• 主要参数：targetFormat、sampleRate、channels。
• 模型调用：不调用模型。
• 运行依赖：pydub==0.25.1、soundfile==0.12.1、numpy==2.2.6；系统 ffmpeg 由 DataMate 环境提供。

AudioGtcrnDenoise

• 注册名：AudioGtcrnDenoise
• 作用：使用 GTCRN 对语音音频做降噪，输出仍为音频。
• 预期输入：音频文件路径或上游 sample["data"] 音频字节。
• 预期输出：降噪后的 wav 音频字节写入 sample["data"]，sample["target_type"] 为 wav。
• 主要参数：modelPath、device、sampleRate 等降噪相关配置。
• 模型调用：调用 GTCRN ONNX 模型，默认模型路径 /models/AudioOperations/gtcrn/gtcrn.onnx。
• 运行依赖：onnxruntime==1.19.2、soundfile==0.12.1、numpy==2.2.6、scipy==1.13.1。

AudioAnomalyFilter

• 注册名：AudioAnomalyFilter
• 作用：检测音频是否异常，包括不可读、时长过短/过长、静音比例过高等。
• 预期输入：音频文件路径或上游 sample["data"] 音频字节。
• 预期输出：不删除音频；将质量结果写入 sample["ext_params"]["audio_quality"]。后续音频算子可根据 quality_flag 和 skip_downstream 决定是否软跳过。
• 主要参数：minDur、maxDur、silenceRatioTh、silenceRmsRatioTh、skipInvalidDownstream。
• 模型调用：不调用模型。
• 运行依赖：优先使用 torchaudio==2.8.0，兜底使用 soundfile==0.12.1。

AudioFastLangId

• 注册名：AudioFastLangId
• 作用：识别语音音频语言，输出 zh 或 en，用于 ASR 自动选模型。
• 预期输入：语音音频文件路径或上游 sample["data"] 音频字节。
• 预期输出：保留当前音频；语言结果写入 sample["ext_params"]["audio_lid"]["lang"]，并可在文件名追加 __lid_zh 或 __lid_en。
• 主要参数：modelSource、modelSavedir、device、batchSize、maxSeconds。
• 模型调用：调用 SpeechBrain LID 模型，默认模型路径 /models/AudioOperations/lid/speechbrain_lang-id-voxlingua107-ecapa。
• 运行依赖：torch==2.8.0、torchaudio==2.8.0、speechbrain==1.0.3、HyperPyYAML==1.2.2。

AudioFastLangIdText

• 注册名：AudioFastLangIdText
• 作用：识别语音音频语言，并将语言标签作为文本结果输出。
• 预期输入：语音音频文件路径。
• 预期输出：sample["text"] 为 zh 或 en，最终导出 .txt；同时写入 sample["ext_params"]["audio_lid"]["lang"]。
• 主要参数：modelSource、modelSavedir、device、batchSize、maxSeconds。
• 模型调用：调用 SpeechBrain LID 模型，默认模型路径 /models/AudioOperations/lid/speechbrain_lang-id-voxlingua107-ecapa。
• 运行依赖：torch==2.8.0、torchaudio==2.8.0、speechbrain==1.0.3、HyperPyYAML==1.2.2。

AudioAsrTranscribe

• 注册名：AudioAsrTranscribe
• 作用：将单个语音音频转写为文本。
• 预期输入：语音音频文件路径或上游 sample["data"] 音频字节；可读取上游 audio_lid.lang 选择中文或英文 ASR 模型。
• 预期输出：转写文本写入 sample["text"]，最终导出当前输入对应的 .txt；运行信息写入 sample["ext_params"]["audio_asr_transcribe"]。
• 主要参数：language、zhModelDir、enModelDir、device、mode、batchSize、maxSegmentSeconds、referenceTextPath、keepArtifacts。
• 模型调用：调用 WeNet ASR。中文默认模型目录 /models/AudioOperations/asr/aishell，英文默认模型目录 /models/AudioOperations/asr/librispeech。
• 运行依赖：torch==2.8.0、torchaudio==2.8.0、numpy==2.2.6、PyYAML==6.0.2、sentencepiece==0.2.1、loguru==0.7.3；wenet.bin.recognize 必须由 DataMate 运行环境提供。

AudioAsrPipeline

• 注册名：AudioAsrPipeline
• 作用：封装完整语音转文本链路：格式标准化、可选 GTCRN 降噪、可选异常检测、语言识别、长音频切分、WeNet ASR、文本合并。
• 预期输入：语音音频文件路径。
• 预期输出：最终 ASR 文本写入 sample["text"] 并导出 .txt；中间产物路径、语言、模型、可选报告写入 sample["ext_params"]["audio_asr"]。
• 主要参数：doDenoise、denoiseModelPath、doAnomalyFilter、minDur、maxDur、silenceRatioTh、lidModelSource、lidDevice、lidMaxSeconds、maxSegmentSeconds、asrDevice、referencePath。
• 模型调用：可调用 GTCRN ONNX、SpeechBrain LID、WeNet ASR。
• 运行依赖：按启用功能使用 pydub、soundfile、numpy、onnxruntime、torch、torchaudio、speechbrain、wenet、系统 ffmpeg。

情感识别、概括、分类算子

AudioEmotionRecognize

• 注册名：AudioEmotionRecognize
• 作用：识别语音情感类别。
• 预期输入：语音音频文件路径或上游 sample["data"] 音频字节。
• 预期输出：保留当前音频；情感标签、置信度、模型信息写入 sample["ext_params"]["audio_emotion"]，可在最终文件名追加情感标记。
• 主要参数：模型路径、设备、top-k 或阈值类配置。
• 模型调用：调用本地语音情感识别模型，模型资产部署在 /models/AudioOperations/...。
• 运行依赖：torch==2.8.0、torchaudio==2.8.0、numpy==2.2.6 等运行环境包。

AudioTextSummarize

• 注册名：AudioTextSummarize
• 作用：对 ASR 后文本做摘要概括。
• 预期输入：优先读取 sample["text"]；为空时可读取 txt/md/json/jsonl 文本文件。
• 预期输出：摘要文本写回 sample["text"]；运行细节写入 sample["ext_params"]["audio_text_summarize"]。
• 主要参数：method、maxSummaryCharsZh、maxSummaryWordsEn、minSummaryWordsEn、lineMode、preserveKeys、onnxModelDir、cpuThreads。
• 模型调用：默认使用轻量抽取式摘要；可选 bert_onnx，读取 /models/AudioOperations/summary/summary-model 下的 ONNX 模型和 tokenizer。
• 运行依赖：numpy==2.2.6、jieba==0.42.1；ONNX 模式需要 onnxruntime==1.19.2、transformers==4.57.6。

AudioSoundClassify

• 注册名：AudioSoundClassify
• 作用：对音频做场景/声音事件分类，输出业务大类和 AudioSet 细类 top-k。
• 预期输入：音频文件路径或上游 sample["data"] 音频字节。
• 预期输出：保留当前音频；分类结果写入 sample["ext_params"]["audio_sound_classify"]，可在最终文件名追加 __sound_<macro_class>。
• 主要参数：backend、astCheckpoint、pannsCheckpoint、astMacroMap、macroMap、device、topK、humanSpeechThreshold、segmentSeconds、hopSeconds。
• 模型调用：默认调用 AST AudioSet 模型 /models/AudioOperations/recog/audioset_10_10_0.4593.pth；兼容 PANNs 模型 /models/AudioOperations/panns/Cnn14_16k_mAP=0.438.pth。
• 运行依赖：torch==2.8.0、torchlibrosa==0.0.4、timm==1.0.26、librosa==0.10.2.post1、numpy==2.2.6、soundfile==0.12.1、scipy==1.13.1、panns-inference==0.1.1。

其他行业单功能音频算子

AudioDcOffsetRemoval

• 注册名：AudioDcOffsetRemoval
• 作用：去除音频直流偏移。
• 预期输入：音频文件路径或上游 sample["data"] 音频字节。
• 预期输出：处理后的 wav 音频字节写入 sample["data"]，sample["target_type"] 为 wav。
• 主要参数：直流偏移处理相关开关或强度参数。
• 模型调用：不调用模型。
• 运行依赖：soundfile==0.12.1、numpy==2.2.6。

AudioHumNotch

• 注册名：AudioHumNotch
• 作用：对工频嗡声做陷波处理。
• 预期输入：音频文件路径或上游 sample["data"] 音频字节。
• 预期输出：处理后的 wav 音频字节写入 sample["data"]。
• 主要参数：freqHz、quality、harmonics 等陷波配置。
• 模型调用：不调用模型。
• 运行依赖：soundfile==0.12.1、numpy==2.2.6、scipy==1.13.1。

AudioNoiseGate

• 注册名：AudioNoiseGate
• 作用：根据能量阈值抑制低电平噪声。
• 预期输入：音频文件路径或上游 sample["data"] 音频字节。
• 预期输出：处理后的 wav 音频字节写入 sample["data"]。
• 主要参数：阈值、攻击/释放时间、衰减比例等门限配置。
• 模型调用：不调用模型。
• 运行依赖：soundfile==0.12.1、numpy==2.2.6。

AudioPreEmphasis

• 注册名：AudioPreEmphasis
• 作用：对音频做预加重，增强高频成分。
• 预期输入：音频文件路径或上游 sample["data"] 音频字节。
• 预期输出：处理后的 wav 音频字节写入 sample["data"]。
• 主要参数：预加重系数。
• 模型调用：不调用模型。
• 运行依赖：soundfile==0.12.1、numpy==2.2.6。

AudioQuantizeEncode

• 注册名：AudioQuantizeEncode
• 作用：对音频做量化/编码格式约束，例如控制位深或 PCM 编码形态。
• 预期输入：音频文件路径或上游 sample["data"] 音频字节。
• 预期输出：重新编码后的音频字节写入 sample["data"]。
• 主要参数：量化位深、目标编码格式等。
• 模型调用：不调用模型。
• 运行依赖：soundfile==0.12.1、numpy==2.2.6。

AudioRmsLoudnessNormalize

• 注册名：AudioRmsLoudnessNormalize
• 作用：按目标 RMS 对音频响度做归一化。
• 预期输入：音频文件路径或上游 sample["data"] 音频字节。
• 预期输出：响度归一化后的 wav 音频字节写入 sample["data"]。
• 主要参数：目标 RMS、最大增益、削波保护等。
• 模型调用：不调用模型。
• 运行依赖：soundfile==0.12.1、numpy==2.2.6。

AudioSimpleAgc

• 注册名：AudioSimpleAgc
• 作用：自动增益控制，使音频电平接近目标范围。
• 预期输入：音频文件路径或上游 sample["data"] 音频字节。
• 预期输出：AGC 处理后的 wav 音频字节写入 sample["data"]。
• 主要参数：目标电平、最大增益、平滑窗口等。
• 模型调用：不调用模型。
• 运行依赖：soundfile==0.12.1、numpy==2.2.6。

AudioSoftPeakLimiter

• 注册名：AudioSoftPeakLimiter
• 作用：软限幅，控制峰值并降低硬削波风险。
• 预期输入：音频文件路径或上游 sample["data"] 音频字节。
• 预期输出：限幅后的 wav 音频字节写入 sample["data"]。
• 主要参数：峰值阈值、软限幅强度等。
• 模型调用：不调用模型。
• 运行依赖：soundfile==0.12.1、numpy==2.2.6。

AudioTelephonyBandpass

• 注册名：AudioTelephonyBandpass
• 作用：电话语音带通滤波，保留常见电话频段。
• 预期输入：音频文件路径或上游 sample["data"] 音频字节。
• 预期输出：带通滤波后的 wav 音频字节写入 sample["data"]。
• 主要参数：lowHz、highHz、order，默认约为 300-3400 Hz。
• 模型调用：不调用模型。
• 运行依赖：soundfile==0.12.1、numpy==2.2.6、scipy==1.13.1。

AudioTrimSilenceEdges

• 注册名：AudioTrimSilenceEdges
• 作用：裁剪音频首尾静音。
• 预期输入：音频文件路径或上游 sample["data"] 音频字节。
• 预期输出：裁剪后的 wav 音频字节写入 sample["data"]。
• 主要参数：frameMs、hopMs、threshDb、padMs。
• 模型调用：不调用模型。
• 运行依赖：soundfile==0.12.1、numpy==2.2.6。