Livestream Recorder

Livestream Recorder is a native macOS app 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 software 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:

brew install yt-dlp ffmpeg deno

2. Build and test

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 software 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.

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.