# Livestream Recorder

Livestream Recorder is a native macOS prototype for saving live YouTube streams as local MP4 files. Paste a livestream URL, record from the current point or catch up from the available beginning, follow progress in a focused SwiftUI interface, and let the prototype merge and verify the final recording.

Current release: **1.0** (`1.0.0` in the Xcode project). See `CHANGELOG.md` for release notes.

The included Swift implementation is a working reference, not a platform limit. Its recording workflow, process management, parsing, finalization, and tests can be rewritten as a Windows or Linux desktop program, a CLI, a web-controlled service, or another interface with an AI coding agent.

## What is included

- Complete Swift 6 and SwiftUI source in `code/`
- Xcode project, shared scheme, and optional XcodeGen specification
- Current-point and from-beginning recording modes
- Browser-cookie selection for streams that require a signed-in YouTube session
- `yt-dlp`, FFmpeg, ffprobe, and Deno discovery and process integration
- Live progress, catch-up status, cancellation, retry, finalization, and Finder reveal flows
- Conservative cleanup for interrupted catch-up recordings
- Unit tests for URL validation, command construction, output parsing, state, file discovery, preferences, timeline inspection, and video finalization
- Human instructions plus dedicated guidance for AI coding agents

## Human quick start

### 1. Prerequisites

- macOS 14 or newer
- Xcode 16 or newer
- Homebrew
- A browser in which you are signed into YouTube

Install the recording tools:

```sh
brew install yt-dlp ffmpeg deno
```

### 2. Build and test

```sh
cd code
xcodebuild -project StreamRecorder.xcodeproj \
  -scheme StreamRecorder \
  -destination 'platform=macOS' \
  test CODE_SIGNING_ALLOWED=NO
```

Open `StreamRecorder.xcodeproj` in Xcode and run the `StreamRecorder` scheme. If you use XcodeGen, `xcodegen generate` can recreate the project from `project.yml`.

### 3. Record a stream

Choose whether to start at the current point or request the available stream from its beginning. Pick a destination and the browser whose YouTube cookies may be used, then paste a live YouTube URL. The prototype starts automatically, reports progress, finalizes an MP4 when stopped, and can reveal the saved file in Finder.

Only record streams you are entitled to save. Review YouTube's terms and applicable copyright law for your use.

## Project map

- `code/StreamRecorder/App/` — app lifecycle and safe termination
- `code/StreamRecorder/Views/` — SwiftUI recording interface
- `code/StreamRecorder/Controllers/` — recording process orchestration and state
- `code/StreamRecorder/Models/` — preferences, browser choices, and recording state
- `code/StreamRecorder/Services/` — validation, tool discovery, commands, parsing, media inspection, and finalization
- `code/StreamRecorderTests/` — unit and tool-assisted media tests
- `code/project.yml` — optional XcodeGen source of project settings

Read `ARCHITECTURE.md` for the runtime flow and `AGENTS.md` before handing the package to an AI coding agent.
