ffx/requirements/project.md

Purpose And Scope

• Project name: FFX
• User problem: TV episode files from mixed sources arrive with inconsistent codecs, stream metadata, subtitle layouts, season and episode numbering, and output filenames, which makes them awkward to archive and use in media-player applications.
• Target users: Individual operators curating a local TV media library on a workstation, especially users willing to define normalization rules per show.
• Success outcome: A user can inspect source files, define reusable show and pattern rules, and produce output files whose streams, metadata, and filenames follow a predictable schema for web playback and library import.
• Out of scope:
  • Multi-user or hosted service workflows.
  • General movie-library management.
  • Distributed transcoding or remote job orchestration.
  • Broad media-server administration beyond file preparation.

Required Product

• Deliverable type: Installable Python command-line application with a Textual terminal UI for inspection and rule editing.
• Core capabilities:
  • Maintain an SQLite-backed database of shows, filename-matching patterns, per-pattern stream layouts and metadata tags, and optional season-shift rules.
  • Inspect existing media files through ffprobe and compare discovered stream metadata with stored normalization rules.
  • Convert media files through ffmpeg into a normalized output layout, including video recoding, audio transcoding to Opus, metadata cleanup and rewrite, and controlled disposition flags.
  • Build output filenames from detected or configured show, season, and episode information, optionally enriched from TMDB and a configurable Jinja-style filename template.
  • Support auxiliary file operations such as subtitle import, unmuxing, crop detection, and rename-only runs.
• Supported environments:
  • Local execution on a Python-capable workstation.
  • Best-supported on Linux-like systems because the implementation assumes ~/.local, /dev/null, nice, and cpulimit.
  • Requires ffmpeg, ffprobe, and cpulimit on PATH.
• Operational owner: The local user running the tool and maintaining its config, database, and external tooling.

Suggested User Stories

• As a library maintainer, I want to define show-specific matching rules once so that future source files can be normalized automatically.
• As an operator, I want to inspect a file before conversion so that I can compare its actual streams and tags against the stored target schema.
• As a user preparing web-playback files, I want to recode video and audio with a small set of predictable options so that results are compatible and consistently named.
• As a user dealing with nonstandard releases, I want CLI overrides for language, title, stream order, default and forced tracks, and season and episode data so that one-off fixes do not require database edits first.
• As a user importing anime or other shifted numbering schemes, I want season and episode offsets per show so that generated filenames align with TMDB and media-library expectations.

Functional Requirements

• The system shall provide a CLI entrypoint named ffx with commands for convert, inspect, shows, unmux, cropdetect, version, and help.
• The system shall persist reusable normalization rules in SQLite for:
  • shows and show formatting digits,
  • regex-based filename patterns,
  • per-pattern media tags,
  • per-pattern stream definitions,
  • shifted-season mappings,
  • internal database version properties.
• The system shall inspect source media using ffprobe and derive a structured description of container metadata and streams.
• The system shall optionally open a Textual UI to browse shows, inspect files, and create, edit, or delete shows, patterns, stream definitions, tags, and shifted-season rules.
• The system shall match filenames against stored regex patterns to decide whether an input file should inherit a target stream and metadata schema.
• The system shall convert supported input files (mkv, mp4, avi, flv, webm) with ffmpeg, supporting at least:
  • VP9, AV1, and H.264 video encoding,
  • Opus audio encoding with bitrate selection based on channel layout,
  • metadata and disposition rewriting,
  • optional crop detection and crop application,
  • optional deinterlacing and denoising,
  • optional subtitle import from external files,
  • rename-only copy mode.
• The system shall support optional TMDB lookups to resolve show names, years, and episode titles when a show ID, season, and episode are available.
• The system shall generate output filenames from show metadata, season and episode indices, and episode names using the configured filename template.
• The system shall allow CLI overrides for stream languages, stream titles, default and forced tracks, stream order, TMDB show and episode data, output directory, label prefix, and processing resource limits.
• The system shall support extracting streams into separate files via unmux and reporting suggested crop parameters via cropdetect.
• The system shall handle invalid input and system failures gracefully by logging warnings or raising click errors for missing files, invalid media, missing TMDB credentials, incompatible database versions, and ambiguous track dispositions when prompting is disabled.

Quality Requirements

• The system should stay understandable as a small local tool: controllers, descriptors, models, and screens should remain separate enough for contributors to trace a workflow end to end.
• The system should produce predictable output for the same database rules, CLI overrides, and source files.
• The system should preserve a lightweight operational footprint: local SQLite state, local log file, no mandatory background services.
• The system should be testable through the existing combinatorial CLI-oriented test harness and through isolated logic in descriptors and controllers.
• The system should expose enough logging to diagnose failed probes, failed conversions, and rule mismatches without requiring a debugger.

Constraints And Assumptions

• Technology constraints:
  • Python package built with setuptools.
  • Primary libraries: click, textual, sqlalchemy, jinja2, requests.
  • Conversion and inspection rely on external executables rather than pure-Python media libraries.
• Hosting or infrastructure constraints:
  • Intended for local execution, not server deployment.
  • Stores default state in ~/.local/etc/ffx.json, ~/.local/var/ffx/ffx.db, and ~/.local/var/log/ffx.log.
• Timeline constraints:
  • The current implemented scope reflects a compact alpha release stream up to version 0.2.3.
• Team capacity assumptions:
  • Maintained as a small codebase where simple patterns and direct controller logic are preferred over framework-heavy abstractions.
• Third-party dependencies:
  • ffmpeg, ffprobe, and cpulimit.
  • TMDB API access through TMDB_API_KEY for metadata enrichment.

Acceptance Scope

• First release boundary:
  • Local installation through pip.
  • Working SQLite-backed rule storage.
  • Functional CLI conversion and inspection workflows.
  • Textual CRUD flows for shows, patterns, tags, tracks, and shifted seasons.
  • TMDB-assisted filename generation, subtitle import, season shifting, database versioning, and configurable output filename templating.
• Excluded follow-up ideas:
  • Completing placeholder screens such as settings and help.
  • Hardening platform portability beyond Linux-like systems.
  • Broader media types, richer release packaging, and production-grade background processing.
• Demonstration scenario:
  • Inspect a TV episode file, define or update the matching show and pattern in the TUI, then run ffx convert so the result uses the stored stream schema, optional TMDB episode naming, and a normalized output filename.