1.基于FFMPEG实现音频转码

一灰灰blogQuickMediaaudio-plugin约 2622 字大约 9 分钟

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-mediaopen in new window

延伸阅读:

Loading...