Compare commits
1 Commits
season-shi
...
381a62046b
| Author | SHA1 | Date | |
|---|---|---|---|
|
381a62046b |
376
AGENTS.md
376
AGENTS.md
@@ -1,376 +0,0 @@
|
||||
# AGENTS.md
|
||||
|
||||
This file is the entry point for agent guidance in this repository.
|
||||
|
||||
It is intentionally generic and reusable across projects. Keep this file focused on non-project-specific constraints, working style, and the structure used to link more detailed guidance.
|
||||
|
||||
# Purpose
|
||||
|
||||
- Provide a small default rule set for agents working in this repository.
|
||||
- Keep the base guidance modular and easy to extend.
|
||||
- Separate reusable agent behavior from project-specific requirements.
|
||||
|
||||
# Comment Syntax
|
||||
|
||||
- A segment wrapped in `<!--` and `-->` is a comment and must be ignored by agents.
|
||||
- Use HTML comments for optional guidance that should stay inactive until enabled.
|
||||
- To enable an optional segment, remove the surrounding `<!--` and `-->` markers.
|
||||
|
||||
# Core Principles
|
||||
|
||||
- Prefer the simplest solution that satisfies the current goal.
|
||||
- Keep guidance lightweight: only add detail when it meaningfully improves outcomes.
|
||||
- Reuse modular guideline files instead of expanding this file indefinitely.
|
||||
- Treat project-specific documents as the source of truth for project behavior.
|
||||
- When guidance conflicts, use the most specific applicable document.
|
||||
|
||||
# Rule Terms
|
||||
|
||||
- A `rule` is the general term for any constraint, requirement, definition, or similar guidance item.
|
||||
- A `rule set` addresses all rules inside one file that share the same rule set ID.
|
||||
- Any rule inside a rule set shall use an ID following the schema `RULESET-0001`, `RULESET-0002`, and so on.
|
||||
- Rules without a rule set ID are also valid, but they are not addressable by rule ID.
|
||||
|
||||
# Scope Of This File
|
||||
|
||||
This file should contain:
|
||||
|
||||
- Generic agent behavior and constraints.
|
||||
- Rules that are reusable across multiple projects.
|
||||
- Links to optional guideline modules.
|
||||
- Links to project-specific requirements.
|
||||
- Commented optional templates for released-product documentation and agent-output locations.
|
||||
|
||||
This file should not contain:
|
||||
|
||||
- Project business requirements.
|
||||
- Project architecture decisions.
|
||||
- Stack-specific implementation details unless they are universally applicable.
|
||||
- Task-specific runbooks that belong in dedicated modules.
|
||||
|
||||
# Default Agent Behavior
|
||||
|
||||
- Read the relevant context before making changes.
|
||||
- Prefer small, understandable edits over broad refactors.
|
||||
- Preserve existing patterns unless there is a clear reason to change them.
|
||||
- Document assumptions when context is missing.
|
||||
- Ignore HTML comment segments.
|
||||
- If a more specific enabled guideline exists for the current task, follow it.
|
||||
|
||||
# Guideline Structure
|
||||
|
||||
Use the following structure for reusable guidance files and project-specific documentation as needed:
|
||||
|
||||
```text
|
||||
/
|
||||
|-- AGENTS.md
|
||||
|-- guidance/
|
||||
| |-- stacks/
|
||||
| |-- conventions/
|
||||
| `-- workflows/
|
||||
|-- prompts/
|
||||
`-- requirements/
|
||||
|
||||
Optional files and directories
|
||||
|-- SCRATCHPAD.md
|
||||
|-- docs/
|
||||
| |-- readme.md
|
||||
| |-- installation.md
|
||||
| `-- history.md
|
||||
|-- process/
|
||||
| |-- log.md
|
||||
| `-- coding-handbook.md
|
||||
```
|
||||
|
||||
# Optional Reusable Modules
|
||||
|
||||
Add files under `guidance/` only when they are needed.
|
||||
|
||||
# Optional Scratchpad
|
||||
|
||||
- `SCRATCHPAD.md` is an optional repo-root scratchpad for temporary
|
||||
information aimed at the next iteration.
|
||||
- Developers may create or delete `SCRATCHPAD.md` at any time.
|
||||
- Developers may refer to `SCRATCHPAD.md` as `scratchpad` when giving agents a
|
||||
source or target for information.
|
||||
- Agents may read, update, create, or remove the scratchpad when the task
|
||||
explicitly calls for it.
|
||||
- Treat the scratchpad as low-formality working context rather than canonical
|
||||
project truth.
|
||||
- Use the scratchpad for short-lived notes, open questions, sketches, and
|
||||
temporary decisions that should be resolved away.
|
||||
- Move durable outcomes into `requirements/`, `guidance/`, code, tests, or
|
||||
another long-lived location.
|
||||
- If `SCRATCHPAD.md` is absent, agents should continue normally.
|
||||
|
||||
# Optional Rule Sets
|
||||
|
||||
- Optional rule sets may be stored in `guidance/optional/` or in `guidance/{section}/optional/`.
|
||||
- Optional rule sets are inactive by default and shall only be applied when a prompt explicitly requests them, for example by phrases such as `Apply rules for lean interface iteration in the following steps.` or `Apply LII rules.`
|
||||
- An optional rule set may be requested by its descriptive name, by its rule set ID, or by another equally clear explicit reference.
|
||||
- Agents shall never infer or auto-enable optional rule sets from general intent alone.
|
||||
- If an optional rule or rule set cannot be identified and addressed clearly, agents shall stop and ask before proceeding.
|
||||
|
||||
# Prepared Orders
|
||||
|
||||
- An `order` is a prepared prompt for one isolated operation rather than a general workflow or standing rule set.
|
||||
- Orders shall be stored under `prompts/`.
|
||||
- Order files shall use the naming schema `ORDER-0001-<slug>.md`, `ORDER-0002-<slug>.md`, and so on.
|
||||
- The canonical order identifier is the `ORDER-0001` style prefix. The trailing slug is descriptive only.
|
||||
- Recommended internal order file structure is: prompt ID, prompt name, purpose, trigger examples, scope, operation, and expected output.
|
||||
- Orders shall only be executed when they are explicitly requested by a prompt such as `Execute ORDER-0007.` or `Execute ORDER 7.`
|
||||
- Agents may accept an unambiguous short numeric reference such as `ORDER 7` as an alias for `ORDER-0007`.
|
||||
- If an order cannot be identified uniquely and clearly, agents shall stop and ask before proceeding.
|
||||
|
||||
# Toolstack Guides
|
||||
|
||||
Location:
|
||||
|
||||
```text
|
||||
guidance/stacks/
|
||||
```
|
||||
|
||||
Examples:
|
||||
|
||||
- `guidance/stacks/python.md`
|
||||
- `guidance/stacks/typescript.md`
|
||||
- `guidance/stacks/docker.md`
|
||||
- `guidance/stacks/terraform.md`
|
||||
|
||||
Use for:
|
||||
|
||||
- Language or framework expectations.
|
||||
- Tooling and environment conventions.
|
||||
- Build, test, and runtime guidance tied to a specific stack.
|
||||
|
||||
# Coding Conventions
|
||||
|
||||
Location:
|
||||
|
||||
```text
|
||||
guidance/conventions/
|
||||
```
|
||||
|
||||
Examples:
|
||||
|
||||
- `guidance/conventions/naming.md`
|
||||
- `guidance/conventions/testing.md`
|
||||
- `guidance/conventions/review.md`
|
||||
|
||||
Use for:
|
||||
|
||||
- Naming and structure conventions.
|
||||
- Testing expectations.
|
||||
- Code review and quality rules.
|
||||
|
||||
# Recurring Workflows
|
||||
|
||||
Location:
|
||||
|
||||
```text
|
||||
guidance/workflows/
|
||||
```
|
||||
|
||||
Examples:
|
||||
|
||||
- `guidance/workflows/feature-delivery.md`
|
||||
- `guidance/workflows/bugfix.md`
|
||||
- `guidance/workflows/release.md`
|
||||
- `guidance/workflows/incident-response.md`
|
||||
|
||||
Use for:
|
||||
|
||||
- Repeatable task flows.
|
||||
- Checklists for common delivery work.
|
||||
- Operational or maintenance procedures.
|
||||
|
||||
|
||||
<!-- Enable this optional section by removing the outer HTML comment markers from this segment
|
||||
when you want agents to create, update, and consult released-product
|
||||
documentation in `docs/`.
|
||||
|
||||
# Released Product Documentation
|
||||
|
||||
Released-product documentation should live outside the generic sections above.
|
||||
|
||||
Recommended location:
|
||||
|
||||
```text
|
||||
docs/
|
||||
```
|
||||
|
||||
Examples:
|
||||
|
||||
- `docs/readme.md`
|
||||
- `docs/installation.md`
|
||||
- `docs/history.md`
|
||||
|
||||
Agent rules for docs output:
|
||||
|
||||
- Keep content compact but comprehensive.
|
||||
- Write for end users, operators, or other consumers of the released product.
|
||||
- Prefer shipped behavior, supported workflows, and stable terminology over
|
||||
internal implementation detail.
|
||||
- Keep documentation synchronized with released behavior.
|
||||
- Update release history when user-visible changes are shipped.
|
||||
|
||||
Recommended topics:
|
||||
|
||||
- Product overview and intended use.
|
||||
- Installation, configuration, and upgrade guidance.
|
||||
- Usage patterns, operational instructions, and support boundaries.
|
||||
- Compatibility notes, migration notes, and release history.
|
||||
- Troubleshooting and common pitfalls when relevant. -->
|
||||
|
||||
|
||||
<!-- Enable this optional section by removing the outer HTML comment markers from this
|
||||
segment when you want agents to produce and consult workflow output in `process/`.
|
||||
|
||||
# Agent Output In `process/`
|
||||
|
||||
The `process/` directory is primarily for agent output created during
|
||||
delivery, maintenance, and review work.
|
||||
|
||||
Recommended location:
|
||||
|
||||
```text
|
||||
process/
|
||||
```
|
||||
|
||||
Agent rules for process output:
|
||||
|
||||
- Use `process/` for agent-produced artifacts rather than released-product
|
||||
documentation.
|
||||
- Keep entries concise, traceable, and tied to resulting changes.
|
||||
- Treat `process/` as workflow output, not as the primary source of product
|
||||
truth.
|
||||
- Prefer summaries and rationale over raw transcript dumps unless a workflow
|
||||
explicitly requires full prompt history.
|
||||
|
||||
# Agent Change Log
|
||||
|
||||
Location:
|
||||
|
||||
```text
|
||||
process/log.md
|
||||
```
|
||||
|
||||
Use for:
|
||||
|
||||
- Capturing prompts given to agents.
|
||||
- Recording concise explanations of the resulting changes made by agents.
|
||||
- Preserving task-by-task rationale, decisions, and implementation notes.
|
||||
|
||||
# Coding Handbook
|
||||
|
||||
Location:
|
||||
|
||||
```text
|
||||
process/coding-handbook.md
|
||||
```
|
||||
|
||||
Use for:
|
||||
|
||||
- A tutorial-style handbook that explains the programming components used in
|
||||
the project.
|
||||
- Compact but comprehensive technical onboarding material for future
|
||||
contributors.
|
||||
- Written explanations that connect code structure, concepts, and
|
||||
implementation patterns. -->
|
||||
|
||||
|
||||
# Project-Specific Requirements
|
||||
|
||||
|
||||
Project-specific material should live outside the generic sections above.
|
||||
|
||||
Recommended location:
|
||||
|
||||
```text
|
||||
requirements/
|
||||
```
|
||||
|
||||
Examples:
|
||||
|
||||
- `requirements/project.md`
|
||||
- `requirements/architecture.md`
|
||||
- `requirements/decisions.md`
|
||||
- `requirements/domain.md`
|
||||
|
||||
Use for:
|
||||
|
||||
- Product and business requirements.
|
||||
- Project goals and constraints.
|
||||
- Architecture and design decisions.
|
||||
- Domain knowledge that is specific to this repository.
|
||||
|
||||
# Agent-Level Variables
|
||||
|
||||
When present, `requirements/identifiers.yml` is an optional project-specific
|
||||
input that defines agent-level variables for use inside `requirements/` and
|
||||
`guidance/`.
|
||||
|
||||
Variable schema:
|
||||
|
||||
- Use `@{VARIABLE_NAME}` for agent-level variables.
|
||||
- Prefer uppercase snake case names such as `@{PROJECT_ID}` or `@{VENDOR_ID}`.
|
||||
- Do not treat `${...}` as an agent-level variable form; that syntax may appear
|
||||
in Bash or other code and should not be interpreted as agent metadata.
|
||||
|
||||
Scope:
|
||||
|
||||
- The effective scope of `requirements/identifiers.yml` is limited to
|
||||
`requirements/` and `guidance/`.
|
||||
- Definitions from `requirements/identifiers.yml` must not leak into product code.
|
||||
|
||||
Defaults:
|
||||
|
||||
- Default `@{VENDOR_ID}` is `osgw`.
|
||||
- Default `@{PROJECT_ID}` is the current repository directory name.
|
||||
|
||||
Resolution rules:
|
||||
|
||||
- Treat `requirements/identifiers.yml` as optional; when it is absent, agents
|
||||
may still resolve the defaults defined above.
|
||||
- If a variable is used in `requirements/` or `guidance/` and it is not
|
||||
defined in `requirements/identifiers.yml` and does not have a default in this
|
||||
file, agents may stop and report the undefined variable.
|
||||
- Prefer updating duplicated identifier values in `requirements/` and
|
||||
`guidance/` to use the variable schema when that improves consistency.
|
||||
|
||||
# Precedence
|
||||
|
||||
Some precedence levels may be absent because optional levels can remain inside
|
||||
HTML comments. The smaller numeric index wins.
|
||||
|
||||
Apply guidance in this order:
|
||||
|
||||
1. Direct user or task instructions.
|
||||
2. Project-specific documents in `requirements/`.
|
||||
<!-- 3. Released-product documentation in `docs/` when shipped behavior or
|
||||
user-facing expectations are relevant. -->
|
||||
4. Relevant modular guides in `guidance/stacks/`, `guidance/conventions/`, or `guidance/workflows/`.
|
||||
<!-- 5. Agent output in `process/` when prior prompts, rationale, or
|
||||
implementation notes are relevant. -->
|
||||
6. This `AGENTS.md`.
|
||||
|
||||
# Maintenance
|
||||
|
||||
- Keep this file short and stable.
|
||||
- Move detail into dedicated modules when a section becomes too specific or too long.
|
||||
- Add new guideline files only when they solve a recurring need.
|
||||
- Remove outdated references when the repository structure changes.
|
||||
|
||||
# Current Status
|
||||
|
||||
This repository defines the base `AGENTS.md` structure plus project-specific
|
||||
requirements and modular guidance.
|
||||
|
||||
Future project work can add:
|
||||
|
||||
- Reusable modules under `guidance/`
|
||||
- Project-specific documentation under `requirements/`
|
||||
- Optional temporary iteration context in `SCRATCHPAD.md`
|
||||
- Optional released-product documentation under `docs/` by uncommenting its segment
|
||||
- Optional agent output under `process/` by uncommenting its segment
|
||||
- Cross-references from this file once those documents exist
|
||||
@@ -1,62 +0,0 @@
|
||||
<!--
|
||||
|
||||
# Scratchpad
|
||||
|
||||
Temporary information holder for the next iteration. Developers may create or
|
||||
delete this file at any time. Anything durable should move into code, tests, or
|
||||
canonical docs, then this file should disappear.
|
||||
|
||||
|
||||
## Goal
|
||||
|
||||
Use this section for the current slice of work. It should explain what the
|
||||
scratchpad is helping us move forward right now.
|
||||
|
||||
## Settled
|
||||
|
||||
Use this for decisions that are stable enough to guide the next steps, but are
|
||||
still temporary enough to live in the scratchpad for now.
|
||||
|
||||
## Focused Snapshot
|
||||
|
||||
Use an extra section like this only when one slice needs its own compact
|
||||
summary. This is useful when a specific API, boundary, or model was recently
|
||||
recreated and should be captured clearly.
|
||||
|
||||
|
||||
## Open
|
||||
|
||||
Use this for unresolved questions, design choices, and risks that still need a
|
||||
decision.
|
||||
|
||||
## Sketches
|
||||
|
||||
Use this for rough candidate structures, names, or shapes. Keep it explicit
|
||||
that these are sketches, not committed architecture.
|
||||
|
||||
|
||||
## Gaps Right Now
|
||||
|
||||
Use this for concrete missing pieces in the current repo state. This section
|
||||
should describe what is absent or incomplete, not broad future ambitions.
|
||||
|
||||
## Next
|
||||
|
||||
Use this for the immediate sequence of work. It should be short, ordered, and
|
||||
biased toward the next deliverable rather than a long roadmap.
|
||||
|
||||
## Delete When
|
||||
|
||||
Use this to define when the scratchpad should disappear. That keeps it clearly
|
||||
temporary and helps prevent it from turning into shadow documentation.
|
||||
|
||||
|
||||
## Suggested Style
|
||||
|
||||
- Prefer short bullets over long prose.
|
||||
- Keep facts, questions, and rough sketches in separate sections.
|
||||
- Add custom sections only when they help the next iteration move faster.
|
||||
- Move durable outcomes out of the scratchpad once they stop being temporary.
|
||||
|
||||
|
||||
-->
|
||||
@@ -1,28 +0,0 @@
|
||||
# Lean Interface Iteration
|
||||
|
||||
Rule set name: `lean-interface-iteration`
|
||||
|
||||
Rule set ID: `LII`
|
||||
|
||||
Status: optional, prompt-activated only
|
||||
|
||||
Trigger examples:
|
||||
|
||||
- `Apply the lean-interface-iteration rules.`
|
||||
- `Apply LII rules.`
|
||||
|
||||
LII-0001: Apply this rule set only when it is explicitly requested in the prompt.
|
||||
|
||||
LII-0002: The target of work under this rule set is the iterated product state for the addressed iteration only.
|
||||
|
||||
LII-0003: Optimize the addressed interface toward the leanest and least complex model that still satisfies the iteration order.
|
||||
|
||||
LII-0004: Backward compatibility, legacy aliases, and compatibility shims are not required unless the prompt explicitly asks to preserve them.
|
||||
|
||||
LII-0005: Prefer one authoritative interface over multiple overlapping parameters, flags, or naming variants.
|
||||
|
||||
LII-0006: Remove or avoid transitional interface layers when they are not required by the addressed iteration order.
|
||||
|
||||
LII-0007: Update affected tests, guidance, requirements, and documentation so they describe the simplified interface model rather than a mixed legacy-and-new model.
|
||||
|
||||
LII-0008: Never change behavior, interfaces, or surrounding areas that are not addressed by the current iteration order.
|
||||
@@ -1,56 +0,0 @@
|
||||
# Preparation Script Design
|
||||
|
||||
Rule set name: `preparation-script-design`
|
||||
|
||||
Rule set ID: `PSD`
|
||||
|
||||
Status: optional, prompt-activated only
|
||||
|
||||
Trigger examples:
|
||||
|
||||
- `Apply the preparation-script-design rules.`
|
||||
- `Apply PSD rules.`
|
||||
|
||||
PSD-0001: Apply this rule set only when it is explicitly requested in the prompt.
|
||||
|
||||
PSD-0002: Use this rule set for scripts whose purpose is to prepare, verify, or expose a local development or automation environment rather than to perform product runtime behavior.
|
||||
|
||||
PSD-0003: Keep a preparation script focused on environment readiness, dependency installation, local helper exposure, and clear verification output; do not mix unrelated product logic into the script.
|
||||
|
||||
PSD-0004: Design the script to be idempotent so repeated runs converge on the same prepared state without unnecessary reinstallation or destructive side effects.
|
||||
|
||||
PSD-0005: Provide a verification-only mode such as `--check` that reports readiness without installing, modifying, or creating dependencies.
|
||||
|
||||
PSD-0006: Separate component checks from installation steps so the script can report what is missing before or after attempted remediation.
|
||||
|
||||
PSD-0007: Group required capabilities into clear purpose-oriented sections such as support toolchains, local package bundles, generated environment helpers, or other relevant readiness areas instead of presenting one undifferentiated dependency list.
|
||||
|
||||
PSD-0008: Prefer explicit per-component check helpers over opaque one-shot checks so failures remain traceable and easy to extend.
|
||||
|
||||
PSD-0009: Generate or update environment helper files only when they provide a stable, reusable way to expose repo-local or workspace-local tools, paths, or environment variables.
|
||||
|
||||
PSD-0010: Generated environment helper files shall be safe to source multiple times and should avoid duplicating path entries or clobbering unrelated user environment state.
|
||||
|
||||
PSD-0011: When a preparation flow seeds optional user-owned files such as config templates, do so non-destructively by creating them only when absent unless the prompt explicitly requests overwrite behavior.
|
||||
|
||||
PSD-0012: Report status in a concise scan-friendly line format of the shape `[status] Label: detail`, where the label names the checked component and the detail string stays short and specific.
|
||||
|
||||
PSD-0013: Prefer a small canonical status vocabulary in those report lines, with `ok` for satisfied checks, `warn` for non-blocking gaps, and a failure status such as `failed` for blocking or unsuccessful states.
|
||||
|
||||
PSD-0014: When a preparation script uses terminal colors in its status output, apply a consistent severity mapping so `ok` is green, `warn` is yellow, and all other status levels are red.
|
||||
|
||||
PSD-0015: In bracketed status markers such as `[ok]` or `[warn]`, keep the square brackets uncolored and apply the severity color only to the inner status text.
|
||||
|
||||
PSD-0016: Colorized status output shall degrade safely in non-terminal or non-color contexts so the script remains readable and automation-friendly without ANSI support.
|
||||
|
||||
PSD-0017: End with an explicit readiness conclusion that distinguishes between successful preparation, incomplete prerequisites, and failed installation attempts.
|
||||
|
||||
PSD-0018: Installation logic should use the narrowest supported platform-specific package-manager actions necessary for the declared scope and should fail clearly when no supported installation path is available.
|
||||
|
||||
PSD-0019: Treat repo-local helper tooling and local package installation boundaries explicitly rather than assuming global installs, especially when the prepared environment is intended to be reproducible.
|
||||
|
||||
PSD-0020: Keep the script suitable for both interactive local developer use and non-interactive automation checks by avoiding prompts during normal execution unless the prompt explicitly requires interactivity.
|
||||
|
||||
PSD-0021: When a script depends on generated helper files or adjacent validation helpers, update those supporting files only as needed to keep the preparation flow coherent and usable.
|
||||
|
||||
PSD-0022: Verify shell syntax after changes and, when feasible, run a dry readiness check so the resulting preparation flow is validated rather than only written.
|
||||
@@ -1,97 +0,0 @@
|
||||
# Architecture
|
||||
|
||||
## Architecture Goals
|
||||
|
||||
- Keep the tool small, local, and easy to reason about.
|
||||
- Separate media inspection, stored normalization rules, and conversion execution clearly enough that users can inspect and adjust behavior.
|
||||
- Favor explicit local state and deterministic rule application over opaque automation.
|
||||
- Make external runtime dependencies and platform assumptions visible.
|
||||
|
||||
## System Context
|
||||
|
||||
- Primary actors:
|
||||
- Local operator running the CLI.
|
||||
- Local operator using the Textual TUI to inspect files and maintain rules.
|
||||
- External systems:
|
||||
- `ffprobe` for media introspection.
|
||||
- `ffmpeg` for conversion and extraction.
|
||||
- TMDB API for optional show and episode metadata.
|
||||
- Local filesystem for source media, generated outputs, subtitles, logs, config, and database files.
|
||||
- Data entering the system:
|
||||
- Media container and stream metadata from source files.
|
||||
- Regex patterns and per-show normalization rules entered in the TUI.
|
||||
- Optional config values from `~/.local/etc/ffx.json`.
|
||||
- Optional TMDB identifiers and CLI overrides.
|
||||
- Optional external subtitle files.
|
||||
- Data leaving the system:
|
||||
- Normalized output media files.
|
||||
- Extracted stream files from unmux operations.
|
||||
- SQLite rows representing shows, patterns, tracks, tags, shifted seasons, and properties.
|
||||
- Local log output and console messages.
|
||||
|
||||
## High-Level Building Blocks
|
||||
|
||||
- Frontend, CLI, API, or worker:
|
||||
- A Click-based CLI in [`src/ffx/ffx.py`](/home/osgw/.local/src/codex/ffx/src/ffx/ffx.py).
|
||||
- A Textual terminal UI rooted in [`src/ffx/ffx_app.py`](/home/osgw/.local/src/codex/ffx/src/ffx/ffx_app.py) with screens for shows, patterns, file inspection, tracks, tags, and shifted seasons.
|
||||
- Core business logic:
|
||||
- Descriptor objects model media files, shows, and tracks.
|
||||
- Controllers encapsulate CRUD operations and workflow orchestration for shows, patterns, tags, tracks, season shifts, configuration, and conversion.
|
||||
- `MediaDescriptorChangeSet` computes differences between a file and its stored target schema to drive metadata and disposition updates.
|
||||
- Storage:
|
||||
- SQLite via SQLAlchemy ORM, with schema rooted in shows, patterns, tracks, media tags, track tags, shifted seasons, and generic properties.
|
||||
- A configuration JSON file supplies optional path, metadata-filtering, and filename-template settings.
|
||||
- Integration adapters:
|
||||
- Process execution wrapper for `ffmpeg`, `ffprobe`, `nice`, and `cpulimit`.
|
||||
- HTTP adapter for TMDB via `requests`.
|
||||
|
||||
## Data And Interface Notes
|
||||
|
||||
- Key entities or records:
|
||||
- `Show`: canonical TV show metadata plus digit-formatting rules for generated filenames.
|
||||
- `Pattern`: regex rule tying filenames to one show and one target media schema.
|
||||
- `Track` and `TrackTag`: persisted target stream layout, codec, dispositions, audio layout, and stream-level tags.
|
||||
- `MediaTag`: persisted container-level metadata for a pattern.
|
||||
- `ShiftedSeason`: mapping from source numbering ranges to adjusted season and episode numbers.
|
||||
- `Property`: internal key-value storage currently used for database versioning.
|
||||
- External interfaces:
|
||||
- CLI commands for conversion, inspection, extraction, and crop detection.
|
||||
- TUI workflows for rule authoring and rule maintenance.
|
||||
- Environment variable `TMDB_API_KEY` for TMDB access.
|
||||
- Config keys `databasePath`, `logDirectory`, and `outputFilenameTemplate`, plus optional metadata-filter rules.
|
||||
- Validation rules:
|
||||
- Only supported media-file extensions are accepted for conversion.
|
||||
- Stored database version must match the runtime-required version.
|
||||
- A normalized descriptor may have at most one default and one forced stream per relevant track type.
|
||||
- Stored target tracks must refer to valid source tracks of matching types.
|
||||
- Shifted-season ranges are intended not to overlap for the same show and season.
|
||||
- TMDB lookups require a show ID and season and episode numbers.
|
||||
- Error-handling approach:
|
||||
- User-facing operational failures are raised as `click.ClickException` or warnings.
|
||||
- Ambiguous default and forced stream states trigger prompts unless `--no-prompt` is set, in which case the command fails fast.
|
||||
- External-process failures and invalid media are surfaced through logs and command errors rather than retries, except for TMDB rate-limit retries.
|
||||
|
||||
## Deployment And Operations
|
||||
|
||||
- Runtime environment:
|
||||
- Local Python environment with the package installed and `ffmpeg`, `ffprobe`, `nice`, and `cpulimit` available on `PATH`.
|
||||
- Deployment shape:
|
||||
- Single-process command execution on demand; no daemon, queue, or network service of its own.
|
||||
- Secrets and configuration handling:
|
||||
- TMDB secret is read from `TMDB_API_KEY`.
|
||||
- User config is read from `~/.local/etc/ffx.json`.
|
||||
- Database path may also be overridden per command via `--database-file`.
|
||||
- Logging and monitoring approach:
|
||||
- File and console logging configured per invocation.
|
||||
- Default log file path is `~/.local/var/log/ffx.log`.
|
||||
- No dedicated monitoring integration is present.
|
||||
|
||||
## Open Technical Questions
|
||||
|
||||
- Question: Should Linux-specific assumptions such as `/dev/null`, `nice`, `cpulimit`, and `~/.local` remain part of the supported-platform contract?
|
||||
- Risk: Portability and operational behavior are underspecified for non-Linux environments.
|
||||
- Next decision needed: Either document Linux-like systems as the official support boundary or refactor the process and path handling for broader portability.
|
||||
|
||||
- Question: Should placeholder TUI surfaces such as settings and help become part of the required product surface or stay explicitly out of scope?
|
||||
- Risk: The UI appears broader than the actually finished feature set.
|
||||
- Next decision needed: Either remove or complete placeholder screens and update requirements accordingly.
|
||||
@@ -1,101 +0,0 @@
|
||||
## 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.
|
||||
Reference in New Issue
Block a user