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