Skip to content
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
41 changes: 41 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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)
Expand All @@ -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 |
Expand All @@ -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.
Expand All @@ -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
Expand Down Expand Up @@ -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**.
Expand Down Expand Up @@ -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.
Expand All @@ -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:
Expand All @@ -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
Expand Down Expand Up @@ -278,6 +297,8 @@ checkpoint0_tests/
Regression and safety coverage.
```

---

## Identity policies

### MANUAL
Expand All @@ -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:
Expand Down Expand Up @@ -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:
Expand All @@ -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`.
Expand All @@ -359,13 +386,17 @@ 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.
- **dev** — ongoing development and testing.

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.**
Expand All @@ -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:
Expand Down
Loading