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
python3
ffmpeg
ffprobe
cpulimit

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.6

DB-free ffx edit workflow for in-place metadata editing via temporary-file rewrite
inspect and edit workflows split into dedicated Textual screens with shared media-workflow support
Textual tables and row actions now separate raw data from rendered labels to avoid markup leaking into stored metadata
responsive screen layout pass, Esc back handling, sortable show/inspect tables, and improved edit-screen notifications/toggles
application-wide UTF-8 i18n catalogs with language precedence from CLI over config over system over German default
metadata normalization extended for localized subtitle titles, ISO language cleanup, and smarter track editor language/title helpers

0.2.5

show-level quality and notes fields
pattern-over-show-over-default season-shift resolution with dynamic DB migration loading
migration prompt now reports the upgrade path and creates an in-place DB backup before applying schema changes
upgrade --branch <name> now fetches remote-only branches before switching
unmux now applies season shifting to subtitle output filenames
convert now keeps DB-defined target subtitle dispositions authoritative over sidecar filename disposition flags when a pattern definition exists
focused modern tests added around migrations, unmux, upgrade, and subtitle-disposition import precedence

0.2.4

lightweight CLI commands now stay import-light via lazy runtime loading
setup/config templating moved to assets/ffx.json.j2
aligned two-step local setup wrappers: ffx setup and ffx configure_workstation
combined ffprobe payload reuse in FileProperties
configurable crop-detect sampling plus per-process crop result caching
single-query controller accessors and conditional DB schema bootstrap
shared screen bootstrap/controller wiring for large detail screens
configurable default season/episode digit lengths
digit-aware rename and padded unmux filename markers

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