Luis-audio-translator 技能

概述

使用该技能通过 scripts/luis_audio_translator.py 执行本地音频处理。该技能具备可移植性：不包含个人路径、API 密钥、机器标识符，也不捆绑任何专有二进制文件。

核心脚本在下载后即可运行，前提是系统已安装 Python 且 FFmpeg 已加入 PATH。喜马拉雅（Ximalaya）.xm 格式解码功能内置于脚本中，完全基于 Python 实现。其他加密或缓存格式可能需要额外的本地辅助二进制工具。

适用场景

• 转换音频格式，包括从视频中提取音频。
• 按比特率压缩音频。
• 按顺序合并多个音频文件。
• 将单个文件切分为等时长片段。
• 从音频/视频文件中截取指定时间范围的内容。
• 检查音频/视频文件的时长、编解码器、比特率、采样率及音频流信息。
• 当用户已配置本地辅助工具时，解码受支持的本地音乐缓存输入文件。
• 使用 scripts/kugou_audio_converter.py 转换酷狗（Kugou）特殊格式。

前置依赖

• Python 3.8 或更高版本。
• FFmpeg：用于格式转换、合并、切分、截取以及视频转音频。
• FFprobe：用于 info 命令及支持时长感知的 split 操作。

路径解析顺序如下：

1. 命令行选项：--app-dir 。
2. 环境变量：
   • LUIS_AUDIO_TRANSLATOR_ENGINE_DIR
   • LUIS_AUDIO_TRANSLATOR_FFMPEG
   • LUIS_AUDIO_TRANSLATOR_FFPROBE
   • LUIS_AUDIO_TRANSLATOR_UM
   • LUIS_AUDIO_TRANSLATOR_MUSIC_TOOL
   • LUIS_AUDIO_TRANSLATOR_SILK
   • LUIS_AUDIO_TRANSLATOR_KGG_HELPER
   • LUIS_AUDIO_TRANSLATOR_KUGOU_INFRA_DLL
   • LUIS_AUDIO_TRANSLATOR_KUGOU_DB
3. 系统 PATH 中的 ffmpeg 和 ffprobe 可执行文件。

请勿在 SKILL.md 中写入用户特定路径。若某台机器需指定本地引擎目录，请在技能外部设置相应环境变量。

运行方式

所有路径均相对于本 SKILL.md 文件所在目录进行解析。

检查依赖状态：

python scripts/luis_audio_translator.py diagnose

转换或提取音频：

python scripts/luis_audio_translator.py convert "input.mp4" --format mp3 --bitrate 192k --output-dir "out"

压缩音频：

python scripts/luis_audio_translator.py compress "input.wav" --format mp3 --bitrate 96k --output-dir "out"

合并音频：

python scripts/luis_audio_translator.py merge "a.mp3" "b.wav" --format mp3 --output-dir "out" --basename "merged"

切分音频：

python scripts/luis_audio_translator.py split "input.mp3" --segment-seconds 300 --format mp3 --output-dir "out"

截取音频片段：

python scripts/luis_audio_translator.py clip "input.mp3" --start 00:01:20 --duration 45 --format wav --output-dir "out"

检查媒体信息：

python scripts/luis_audio_translator.py info "input.flac"

解码本地缓存输入文件：

python scripts/luis_audio_translator.py decrypt "input.ncm" --output-dir "out"

解码喜马拉雅（Ximalaya）.xm 输入文件：

python scripts/luis_audio_translator.py decrypt "input.xm" --output-dir "out"

转换酷狗（Kugou）特殊格式：

python scripts/kugou_audio_converter.py diagnose --app-dir ""
python scripts/kugou_audio_converter.py convert "KugouMusic" --format mp3 --output-dir "out" --recursive --app-dir ""

快速参考

常用输出格式：mp3、wav、ogg、flac、m4a、m4r、mp2、aiff、ac3、wma、amr、aac、opus、caf、au、mka、webm。

由 kugou_audio_converter.py 处理的酷狗（Kugou）特殊输入格式：.kgm、.kgma、.kgtemp、.kgm.flac、.kgg。

由 luis_audio_translator.py decrypt 处理的喜马拉雅（Ximalaya）输入格式：.xm。

特殊输出格式处理规则：

• amr 强制使用 8000 Hz 单声道。
• flac 使用有符号 16 位采样格式。
• m4r 使用 MP4 容器封装。

有关支持的输入扩展名列表及可选解密辅助行为，请参阅 references/core-behavior.md。

隐私性与可移植性

• 该技能不嵌入本地用户名、绝对安装路径、凭据或机器 ID。
• 脚本不会通过网络发送任何文件或元数据。
• JSON 输出中可能包含输入/输出路径，因为 Agent 需要这些路径以继续后续工作流。
• --print-command 会打印完整本地路径，仅限调试用途。

常见陷阱

• 若 diagnose 报告未找到 FFmpeg，请安装 FFmpeg 或设置 LUIS_AUDIO_TRANSLATOR_FFMPEG 环境变量。
• 若 split 失败但 convert 正常，说明缺少 FFprobe，请安装 FFprobe 或设置 LUIS_AUDIO_TRANSLATOR_FFPROBE 环境变量。
• 除 .xm 外的其他解密辅助工具均为可选组件，且依赖具体环境；常规格式转换和 .xm 解码不应依赖它们。
• .kgg 格式转换需要 kgg-helper 及兼容的本地酷狗（Kugou）infra.dll；如存在 KGMusicV3.db，则会一并使用。请先运行酷狗转换器的 diagnose 命令确认环境就绪。
• .xm 解码完全基于纯 Python 实现，无需 Node.js、WebAssembly 或外部辅助工具。
• OpenClaw、Hermes、Claude 和 Codex 应通过相对于 SKILL.md 的路径解析 scripts/luis_audio_translator.py 来调用该脚本，而非使用机器特定的绝对路径。

验证方法

• 运行 python scripts/luis_audio_translator.py diagnose。
• 运行 python -m py_compile scripts/luis_audio_translator.py scripts/kugou_audio_converter.py scripts/xm_audio_decoder.py。
• 运行 python scripts/xm_audio_decoder.py --self-test。
• 生成或提供一个简短测试音视频文件，并依次运行 info、convert、merge 和 split 命令进行验证。