audioport

audioport

audioport 可在本地文件上完成日常音频处理。它会读取 ffprobe 报告的文件信息——格式、时长、比特率、采样率和声道数——在常见音频格式之间转换，从文件中截取从指定秒数开始的片段，并使用 ffmpeg 的 loudnorm 滤镜标准化响度。第五个工具可进行转录，但只能通过你自行配置的转录引擎；audioport 不捆绑任何引擎，也不会编造转录文本。

所有处理都通过本机上的 ffmpeg 和 ffprobe 二进制文件运行，并以参数数组调用（绝不使用 shell），因此必须安装这些二进制文件，处理工具才能正常工作。如果缺少这些二进制文件，则会返回其自身的错误，而不是伪造结果。

转录

转录由 AUDIOPORT_TRANSCRIBER_COMMAND 环境变量指定的本地命令执行。运行该命令时，音频文件路径会作为最后一个参数传入，其标准输出即为转录文本。例如：

export AUDIOPORT_TRANSCRIBER_COMMAND="whisper-cli --model base"

未设置该变量时，transcribe 和 transcribe_audio 工具会失败，并显示包含 AUDIOPORT_TRANSCRIBER_COMMAND 的错误。这里没有 API 密钥，没有托管服务，也没有猜测语音内容的备用方案。

安装

npx @reneturcios/audioport metadata song.mp3

或者运行容器镜像：

docker run -i ghcr.io/cloudcorprecords/audioport

容器默认启动 MCP 服务（见下文），且不捆绑 ffmpeg/ffprobe；要使用处理工具，请在主机上安装它们，或使用安装了 ffmpeg 的派生镜像。传入 CLI 参数即可将其用作 CLI。

CLI

audioport metadata song.mp3
audioport convert song.wav song-out.mp3 mp3 --bitrate 192k
audioport trim song.mp3 clip.mp3 5 --duration 10
audioport normalize song.wav song-normalized.wav
audioport transcribe song.mp3 --language en

audioport --version

convert 命令会将输出路径的扩展名替换为目标格式（如果两者不同）；将 song-out.ogg 转换为 mp3 时，会写入 song-out.mp3。支持的格式：mp3、wav、ogg、flac、aac、m4a。

每条命令都会以 JSON 格式打印结果。退出码：成功时为 0，处理失败时为 1（包括缺少转录引擎的情况），用法错误时为 2。

MCP 服务

同一个二进制文件支持两种用途。mcp 子命令会启动一个 stdio MCP 服务：

npx -y @reneturcios/audioport mcp

MCP 客户端配置：

{
  "mcpServers": {
    "audioport": {
      "command": "npx",
      "args": ["-y", "@reneturcios/audioport", "mcp"],
      "env": { "AUDIOPORT_TRANSCRIBER_COMMAND": "whisper-cli --model base" }
    }
  }
}

工具

工具	输入	返回内容
get_audio_metadata	input（必填）	格式、秒数形式的时长、比特率、采样率和声道数；ffprobe 未提供的字段为 null。
convert_audio	input、output、format（必填），bitrate（可选）	实际输出路径（扩展名与格式一致）、格式和比特率。
trim_audio	input、output、start（必填），duration（可选）	输出路径、起始秒数和时长。
normalize_audio	input、output（必填）	经过 loudnorm 处理后的输入和输出路径。
transcribe_audio	input（必填），language（可选）	配置的引擎生成的转录文本；如果未配置引擎，则返回包含 AUDIOPORT_TRANSCRIBER_COMMAND 的错误。

开发

npm install
npm run build   # tsc -> dist/
npm test        # node test runner over test/*.test.ts, fake executors only
npm run dev     # run the CLI from source via tsx

许可证

MIT — 参见 LICENSE。