Adds requirements, streamlines CLI helper procedures

requirements/project.md

@@ -0,0 +1,101 @@
+## 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.