wtffmpeg: Turn Any English Sentence into an FFmpeg Command

“Convert my_video.avi to mp4 with no sound.”
wtffmpeg listens, writes the exact FFmpeg command, and politely asks if you want to run it.

This long-form guide walks you through everything you need to know to install, run, and fine-tune wtffmpeg—without ever opening a second browser tab.
It is written for college-level readers who are comfortable with the terminal but would rather not memorize FFmpeg flags.

Table of Contents

  1. What wtffmpeg Actually Does
  2. Hardware and Software Prerequisites
  3. Step-by-Step Installation
  4. First Run: A 60-Second Walkthrough
  5. Everyday Use Cases with Copy-Paste Examples
  6. Interactive Mode: Fixing Commands on the Fly
  7. Swapping Models and Customising Prompts
  8. Troubleshooting Checklist
  9. Security, Safety, and Legal Notes
  10. Quick-Reference Cheat Sheet

1. What wtffmpeg Actually Does

Question Plain-English Answer
Purpose Translates plain English into ready-to-run FFmpeg commands
Where it runs 100 % on your machine—no cloud calls, no uploads
GPU support Optional; uses llama-cpp-python to offload layers to CUDA, Metal, or OpenBLAS
Model needed One GGUF file (e.g., Phi-3-mini-4k-instruct-q4.gguf)
Output A shell command you can accept, reject, or edit

One-Sentence Summary

Type what you want; wtffmpeg writes the FFmpeg command; you stay in control.

2. Hardware and Software Prerequisites

Item Minimum Recommended
OS Linux, macOS, Windows (WSL) Any 64-bit OS with Python 3.8+
Python 3.8 3.10 or newer
RAM 4 GB free for the model 8 GB+
Storage 2 GB for the model + code SSD for faster load
GPU Optional RTX-class NVIDIA, Apple M-series, or AMD ROCm

3. Step-by-Step Installation

3.1 Clone the Repository

git clone https://github.com/scottvr/wtffmpeg.git
cd wtffmpeg

3.2 Create a Virtual Environment (Strongly Advised)

python3 -m venv .venv
source .venv/bin/activate      # Windows: .venv\Scripts\activate

3.3 Install llama-cpp-python with Hardware Acceleration

Choose the line that matches your hardware.

Hardware One-Line Install
NVIDIA (CUDA) CMAKE_ARGS="-DLLAMA_CUBLAS=on" pip install llama-cpp-python
Apple Silicon (Metal) CMAKE_ARGS="-DLLAMA_METAL=on" pip install llama-cpp-python
CPU only (OpenBLAS) pip install llama-cpp-python

If the compile step fails, double-check that your compiler and CUDA/Metal tool-chain versions match the llama-cpp-python docs.

3.4 Install wtffmpeg

pip install .

The command wtff is now available inside the virtual environment.

3.5 Download a GGUF Model

Two popular choices:

Model Size (approx.) Link
Phi-3-mini-4k-instruct-q4.gguf 2.3 GB Hugging Face
Mistral-7B-Instruct-v0.2-GGUF 4.1 GB Hugging Face

Place the .gguf file in the project root or any folder you prefer.
You can override the default path with --model /path/to/file.gguf.

4. First Run: A 60-Second Walkthrough

  1. Open the terminal.
  2. Activate the environment: source .venv/bin/activate
  3. Type:
wtff "convert my_video.avi to mp4 with no sound"
  1. Wait for the spinner:
Loading model... (this may take a moment)
Model loaded. Generating command...
  1. Review the output:
--- Generated ffmpeg Command ---
ffmpeg -i my_video.avi -an -c:v libx264 my_video.mp4
------------------------------
Execute this command? [y/N]
  1. Press y to run it, N to cancel, or c to copy to clipboard.

That’s it—no Stack Overflow, no manual page.

5. Everyday Use Cases with Copy-Paste Examples

Each example is self-contained. Replace filenames as needed.

Goal One-Line Prompt Generated Command
Make a web-friendly MP4 wtff "turn presentation.mov into a web-friendly mp4" ffmpeg -i presentation.mov -c:v libx264 -crf 23 -preset medium -c:a aac output.mp4
Extract high-quality MP3 wtff "extract the audio from lecture.mp4 and save it as a high-quality mp3" ffmpeg -i lecture.mp4 -q:a 0 -map a lecture.mp3
10-second clip starting at 2 min wtff "create a 10-second clip from movie.mkv starting at the 2 minute mark" ffmpeg -ss 00:02:00 -i movie.mkv -t 10 -c copy clip.mkv
Resize to 720p, skip confirmation wtff -x "resize video.mp4 to 720p" ffmpeg -i video.mp4 -vf scale=-2:720 -c:v libx264 -crf 23 video_720p.mp4

Pro tip: Add constraints in plain English, e.g., “use hardware acceleration” or “keep original frame rate.”

6. Interactive Mode: Fixing Commands on the Fly

Start interactive mode:

wtff --model mistral-7b-instruct-v0.1.Q3_K_M.gguf -i

You’ll see:

Model loaded.
Entering interactive mode. Type 'exit' or 'quit' to leave.
wtff>

6.1 Real-Time Fixes

Suppose the model suggests:

ffmpeg -i test_pattern.mp4 -vf "reverse" -c copy output.mp4

FFmpeg will refuse this because -c copy and -vf reverse are incompatible.
Type:

wtff> reverse the video test_pattern.mp4. Do not use `-c copy` in your command.

New output:

ffmpeg -i test_pattern.mp4 -vf "reverse" -c:v libx264 -crf 18 -pix_fmt yuv420p output.mp4

6.2 Shell Escape with !

Need to list files without leaving the session?

wtff> !ls -l *.mp4

Any shell command works after the exclamation mark.

7. Swapping Models and Customising Prompts

7.1 Use Your Own Model

wtff --model /abs/path/to/custom.gguf "fade in audio over 3 seconds"

7.2 Change the System Prompt

Edit the string stored in system_prompt inside the source code.
Common tweaks:

Tweak Example Line
Always add -y system_prompt += " Always include -y to overwrite without prompting."
Prefer GPU encoders system_prompt += " Prefer h264_nvenc when hardware is available."

Re-install with pip install . after edits.

8. Troubleshooting Checklist

Symptom Cause Fix
command not found: wtff Virtual env not activated source .venv/bin/activate
Model never loads RAM or path issue Verify .gguf path and free RAM
Command fails Model hallucination Add an extra sentence to the prompt
GPU not used Wrong llama-cpp build Re-install with correct CMAKE_ARGS

9. Security, Safety, and Legal Notes

  • Local-Only: No data leaves your computer.
  • Review Before Run: FFmpeg can overwrite files without recovery.
  • Disclaimer (from author): “This was largely made to amuse myself… Use at your own risk.”
  • Best Practice: Test on copies first; keep backups.

10. Quick-Reference Cheat Sheet

Installation in One Block

git clone https://github.com/scottvr/wtffmpeg.git
cd wtffmpeg
python3 -m venv .venv && source .venv/bin/activate
CMAKE_ARGS="-DLLAMA_CUBLAS=on" pip install llama-cpp-python  # Adjust for your GPU
pip install .

Essential Commands

Task One-Liner
Basic conversion wtff "convert in.avi to mp4"
Extract audio wtff "extract audio from in.mp4 to wav"
Quick 720p resize wtff -x "resize in.mp4 to 720p"
Interactive mode wtff -i
Custom model wtff --model ./mymodel.gguf "fade out last 5 seconds"

Closing Thoughts

wtffmpeg is not magic—it is a thin but useful wrapper that lets natural language meet FFmpeg’s raw power. Install once, keep the model file handy, and you can stop memorising flags forever.

Remember: the generated command is only as good as the prompt you give it. When in doubt, add one more sentence of detail.