FFX
FFX is a local CLI and Textual TUI for inspecting TV episode files, storing normalization rules in SQLite, and converting outputs into a predictable stream, metadata, and filename layout.
Requirements
- Linux-like environment
python3ffmpegffprobecpulimit
Installation
FFX uses a two-step local setup flow.
1. Install The Bundle
This step creates or reuses the persistent bundle virtualenv in ~/.local/share/ffx.venv, installs FFX into it, and ensures ffx is exposed through a shell alias.
bash tools/setup.sh
If you also want the Python packages needed for the modern test suite:
bash tools/setup.sh --with-tests
You can verify the bundle state without changing anything:
bash tools/setup.sh --check
2. Prepare System Dependencies And Local User Files
This step installs or verifies workstation dependencies and seeds local config and data directories. It is the step wrapped by the CLI command ffx configure_workstation.
Run it directly:
bash tools/configure_workstation.sh
Or through the installed CLI:
ffx configure_workstation
Check-only mode is available in both forms:
bash tools/configure_workstation.sh --check
ffx configure_workstation --check
tools/configure_workstation.sh does not manage the bundle virtualenv. Python-side test packages belong to tools/setup.sh --with-tests.
Basic Usage
Examples:
ffx version
ffx inspect /path/to/episode.mkv
ffx convert /path/to/episode.mkv
ffx shows
Modern Tests
Install Python test packages first:
bash tools/setup.sh --with-tests
Then run the modern automatically discovered test suite:
./tools/test.sh
This runner uses pytest and intentionally excludes the legacy harness under tests/legacy/.
Default Local Paths
- Config:
~/.local/etc/ffx.json - Database:
~/.local/var/ffx/ffx.db - Log file:
~/.local/var/log/ffx.log - Bundle venv:
~/.local/share/ffx.venv
TMDB
TMDB-backed metadata enrichment requires TMDB_API_KEY to be set in the environment.
Version History
0.2.3
- PyPI packaging
- output filename templating
- season shifting
- DB versioning
0.2.2
- CLI overrides
0.2.1
- signature handling
- tag cleanup
- bugfixes and refactoring
0.2.0
- tests
- config file
0.1.3
- subtitle file imports
0.1.2
- bugfixes
0.1.1
- bugfixes
- TMDB show identification