简介这是一套面向Java开发者的音频处理工具包源码基于ffmpeg封装帮助开发者在不编写底层音视频代码的前提下快速实现音频格式转换、音频信息提取等常见操作适用于音频播放器、音频编辑器及各类需要处理音频的应用开发场景。资源包共27个文件约106.02MB以10个XML配置文件和7个Java源文件为主体前者用于调整输入输出格式、处理精度等运行参数后者承载音频转换与提取的核心逻辑此外还包含ffmpeg、ffprobe、mediaconvert等可执行文件以及wav示例音频、LICENSE、readme.txt和.gitignore等辅助文件整体结构清晰便于按模块阅读与集成。目前已有108人学习下载。对于希望将ffmpeg能力接入Java项目的开发者而言这份源码可直接作为集成参考省去从零搭建音频处理底层的时间同时也能借助配置与示例快速理解参数调优和调用方式。1. 从一次线上事故说起为什么我要用 Java 封装 FFmpeg去年双十一前夜客服系统里一条语音留言突然播不出来。排查发现用户上传的是 48kHz 立体声 AAC 文件而我们的 Java 服务用javax.sound.sampled读取时直接抛了UnsupportedAudioFileException。临时方案是让运维手动转码但积压的语音文件越来越多手动处理根本扛不住。那天凌晨三点我决定用 FFmpeg 做底层写一套 Java 音频处理 SDK把转码、重采样、裁剪、拼接这些能力封装成一行调用。这就是「基于 FFmpeg 的 Java 音频处理 SDK 设计源码」要解决的问题Java 生态里音频处理一直是短板原生库对格式支持有限而 FFmpeg 命令行虽然强大但直接Runtime.exec调用存在进程管理、参数注入、流读取阻塞等一堆坑。一套设计良好的 SDK应该让业务代码只关心「把这段音频转成 16kHz 单声道 WAV」而不是去拼 FFmpeg 命令、解析 stderr、处理超时。适合谁看如果你正在做语音识别前置处理、在线教育音频转码、客服系统录音归档或者单纯想给团队沉淀一个可复用的音频工具库这篇笔记里的设计思路和源码结构可以直接参考。2. 先想清楚封装边界Java 调 FFmpeg 的三种姿势与选型2.1 命令行进程调用、JNI 绑定、还是纯 Java 重写在动手写 SDK 之前必须先回答一个问题Java 和 FFmpeg 之间用什么方式通信。常见做法有三种我逐一试过血泪经验如下。第一种是ProcessBuilder启动 FFmpeg 可执行文件通过 stdin/stdout 传数据。优点是实现简单、跨平台、FFmpeg 升级不影响 Java 代码缺点是进程创建开销大高并发下线程池容易被阻塞而且 Windows 和 Linux 的路径分隔符、可执行文件后缀都要单独处理。第二种是 JNI 绑定比如 JavaCPP 提供的 FFmpeg 封装。优点是性能好、无进程开销缺点是编译复杂不同平台的动态库要分别打包FFmpeg 版本升级后 JNI 头文件可能不兼容调试时 JVM crash 的日志很难看。第三种是纯 Java 重写解码逻辑比如用 Tritonus 或 JavaSound 的 SPI。优点是零依赖缺点是格式支持极其有限AAC、OPUS 这些常见编码根本解不了等于把问题推回给业务方。我的选型结论是以命令行进程调用为主JNI 作为可选加速层。原因很实际——音频处理在大多数业务里不是高频操作进程开销可以接受而 FFmpeg 命令行参数极其灵活SDK 只需要做参数拼装和结果校验维护成本最低。下面这段代码是 SDK 里最核心的进程执行器我把它单独抽出来因为后面所有功能都依赖它。public class FFmpegExecutor { private final String ffmpegPath; private final Duration timeout; public FFmpegExecutor(String ffmpegPath, Duration timeout) { this.ffmpegPath ffmpegPath; this.timeout timeout; } public FFmpegResult execute(ListString args) throws IOException, InterruptedException { ListString command new ArrayList(); command.add(ffmpegPath); command.addAll(args); ProcessBuilder pb new ProcessBuilder(command); pb.redirectErrorStream(true); // 合并 stderr 到 stdout避免缓冲区死锁 Process process pb.start(); StringBuilder output new StringBuilder(); try (BufferedReader reader new BufferedReader( new InputStreamReader(process.getInputStream(), StandardCharsets.UTF_8))) { String line; while ((line reader.readLine()) ! null) { output.append(line).append(\n); } } boolean finished process.waitFor(timeout.toMillis(), TimeUnit.MILLISECONDS); if (!finished) { process.destroyForcibly(); throw new TimeoutException(FFmpeg 执行超时: timeout); } int exitCode process.exitValue(); return new FFmpegResult(exitCode, output.toString()); } }这段代码有三个关键点。第一redirectErrorStream(true)必须开否则当 FFmpeg 输出大量日志时stderr 缓冲区写满会导致进程阻塞Java 这边读 stdout 又读不到东西直接死锁——这个坑我踩过两次。第二超时用waitFor(timeout)而不是process.waitFor()防止某个损坏文件让 FFmpeg 卡死。第三ffmpegPath通过构造函数注入不写死在代码里方便不同环境配置。2.2 SDK 的模块划分与包结构一个可维护的 SDK 不能把所有代码塞进一个类。我按职责拆成四个包core放执行器和结果封装probe放媒体信息探测convert放转码和重采样edit放裁剪、拼接、音量调整。每个包对外只暴露一个 Service 接口实现类包级私有这样业务方只能看到接口后续换实现不影响调用方。com.example.audio.sdk ├── core │ ├── FFmpegExecutor.java │ ├── FFmpegResult.java │ └── AudioSdkConfig.java ├── probe │ ├── MediaProbeService.java │ └── MediaInfo.java ├── convert │ ├── AudioConvertService.java │ └── ConvertRequest.java └── edit ├── AudioEditService.java └── EditRequest.javaAudioSdkConfig用 Builder 模式把 FFmpeg 路径、超时时间、临时目录、日志级别都做成可配置项。默认值我设成超时 30 秒临时目录用System.getProperty(java.io.tmpdir)日志级别只记录 exitCode 非零的情况。这样业务方 new 一个 Config 就能用不需要看文档。2.3 参数拼装的安全边界直接拼接字符串构造 FFmpeg 命令是另一个大坑。如果文件名里带空格或引号命令会解析错乱更严重的是如果文件名来自用户输入可能被注入额外参数。我的做法是所有参数用ListString传递ProcessBuilder会自动处理转义绝不手动拼字符串。对于输入输出路径额外做一次Paths.get(path).toAbsolutePath().normalize()防止../路径穿越。public class AudioConvertService { private final FFmpegExecutor executor; public AudioConvertService(FFmpegExecutor executor) { this.executor executor; } public void convertToWav(Path input, Path output, int sampleRate, int channels) throws IOException, InterruptedException { Path safeInput input.toAbsolutePath().normalize(); Path safeOutput output.toAbsolutePath().normalize(); if (!Files.exists(safeInput)) { throw new IllegalArgumentException(输入文件不存在: safeInput); } ListString args Arrays.asList( -y, // 覆盖输出文件 -i, safeInput.toString(), -ar, String.valueOf(sampleRate), -ac, String.valueOf(channels), -acodec, pcm_s16le, -f, wav, safeOutput.toString() ); FFmpegResult result executor.execute(args); if (result.getExitCode() ! 0) { throw new AudioProcessException(转码失败: result.getOutput()); } } }参数说明-y表示输出文件已存在时直接覆盖避免交互式确认卡住进程-ar设采样率语音识别常用 16000-ac设声道数1 表示单声道-acodec pcm_s16le是 WAV 的 16 位小端 PCM 编码-f wav强制输出格式。这几个参数组合是我在语音预处理场景里验证过最稳的转出来的文件直接喂给主流 ASR 引擎不会报格式错误。3. 核心功能实现探测、转码、裁剪与拼接的代码落地3.1 用 ffprobe 获取音频元信息转码之前通常需要知道源文件的采样率、声道数、时长、编码格式。FFmpeg 套件里的ffprobe就是干这个的输出 JSON 格式最方便解析。SDK 里我封装了一个MediaProbeService调用ffprobe -v quiet -print_format json -show_format -show_streams然后用 Jackson 解析。public class MediaProbeService { private final String ffprobePath; private final ObjectMapper mapper new ObjectMapper(); public MediaProbeService(String ffprobePath) { this.ffprobePath ffprobePath; } public MediaInfo probe(Path input) throws IOException, InterruptedException { ListString args Arrays.asList( -v, quiet, -print_format, json, -show_format, -show_streams, input.toAbsolutePath().normalize().toString() ); ProcessBuilder pb new ProcessBuilder(); ListString command new ArrayList(); command.add(ffprobePath); command.addAll(args); pb.command(command); pb.redirectErrorStream(true); Process process pb.start(); JsonNode root mapper.readTree(process.getInputStream()); process.waitFor(10, TimeUnit.SECONDS); JsonNode format root.get(format); JsonNode audioStream null; for (JsonNode stream : root.get(streams)) { if (audio.equals(stream.get(codec_type).asText())) { audioStream stream; break; } } if (audioStream null) { throw new AudioProcessException(文件中没有音频流); } return new MediaInfo( audioStream.get(codec_name).asText(), audioStream.get(sample_rate).asInt(), audioStream.get(channels).asInt(), format.get(duration).asDouble() ); } }逻辑说明-v quiet抑制 ffprobe 的冗余日志只输出 JSON-show_format给出容器级信息包括时长-show_streams给出每个流的编码细节。解析时先遍历 streams 找到codec_type为audio的那一个因为视频文件里可能同时有视频流和音频流。duration字段在 format 节点下单位是秒浮点数。这个探测结果直接决定后续转码参数——比如源采样率已经是 16000 且单声道就可以跳过重采样省一次 IO。3.2 转码与重采样参数怎么设才不翻车转码是 SDK 里调用最频繁的功能。除了上面convertToWav的基础版实际业务里还需要控制码率、指定编码器、处理多声道下混。下面这个ConvertRequest用 Builder 模式把参数收拢避免方法签名膨胀。public class ConvertRequest { private Path input; private Path output; private String codec pcm_s16le; private int sampleRate 16000; private int channels 1; private String bitrate; // 可选如 128k private String format wav; // Builder 省略只展示核心构建逻辑 public ListString toFFmpegArgs() { ListString args new ArrayList(); args.add(-y); args.add(-i); args.add(input.toAbsolutePath().normalize().toString()); args.add(-ar); args.add(String.valueOf(sampleRate)); args.add(-ac); args.add(String.valueOf(channels)); args.add(-acodec); args.add(codec); if (bitrate ! null !bitrate.isEmpty()) { args.add(-b:a); args.add(bitrate); } args.add(-f); args.add(format); args.add(output.toAbsolutePath().normalize().toString()); return args; } }参数选择上有几个经验值。语音场景sampleRate16000、channels1、codecpcm_s16le这是 Whisper、Paraformer 等 ASR 模型的标准输入。音乐场景sampleRate44100、channels2、codeclibmp3lame、bitrate192k兼顾质量和体积。如果源文件是 5.1 声道要下混成立体声FFmpeg 默认的下混矩阵可能让某些声道音量异常需要加-af panstereo|c00.5*c00.5*c2|c10.5*c10.5*c3手动指定混合系数。这个pan滤镜的坑在于不同 FFmpeg 版本对声道布局的命名有差异5.1 可能是5.1也可能是5.1(side)稳妥做法是先 probe 拿到channel_layout再拼滤镜。3.3 裁剪与拼接时间戳精度和重编码取舍裁剪用-ss和-t参数。-ss放在-i前面是快速定位但可能不准放在-i后面是精确裁剪但会解码整个文件。我的做法是对精度要求不高的场景比如截取一段背景音乐用前置-ss对语音对齐要求高的场景用后置-ss加-accurate_seek。public void trim(Path input, Path output, double startSec, double durationSec) throws IOException, InterruptedException { ListString args Arrays.asList( -y, -i, input.toAbsolutePath().normalize().toString(), -ss, String.format(%.3f, startSec), -t, String.format(%.3f, durationSec), -acodec, copy, // 不重编码速度快但关键帧对齐可能偏移 output.toAbsolutePath().normalize().toString() ); FFmpegResult result executor.execute(args); if (result.getExitCode() ! 0) { throw new AudioProcessException(裁剪失败: result.getOutput()); } }注意-acodec copy表示不重编码直接复制音频流速度极快但裁剪点只能落在关键帧上实际起点可能比startSec早几十毫秒。如果业务对时间精度敏感把-acodec copy换成-acodec pcm_s16le重新编码代价是耗时增加但精度到毫秒级。拼接多个音频文件有两种方式。一种是 concat 协议要求所有文件编码参数完全一致否则会花屏或报错另一种是 concat 滤镜兼容性好但需要重编码。我一般先用 probe 检查所有输入文件的采样率、声道数、编码格式一致就用 concat 协议不一致就先统一转码再拼接。public void concat(ListPath inputs, Path output) throws IOException, InterruptedException { Path listFile Files.createTempFile(concat, .txt); try { ListString lines new ArrayList(); for (Path input : inputs) { lines.add(file input.toAbsolutePath().normalize() ); } Files.write(listFile, lines, StandardCharsets.UTF_8); ListString args Arrays.asList( -y, -f, concat, -safe, 0, -i, listFile.toString(), -acodec, copy, output.toAbsolutePath().normalize().toString() ); FFmpegResult result executor.execute(args); if (result.getExitCode() ! 0) { throw new AudioProcessException(拼接失败: result.getOutput()); } } finally { Files.deleteIfExists(listFile); } }-safe 0允许列表文件里使用绝对路径不加这个参数 FFmpeg 会拒绝不安全的路径。列表文件每行格式是file 路径路径里的单引号需要转义成\这个细节在 Windows 路径里尤其容易翻车。4. 避坑与排查进程调用 FFmpeg 最常见的五类翻车4.1 现象进程卡死Java 线程池耗尽原因FFmpeg 输出日志到 stderrJava 只读 stdoutstderr 缓冲区写满后 FFmpeg 阻塞Java 读 stdout 也阻塞互相等待。解决ProcessBuilder.redirectErrorStream(true)合并两个流或者单独起线程消费 stderr。我选择合并代码简单且不会丢日志。4.2 现象转码后音频时长对不上末尾多出静音原因某些编码格式如 MP3有编码器延迟FFmpeg 会在文件头写入 delay 信息但部分播放器不读。解决转码时加-af aresampleasync1:first_pts0重置时间戳或者输出 WAV 这种无延迟格式。如果必须输出 MP3用-write_xing 1写入 Xing 头大多数播放器能正确识别。4.3 现象Windows 上路径带空格FFmpeg 报 “No such file or directory”原因手动拼接命令字符串时没有给路径加引号。解决永远用ListString传参ProcessBuilder会自动处理。如果确实需要拼字符串比如写日志用String.join( , args)仅用于展示不用于执行。4.4 现象并发转码时 CPU 打满响应变慢原因FFmpeg 默认使用所有可用核心多个进程同时跑会互相抢资源。解决在 SDK 里加信号量控制并发数或者给每个 FFmpeg 进程加-threads 2限制线程数。我的配置是并发数 CPU 核心数 / 2单进程-threads 2这样在 8 核机器上最多 4 个转码任务同时跑每个用 2 线程留出余量给业务线程。4.5 现象临时文件堆积磁盘写满原因转码失败时没有清理中间文件或者 concat 的列表文件忘记删。解决所有临时文件用Files.createTempFile创建在finally块里Files.deleteIfExists。对于转码输出文件如果 exitCode 非零也主动删除半成品避免业务方误用。5. 进阶技巧用 Java 做音频流式处理与质量校验5.1 边转码边读取把 FFmpeg 输出接到 Java 流前面讲的都是文件到文件的转码。如果业务需要实时处理比如把用户上传的音频转成 PCM 后直接送进 ASR 引擎可以不走临时文件让 FFmpeg 输出到 stdoutJava 从process.getInputStream()读取。public InputStream transcodeToStream(Path input, int sampleRate) throws IOException { ListString args Arrays.asList( -i, input.toAbsolutePath().normalize().toString(), -ar, String.valueOf(sampleRate), -ac, 1, -acodec, pcm_s16le, -f, s16le, // 裸 PCM 流无容器头 - ); ProcessBuilder pb new ProcessBuilder(); ListString command new ArrayList(); command.add(ffmpegPath); command.addAll(args); pb.command(command); pb.redirectErrorStream(false); // stderr 单独处理避免污染 PCM 数据 Process process pb.start(); // 必须异步消费 stderr否则可能阻塞 new Thread(() - { try (BufferedReader r new BufferedReader( new InputStreamReader(process.getErrorStream()))) { while (r.readLine() ! null) { /* 丢弃或记日志 */ } } catch (IOException ignored) {} }).start(); return process.getInputStream(); }关键点输出格式用s16le裸 PCM不带 WAV 头ASR 引擎通常直接吃这种流。-表示输出到 stdout。stderr 必须单独起线程消费不能合并到 stdout否则 PCM 数据里会混入日志文本。这个方案省掉了临时文件 IO在批量处理场景下能提升 20% 左右吞吐。5.2 转码质量校验用 PSNR 和时长偏差做自动化断言SDK 交付给业务方后最怕的是“转码成功但质量不对”。我在测试阶段加了两个自动校验时长偏差和 PSNR。时长偏差用 ffprobe 分别探测输入输出偏差超过 100ms 就告警。PSNR 用 FFmpeg 的psnr滤镜对比源文件和转码文件语音场景 PSNR 低于 30dB 说明质量损失过大。public double calculatePsnr(Path original, Path processed) throws IOException, InterruptedException { ListString args Arrays.asList( -i, original.toAbsolutePath().normalize().toString(), -i, processed.toAbsolutePath().normalize().toString(), -lavfi, psnr, -f, null, - ); FFmpegResult result executor.execute(args); // FFmpeg 把 PSNR 输出到 stderr格式如 average:35.2 Pattern p Pattern.compile(average:([0-9.])); Matcher m p.matcher(result.getOutput()); if (m.find()) { return Double.parseDouble(m.group(1)); } throw new AudioProcessException(无法解析 PSNR: result.getOutput()); }这个校验跑在 CI 里每次修改转码参数都会触发。有一次我把-ar从 16000 改成 8000 想省带宽PSNR 直接掉到 22dB自动化测试拦住了这次变更。如果没有这个校验问题会流到线上被用户投诉“声音发闷”才发现。5.3 配置外置与多环境适配最后说一个工程习惯FFmpeg 路径不要写死在代码里。我见过太多项目在开发机上是/usr/local/bin/ffmpeg到了容器里变成/usr/bin/ffmpeg上线就报FileNotFoundException。SDK 的AudioSdkConfig支持从环境变量FFMPEG_PATH和FFPROBE_PATH读取也支持在配置文件里指定。如果都没配就依次尝试which ffmpeg、/usr/bin/ffmpeg、/usr/local/bin/ffmpeg全找不到就抛出带明确提示的异常告诉用户去 ffmpeg 下载官网获取对应平台的静态编译版本。这套 SDK 我从事故当晚开始写到现在迭代了十几个版本支撑了日均百万级的音频处理请求。最大的教训是不要相信“这个文件格式肯定没问题”永远先用 ffprobe 探测再决定转码参数不要手动拼命令字符串ListString加ProcessBuilder能省掉 90% 的路径问题不要忘记消费 stderr那个黑匣子里的日志既是排错依据也是阻塞元凶。希望帮到你。本文还有配套的精品资源点击获取