diff --git a/README.md b/README.md index e2ac4f0..fe30379 100644 --- a/README.md +++ b/README.md @@ -11,6 +11,8 @@ Recorder started as a mature dynamic recording engine. The project now adds an identity-aware **Inspect / Watch / Record / Auto** layer around that engine, turning playlist discovery into an unattended recording workflow rather than a one-shot recording command. +--- + ## Why Recorder exists Recording a live stream sounds simple — until you need the recording to actually survive for hours unattended. @@ -47,6 +49,8 @@ The Recorder keeps that recording alive when the live-stream environment stops b The result is not simply a command that downloads a stream. It is an unattended live-recording system designed around the reality that online sources, networks, authorization, quality, and availability can all change while the event itself continues. +--- + ## Contents - [Inspect → Watch → Record → Auto](#inspect--watch--record--auto) @@ -60,9 +64,12 @@ The result is not simply a command that downloads a stream. It is an unattended - [Configuration](#configuration) - [Testing and CI](#testing-and-ci) - [Project status](#project-status) +- [Legal / Responsible Use](#legal--responsible-use) - [What’s next](#whats-next) - [End-user installation status](#end-user-installation-status) +--- + ## Inspect → Watch → Record → Auto | Stage | What Recorder does | @@ -74,6 +81,8 @@ The result is not simply a command that downloads a stream. It is an unattended The same Coordinator can also keep targets in **MANUAL** mode, where discovered identities are visible but recording starts only when the user selects one. +--- + ## Identity-aware source coordination Recorder separates **what is being recorded** from the individual playlist URL that happens to carry it at a particular moment. @@ -96,6 +105,8 @@ Key capabilities include: - **Optional refresh and launch sounds**, including snooze control. - **Regression and safety coverage** exercised by GitHub Actions. +--- + ## Architecture ```text @@ -137,6 +148,8 @@ Dynamic recorder A canonical identity can have only one active owner. The registry covers workers in **LAUNCHING**, **RECORDING**, and **WAITING_FOR_SOURCE** states, so MANUAL and automatic launches cannot accidentally create duplicate active recordings for the same identity. +--- + ## The recording engine — keeping a live recording alive The Coordinator solves the problem of **what should be recorded and when it should start**. @@ -200,6 +213,8 @@ Together, the two parts have distinct responsibilities: **The Coordinator finds and manages the recordings that should exist. The recording engine does the difficult work of keeping each one alive.** +--- + ## Coordinator dashboard The Coordinator is the main Inspect / Watch interface. It presents the system as a live terminal dashboard rather than a GUI. @@ -222,6 +237,8 @@ It shows: The dashboard also exposes runtime controls for manual recording selection, information, sound control, refresh, and exit. +--- + ## Unattended recording workflow A typical automatic workflow is: @@ -246,6 +263,8 @@ Continue watching for additional identities If the 20-worker active ceiling is reached, remaining identities stay watched instead of being incorrectly marked as failed. +--- + ## Project structure ```text @@ -278,6 +297,8 @@ checkpoint0_tests/ Regression and safety coverage. ``` +--- + ## Identity policies ### MANUAL @@ -292,6 +313,8 @@ Every newly eligible canonical identity is automatically launched through the sa Multiple matching identities can appear in one scan. Recorder can launch them as capacity permits while keeping duplicate ownership and the global worker ceiling enforced centrally. +--- + ## Configuration User-maintained runtime configuration is intentionally kept **outside this repository** in: @@ -322,6 +345,8 @@ python record_dynamic.py The repository deliberately does not publish live user configuration, signed playback URLs, cookies, or local sound files. +--- + ## Optional sounds Recorder and the Coordinator use separate optional local sound files: @@ -340,6 +365,8 @@ Coordinator launch notification takes priority when both Coordinator notificatio These optional local sound assets are not included in the repository. +--- + ## Testing and CI Python dependencies are installed from `requirements.txt`. @@ -359,6 +386,8 @@ run_all_tests.bat The test suite covers the shared source core, identity derivation, Coordinator behavior, launch planning, registry ownership, runtime status, worker launch, terminal hosting, sound behavior, and architecture boundaries. +--- + ## Branches - **main** — stable Recorder baseline. @@ -366,6 +395,8 @@ The test suite covers the shared source core, identity derivation, Coordinator b Development is normally validated on `dev` and promoted to `main` after the regression suite is green. +--- + ## Project status **Inspect / Watch / Record / Auto is implemented and promoted to the stable baseline.** @@ -374,6 +405,16 @@ Recorder already combines a mature recording engine with source discovery, quali That gives the project a stable foundation to build on. +--- + +## Legal / Responsible Use + +Recorder is intended for lawful and authorized recording workflows. + +Users are responsible for ensuring that their use complies with applicable laws, service terms, content rights, and access permissions. Nothing in this project grants rights to access, decrypt, copy, record, or distribute content that the user is not otherwise authorized to use. + +--- + ## What’s next The next phase extends the same foundation both technically and as a product: