Documentation

Everything you need to know about using nano-ffmpeg.

Getting Started

nano-ffmpeg wraps ffmpeg in a keyboard-driven terminal dashboard. Install it and run:

$ nano-ffmpeg

That's it. The TUI guides you through file selection, operation picking, settings configuration, and encoding. You need ffmpeg and ffprobe installed.

Install ffmpeg

# macOS

$ brew install ffmpeg

# Ubuntu / Debian

$ sudo apt install ffmpeg

# Fedora

$ sudo dnf install ffmpeg

# Windows

$ winget install ffmpeg

Screen Flow

nano-ffmpeg uses a multi-screen navigation pattern:

Home → File Picker → Operations → Settings → Progress → Result

Home — ffmpeg version, capabilities, recent files, operation list
File Picker — Browse filesystem or type a path. Inline ffprobe metadata preview.
Operations — Choose from 12 operations
Settings — Presets + individual knobs. Live command preview.
Progress — Live progress bar, ETA, stats, scrollable log
Result — Output path, size comparison, do another or quit

Press Esc on any screen to go back. Press q to quit.

Operations

Convert Format

Change container format (MP4, MKV, WebM, AVI, MOV) and video codec (H.264, H.265, AV1, VP9). Quality presets from High to Tiny.

Extract Audio

Strip video track, keep audio. Output to MP3, AAC, FLAC, WAV, OGG, or Opus. Bitrate presets: CD Quality (320k), Podcast (128k), Lo-fi (64k). Uses stream copy when possible for instant, lossless extraction.

Resize / Scale

Scale to 4K, 1080p, 720p, 480p, or 360p. Aspect ratio options: keep original, force 16:9/4:3, crop to fit. Warns if you try to upscale.

Trim / Cut

Set start and end time in HH:MM:SS format. Lossless cut (stream copy) when possible. Pre-fills total duration from ffprobe.

Compress

CRF quality slider: Visually Lossless (18) to Heavy (32). Codec choice: H.264, H.265, AV1. Two-pass encoding option. Preset speed: slow/medium/fast.

Merge / Concat

Join multiple files together. Detects format mismatches and re-encodes when needed.

Add Subtitles

Burn-in (hardcode) or embed as soft track from SRT, ASS, or SSA files. Font, size, and position customization for burn-in.

Create GIF/WebP

Frame rate control (10/15/24 fps), resolution presets, palette optimization for GIF quality, start time and duration selection.

Extract Thumbnails

Single frame at a timestamp, 4x4 contact sheet grid, or one frame every N seconds.

Watermark

Image overlay with 9-point position grid and opacity control. Text overlay with font, color, and size.

Audio Adjustments

Normalize (loudnorm), volume boost/reduce (dB), fade in/out, or remove audio entirely.

Video Filters

Stabilize (vidstab), deinterlace, speed up/slow down, rotate, flip, crop, color adjustment.

Keybindings

Global

Key	Action
`q`	Quit
`Ctrl+C`	Force quit
`?`	Toggle help overlay

Navigation

Key	Action
`↑ / k`	Move up
`↓ / j`	Move down
`Enter`	Select / confirm / execute
`Esc`	Go back one screen

File Picker

Key	Action
`Enter`	Open directory / select file
`Backspace`	Parent directory
`/`	Toggle path input mode

Settings

Key	Action
`← / →`	Change field value
`Enter`	Execute ffmpeg command
`c`	Copy command to clipboard

Progress

Key	Action
`Esc`	Cancel (with confirmation)
`y / n`	Confirm or deny cancellation

Configuration

Config is stored at ~/.config/nano-ffmpeg/config.json:

{

"default_output_dir": "",

"theme": "dark",

"recent_files": [],

"hw_accel": "auto",

"ffmpeg_path": ""

}

default_output_dir — Where output files are saved (empty = same as input)

theme — Color theme (currently: dark)

recent_files — Last 10 files used (auto-populated)

hw_accel — Hardware acceleration: auto, off, videotoolbox, nvenc, vaapi

ffmpeg_path — Override ffmpeg binary path (empty = auto-detect)

Capabilities are cached separately at ~/.config/nano-ffmpeg/capabilities.json and auto-invalidated when your ffmpeg version changes.

Progress Screen

The progress screen parses ffmpeg's stderr in real-time:

Gradient progress bar — green (0%) to cyan (100%), adapts to terminal width
ETA — Smoothed with rolling average over last 5 updates to avoid jitter
Stats — Elapsed, speed, FPS, frames, output size, bitrate
Braille spinner — For indeterminate operations (stream copy, concat)
Live log — Scrollable raw ffmpeg output, last 6 lines visible
Cancel — Esc opens confirmation, y sends SIGINT and cleans up partial output

Smart Defaults

nano-ffmpeg runs ffprobe on your input file and uses the results to set intelligent defaults:

4K H.265 input → suggests H.265 output, not H.264

Resize → grays out resolutions larger than source

Compress → calculates current bitrate, suggests CRF for ~50% reduction

Extract audio from AAC track → pre-selects AAC (stream copy = instant)

Trim → pre-fills total duration in the time input

File has subtitles → offers extract or replace options