ffx/README.md

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

• pattern details now show an inline Show: <quality> hint next to the quality field when the pattern itself has no stored quality but the selected show does
• inspect stream tables now show attachment format labels like TTF in the codec column and keep attachment language cells blank instead of showing an undefined language
• ffmpeg damaged-MP3 diagnostics now recognize additional corruption lines such as invalid new backstep, keeping them grouped under the warn-corrupt-mpeg-audio review summary

0.4.1

• convert now supports --copy-video and --copy-audio to keep the selected stream type in copy mode without applying the corresponding reencode flags, filters, or formatting options
• ffmpeg conversions now monitor diagnostics while the process is running, retry unset AVI packet timestamps once with -fflags +genpts, and stop early when a file should be skipped instead of waiting for the full job to finish
• end-of-run convert summaries now list only ffmpeg findings that still require review, including named remedy identifiers such as warn-corrupt-mpeg-audio
• upgrade now finishes by reporting the installed FFX version together with the active bundle branch

0.3.1

• debug mode screen titles now append the active Textual screen class name, making screen-specific troubleshooting easier during inspect and edit flows
• --cut again works as a combined flag/option: omitted disables cutting, bare --cut applies the default 60,180, and explicit duration or START,DURATION values stay supported
• H.265 unmux commands no longer force an invalid -f h265 output format, keeping ffmpeg copy extraction aligned with the required Annex B bitstream filter
• H.264 encoding now falls back from libx264 to libopenh264 with a warning when needed, and the test fixtures use the same encoder fallback so the suite remains portable across ffmpeg builds

0.3.0

• inspect and edit screens now refresh nested track and pattern changes more reliably, with inspect-mode tables aligned to the target pattern view shown in the differences pane
• metadata editing got a follow-up polish pass with clearer ffmpeg notifications, a shared in-screen log pane, safer apply/reload handling, and expanded cleanup and normalization coverage
• track and asset probing recognize additional codecs, and the modern test suite now covers more metadata-editor, change-set, screen-state, and asset-probe behavior
• Textual now requires version 8.0 or newer to match the UI APIs used by the current screens

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