PHP-FFmpeg 使用中文详细文档

php-ffmpeg 是一个基于 PHP 的强大多媒体处理库，它封装了 FFmpeg 命令行工具的功能，允许你在 PHP 程序中方便地进行音视频转码、截图、裁剪、合并、提取音频等操作。该项目由 PHP-FFMpeg/PHP-FFMpeg 维护。

本教程将全面介绍 php-ffmpeg 的安装、配置和使用方法，并附带大量实用示例，适合初学者到进阶开发者参考。

---

📦 一、环境准备与安装

1.1 安装要求

• PHP >= 7.4（推荐 8.0+）
• FFmpeg 可执行文件已安装在系统中
• Composer 包管理器
• 允许 shell 执行权限（用于调用外部命令）

注意：php-ffmpeg 只是 FFmpeg 的封装，不包含 FFmpeg 本身！

---

1.2 安装 FFmpeg

Linux (Ubuntu/Debian)

sudo apt update
sudo apt install ffmpeg -y

验证是否安装成功：

ffmpeg -version

macOS

使用 Homebrew：

brew install ffmpeg

Windows

前往官网下载静态构建版本：
👉 https://www.gyan.dev/ffmpeg/builds/

解压后将 bin/ffmpeg.exe 路径添加到系统环境变量 PATH 中。

测试：

ffmpeg -version

---

1.3 安装 php-ffmpeg 库（通过 Composer）

composer require php-ffmpeg/php-ffmpeg

💡 提示：某些系统可能需要额外扩展支持，如 ffmpeg PHP 扩展不是必需的，该库使用进程调用方式运行 ffmpeg 命令。

---

⚙️ 二、基本配置与初始化

require_once 'vendor/autoload.php';

use FFMpeg\FFMpeg;
use FFMpeg\Coordinate\Dimension;
use FFMpeg\Format\Video\X264;
use FFMpeg\Coordinate\TimeCode;

// 创建 FFMpeg 实例
$ffmpeg = FFMpeg::create([
    'ffmpeg.binaries'  => '/usr/bin/ffmpeg', // 自定义路径（可选）
    'ffprobe.binaries' => '/usr/bin/ffprobe', // 必须安装 ffprobe
    'timeout'          => 3600,               // 进程超时时间（秒）
    'ffmpeg.threads'   => 4,                  // 使用线程数
]);

✅ 如果你不确定路径，在终端输入 which ffmpeg 和 which ffprobe 查看位置。

---

🎬 三、核心功能详解 + 示例代码

---

🔹 功能一：读取媒体信息（Metadata）

获取视频或音频的基本信息，如时长、分辨率、码率、编码格式等。

$video = $ffmpeg->open('path/to/video.mp4');

// 获取流信息
$ffprobe = $ffmpeg->getFFProbe();
$duration = $ffprobe->format('path/to/video.mp4')->get('duration'); // 单位：秒
$bitrate = $ffprobe->format('path/to/video.mp4')->get('bit_rate');

// 视频流详情
$videoStreams = $ffprobe->streams('path/to/video.mp4');
foreach ($videoStreams as $stream) {
   
   
    if ($stream->isVideo()) {
   
   
        echo "分辨率: " . $stream->get('width') . 'x' . $stream->get('height') . "\n";
        echo "帧率: " . $stream->get('r_frame_rate') . "\n";
        echo "编解码器: " . $stream->get('codec_name') . "\n";
    }
}

---

🔹 功能二：视频转码（Convert Video）

将视频转换为其他格式或调整参数（如 H.264 编码 MP4 输出）。

$video = $ffmpeg->open('input.mp4');

$format = new X264(); // 使用 H.264 编码
$format->setKiloBitrate(1000); // 设置比特率为 1000kbps
$format->setAudioCodec("aac"); // 音频编码
$format->setAudioKiloBitrate(128);

$video