Rand Stats

FFmpegProgressBar

zef:sasha

FFmpegProgressBar

A Raku module that adds a progress bar to ffmpeg commands.

output.mp4 ████████████░░░░░░ 75% 00:00:05 ETA: 2s

With optional frame/bitrate info:

output.mp4 ████████████░░░░░░ 75% 00:00:05 ETA: 2s [750/1000 (25.5fps)] (2.5Mbps)

Features

Requirements

Installation

zef install ffmpegprogressbar

Installing from source

To install from a local folder:

cd /path/to/FFmpegProgressBar
zef install .

Usage

Command Line

ffpb -i input.mp4 -c:v libx264 output.mp4

Command Line Options

Library

use FFmpegProgressBar;

my $progress = FfmpegProgress.new(:duration(30), :verbose(True));
$progress.run('-i', 'input.mp4', 'output.mp4');

Or use the subroutine interface:

ffmpeg-progress(
    '-i', 'input.mp4',
    '-c:v', 'libx264',
    'output.mp4',
    :duration(30),
:verbose(True)
)

Library Options

Library Methods

use FFmpegProgressBar;

my $ff = FfmpegProgress.new(:duration(30), :verbose(True));
$ff.run('-i', 'input.mp4', 'output.mp4');

# Or control externally:
my $ff2 = FfmpegProgress.new(:ffmpeg('/path/to/ffmpeg'));
$ff2.run('-i', 'input.mp4', 'output.mp4');
# ... in another thread or loop:
$ff2.quit() if $some-condition;
$ff2.quit(:force);  # force kill

Progress Tracking API

FFmpegProgressBar provides three ways to monitor encoding progress externally:

Simple async iteration that yields percent directly. Use :quiet to suppress the progress bar:

use FFmpegProgressBar;

my $p = FfmpegProgress.new(:quiet);
my $promise = start { $p.run('-i', 'input.mp4', 'output.mp4') };

for $p.watch-progress(:interval(0.5)) -> $percent {
    say "Progress: {$percent.fmt('%.1f')}%";
    $p.quit() if $percent >= 50;
}

await $promise;
say $p.get-progress().summary;

With full snapshots (watch-progress(:emit)):

for $p.watch-progress(:emit) -> $snap {
    say $snap.summary;
    $p.quit() if $snap.is-stalled;
}

get-progress()

One-off read - returns a ProgressSnapshot:

my $snap = $p.get-progress();
say $snap.percent;       # 75.0
say $snap.fps;          # 25.0
say $snap.is-complete;  # Bool
say $snap.is-failed;    # Bool
say $snap.summary;

progress-supply()

Reactive supply for event-driven code:

$p.progress-supply.tap: -> $snap {
    say "Progress: {$snap.percent.fmt('%.1f')}%";
};

The progress API returns time-based percentage that matches the progress bar exactly.

Dotfile Configuration

You can create a config file to set default options. The following paths are checked in order:

Unix/Linux/macOS

Windows

Each line should contain one option (like CLI arguments). Lines starting with # are treated as comments.

Example ~/.ffpbrc:

# Always show verbose info, frame info and use hash style
-V
-F
-S hash

Examples

# Basic encoding
ffpb -i input.mp4 output.mkv

# With verbose output
ffpb -V -i input.mp4 output.mp4

# With frames and bitrate
ffpb -F -B -i input.mp4 output.mp4

# With custom bar style
ffpb -S hash -i input.mp4 output.mp4

# With duration override
ffpb -D 60 -i input.mp4 output.mp4

# With custom ffmpeg/ffprobe paths
ffpb -M /usr/bin/ffmpeg -P /usr/bin/ffprobe -i input.mp4 output.mp4

# Show stderr on success
ffpb -E -i input.mp4 output.mp4

# Last 50 lines				
ffpb -E 50 -i input.mp4 output.mp4

# All stderr output
ffpb -E all -i input.mp4 output.mp4

# Two-pass encoding
ffpb -i input.mp4 -c:v libx264 -pass 2 -f mp4 output.mp4

FFmpegProgressBar automatically detects -pass 2 and runs the analysis pass (pass 1) silently before displaying the progress bar for the encoding pass.

Bar styles (use -S or --style)

Windows Support

Full Windows support is implemented. The following features work on Windows 10 and later:

Requirements on Windows

For best results, use Windows Terminal which has full ANSI/VT support.

Note on Keyboard Input

AUTHOR

Sasha Abbott sashaa@disroot.org

LICENSE

This library is free software; you can redistribute it and/or modify it under CC0.