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

You can also force the UI theme for a single run:

$ nano-ffmpeg --theme dark

$ nano-ffmpeg --theme light

You can also control the startup path:

# Start File Picker in this directory

$ nano-ffmpeg --dir /path/to/folder

# Skip File Picker and preload this file

$ nano-ffmpeg --dir /path/to/video.mp4

That's it. The TUI guides you through file selection, operation picking, settings configuration, and encoding. You need ffmpeg and ffprobe installed. For full Stabilize support, use an ffmpeg build with vidstab (Homebrew: ffmpeg-full).

If you install nano-ffmpeg via the Homebrew tap, ffmpeg-full is installed as a dependency. On Windows, the Scoop manifest declares extras/ffmpeg as a dependency so ffmpeg is pulled automatically.

Install nano-ffmpeg

# macOS / Linux (Homebrew)

$ brew install dgr8akki/tap/nano-ffmpeg

# Windows (Scoop)

> scoop bucket add extras

> scoop bucket add nano-ffmpeg https://github.com/dgr8akki/scoop-bucket

> scoop install nano-ffmpeg

# Any OS with Go

$ go install github.com/dgr8akki/nano-ffmpeg@latest

Install ffmpeg separately (if not using Homebrew tap / Scoop)

# macOS

$ brew install ffmpeg-full

# macOS (minimal build; Stabilize uses deshake fallback)

$ brew install ffmpeg

# Ubuntu / Debian

$ sudo apt install ffmpeg

# Fedora

$ sudo dnf install ffmpeg

# Windows (Scoop)

> scoop bucket add extras

> scoop install extras/ffmpeg

# Windows (winget)

> 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. Use --dir <directory> to change the startup directory.
Direct file startup — Use --dir <file> to skip File Picker and start directly in Operations with the file preloaded.
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, preset speed slow/medium/fast/ultrafast, and audio codec (copy, AAC, MP3, Opus).

Extract Audio

Strip video track, keep audio. Output to MP3, AAC, FLAC, WAV, OGG, or Opus. Bitrate presets from CD Quality (320k) down to Lo-fi (64k). The chosen format maps to a fixed encoder; there is no automatic stream copy today.

Resize / Scale

Scale to 4K, 1080p, 720p, 480p, or 360p height (width is auto-derived). Codec choice: H.264 or H.265. An aspect-ratio field is rendered but currently has no effect -- see the Future Scope doc.

Trim / Cut

Set start and end time in HH:MM:SS format. Lossless cut (stream copy) toggle. End time is pre-filled with the input's total duration from ffprobe.

Compress

CRF quality: Visually Lossless (18) to Heavy (32). Codec choice: H.264, H.265, AV1. Preset speed: slow/medium/fast. (A Two-Pass toggle is shown in the UI but is not yet wired up -- see the Future Scope doc.)

Merge / Concat

Joins every file in the input's folder that shares the same extension, in alphabetical order, using ffmpeg's concat demuxer. Stream-copy or re-encode to H.264/AAC. No reorder UI yet.

Add Subtitles

Burn-in (hardcode) or soft-embed subtitle streams already present in the input file. Pick which subtitle track to use. Font, size, and position customization are not yet exposed.

Create GIF

Frame rate (10/15/24 fps), width presets, palette generation and paletteuse for quality, start time and duration selection. Output is GIF only today; WebP output is planned.

Extract Thumbnails

Single frame at a timestamp, 4x4 contact sheet, or one frame every 5 seconds. Output is PNG.

Watermark

Overlays a solid white color box. Five positions (four corners and center), opacity (25/50/75%), and size presets (small/medium/large). Image and text watermarks are planned.

Audio Adjustments

Normalize (loudnorm), volume up/down (dB), fade in + fade out (2s, auto-clamped to input duration), or remove audio entirely.

Video Filters

Stabilize (vidstab when available; falls back to deshake with a warning in Settings), deinterlace (yadif), speed 2x/0.5x, rotate 90°, horizontal/vertical flip. Crop and color filters are planned.

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 select/toggle value or move the text cursor
`Typing`	Edit text fields (Start/End Time, Duration, Timestamp)
`Enter`	Execute ffmpeg command

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 (dark or light)

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)

Passing --theme dark|light overrides the config theme for that run.

Passing --dir <directory|file> overrides startup location for that run.

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 ffprobeon your input file and uses parts of the result to avoid dead ends. The behaviors below are what's actually wired up today:

Trim → the End Time field is pre-filled with the input's total duration

Add Subtitles → the Subtitle Track selector lists the subtitle streams detected in the input (codec and language, when present); if none are found, burn-in is disabled automatically

Audio Adjustments (fade) → the fade-out start is clamped to the input duration so short clips don't produce an invalid filter

Video Filters → if vidstab is unavailable, Stabilize automatically uses deshake and shows a fallback warning in Settings

File Picker → shows an inline ffprobe preview (format, duration, size, video codec/resolution/fps, audio codec/channels/sample-rate, subtitle track count) while you're browsing

More ambitious defaults -- suggesting an output codec based on the input, graying out upscale targets, pre-selecting AAC for stream copy, and so on -- are tracked in docs/future_scope.md.