PhxMediaLibrary.VideoProcessor.FFmpeg (PhxMediaLibrary v0.6.1)

Copy Markdown View Source

Video processor implementation using ffprobe and ffmpeg.

Requires both executables to be installed and available on $PATH. Used automatically when available?/0 returns true.

Metadata extraction

Runs:

ffprobe -v quiet -print_format json -show_streams -show_format <file>

and parses the JSON output to produce:

  • "duration" — total duration in seconds (float)
  • "width" / "height" — video stream dimensions (integer)
  • "codec" — video codec name, e.g. "h264" or "vp9" (string)
  • "fps" — frames per second derived from r_frame_rate, e.g. 30.0 (float)
  • "audio_codec" — first audio stream codec, e.g. "aac" (string, optional)
  • "bit_rate" — overall bit rate in bits/s from the format section (integer, optional)

Poster frame extraction

Runs:

ffmpeg -ss <offset> -i <file> -frames:v 1 -f image2pipe -vcodec mjpeg pipe:1

and returns the raw JPEG bytes.

Availability

available?/0 checks for both ffprobe and ffmpeg via System.find_executable/1. Returns false if either is missing, causing the library to fall back to PhxMediaLibrary.VideoProcessor.Null silently.

Installation

# macOS
brew install ffmpeg

# Ubuntu / Debian
apt-get install ffmpeg

Summary

Functions

available?()

Returns true when both ffprobe and ffmpeg are found on $PATH.

extract_metadata(file_path)

Extract metadata from a video file using ffprobe.

extract_poster(file_path, offset_seconds \\ 0.0)

Extract a JPEG poster frame from a video using ffmpeg.

Functions

available?()

@spec available?() :: boolean()

Returns true when both ffprobe and ffmpeg are found on $PATH.

extract_metadata(file_path)

@spec extract_metadata(String.t()) :: {:ok, map()} | {:error, term()}

Extract metadata from a video file using ffprobe.

Returns {:ok, metadata} on success, or {:error, reason} on failure. Returns {:error, :ffmpeg_not_available} when ffprobe is not on $PATH.

extract_poster(file_path, offset_seconds \\ 0.0)

@spec extract_poster(String.t(), float()) :: {:ok, binary()} | {:error, term()}

Extract a JPEG poster frame from a video using ffmpeg.

offset_seconds specifies where in the video to capture the frame and is clamped to >= 0.0. Returns {:ok, jpeg_binary} on success. Returns {:error, :ffmpeg_not_available} when ffmpeg is not on $PATH.