# Architecture

## Overview

Livestream Recorder is a native SwiftUI macOS application that coordinates command-line media tools. The interface collects recording preferences and a YouTube livestream URL. `RecordingController` validates the destination, launches `yt-dlp` directly with structured arguments, consumes machine-readable progress markers, tracks media duration with ffprobe, and asks FFmpeg to produce a verified MP4.

There is no database, backend, account system, analytics service, or embedded API credential.

## Recording flow

1. `ContentView` loads saved mode, destination, and browser preferences.
2. `YouTubeURLValidator` accepts supported YouTube URL shapes.
3. `ToolchainLocator` finds `yt-dlp`, `ffmpeg`, and `deno` in the shell path and common installation locations.
4. `YTDLPCommandBuilder` produces an executable URL, argument array, and enriched process environment.
5. `RecordingController` launches one process and consumes stdout and stderr asynchronously.
6. `YTDLPOutputParser` converts prefixed lines into progress, start-time, file, and error events.
7. In from-beginning mode, `MediaTimelineInspector` uses ffprobe to estimate captured media duration and detect the live edge.
8. On completion or a user stop, `CompletedFileLocator` identifies merged or separate media artifacts.
9. `VideoFinalizer` merges or remuxes the sources into MP4, optionally consulting `InterruptedTailAnalyzer` for a clearly unusable interrupted tail.
10. The UI reports the saved file and can reveal it in Finder.

## Main boundaries

- `Views/ContentView.swift` — presentation and user input
- `Controllers/RecordingController.swift` — process lifecycle and application state
- `Services/YTDLPCommandBuilder.swift` — recording command contract
- `Services/YTDLPOutputParser.swift` — external-process output boundary
- `Services/MediaTimelineInspector.swift` — ffprobe duration and live-edge checks
- `Services/CompletedFileLocator.swift` — output artifact discovery
- `Services/VideoFinalizer.swift` — merge, remux, trim, and output verification
- `Services/InterruptedTailAnalyzer.swift` — conservative interrupted-tail analysis
- `Models/RecordingState.swift` — explicit UI-visible state machine

## Porting model

The product behavior separates cleanly from SwiftUI. A Windows, Linux, or CLI rewrite needs:

- URL and destination validation
- dependency discovery or bundled-tool management
- safe process spawning without shell interpolation
- asynchronous stdout/stderr parsing
- explicit recording and cancellation states
- artifact discovery and FFmpeg finalization
- platform-appropriate credential/session handling
- tests for command construction, parsing, state, and media output

Use the existing tests and service boundaries as the contract. Port behavior rather than translating Swift files line by line.
