174 lines
4.9 KiB
Markdown
174 lines
4.9 KiB
Markdown
# 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.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
|