README

一个面向对象的库，用于使用 FFmpeg / AVConv 转换视频/音频文件。

请注意

此库的工作原理

此库需要一个有效的 FFMpeg 安装。您需要 FFMpeg 和 FFProbe 的二进制文件来使用它。请确保这些二进制文件可以通过系统 PATH 定位以获得二进制检测的好处，否则您必须在加载时明确给出二进制文件路径。

已知问题

• 当使用 libav 0.8 时，使用旋转和缩放将产生损坏的输出。该错误已在版本 9 中修复。此错误在最新的 FFmpeg 版本中不会出现。

安装

此库需要 PHP 8.0 或更高版本。对于旧版本的 PHP，请查看 0.x-分支。

安装 PHP-FFMpeg 的推荐方法是使用 Composer。

$ composer require php-ffmpeg/php-ffmpeg

基本用法

require 'vendor/autoload.php';

$ffmpeg = FFMpeg\FFMpeg::create();
$video = $ffmpeg->open('video.mpg');
$video
    ->filters()
    ->resize(new FFMpeg\Coordinate\Dimension(320, 240))
    ->synchronize();
$video
    ->frame(FFMpeg\Coordinate\TimeCode::fromSeconds(10))
    ->save('frame.jpg');
$video
    ->save(new FFMpeg\Format\Video\X264(), 'export-x264.mp4')
    ->save(new FFMpeg\Format\Video\WMV(), 'export-wmv.wmv')
    ->save(new FFMpeg\Format\Video\WebM(), 'export-webm.webm');

文档

此文档是了解 API 的入门。建议浏览源代码，因为它具有自带的文档。

FFMpeg

FFMpeg\FFMpeg 是用于操作媒体的主要对象。要构建它，请使用静态 FFMpeg\FFMpeg::create

$ffmpeg = FFMpeg\FFMpeg::create();

FFMpeg 将自动检测 ffmpeg 和 ffprobe 二进制文件。如果您想明确提供二进制文件路径，可以将数组作为配置传递。也可以传递一个 Psr\Logger\LoggerInterface 以记录二进制执行。

$ffmpeg = FFMpeg\FFMpeg::create(array(
    'ffmpeg.binaries'  => '/opt/local/ffmpeg/bin/ffmpeg',
    'ffprobe.binaries' => '/opt/local/ffmpeg/bin/ffprobe',
    'timeout'          => 3600, // The timeout for the underlying process
    'ffmpeg.threads'   => 12,   // The number of threads that FFMpeg should use
), $logger);

您可以通过传递一个 temporary_directory 键来指定临时文件的路径。

$ffmpeg = FFMpeg\FFMpeg::create(array(
    'temporary_directory' => '/var/ffmpeg-tmp'
), $logger);

操作媒体

FFMpeg\FFMpeg 根据 URI 创建媒体。URI 可以是本地文件系统资源的指针、HTTP 资源或 FFmpeg 支持的任何资源。

注意：要列出您 FFmpeg 构建支持的资源类型，请使用 -protocols 命令

ffmpeg -protocols

要打开资源，请使用 FFMpeg\FFMpeg::open 方法。

$ffmpeg->open('video.mpeg');

可以解析两种类型的媒体：FFMpeg\Media\Audio 和 FFMpeg\Media\Video。第三种类型 FFMpeg\Media\Frame 通过视频提供。

视频

FFMpeg\Media\Video 可以进行转码，即：更改编解码器、提取音频或视频。可以提取帧。

转码

您可以使用 FFMpeg\Media\Video:save 方法进行视频转码。您需要传递一个 FFMpeg\Format\FormatInterface。

请注意，音频和视频比特率在格式中设置。您可以通过将千比特率设置为 0 来禁用 -b:v 选项。

$format = new FFMpeg\Format\Video\X264();
$format->on('progress', function ($video, $format, $percentage) {
    echo "$percentage % transcoded";
});

$format
    ->setKiloBitrate(1000)
    ->setAudioChannels(2)
    ->setAudioKiloBitrate(256);

$video->save($format, 'video.avi');

实时监控转码进度，请参阅下面的格式文档以获取更多信息。

提取图像

您可以使用 FFMpeg\Media\Video::frame 方法在任何时间码提取帧。

此代码返回一个与第 42 秒对应的 FFMpeg\Media\Frame 实例。您可以将任何 FFMpeg\Coordinate\TimeCode 作为参数传递，请参阅下面的专用文档以获取更多信息。

$frame = $video->frame(FFMpeg\Coordinate\TimeCode::fromSeconds(42));
$frame->save('image.jpg');

如果您想从视频中提取多个图像，可以使用以下过滤器

$video
    ->filters()
    ->extractMultipleFrames(FFMpeg\Filters\Video\ExtractMultipleFramesFilter::FRAMERATE_EVERY_10SEC, '/path/to/destination/folder/')
    ->synchronize();

$video
    ->save(new FFMpeg\Format\Video\X264(), '/path/to/new/file');

默认情况下，这将保存帧为 jpg 图像。

您可以使用 setFrameFileType 覆盖此设置，以将帧保存为其他格式

$frameFileType = 'jpg'; // either 'jpg', 'jpeg' or 'png'
$filter = new ExtractMultipleFramesFilter($frameRate, $destinationFolder);
$filter->setFrameFileType($frameFileType);

$video->addFilter($filter);

剪辑

在指定点切割视频。使用输入搜索方法。这是比使用过滤器剪辑更快的选项。

$clip = $video->clip(FFMpeg\Coordinate\TimeCode::fromSeconds(30), FFMpeg\Coordinate\TimeCode::fromSeconds(15));
$clip->save(new FFMpeg\Format\Video\X264(), 'video.avi');

剪辑过滤器需要两个参数

• $start，一个 FFMpeg\Coordinate\TimeCode 的实例，指定剪辑的起点
• $duration，可选，一个 FFMpeg\Coordinate\TimeCode 的实例，指定剪辑的持续时间

在剪辑中，你可以应用与视频上相同的过滤器，例如调整大小过滤器。

$clip = $video->clip(FFMpeg\Coordinate\TimeCode::fromSeconds(30), FFMpeg\Coordinate\TimeCode::fromSeconds(15));
$clip->filters()->resize(new FFMpeg\Coordinate\Dimension(320, 240), FFMpeg\Filters\Video\ResizeFilter::RESIZEMODE_INSET, true);
$clip->save(new FFMpeg\Format\Video\X264(), 'video.avi');

生成波形图

你可以使用 FFMpeg\Media\Audio::waveform 方法生成音频文件的波形图。

此代码返回一个 FFMpeg\Media\Waveform 实例。你可以选择性地传递尺寸作为前两个参数，以及ffmpeg用于波形图的十六进制字符串颜色数组，有关更多信息，请参阅下面的专用文档。

输出文件必须使用PNG扩展名。

$waveform = $audio->waveform(640, 120, array('#00FF00'));
$waveform->save('waveform.png');

如果你想要从视频中获取波形图，首先将其转换为音频文件。

// Open your video file
$video = $ffmpeg->open( 'video.mp4' );

// Set an audio format
$audio_format = new FFMpeg\Format\Audio\Mp3();

// Extract the audio into a new file as mp3
$video->save($audio_format, 'audio.mp3');

// Set the audio file
$audio = $ffmpeg->open( 'audio.mp3' );

// Create the waveform
$waveform = $audio->waveform();
$waveform->save( 'waveform.png' );

过滤器

你可以使用 FFMpeg\Media\Video::addFilter 方法在 FFMpeg\Media\Video 上应用过滤器。视频接受音频和视频过滤器。

你可以构建自己的过滤器，PHP-FFMpeg 中包含了一些，它们可以通过 FFMpeg\Media\Video::filters 方法访问。

过滤器是可链的

$video
    ->filters()
    ->resize($dimension, $mode, $useStandards)
    ->framerate($framerate, $gop)
    ->synchronize();

旋转

将视频旋转到指定角度。

$video->filters()->rotate($angle);

$angle 参数必须是以下常量之一：

• FFMpeg\Filters\Video\RotateFilter::ROTATE_90：顺时针90°
• FFMpeg\Filters\Video\RotateFilter::ROTATE_180：180°
• FFMpeg\Filters\Video\RotateFilter::ROTATE_270：逆时针90°

调整大小

将视频调整到指定大小。

$video->filters()->resize($dimension, $mode, $useStandards);

调整大小过滤器需要三个参数：

• $dimension，一个 FFMpeg\Coordinate\Dimension 实例
• $mode，FFMpeg\Filters\Video\ResizeFilter::RESIZEMODE_* 常量之一
• $useStandards，一个布尔值，用于强制使用最接近的宽高比标准。

如果你想要一个非标准比例的视频，你可以使用填充过滤器将视频调整到所需大小，并将其包裹在黑色边框中。

$video->filters()->pad($dimension);

填充过滤器需要一个参数

• $dimension，一个 FFMpeg\Coordinate\Dimension 实例

之后不要忘记保存。

$video->save(new FFMpeg\Format\Video\X264(), $new_file);

水印

使用给定图像给视频添加水印。

$video
    ->filters()
    ->watermark($watermarkPath, array(
        'position' => 'relative',
        'bottom' => 50,
        'right' => 50,
    ));

水印过滤器需要两个参数：

$watermarkPath，水印文件的路径。$coordinates，一个定义水印位置的数组。你可以使用如上所示的相对定位或绝对定位

$video
    ->filters()
    ->watermark($watermarkPath, array(
        'position' => 'absolute',
        'x' => 1180,
        'y' => 620,
    ));

帧率

更改视频的帧率。

$video->filters()->framerate($framerate, $gop);

帧率过滤器需要两个参数：

• $framerate，一个 FFMpeg\Coordinate\FrameRate 实例
• $gop，一个 GOP 值（整数）

同步

同步音频和视频。

某些容器可能使用延迟，导致输出不同步。此过滤器解决了这个问题。

$video->filters()->synchronize();

剪辑

在指定点切割视频。

$video->filters()->clip(FFMpeg\Coordinate\TimeCode::fromSeconds(30), FFMpeg\Coordinate\TimeCode::fromSeconds(15));

剪辑过滤器需要两个参数

• $start，一个 FFMpeg\Coordinate\TimeCode 的实例，指定剪辑的起点
• $duration，可选，一个 FFMpeg\Coordinate\TimeCode 的实例，指定剪辑的持续时间

裁剪

根据宽度和高度（一个 Point）裁剪视频。

$video->filters()->crop(new FFMpeg\Coordinate\Point("t*100", 0, true), new FFMpeg\Coordinate\Dimension(200, 600));

它需要两个参数：

• $point，一个 FFMpeg\Coordinate\Point 实例，指定裁剪点
• $dimension，一个 FFMpeg\Coordinate\Dimension 实例，指定输出视频的尺寸

音频

FFMpeg\Media\Audio 也可以进行转码，即：更改编解码器、分离音频或视频。可以提取帧。

转码

你可以使用 FFMpeg\Media\Audio:save 方法转码音频。你需要传递一个 FFMpeg\Format\FormatInterface。

请注意，音频千比特率是在音频格式上设置的。

$ffmpeg = FFMpeg\FFMpeg::create();
$audio = $ffmpeg->open('track.mp3');

$format = new FFMpeg\Format\Audio\Flac();
$format->on('progress', function ($audio, $format, $percentage) {
    echo "$percentage % transcoded";
});

$format
    ->setAudioChannels(2)
    ->setAudioKiloBitrate(256);

$audio->save($format, 'track.flac');

实时监控转码进度，请参阅下面的格式文档以获取更多信息。

过滤器

你可以使用 FFMpeg\Media\Audio::addFilter 方法在 FFMpeg\Media\Audio 上应用过滤器。它只接受音频过滤器。

你可以构建自己的过滤器，PHP-FFMpeg 中包含了一些，它们可以通过 FFMpeg\Media\Audio::filters 方法访问。

剪辑

在指定点切割音频。

$audio->filters()->clip(FFMpeg\Coordinate\TimeCode::fromSeconds(30), FFMpeg\Coordinate\TimeCode::fromSeconds(15));

元数据

向音频文件添加元数据。只需传递一个包含所有要添加的元数据的键=值对的数组。如果没有传递参数到过滤器，则将从输入文件中删除所有元数据。目前支持的数据包括标题、艺术家、专辑、作曲家、曲目、年份、描述、封面

$audio->filters()->addMetadata(["title" => "Some Title", "track" => 1]);

//remove all metadata and video streams from audio file
$audio->filters()->addMetadata();

向音频文件添加封面

$audio->filters()->addMetadata(["artwork" => "/path/to/image/file.jpg"]);

注意：目前ffmpeg（版本3.2.2）仅支持.mp3文件的封面输出

重采样

重采样音频文件。

$audio->filters()->resample($rate);

重采样过滤器需要两个参数

• $rate，一个有效的音频采样率值（整数）

帧

帧是视频在某个时间码处的图像；请参阅上面的文档了解帧提取。

您可以使用 FFMpeg\Media\Frame::save 方法保存帧。

$frame->save('target.jpg');

此方法有一个可选的第二个布尔参数。将其设置为 true 以获取准确的图像；执行时间会更长。

GIF

GIF 是从视频序列中提取的动画图像。

您可以使用 FFMpeg\Media\Gif::save 方法保存 GIF 文件。

$video = $ffmpeg->open( '/path/to/video' );
$video
    ->gif(FFMpeg\Coordinate\TimeCode::fromSeconds(2), new FFMpeg\Coordinate\Dimension(640, 480), 3)
    ->save($new_file);

此方法有一个第三个可选的布尔参数，即动画的持续时间。如果您不设置它，您将获得一个固定的 GIF 图像。

连接

此功能允许您基于多个来源生成一个音频或视频文件。

根据来源的编解码器，有两种连接视频的方法。如果您的来源都使用相同的编解码器进行编码，您将希望使用 FFMpeg\Media\Concatenate::saveFromSameCodecs，它具有更好的性能。如果您的来源使用不同的编解码器进行编码，您将希望使用 FFMpeg\Media\Concatenate::saveFromDifferentCodecs。

第一个函数将使用初始编解码器作为生成文件的编解码器。使用第二个函数，您可以选择生成文件想要的编解码器。

您还需要注意，当使用 saveFromDifferentCodecs 方法时，您的文件必须包含视频和音频流。

在两种情况下，您都必须提供一个文件数组。

要连接具有相同编解码器的视频，请按照以下步骤操作

// In order to instantiate the video object, you HAVE TO pass a path to a valid video file.
// We recommend that you put there the path of any of the video you want to use in this concatenation.
$video = $ffmpeg->open( '/path/to/video' );
$video
    ->concat(array('/path/to/video1', '/path/to/video2'))
    ->saveFromSameCodecs('/path/to/new_file', TRUE);

保存函数的布尔参数允许您使用复制参数，这可以极大地加速编码文件的生成。

要连接使用不同编解码器的视频，请按照以下步骤操作

// In order to instantiate the video object, you HAVE TO pass a path to a valid video file.
// We recommend that you put there the path of any of the video you want to use in this concatenation.
$video = $ffmpeg->open( '/path/to/video' );

$format = new FFMpeg\Format\Video\X264();
$format->setAudioCodec("libmp3lame");

$video
    ->concat(array('/path/to/video1', '/path/to/video2'))
    ->saveFromDifferentCodecs($format, '/path/to/new_file');

有关 FFMPEG 中连接的更多详细信息，请参阅 此处、此处 和 此处。

高级媒体

高级媒体可能有多个输入和多个输出。

此类主要开发用于与 -filter_complex 一起使用。

因此，其 filters() 方法只接受可以在 -filter_complex 命令内部使用的过滤器。高级媒体已经包含一些内置的过滤器。

基本用法

例如

$advancedMedia = $ffmpeg->openAdvanced(array('video_1.mp4', 'video_2.mp4'));
$advancedMedia->filters()
    ->custom('[0:v][1:v]', 'hstack', '[v]');
$advancedMedia
    ->map(array('0:a', '[v]'), new X264('aac', 'libx264'), 'output.mp4')
    ->save();

此代码获取 2 个输入视频，将它们水平堆叠成 1 个输出视频，并将第一个视频的音频添加到新视频中。（在只有 1 个输入和 1 个输出的简单过滤器图中是不可能的）。

复杂示例

这是高级媒体可能性的更复杂示例。假设所有输入视频都已经具有相同的分辨率和持续时间。（"xstack" 过滤器已添加到 ffmpeg 的 4.1 版本中）。

$inputs = array(
    'video_1.mp4',
    'video_2.mp4',
    'video_3.mp4',
    'video_4.mp4',
);

$advancedMedia = $ffmpeg->openAdvanced($inputs);
$advancedMedia->filters()
    ->custom('[0:v]', 'negate', '[v0negate]')
    ->custom('[1:v]', 'edgedetect', '[v1edgedetect]')
    ->custom('[2:v]', 'hflip', '[v2hflip]')
    ->custom('[3:v]', 'vflip', '[v3vflip]')
    ->xStack('[v0negate][v1edgedetect][v2hflip][v3vflip]', XStackFilter::LAYOUT_2X2, 4, '[resultv]');
$advancedMedia
    ->map(array('0:a'), new Mp3(), 'video_1.mp3')
    ->map(array('1:a'), new Flac(), 'video_2.flac')
    ->map(array('2:a'), new Wav(), 'video_3.wav')
    ->map(array('3:a'), new Aac(), 'video_4.aac')
    ->map(array('[resultv]'), new X264('aac', 'libx264'), 'output.mp4')
    ->save();

此代码获取 4 个输入视频，然后对第一个视频进行取反，将结果存储在 [v0negate] 流中，检测第二个视频的边缘，将结果存储在 [v1edgedetect] 流中，水平翻转第三个视频，将结果存储在 [v2hflip] 流中，垂直翻转第四个视频，将结果存储在 [v3vflip] 流中，然后取这 4 个生成的流并组合成一个 2x2 的拼贴视频。然后将原始视频的音频保存到 4 个不同的格式，并将生成的拼贴视频保存到单独的文件中。

如您所见，您可以在同一个 ffmpeg 命令中同时使用多个输入源，对它们进行复杂的处理，并生成多个输出文件。

只给我一个映射！

您不必使用 -filter_complex。您可以使用仅 -map 选项。例如，仅从视频中提取音频

$advancedMedia = $ffmpeg->openAdvanced(array('video.mp4'));
$advancedMedia
    ->map(array('0:a'), new Mp3(), 'output.mp3')
    ->save();

自定义

如果需要，您可以额外自定义 AdvancedMedia 的结果 ffmpeg 命令。

$advancedMedia = $ffmpeg->openAdvanced($inputs);
$advancedMedia
    ->setInitialParameters(array('the', 'params', 'that', 'will', 'be', 'added', 'before', '-i', 'part', 'of', 'the', 'command'))
    ->setAdditionalParameters(array('the', 'params', 'that', 'will', 'be', 'added', 'at', 'the', 'end', 'of', 'the', 'command'));

格式

一个格式实现了 FFMpeg\Format\FormatInterface。要保存到视频文件，请使用 FFMpeg\Format\VideoInterface，音频文件请使用 FFMpeg\Format\AudioInterface。

格式还可以扩展 FFMpeg\Format\ProgressableInterface 以获取转码的实时信息。

预定义格式已经提供进度信息作为事件。

$format = new FFMpeg\Format\Video\X264();
$format->on('progress', function ($video, $format, $percentage) {
    echo "$percentage % transcoded";
});

$video->save($format, 'video.avi');

为事件提供的回调可以是任何可调用的。

添加附加参数

您可以根据视频格式向编码请求添加附加参数。

setAdditionalParameters 方法的参数是一个数组。

$format = new FFMpeg\Format\Video\X264();
$format->setAdditionalParameters(array('foo', 'bar'));
$video->save($format, 'video.avi');

添加初始参数

您还可以根据视频格式向编码请求添加初始参数。这特别方便在覆盖 FFMpeg 中的默认输入编解码器时使用。

setInitialParameters 方法的参数是一个数组。

$format = new FFMpeg\Format\Video\X264();
$format->setInitialParameters(array('-acodec', 'libopus'));
$video->save($format, 'video.avi');

创建自己的格式

创建格式最简单的方法是扩展抽象的 FFMpeg\Format\Video\DefaultVideo 和 FFMpeg\Format\Audio\DefaultAudio，并实现以下方法。

class CustomWMVFormat extends FFMpeg\Format\Video\DefaultVideo
{
    public function __construct($audioCodec = 'wmav2', $videoCodec = 'wmv2')
    {
        $this
            ->setAudioCodec($audioCodec)
            ->setVideoCodec($videoCodec);
    }

    public function supportBFrames()
    {
        return false;
    }

    public function getAvailableAudioCodecs()
    {
        return array('wmav2');
    }

    public function getAvailableVideoCodecs()
    {
        return array('wmv2');
    }
}

坐标

FFMpeg 使用许多时间和空间坐标的单位。

• FFMpeg\Coordinate\AspectRatio 表示宽高比。
• FFMpeg\Coordinate\Dimension 表示一个维度。
• FFMpeg\Coordinate\FrameRate 表示帧率。
• FFMpeg\Coordinate\Point 表示一个点。（从 v0.10.0 开始支持动态点）
• FFMpeg\Coordinate\TimeCode 表示时间码。

FFProbe

FFMpeg\FFProbe 是 FFMpeg\FFMpeg 内部使用的，用于探测媒体。您也可以用它来提取媒体元数据。

$ffprobe = FFMpeg\FFProbe::create();
$ffprobe
    ->streams('/path/to/video/mp4') // extracts streams informations
    ->videos()                      // filters video streams
    ->first()                       // returns the first video stream
    ->get('codec_name');            // returns the codec_name property

$ffprobe = FFMpeg\FFProbe::create();
$ffprobe
    ->format('/path/to/video/mp4') // extracts file informations
    ->get('duration');             // returns the duration property

验证媒体文件

（自 0.10.0 版起）您可以使用 PHP-FFMpeg 的 FFProbe 包装器验证媒体文件。

$ffprobe = FFMpeg\FFProbe::create();
$ffprobe->isValid('/path/to/file/to/check'); // returns bool

许可证

本项目遵循 MIT 许可证。

音乐：Waylon Thornton 的 "Favorite Secrets"，来自 Free Music Archive CC BY NC SA

音乐：Jahzzar 的 "Siesta"，来自 Free Music Archive CC BY SA