纯 PHP 音视频处理引擎：FLV/MP4/HLS 互转 · H.264 解码与重编码 · AAC/MP3/Opus/WAV 全格式互转

项目简介

纯 PHP 8.1+ 实现的轻量级媒体处理工具包，零外部依赖（无需 FFmpeg）。
支持 FLV、FMP4、MP4、HLS 互转，直播流网关、推流、拉流、转播，以及 H.264 解码 + 缩放 + 重新编码（Baseline Profile）+ AAC/MP3/Opus/WAV 全格式互转。

📋 目录

• 项目简介
• 核心功能
• 环境依赖
• 安装
• 快速开始
• 高级功能
  • Opus转AAC
  • FLV 直播网关
  • 静态文件网关
  • 推流客户端
  • 拉流客户端
  • 直播转发（转播）
• 测试与播放
• 应用场景
• H.264 重编码详解
  • FLV → HLS 多码率示例
  • FLV → FLV 重编码示例
  • MP4 → MP4 重编码示例
  • 水印工具
  • 性能测试报告
• AAC/MP3/OPUS/WAV的编码解码
• 技术说明
• 开源协议 & 免责声明
• 联系方式

🎯 核心功能

环境依赖

• 💡 仅支持 PHP CLI 命令行运行，不支持 Nginx/FPM 网页模式调用。
• 💡 无需 FFmpeg，无需任何第三方二进制程序，全部纯 PHP 实现。
• 💡 容器封装转换（FLV/MP4/HLS 互转，仅修改封装格式，速度快）。
• ⚠️ H.264 重编码功能要求 proc_open 不被禁用。（该模块采用多进程分布式计算，需要创建子进程来并行处理帧数据。）
• ⚠️ Opus 实时转码（仅直播场景）要求 proc_open 不被禁用。（在 WebRTC 转 RTMP 等实时场景下，会启动独立的后台 Worker 进程进行音频转码；静态文件的 Opus 转码不需要此函数。）
• ⚠️ H.264 重编码模块属于 CPU 密集型计算，性能取决于服务器配置，不建议用于直播实时转码场景，同时建议开启 JIT 加速。

🚀 安装

composer require xiaosongshu/flv2mp4

📚 快速开始

<?php

declare(strict_types=1);
require_once __DIR__ . '/vendor/autoload.php';

ini_set('memory_limit', '512M');

$file = __DIR__ . '/test.flv';

// 1. FLV → 混合 fMP4 切片
\Xiaosongshu\Flv2mp4\Client::runFlv2Fmp4Mixed($file, __DIR__ . '/output_merge');

// 2. FLV → 分离 fMP4 切片（音视频独立）
\Xiaosongshu\Flv2mp4\Client::runFlv2Fmp4Separate($file, __DIR__ . '/output_separate');

// 3. FLV → HLS
\Xiaosongshu\Flv2mp4\Client::runFlv2Hls($file, __DIR__ . '/hls');

// 4. HLS → FLV
\Xiaosongshu\Flv2mp4\Client::runHls2Flv(__DIR__ . '/hls/index.m3u8', __DIR__ . '/output.flv');

// 5. MP4 → FLV
\Xiaosongshu\Flv2mp4\Client::runMp42Flv(__DIR__ . '/test.mp4', __DIR__ . '/output.flv');

// 6. FLV → MP4
\Xiaosongshu\Flv2mp4\Client::runFlv2Mp4($file, __DIR__ . '/output.mp4');

// 7. fMP4 → FLV（混合/分离均支持）
\Xiaosongshu\Flv2mp4\Client::runFmp42Flv(__DIR__ . '/output_merge/index.m3u8', __DIR__ . '/output.flv');

// 8. MP4 → HLS
\Xiaosongshu\Flv2mp4\Client::runMp42Hls(__DIR__ . "/demo.mp4", __DIR__ . "/mp4_hls");

// 9. HLS → MP4
\Xiaosongshu\Flv2mp4\Client::runHls2Mp4( __DIR__ .'/mp4_hls/demo/index.m3u8', __DIR__.'/hls_2_mp4.mp4');

// 10. MP4 → fMP4
\Xiaosongshu\Flv2mp4\Client::runMp42Fmp4(__DIR__.'/demo.mp4', __DIR__.'/mp4_2_fmp4');

// 11. fMP4 → MP4
\Xiaosongshu\Flv2mp4\Client::runFmp42Mp4(__DIR__.'/mp4_2_fmp4/index.m3u8',__DIR__.'/1234567.mp4');

🌐 高级功能

Opus 2 AAC

WebRtcFlvRelay 可接收 WebRTC RTP 数据，将 H.264 视频封装为 FLV，并通过纯 PHP Worker 把 Opus 音频实时转码为 AAC-LC，再推送到 WebSocket-FLV 服务，由该服务继续录制或转发到 RTMP 等目标。

<?php

require_once __DIR__ . '/vendor/autoload.php';

use Xiaosongshu\Flv2mp4\Flv\WebRtcFlvRelay;
use Xiaosongshu\Flv2mp4\Opus\OpusWorkerClient;

$clientId = 1;
$streamId = 'stream_001';
$opusWorkerPort = 8330;
$pushUrl = "ws://127.0.0.1:8501/live/{$streamId}";

$relay = new WebRtcFlvRelay(
 $clientId, $streamId, $pushUrl, null, null, $opusWorkerPort);
$relay->connect();

// 在 WebRTC 服务端的 RTP 回调中调用：
// $relay->pushRtp($plainRtp, 'video');
// $relay->pushRtp($plainRtp, 'audio');

// 推流结束时关闭 relay，并在主进程退出时关闭自动启动的 Worker。
$relay->finish();
OpusWorkerClient::shutdownOwnedWorkers();

项目根目录的 examples\webrtc.php 提供了完整的 WebRTC 转 FLV 示例。常用配置如下：

// 每个项目实例应使用不同的 Worker 端口。
$opusWorkerPort = 8330;

// 支持 RTMP、HTTP-FLV 和 WebSocket-FLV 服务提供的推流地址；
// 示例默认使用 WebSocket-FLV，并以 streamId 替换占位符。
$wsFlvPushUrl = 'ws://127.0.0.1:8501/live/{streamId}';

运行示例：

php webrtc.php

说明：

• relay 连接时会自动启动 bin/opus-worker.php（若目标端口尚无 Worker），无需手动启动 Worker；
• Worker 仅监听 127.0.0.1，默认端口为 8330；
• 自动启动时会把宿主项目真实的 vendor/autoload.php 通过 --autoload 传给 Worker，兼容通过 composer require xiaosongshu/flv2mp4 安装及自定义 vendor-dir；
• 默认输出为 48kHz、单声道、64kbps AAC-LC；
• 同一个 Worker 进程可以管理多路独立连接，但纯 PHP 实时转码会消耗较多 CPU，建议单实例先按一路实时节目规划；
• 同一台机器启动多个项目实例时，必须为每个实例配置不同的 $opusWorkerPort；
• 主进程收到 Ctrl+C 或退出时，应调用 OpusWorkerClient::shutdownOwnedWorkers()，start.php 已包含相应的退出处理；
• PHP 必须允许使用 proc_open，否则无法自动创建 Worker 子进程；
• Worker 队列包含有界背压保护。不要仅通过扩大队列解决性能不足，否则可能增加音频延迟并造成音视频不同步。
• webrtc服务需要用到工具包xiaosongshu/webrtc。

FLV 直播网关

支持多级代理部署，实现高并发直播流转发。新建文件flvGateway.php，内容如下:

<?php
require_once __DIR__ . '/vendor/autoload.php';
$gateway = new \Xiaosongshu\Flv2mp4\Manage\FlvGateway(8080, 'http://127.0.0.1:8501');
$gateway->debug = true;
$gateway->start();

启动flv网关

php flvGateway.php

静态文件网关

轻量级 HTTP 文件服务器，支持目录浏览开关。新建文件fileGateway.php，内容如下:

<?php
require_once __DIR__ . '/vendor/autoload.php';
$server = new \Xiaosongshu\Flv2mp4\Manage\FileGateway( '0.0.0.0',8100,__DIR__,false);
$server->debug = true;
$server->start();

启动file网关

php fileGateway.php```
### 推流客户端

支持 HTTP-FLV、WS-FLV、RTMP 三种协议，倍速推流、断线重连。新建文件`pusher.php`，内容如下:
```php
require_once __DIR__ . '/vendor/autoload.php';
ini_set('memory_limit', '2048M');
$pusher = new \Xiaosongshu\Flv2mp4\Manage\PusherManage(__DIR__."/test.flv", "http://127.0.0.1:8501/live/stream", 1.0, false);
$pusher->start();

启动推流

php pusher.php

拉流客户端

从直播流拉取并保存为本地 FLV，适合录制或调试。新建文件puller.php，内容如下：

require_once __DIR__ . '/vendor/autoload.php';
ini_set('memory_limit', '2048M');
$puller = new \Xiaosongshu\Flv2mp4\Manage\PullerManage("ws://127.0.0.1:8501/live/stream.flv", __DIR__."/pull_record.flv", 0, false);
$puller->start();

启动拉流客户端

php puller.php

直播转发

一路拉流，同时转发至多个目标地址（支持协议混用）。新建文件forward.php，内容如下：

require_once __DIR__ . '/vendor/autoload.php';
ini_set('memory_limit', '2048M');
$forwarder = new \Xiaosongshu\Flv2mp4\Flv\FlvForwardClient("http://127.0.0.1:8501/a/b.flv", ["rtmp://127.0.0.1:1935/c/d","ws://127.0.0.1:8501/c/e"], 0, true);
$forwarder->start();

启动转播客户端

php forward.php

🧪 测试&推流&播放

🎯 应用场景

• 直播录制：RTMP/FLV 直播流实时转存为 fMP4 / HLS
• 视频回放：录制流随时点播回看
• 流转发：多级网关实现负载均衡与边缘加速
• 离线批处理：批量转换 FLV / MP4 格式
• 伪直播推流：点播文件伪装为直播流推送
• 跨平台转播：一次拉流，同时转发到多个平台
• 多码率 HLS：纯 PHP 实现的 H.264 重编码，生成自适应码率 HLS

🔥 H.264 解码 + 缩放 + 重编码

支持 Baseline Profile 的 H.264 解码、缩放、重新编码，为以下场景提供核心能力：

通过 Composer 安装后无需手动运行 Opus/HLS/FLV/MP4 Worker；程序会使用当前 PHP CLI 和宿主 vendor/autoload.php 自动启动。多进程模式要求启用 proc_open，建议在 CLI 环境运行。

技术定位：这是一个完整的 H.264 像素处理管道（解码 → 处理 → 编码），不依赖 FFmpeg，纯 PHP 实现。

flv->hls

以下为flv转码多码率hls示例：

<?php

require_once __DIR__ . '/vendor/autoload.php';
ini_set('memory_limit', '2048M');
$profiles = [
 // 不同码率分别配置
 '240p' => [ 'width' => 426,      // 或 424，保持 16:9 比例即可
 'height' => 240, 'bitrate' => 300000, // 300 Kbps（视频码率）
 'fps' => 24, 'audioBitrate' => 48000, // 48 Kbps 'qp' => 30,          // 保持 30 以确保稳定性
 'watermark'=>true,     // 是否添加水印
 'watermark_file'=> __DIR__."/src/Static/watermark_80x16.yuv",// 水印文件
 ]];
// 如果重编码质量要求高，那么开启多进程加速，低码率则不需要加速
$generator = new \Xiaosongshu\Flv2mp4\Recode\PurePhpHlsGenerator($profiles, __DIR__ . '/hls/output',true);
$generator->processFlv(__DIR__ . '/input.flv');
echo "索引地址: hls/output/master.m3u8\n";
echo "所有处理完成！\n";

flv->flv

将flv使用新的码率编码

<?php
require_once __DIR__ . '/vendor/autoload.php';
ini_set('memory_limit', '2048M');

$config = [
 'width' => 320,        // 目标宽度，0 = 保持原分辨率
 'height' => 180,       // 目标高度，0 = 保持原分辨率
 'bitrate' => 150000,   // 目标码率（bps），0 = 使用 QP 模式
 'fps' => 15,           // 目标帧率
 'qp' => 30,            // QP 质量参数（码率为 0 时生效）
 'watermark'=>true,     // 是否添加水印
 'watermark_file'=> __DIR__."/src/Static/watermark_80x16.yuv",// 水印文件
];
// 如果重编码质量要求高，那么开启多进程加速，低码率则不需要加速
$recoder = new \Xiaosongshu\Flv2mp4\Recode\FlvRecoder($config,true);
$recoder->setMaxFrames(50);  // 可选：限制处理帧数
$recoder->processFlv(__DIR__ . '/input.flv', __DIR__.'/output.flv');
echo "flv重编码完成\r\n";

mp4->mp4

将mp4文件使用新的码率编码

<?php
require_once __DIR__ . '/vendor/autoload.php';
ini_set('memory_limit', '2048M');

$config = [
 'width' => 320,        // 目标宽度，0 = 保持原分辨率
 'height' => 180,       // 目标高度，0 = 保持原分辨率
 'bitrate' => 150000,   // 目标码率（bps），0 = 使用 QP 模式
 'fps' => 15,           // 目标帧率
 'qp' => 30,            // QP 质量参数（码率为 0 时生效）
 'watermark'=>true,     // 是否添加水印
 'watermark_file'=> __DIR__."/src/Static/watermark_80x16.yuv",// 水印文件
];
// 如果重编码质量要求高，那么开启多进程加速，低码率则不需要加速
$recoder = new \Xiaosongshu\Flv2mp4\Recode\Mp4Recoder($config,true);
$recoder->setMaxFrames(50); // 可选：限制处理帧数
$recoder->processMp4(__DIR__ . '/input.mp4', __DIR__ . '/output.mp4');
echo "mp4重编码完成\r\n";

• 添加水印的时候，需要使用yuv格式文件，并且文件名称如上面的示例所示，必须包含水印文件的宽高（watermark_{width}x{height}.yuv）。工具会自动从文件名解析宽高（如 watermark_80x16.yuv → 宽 80，高 16），请确保文件名格式准确。
• 重编码模块提供了 YUV 像素级操作接口，你可以基于此实现自定义功能，如添加字幕、画中画、视频拼接等。
• h264详细使用方法见README。

已支持的重编码特性

• I 帧解码与编码（完全精确，INF dB）
• P 帧解码与编码（Baseline Profile）
• 帧内预测：4x4（9种模式）+ 16x16（4种模式）
• 帧间预测：P 帧运动估计（菱形搜索优化）
• 1/4 像素精度：6-tap 滤波器插值
• CAVLC 熵编码（Baseline Profile）
• 分辨率缩放（解码后 YUV 缩放 → 重新编码）
• 码率控制（通过 QP 参数调节）
• B 帧支持（计划中，需扩展至 Main Profile 并实现双向预测）
• CABAC 熵编码（计划中，Main Profile 支持）

⚠️ 性能说明：当前 H.264 重编码模块由纯 PHP 实现，适用于短时长视频（建议 ≤ 10 秒）的离线处理或功能验证。对于长视频或高分辨率转码，建议使用 FFmpeg 等专业工具。

水印生成工具

本项目提供php生成水印yuv功能，GD 扩展优先，无 GD 时自动降级为点阵字体。

• generateFromText() 生成文字水印 YUV， GD 扩展优先，无 GD 时自动降级为点阵字体,内置点阵字体仅支持 ASCII 字符（英文字母、数字、英文标点）
• generateFromImage() 从图片生成水印 YUV，需要 GD 扩展，支持png/jpg

使用文字生成水印文件

<?php
require_once __DIR__ . '/vendor/autoload.php';

use Xiaosongshu\Flv2mp4\Codec\WatermarkUtil;

echo "=== 测试 WatermarkUtil ===\n\n";
// 测试1：生成文字水印
echo "1. 生成文字水印 (xiaosongshu, 80x16)...\n";$outputFile1 = __DIR__ . '/test_wm_text.yuv';
$start = microtime(true);
$result = WatermarkUtil::generateFromText(
 'xiaosongshu', $outputFile1, 80, 16,
 [ 'fontSize' => 5, // 内置字体大小 1-5 `fontSize` 取值范围 1-5（数字越大字体越大），内置点阵字体仅支持 ASCII 字符。
 'fontColor' => [255, 255, 255], 'bgColor' => [0, 0, 0], ]);
$cost = round(microtime(true) - $start, 3);
if ($result && file_exists($outputFile1)) {
 $size = filesize($outputFile1); $expectedSize = 80 * 16 + (80 * 16 >> 1); echo " 成功! 文件大小: {$size} 字节 (期望: {$expectedSize}) - 耗时: {$cost}s\n";
 if ($size === $expectedSize) { echo " ✅ 文件尺寸正确\n";
 } else { echo " ❌ 文件尺寸不匹配\n";
 }} else {
 echo " ❌ 生成失败\n";
}

使用图片生成水印文件

• 需要php安装gd扩展

<?php

require_once __DIR__ . '/vendor/autoload.php';

use Xiaosongshu\Flv2mp4\Codec\WatermarkUtil;

echo "=== 测试 WatermarkUtil ===\n\n";
// 测试1：从图片生成水印
echo "1. 从图片生成水印 (xiaosongshu, 80x16)...\n";$outputFile1 = __DIR__ . '/test_wm_copy_80x16.yuv';
$start = microtime(true);
$result = WatermarkUtil::generateFromImage(
 __DIR__."/watermark_80x16.png", $outputFile1, 80, 16,);
$cost = round(microtime(true) - $start, 3);
if ($result && file_exists($outputFile1)) {
 $size = filesize($outputFile1); $expectedSize = 80 * 16 + (80 * 16 >> 1); echo " 成功! 文件大小: {$size} 字节 (期望: {$expectedSize}) - 耗时: {$cost}s\n";
 if ($size === $expectedSize) { echo " ✅ 文件尺寸正确\n";
 } else { echo " ❌ 文件尺寸不匹配\n";
 }} else {
 echo " ❌ 生成失败\n";
}

性能测试报告

实验环境

跨平台测试结果对比

Linux 环境未开启 OPcache，仍比 Windows 环境（已开启 JIT）快约 5~6 秒。

AAC-MP3-OPUS-WAV的编码解码

# aac-lc → mp3
\Xiaosongshu\Flv2mp4\Client::runAac2Mp3( __DIR__ . '/input.aac',__DIR__ . '/aac2mp3.mp3');
# aac-lc → wav
\Xiaosongshu\Flv2mp4\Client::runAac2Wav(__DIR__ . '/input.aac',__DIR__ . '/aac2wav.wav');
# wav → aac-lc
\Xiaosongshu\Flv2mp4\Client::runWav2Aac(__DIR__ . '/input.wav',__DIR__ . '/wav2aac.aac');
# opus → wav
\Xiaosongshu\Flv2mp4\Client::runOpus2Wav(__DIR__ . '/input.opus',__DIR__ . '/opus2wav.wav');
# mp3 → wav
\Xiaosongshu\Flv2mp4\Client::runMp32Wav(__DIR__ . '/input.mp3',__DIR__ . '/mp32wav.wav');
# wav → mp3
\Xiaosongshu\Flv2mp4\Client::runWav2Mp3(__DIR__ . '/input.wav',__DIR__ . '/wav2mp3.mp3');
# opus → mp3
\Xiaosongshu\Flv2mp4\Client::runOpus2Mp3(__DIR__ . '/input.opus',__DIR__ . '/opus2mp3.mp3');
# opus → aac-lc
\Xiaosongshu\Flv2mp4\Client::runOpus2Aac(__DIR__ . '/input.opus',__DIR__ . '/opus2aac.aac');
# mp3 → aac-lc
\Xiaosongshu\Flv2mp4\Client::runMp32Aac(__DIR__ . '/input.mp3',__DIR__ . '/mp32aac.aac');
# mp3 → opus
\Xiaosongshu\Flv2mp4\Client::runMp32Opus(__DIR__ . '/input.mp3', __DIR__ . '/mp32opus.opus');
# wav → opus
\Xiaosongshu\Flv2mp4\Client::runWav2Opus(__DIR__ . '/input.wav', __DIR__ . '/wav2opus.opus');
# aac-lc → opus 
\Xiaosongshu\Flv2mp4\Client::runAac2Opus(__DIR__ . '/input.aac', __DIR__ . '/aac2opus.opus');

🔧 技术说明

• 纯 PHP 8.1+ 实现，无 FFmpeg 依赖
• 项目地址：github.com/2723659854/flv2mp4
• 当前项目最初主要是为 xiaosongshu/rtmp_server 提供服务
• 建议使用 PHPStan Level 8 进行静态分析
• H.264 重编码采用分布式多进程架构，充分利用多CPU资源，若服务器是单核则建议关闭分布式。

开源协议 & 免责声明

• 开源协议：本项目基于 Apache License 2.0 开源，允许自由使用、修改、分发（含商业用途）。代码按“现状”（AS IS）提供，不提供任何明示或暗示的担保，作者不对因使用本软件而产生的任何损害承担责任。
• 专利风险提示：本项目包含 H.264、AAC-LC、MP3 等受专利保护的音视频编解码器纯 PHP 实现。上述开源协议仅授予版权许可，不包含任何专利授权。
• 使用限制与责任转移：上述编解码器实现仅供学习、研究、测试和个人非商业使用。若使用者将其用于任何商业产品分发或商业运营，请自行向相关专利授权方（如 Via Licensing、MPEG LA、Fraunhofer IIS 等）获取合法的专利授权，并自行承担全部专利侵权风险。本项目作者不承担由此产生的任何专利侵权责任。
• 最终解释权：若您使用本项目，即视为您已阅读、理解并同意本免责声明的全部条款。

📧 联系方式

• 📬 邮箱：2723659854@qq.com
• 🐙 GitHub：2723659854

本作品采用《CC 协议》，转载必须注明作者和本文链接