Desktop App · version 1.0
Livestream Recorder
A native macOS app for recording live YouTube streams from now or from the available beginning, following catch-up progress, and finalizing reliable local MP4 files. Includes source, tests, and agent-ready instructions for customization or cross-platform rewrites.
The full source, tests, and documentation live in the public repository. MIT licensed. Issues and pull requests are off: fork it and make it yours.
Why I built this
Saving a livestream sounds like one command until you need a usable desktop workflow: browser-session access, start-now and catch-up modes, visible progress, cancellation, retries, process cleanup, separate media tracks, and an MP4 that opens reliably after an interrupted recording.
Livestream Recorder is the working result. It turns that fragile command-line path into a focused native interface and keeps the difficult pieces—process state, output parsing, live-edge tracking, artifact discovery, conservative tail cleanup, and finalization—separate and tested.
From live URL to verified MP4
The recording lifecycle is already connected.
- Choose start mode, destination, and browser.
- Paste an authorized live YouTube URL.
- Follow download and catch-up progress.
- Stop, finalize, and reveal the MP4.
Features
Two recording modes
Start at the current live point or request the stream from its available beginning and catch up toward live.
Paste to record
Choose the destination and browser once, then paste a supported YouTube livestream URL to begin.
Catch-up visibility
See captured media time, wall-clock time, download progress, and when the recording reaches the live edge.
Browser-session support
Select a local signed-in browser for streams that require YouTube cookies without storing cookie values in the software.
Reliable finalization
Locate merged or separate artifacts, remux or merge them with FFmpeg, and verify the resulting MP4.
Safe interruption
Stop gracefully, escalate a stuck process, finish work during app termination, and conservatively remove only clearly unusable tails.
Use cases
Personal stream archive
Save an authorized live broadcast to a local MP4 with a small, understandable workflow.
Creator backup tool
Adapt the software for creators who want a local copy while broadcasting.
Cross-platform desktop product
Port the service boundaries into a Windows, Linux, or cross-platform interface.
Command-line recorder
Replace SwiftUI with flags, progress output, signals, and meaningful exit codes.
Media workflow foundation
Add quality, codec, audio-only, naming, queue, and post-processing controls.
Process-integration reference
Study a tested native wrapper around long-running command-line tools and asynchronous output.
Tech stack
Application logic
Swift 6
Provides strict concurrency, typed state, process orchestration, parsing, and media-service boundaries.
Desktop interface
SwiftUI and AppKit
Build the focused window, native folder picker, saved preferences, Finder reveal, and termination flow.
Stream acquisition
yt-dlp
Discovers formats, reads an explicitly selected local browser session, and downloads the live media.
Media pipeline
FFmpeg and ffprobe
Inspect durations, merge tracks, remux output, analyze interrupted tails, and verify MP4 files.
Extraction runtime
Deno
Supplies the JavaScript runtime used by current YouTube extraction behavior.
Verification
XCTest
Covers URL rules, commands, parsing, state, preferences, artifact discovery, timelines, and finalization.
Screenshots and demos
What’s included
- Livestream Recorder version 1.0 with sanitized Swift 6 and SwiftUI source and no browser data, recordings, signing identities, personal paths, or build output
- Xcode project, shared scheme, and optional XcodeGen project specification
- Current-point and from-beginning recording workflows
- Tool discovery, safe process launching, progress parsing, retry, cancellation, and termination handling
- Media timeline inspection, output discovery, MP4 finalization, and conservative interrupted-tail analysis
- Unit and tool-assisted media tests
- Human quick start, versioned changelog, and dedicated AI-agent instructions
- Architecture, decisions, customization, configuration, security, distribution, and build guides
Documentation
The documentation lives in the repository, in one README: setup and usage, why I built it, how it was built, architecture, configuration, deployment, customization, security, the technical decisions, and the changelog. AGENTS.md gives coding agents the project context and operating rules.
Why use this
- Skip the fragile process-management and media-finalization groundwork
- Start with a real native app instead of a command pasted into a button
- Give an AI coding agent explicit behavior, architecture, tests, and porting guidance
- Customize the macOS version without reverse-engineering its edge cases
- Rewrite it for Windows, Linux, a CLI, or another interface while preserving the product contract
- Own the source and every dependency, packaging, and distribution decision
Customize it
Use the working source as a foundation. Keep it small, change it for your own workflow, or turn it into a different product.
- Ship it under your studio name: window, copy, icon, signing, and the recording habits your audience expects.
- Add quality, codec, audio-only, and filename controls until it feels like a product people pay to keep open.
- Build a queue for several authorized streams so a show night does not mean babysitting one URL.
- Port the same engine to Windows, Linux, Electron, or Tauri and sell a cross-platform companion.
- Expose a CLI with progress and exit codes for automation, agents, and headless capture jobs.
- Add another provider behind a clean validator and contract—only where terms and tests say you should.
MIT license
The repository includes an MIT LICENSE file. You can use, copy, change, publish, distribute, sublicense, or sell the code, including as part of a commercial product.
Keep the copyright and license notice with copies or substantial portions of the code. Third-party dependencies and assets keep their own licenses.