1.基于FFMPEG实现音频转码
audio-plugin 最早的需求背景非常典型:微信语音是 amr 格式,html5 页面的 audio 标签直接播放不了,必须先转成 mp3;而 Java 自身很难搞定 amr 的编解码,所以插件选择了业界最成熟的 ffmpeg 来干这个脏活,Java 这边只负责"拼命令行 + 执行 + 处理临时文件"。
本篇作为 audio-plugin 的第一篇,手把手带大家把"音频转码"这个能力跑起来,包括环境安装、依赖引入、基本使用、参数说明,以及实际使用时踩过的坑。
I. 问题背景
音频转码这个事,说起来简单:给一个 .amr 文件,吐一个 .mp3 出来。但要自己实现就没那么轻松了——
- 音频编解码是重活,amr、mp3、ogg、aac 每种格式的编解码器都不一样,Java 标准库只支持 wav/mp3 等少数几种,amr 基本无解
- 市面上各类音频编解码的鼻祖级工具就是 ffmpeg,它几乎支持所有主流音频/视频格式的转码
- 调用 ffmpeg 也简单,本质就是一行命令:
ffmpeg -i 输入.amr 输出.mp3
所以设计思路是:Java 不做编解码,只做封装。把"读取输入源 -> 落成本地临时文件 -> 拼 ffmpeg 命令 -> 执行 -> 输出文件"这一套流程封装成链式的 AudioWrapper,让调用方几行代码搞定转码。
环境安装注意事项
因为底层是靠命令行调用 ffmpeg,所以本机(或服务所在机器)必须安装 ffmpeg,并且 ffmpeg 可执行文件要能在 PATH 中找到。
安装方式(任选其一):
- 官网下载对应平台的安装包,配置好环境变量
- linux 静态编译包,解压即用:
#!/bin/bash
## download ffmpeg cmd
wget https://johnvansickle.com/ffmpeg/releases/ffmpeg-release-64bit-static.tar.xz
## exact package
xz -d ffmpeg-release-64bit-static.tar.xz
tar -xvf ffmpeg-release-64bit-static.tar
mv ffmpeg-release-64bit-static ffmpeg
cd ffmpeg
装完之后先手动验证一下:
ffmpeg -version
能正常输出版本信息,说明环境 OK。强烈建议在写代码之前,先手动执行一次转码命令验证环境,比如准备一个 test.amr 文件:
ffmpeg -i test.amr test.mp3
如果播放器能正常播放 test.mp3,后面用插件就不太可能有问题;反过来,如果环境没装好,插件执行命令时只会默默失败,排查起来反而多绕一圈。
注意:不要直接拿微信聊天记录里的语音文件来测试,微信对语音做过特殊处理,不是标准的 amr 文件,可能导致转码异常或时长不对。手头没有测试文件的话,项目测试目录里有一个标准的
test.amr。
II. 依赖引入
项目已发布到 maven 中央仓库,直接依赖即可,请注意使用最新版本:
<!-- https://mvnrepository.com/artifact/com.github.liuyueyi.media/audio-plugin -->
<dependency>
<groupId>com.github.liuyueyi.media</groupId>
<artifactId>audio-plugin</artifactId>
<version>3.1.0</version>
</dependency>
gradle 用户:
// https://mvnrepository.com/artifact/com.github.liuyueyi.media/audio-plugin
implementation 'com.github.liuyueyi.media:audio-plugin:3.1.0'
如果使用的是旧版本坐标
com.github.hui.media:audio-plugin(如 1.0),则需要额外添加作者的 maven 仓库源:<repositories> <repository> <id>yihui-maven-repo</id> <url>https://raw.githubusercontent.com/liuyueyi/maven-repository/master/repository</url> </repository> </repositories>
III. 使用姿势
3.1 最简单的示例
先看一个可运行的完整 case,对应测试类 AudioWrapperTest:
public class AudioWrapperTest {
@Test
public void testAudioParse() {
String[] arys = new String[]{"test.amr",
"http://s11.mogucdn.com/mlcdn/c45406/170713_3g25ec8fak8jch5349jd2dcafh61c.amr"};
for (String src : arys) {
String output = AudioWrapper.of(src)
.setInputType("amr")
.setOutputType("mp3")
.asFile();
System.out.println(output);
}
}
}
上面这个循环分别测试了两种输入源:一个是从 classpath 加载的相对路径文件 test.amr,一个是网络音频 url。执行后输出(以 mac 为例):
/Users/yihui/.../target/test-classes/test_out.mp3
/tmp/quickmedia/20261112/170713_3g25ec8fak8jch5349jd2dcafh61c_out.mp3
注意返回值 output 是转码后输出文件的绝对路径,文件名规则是 原文件名_out.输出格式。
可以看到使用姿势非常简洁,三段式:
AudioWrapper.of(...)指定输入源,返回一个Builder对象setInputType/setOutputType等链式调用配置参数asFile()/asStream()表示执行转码并按指定方式输出
3.2 三种输入源
AudioWrapper 提供了三个 of 方法,对应三种输入源:
public static Builder<String> of(String str); // 路径或 url 字符串
public static Builder<URI> of(URI uri); // 网络资源
public static Builder<InputStream> of(InputStream inputStream); // 输入流
其中 String 类型最常用,内部会按下面三种情况区分处理:
| 输入形式 | 处理方式 | 临时文件位置 |
|---|---|---|
http 开头的 url | 先下载到临时目录 | 临时目录,如 /tmp/quickmedia/20261112/ |
绝对路径(如 /a/b/test.amr) | 直接使用 | 原文件所在目录 |
相对路径(如 test.amr) | 从 classpath 中解析 | 解析后的实际目录 |
~/ 开头 | 展开用户目录后按绝对路径处理 | 原文件所在目录 |
临时目录的默认规则(见 FileWriteUtil):
- linux/mac:
/tmp/quickmedia/,windows:C://tmp/quickmedia/ - 目录后面会拼接当天日期(如
20261112),按天归档 - 可以通过系统属性
quick.media.tmp.path自定义,比如启动参数-Dquick.media.tmp.path=/data/tmp
3.3 输出方式:asFile 与 asStream
asFile() 返回输出文件的绝对路径,转码失败时返回 null:
String output = AudioWrapper.of("test.amr")
.setInputType("amr")
.setOutputType("mp3")
.asFile();
如果不想落成磁盘上的目标文件再读,而是希望直接拿到流(比如 web 场景转完直接写回响应),用 asStream(),它内部就是先 asFile() 再读输出文件:
InputStream stream = AudioWrapper.of("test.amr")
.setInputType("amr")
.setOutputType("mp3")
.asStream();
3.4 输入流方式的注意事项
InputStream 方式比较特殊,因为流本身没有文件名,必须通过 setInputType 指定源音频格式,插件会用 时间戳_随机数.格式 在临时目录生成临时源文件,否则临时文件没有后缀,ffmpeg 可能无法识别格式:
try (InputStream in = new FileInputStream("/a/b/xxx.amr")) {
String output = AudioWrapper.of(in)
.setInputType("amr")
.setOutputType("mp3")
.asFile();
}
对应的,路径/url 方式下后缀是从文件名里解析的,setInputType 可以省略;但保险起见,官方测试用例里两种场景都显式设置了 setInputType,建议保持一致。
IV. 参数说明
AudioWrapper.Builder 上可用的配置方法如下:
| 方法 | 说明 | 是否必须 |
|---|---|---|
of(...) | 指定输入源,支持 String/URI/InputStream | 必须 |
setInputType(String) | 源音频格式(后缀名,如 amr);InputStream 输入源必须设置 | 视输入源而定 |
setOutputType(String) | 输出音频格式(后缀名,如 mp3) | 必须,缺失时直接抛异常 |
addOption(String, Object) | 追加 ffmpeg 命令行参数,如 addOption("ar", 44100) | 可选 |
asFile() | 执行转码,返回输出文件绝对路径,失败返回 null | 二选一 |
asStream() | 执行转码,返回输出文件的输入流 | 二选一 |
插件内部还会默认追加三个兜底参数(在 Builder 的构造器里,不想要可以 addOption 覆盖):
| 默认参数 | 作用 |
|---|---|
-y | 覆盖写,输出文件已存在时直接覆盖;不加这个,ffmpeg 在遇到同名文件时会交互式等待输入 y/n,代码里进程会一直卡住 |
write_xing 0 | 解决 mac/ios 播放器显示音频时长不对的问题 |
loglevel quiet | 不输出 ffmpeg 日志,避免输出流无人消费的问题 |
最终拼装出来的命令形如:
ffmpeg -i /tmp/quickmedia/20261112/xxx.amr -y -write_xing 0 -loglevel quiet /tmp/quickmedia/20261112/xxx_out.mp3
命令的执行由 ProcessUtil 完成,它做了几件细节工作:用独立线程消费命令行的输出流和异常流(防止缓冲区写满导致进程阻塞)、设置 2 秒的超时时间避免死等。
V. 常见坑
最后汇总一下实际使用中踩过的坑:
1. 环境未安装 ffmpeg
所有转码都依赖本机的 ffmpeg 命令,没装环境的话,执行时会在日志里输出 operate audio error! cmd: ...,asFile 返回 null。部署到新机器上,先跑 ffmpeg -version 再上线。
2. mac/ios 下音频时长显示不对
amr 转 mp3 后,在某些播放器(尤其 mac 和 iphone)上显示的时长比实际小,但播放本身没问题。原因和 mp3 头部的时长信息有关,解决方式就是插件默认加的 write_xing 0 参数;如果手动覆盖默认参数时把它弄丢了,这个坑就会重新出现。
3. 大文件转码超时
ProcessUtil 对命令执行设置了 2 秒超时,超过 2 秒会抛 TimeoutException,asFile 会捕获并返回 null。对大文件或者高负载机器需要注意这一点;并且超时后插件并不会主动终止 ffmpeg 进程,如果遇到这种场景,建议基于源码自行调整超时或干脆直接封装 Runtime.exec 自己控制。
4. 并发场景下 RT 线性增加
早期版本没有处理命令行的输出流、异常流,也不输出日志,导致并发一高,rt 就线性上涨——根本原因是 ffmpeg 的输出/异常信息没人消费,缓存它们的空间有限,把进程卡住了。当前版本的处理方式有两条:独立线程消费输出流/异常流,以及默认 loglevel quiet 不产生日志。如果你 addOption 时把日志重新打开,在并发场景要留意这个坑。
5. 微信语音不是标准的 amr
直接拿微信里导出的语音文件测试,可能转码报错或时长不对,这不是插件的锅。测试请用标准 amr 文件。
6. 临时文件与输出文件
- 输出文件名固定为
原文件名_out.输出格式,输出目录与临时源文件同目录,多次转码同名文件时靠默认-y覆盖 - 网络资源/输入流的临时文件都在
/tmp/quickmedia/yyyyMMdd/(win 为C://tmp/quickmedia/yyyyMMdd/),按天归档,不会自动清理,需要业务方自己定期清理磁盘,或者用quick.media.tmp.path把目录指到有清理机制的地方 - windows 下临时路径里是
C://tmp/...这种写法,注意不要和防火墙/权限策略冲突
VI. 小结
本篇介绍了 audio-plugin 的核心能力:基于 ffmpeg 的音频转码。整体使用非常简单:of() 定输入源,setInputType/setOutputType 定格式,asFile()/asStream() 定输出方式,剩下的下载临时文件、拼命令、执行、输出文件名管理都由插件兜底。
项目地址: https://github.com/liuyueyi/quick-media
延伸阅读: