protoss-voice

核心用法

Protoss Voice 是一个音频后处理技能，而非 TTS 生成器。它通过调用 ffmpeg 和 sox 工具链，将任意输入音频（WAV/MP3/OGG 等）转换为具有"神族灵能"风格的特效音频。典型工作流为：先用 Kokoro 等 TTS 技能生成基础语音，再经本技能处理，最终输出带 _psionic.wav 后缀的文件。

处理链路包含四个阶段：格式统一转换（ffmpeg）、核心特效处理（sox 实现音高下移-200、反向混响、音量调整）、母带处理（低频增强+5dB、100Hz高通、-1dB 归一化）、最终编码输出。用户也可直接处理真人录音，实现 Zeratul、Artanis 等角色的声线模拟。

显著优点

1. 模块化设计：与 TTS 解耦，可叠加于任意语音源，灵活性极高
2. 零网络依赖：纯本地处理，无 API 调用成本与隐私泄露风险
3. 专业级音频链：基于成熟的 ffmpeg/sox 生态，效果稳定可预期
4. 自动化集成：支持 Agent 工作流自动串联，从生成到发送全程无人值守

潜在缺点与局限性

• 依赖外部二进制：需用户预装 ffmpeg 和 sox，跨平台部署存在环境差异
• 无输入校验：当前版本未对文件路径做严格过滤，存在命令注入理论风险
• 特效单一：仅提供固定"V9 Massive Void"预设，不支持参数微调或自定义效果链
• 输出格式受限：默认输出 WAV，需额外调用 ffmpeg 转码为 OGG 等适合即时通讯的格式

适合的目标群体

• 游戏内容创作者（星际争霸同人配音、角色扮演视频）
• AI 角色扮演应用开发者（需构建特定种族/阵营声线）
• 播客与有声书制作（科幻题材的声音设计）
• 语音聊天机器人增强（Discord/Telegram 等平台的趣味交互）

使用风险

• 供应链风险：ffmpeg/sox 若从非官方渠道安装，可能引入恶意二进制
• 路径注入：恶意构造的输入文件名可能触发 shell 元字符解析
• 临时文件残留：虽已实现 finally 块清理，但异常中断时仍可能遗留隐藏文件
• 性能瓶颈：长音频的 sox 混响处理计算密集，大文件可能出现显著延迟

核心用法

Protoss Voice是一款音频后期处理工具，专用于将普通语音（TTS生成或真人录音）转化为《星际争霸》神族风格的"灵能音效"。其核心工作流为三段式处理：

1. 输入：接收任意格式音频（WAV/MP3/OGG等），通过sys.argv[1]传入文件路径
2. 黑盒处理：调用FFmpeg进行格式标准化，使用SoX应用多阶段音效链（包含低通滤波、混响、音高偏移等"V9 Massive Void"引擎效果）
3. 输出：生成带_psionic.wav后缀的处理文件

典型集成场景：

• 与Kokoro-TTS等语音合成工具联动，先生成基础语音再施加神族滤镜
• 作为Discord/Telegram机器人的语音消息后处理器
• 游戏Mod或角色扮演内容的音频素材制作

显著优点

• 零网络依赖：纯本地运算，无外联API，隐私敏感场景友好
• 模块化设计：不绑定特定TTS引擎，可接入任意语音源
• 专业级音效：基于成熟的FFmpeg+SoX工具链，效果稳定可控
• 开源透明：MIT协议，代码仅138行Python，易于审计和定制

潜在局限

• 系统依赖门槛：需预装FFmpeg和SoX（macOS通过brew install解决，Linux/Windows需手动配置）
• 仅支持单声道处理：输出固定为WAV格式，需额外转码（如示例中的Opus）才能优化传输
• 音效风格固定：V9引擎参数硬编码，缺乏实时调节接口（需修改源码调整"灵能浓度"）

适合人群

• 星际争霸同人创作者、游戏视频UP主
• 需要为AI角色赋予特定声纹的开发者
• 追求"非人感"机械/外星语音效果的内容创作者

常规风险

• 命令注入（中等风险）：输入文件路径直接拼接入subprocess调用，若路径含shell特殊字符可能被恶意利用。安全报告建议用shlex.quote()加固
• 资源耗尽：无输入文件大小限制，超大音频可能导致CPU/内存过载
• 临时文件残留：虽然代码含finally清理块，但极端异常情况下可能遗留中间文件

安全评级A（85分）属于可控风险级别，建议在容器化或受限环境中运行，避免处理不可信来源的文件路径。