How book000/youtube-live-recorder works
Project type & purpose (from README + tree)
This is a Dockerized automation tool (“youtube-live-recorder”) that monitors a YouTube Channel or Playlist and records/downloads live videos into a target directory. It’s not a full-stack web app; it’s a headless worker/CLI-style service intended to run via Docker Compose with configuration supplied by an env file (recorder.env).
Key runtime behaviors implied by the repo:
• Polling/monitoring: detect a new live stream / newly available video for a given CHANNEL or PLAYLIST, optionally filtered by TITLE_FILTER.
• Recording/downloading: once detected, download/record the stream (very likely via external CLI tools packaged in the container image).
• Persistence: save outputs to disk under a directory named by TARGET.
File structure → architectural hints
Top-level:
• docker-compose.yml: primary runtime entrypoint for end users; defines one or more services, volumes, env injection.
• watch-new-movie/: a Node.js/TypeScript subproject that is almost certainly the watcher component:
• watch-new-movie/src/main.ts: main watcher logic entrypoint.
• watch-new-movie/package.json, tsconfig.json, lint configs: confirms TS CLI/service.
• watch-new-movie/Dockerfile + watch-new-movie/entrypoint.sh: strongly suggests the watcher can be built/run as its own container OR embedded into the root image.
docker-compose stack
• Service: youtube-live-recorder (name from compose; if unknown, label generically)
• Built from Dockerfile (root)
• Started via entrypoint.sh
• Receives env from recorder.env (document variables: TARGET, CHANNEL/PLAYLIST, TITLE_FILTER)
• Mounts volume/bind mount for output directory
Internal logical runtime processes (even if same container)
• Watcher process (from watch-new-movie/src/main.ts)
• Responsibility: poll channel/playlist, apply title filter, emit “video id / live url / job trigger”
• Recorder/Downloader process (implied by “Record and download YouTube live videos” + presence of shell entrypoint scripts)
• Responsibility: invoke downloader/recorder toolchain; manage retries; write files
• Filesystem writer (can be a subcomponent): ensures directory naming based on TARGET, organizes outputs
Dependencies packaged in the image
• Download/record tool (e.g., yt-dlp/ffmpeg-like functionality)
• Shell orchestration (entrypoint.sh)
• entrypoint.sh → Watcher: “start watcher loop”
• Watcher → Recorder: “trigger recording for video/stream”
• Recorder → YouTube CDN: “media download”
• Recorder → Output Volume: “write .mp4/.ts + metadata”
• Watcher → YouTube metadata endpoints: “list channel/playlist items; detect live”
• Config Loader
• Reads env: TARGET, CHANNEL, PLAYLIST, TITLE_FILTER
• Validates: “Either CHANNEL or PLAYLIST required”
• YouTube Discovery Client
• Fetches latest videos / live status for channel/playlist
• Produces a normalized list of candidate videos
• Filter Engine
• Applies TITLE_FILTER
• State/De-duplication
• Avoid re-recording the same video (store seen IDs)
• Where state lives: filesystem (under TARGET), in-memory, or a small state file (represent as “Local State Store” even if just a file)
• Job Trigger / Orchestrator
• Calls the recorder/downloader (shell exec)
• Handles concurrency (single flight vs parallel)
• Logging/Telemetry
• Logs to stdout (container logs)
Interactions:
• Config Loader → Discovery Client: supplies IDs and options
• Discovery Client → Filter Engine → State Check → Trigger Recorder
• Trigger Recorder → “Recorder CLI toolchain”
• Recorder toolchain → Output FS
Architectural patterns / principles to highlight (specific to this project)
• Worker pattern / daemon loop: a long-running container that polls and reacts.
• Separation of concerns:
• “Discovery/Decision” (watch-new-movie Node/TS)
• “Execution” (record/download toolchain via shell)
• Immutable runtime packaging: Docker image contains everything required; Compose injects config and storage.
• External system boundary: YouTube is a hard dependency; clearly mark it as outside your trust boundary.
• Persistent volume boundary: outputs are durable; container is ephemeral.