CoolCMS API

FfmpegService
in package

Wraps the `ffmpeg` CLI to extract a poster frame from a video.

ffmpeg is an optional dependency: when it is missing, isAvailable() returns false and the video upload continues without a poster (a catch-up cron fills it in later).

The command -v ffmpeg detection is cached per request (singleton service).

Table of Contents

Constants

FORMAT_MOV  : string = 'mov'
FORMAT_MP4  : string = 'mp4'

Properties

$availableCache  : bool|null
$binaryPath  : string|null
$ffmpegBinary  : string|null
$probeBinaryPath  : string|null
null = not resolved yet, '' = `ffprobe` unavailable, otherwise the binary path.

Methods

__construct()  : mixed
extractFirstFrame()  : bool
Extracts the first video frame to `$outputPath` as a jpg.
getVideoDimensions()  : array{width: int, height: int}|null
Returns the native video dimensions via `ffprobe` (best effort), or null when `ffprobe` is missing, the file does not exist or the probe fails.
isAvailable()  : bool
isProbeAvailable()  : bool
Whether `ffprobe` is available. Without it a video cannot be verified and the upload is rejected.
normalizeFormat()  : string
Allowed input formats for `-f`; anything else falls back to `mp4` (same demuxer).
probeVideoContainer()  : string|null
Verifies that the file is a video in an `mp4`/QuickTime container with at least one video track. Returns the format for the forced demuxer ({@see FORMAT_MP4} / {@see FORMAT_MOV}), or null when `ffprobe` is missing, the file is not a video or it uses another container.
resolveProbeBinary()  : string|null
Finds the `ffprobe` binary (next to `ffmpeg`, in `$PATH` or common locations). The result is cached.
runWithTimeout()  : string|null
Runs a command with a time limit and returns stdout; null on a non-zero exit, a timeout or an error.

Constants

Properties

$ffmpegBinary read-only

private string|null $ffmpegBinary = null

$probeBinaryPath

null = not resolved yet, '' = `ffprobe` unavailable, otherwise the binary path.

private string|null $probeBinaryPath = null

Methods

__construct()

public __construct([string|null $ffmpegBinary = null ]) : mixed
Parameters
$ffmpegBinary : string|null = null

extractFirstFrame()

Extracts the first video frame to `$outputPath` as a jpg.

public extractFirstFrame(string $videoPath, string $outputPath[, int $timeoutSec = 30 ][, string $format = self::FORMAT_MP4 ]) : bool

Returns true on success and false on any error (silent: errors only go to the Tracy log).

Parameters
$videoPath : string
$outputPath : string
$timeoutSec : int = 30
$format : string = self::FORMAT_MP4
Return values
bool

getVideoDimensions()

Returns the native video dimensions via `ffprobe` (best effort), or null when `ffprobe` is missing, the file does not exist or the probe fails.

public getVideoDimensions(string $videoPath) : array{width: int, height: int}|null
Parameters
$videoPath : string
Return values
array{width: int, height: int}|null

isAvailable()

public isAvailable() : bool
Return values
bool

isProbeAvailable()

Whether `ffprobe` is available. Without it a video cannot be verified and the upload is rejected.

public isProbeAvailable() : bool
Return values
bool

normalizeFormat()

Allowed input formats for `-f`; anything else falls back to `mp4` (same demuxer).

public static normalizeFormat(string $format) : string
Parameters
$format : string
Return values
string

probeVideoContainer()

Verifies that the file is a video in an `mp4`/QuickTime container with at least one video track. Returns the format for the forced demuxer ({@see FORMAT_MP4} / {@see FORMAT_MOV}), or null when `ffprobe` is missing, the file is not a video or it uses another container.

public probeVideoContainer(string $videoPath[, int $timeoutSec = 15 ]) : string|null

ffprobe runs with the forced mov demuxer (mp4 and mov share one) and a local-only protocol, so the content cannot switch it to a streaming or concat input. The two are told apart by major_brand (qt = QuickTime).

Parameters
$videoPath : string
$timeoutSec : int = 15
Return values
string|null

resolveProbeBinary()

Finds the `ffprobe` binary (next to `ffmpeg`, in `$PATH` or common locations). The result is cached.

private resolveProbeBinary() : string|null
Return values
string|null

runWithTimeout()

Runs a command with a time limit and returns stdout; null on a non-zero exit, a timeout or an error.

private runWithTimeout(string $cmd, int $timeoutSec) : string|null
Parameters
$cmd : string
$timeoutSec : int
Return values
string|null
On this page

Search results