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

```sh
bash tools/setup.sh
```

If you also want the Python packages needed for the modern test suite:

```sh
bash tools/setup.sh --with-tests
```

You can verify the bundle state without changing anything:

```sh
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:

```sh
bash tools/configure_workstation.sh
```

Or through the installed CLI:

```sh
ffx configure_workstation
```

Check-only mode is available in both forms:

```sh
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:

```sh
ffx version
ffx inspect /path/to/episode.mkv
ffx convert /path/to/episode.mkv
ffx shows
```

## Modern Tests

Install Python test packages first:

```sh
bash tools/setup.sh --with-tests
```

Then run the modern automatically discovered test suite:

```sh
./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