Repository: caorushizi/mediago

Stars: 8936

CLAUDE.md Copy Chapter

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview Copy Chapter

MediaGo is a cross-platform video downloader supporting m3u8/HLS streams. The codebase is a pnpm monorepo with three products:

1. Desktop app (apps/electron + apps/ui) — Electron wrapper that launches Go Core as a subprocess
2. Web server (apps/server + apps/ui) — Node.js launcher that spawns Go Core as a subprocess
3. Video player (apps/core + apps/player-ui) — Player UI embedded in Go Core for video playback

All three products share the Go Core backend (apps/core) for download orchestration.

Common Commands Copy Chapter

pnpm install                # Install all dependencies (run once per clone)
pnpm dev:electron           # Start Electron desktop dev environment (HMR)
pnpm dev:server             # Start server dev environment (HMR)
pnpm build:electron         # Production build for Electron
pnpm build:web              # Build UI only (server mode)
pnpm core:dev               # Start Go Core dev server (port 9900)
pnpm core:build             # Compile Go Core binary
pnpm player:dev             # Start Player dev (alias for core:dev)
pnpm player:build           # Build Player (alias for core:build)
pnpm deps:download          # Download third-party tools (ffmpeg, BBDown, etc.)
pnpm deps:download:all      # Download tools for all platforms
pnpm lint                   # Lint with oxlint
pnpm lint:fix               # Auto-fix lint issues
pnpm format                 # Format with oxfmt
pnpm format:check           # Check formatting without modifying
pnpm check                  # Full check: lint + format + type check
pnpm type:check             # TypeScript type checking via Turborepo
pnpm pack:electron          # Build + package Electron distributable

Commits use Conventional Commits format (e.g. feat(electron): add queue UI).

Architecture Copy Chapter

Monorepo Layout Copy Section

Apps:

- apps/core/ — Go (Gin) REST API backend for download orchestration. Runs on port 9900. Uses SQLite (GORM), SSE for real-time events, PTY for capturing download tool output. Built with Gulp + Go cross-compilation.
- apps/electron/ — Electron main process (tsdown build, inversify DI). Launches Go Core via @mediago/service-runner.
- apps/server/ — Node.js launcher (tsdown build). Spawns Go Core via @mediago/service-runner.
- apps/ui/ — Shared React 19 frontend (Vite 8, Ant Design 6, Zustand, TailwindCSS 4, i18next). Used by both Electron and server targets.
- apps/player-ui/ — React 19 frontend for player (Vite 8, shadcn/ui, video.js, TailwindCSS 4). Built assets are embedded into Go Core via //go:embed.

Packages:

- packages/shared/common/ — Platform-agnostic shared types, constants, and utilities
- packages/core-sdk/ — TypeScript SDK for Go Core REST API (Axios, SSE via eventsource)
- packages/electron-preload/ — Electron preload scripts for IPC bridge
- packages/browser-extension/ — Browser extension (Lit web components)
- docs/ — VitePress documentation (Chinese, English, Japanese)

Multi-Target Build Copy Section

The APP_TARGET env var (electron | server) controls which backend the UI builds against. Both targets share the same React UI but connect via different transports:

- Electron: IPC bridge (preload) + Go Core direct (via @mediago/core-sdk)
- Server/Web: HTTP/WebSocket + Go Core direct (via @mediago/core-sdk)

The UI adapter layer (apps/ui/src/hooks/adapters/) abstracts this: electron.ts provides IPC bridge in desktop mode, platform-stubs.ts provides no-op stubs in web mode, and index.ts exports platformApi which selects the appropriate adapter.

Key Patterns Copy Section

- Go Core as subprocess: Both Electron and server apps launch Go Core via @mediago/service-runner, which manages the process lifecycle and port allocation
- Dependency Injection: inversify with @inversifyjs/binding-decorators in Electron backend
- State Management: Zustand in the UI
- Real-time events: Go Core emits SSE events (/api/events); the UI's api/events.ts subscribes and dispatches to React via a listener pattern
- TypeScript: Strict mode with experimental decorators and decorator metadata enabled
- Module format: ES Modules everywhere

Tooling Copy Chapter

- Package manager: pnpm 10.15.0 (enforced via packageManager field)
- Build orchestration: Turborepo
- App bundling: tsdown for Node/Electron, Vite 8 for UI apps
- Go builds: Gulp orchestrating go build / go run in apps/core
- Linter: oxlint (config in .oxlintrc.json)
- Formatter: oxfmt (config in .oxfmtrc.json)
- Pre-commit: husky + lint-staged (runs oxlint --fix + oxfmt --write on staged files)
- Electron packaging: electron-builder

Style Conventions Copy Chapter

- TypeScript, ES modules, 2-space indentation, UTF-8, LF endings
- Components: PascalCase. Utilities: camelCase. Constants: SCREAMING_SNAKE_CASE
- UI port: 8555 (strict). Go Core port: 9900. Player UI port: 8556

README.md Copy Chapter

<div align="center">
<h1>MediaGo</h1>
<a href="https://downloader.caorushizi.cn/en/guides.html?form=github">Quick Start</a>
<span>&nbsp;&nbsp;•&nbsp;&nbsp;</span>
<a href="https://downloader.caorushizi.cn/en?form=github">Website</a>
<span>&nbsp;&nbsp;•&nbsp;&nbsp;</span>
<a href="https://downloader.caorushizi.cn/en/documents.html?form=github">Docs</a>
<span>&nbsp;&nbsp;•&nbsp;&nbsp;</span>
<a href="https://github.com/caorushizi/mediago/discussions">Discussions</a>
<br>

<a href="https://github.com/caorushizi/mediago/blob/master/README.zh.md">中文</a>
<span>&nbsp;&nbsp;•&nbsp;&nbsp;</span>
<a href="https://github.com/caorushizi/mediago/blob/master/README.jp.md">日本語</a>
<br>

<!-- MediaGo Pro -->
<a href="https://mediago.torchstellar.com/?from=github">
<img src="https://img.shields.io/badge/✨_New_Release-MediaGo_Pro-ff6b6b?style=for-the-badge&logo=data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAyNCAyNCIgZmlsbD0id2hpdGUiPjxwYXRoIGQ9Ik0xMiAyTDMgN2wzIDMgNi00IDYgNCAzLTMtOS01eiIvPjxwYXRoIGQ9Ik0zIDE3bDkgNSA5LTUtMy0zLTYgNC02LTQtMyAzeiIvPjwvc3ZnPg==" alt="MediaGo Pro" />
</a>
<a href="https://mediago.torchstellar.com/?from=github">
<img src="https://img.shields.io/badge/🚀_Try_Now-Online_Version_No_Install-2a82f6?style=for-the-badge" alt="Try Now" />
</a>
<br>

<img alt="GitHub Downloads (all assets, all releases)" src="https://img.shields.io/github/downloads/caorushizi/mediago/total">
<img alt="GitHub Downloads (all assets, latest release)" src="https://img.shields.io/github/downloads/caorushizi/mediago/latest/total">
<img alt="GitHub Repo stars" src="https://img.shields.io/github/stars/caorushizi/mediago">
<img alt="GitHub forks" src="https://img.shields.io/github/forks/caorushizi/mediago">
<img alt="GitCode" src="https://gitcode.com/caorushizi/mediago/star/badge.svg">
<br>

<a href="https://trendshift.io/repositories/11083" target="_blank">
<img src="https://trendshift.io/api/badge/repositories/11083" alt="caorushizi%2Fmediago | Trendshift" style="width: 250px; height: 55px;" width="250" height="55"/>
</a>

<hr />
</div>

What is MediaGo? Copy Chapter

A cross-platform streaming media downloader with built-in browser sniffing — grab m3u8, HLS, and more with zero packet-capture hassle.

- ✅&nbsp; No packet capture needed — The built-in browser automatically detects video resources on any page. Just pick what you want from the detected list and download.
- 📱&nbsp; Watch on mobile — Seamlessly switch between PC and mobile. Once a video is downloaded, scan a QR code to watch it on your phone.
- ⚡️&nbsp; Batch downloads — Download multiple videos and live streams at the same time — no wasted bandwidth.
- 🎉&nbsp; Docker support — Deploy the web UI via Docker for quick, headless operation.
- 🦞&nbsp; OpenClaw Skill — Download videos with natural language through AI coding assistants (OpenClaw, Claude Code, etc.). Install with npx clawhub@latest install mediago.

Quick Start Copy Chapter

You need Node.js and pnpm. Install Node.js from the official site, then install pnpm:

npm i -g pnpm

Running locally Copy Chapter

Clone the repo

git clone https://github.com/caorushizi/mediago.git
Install dependencies

pnpm install
Start the Electron desktop app (dev mode)

pnpm dev:electron
— or — start the web server (dev mode)

pnpm dev:server
Package the Electron app for distribution

pnpm pack:electron
Package the web server for distribution

pnpm pack:server

Releases Copy Chapter

v3.5.0-beta.0 (Apr 3, 2026) Copy Section

#### Downloads

- Windows (installer) v3.5.0-beta.0
- Windows (portable) v3.5.0-beta.0
- macOS ARM64 (Apple Silicon) v3.5.0-beta.0
- macOS x64 (Intel) v3.5.0-beta.0
- Linux v3.5.0-beta.0
- Docker v3.5.0-beta.0: docker run -d --name mediago -p 8899:8899 -v /path/to/mediago:/app/mediago ghcr.io/caorushizi/mediago:3.5.0-beta.0

v3.0.0 (Oct 7, 2024) Copy Section

#### Downloads

- Windows (installer) v3.0.0
- Windows (portable) v3.0.0
- macOS ARM64 (Apple Silicon) v3.0.0
- macOS x64 (Intel) v3.0.0
- Linux v3.0.0
- Docker: docker run -d --name mediago -p 8899:8899 -v /path/to/mediago:/app/mediago ghcr.io/caorushizi/mediago:latest

One-click Docker deployment via BT Panel Copy Section

1. Install BT Panel using the official script.
2. Log in to the panel, click Docker in the sidebar, and follow the prompts to install the Docker service.
3. Find MediaGo in the app store, click Install, configure your domain, and you're done.

Screenshots Copy Chapter

!Home

!Home — dark mode

!Settings

!Resource extraction

Changelog (v3.0.0) Copy Chapter

- Docker deployment for the web UI
- Redesigned desktop UI
- Video playback on desktop and mobile
- Fixed blank window on macOS launch
- Improved batch download UX
- Added Windows portable build (no install required)
- Enhanced resource sniffing — detect multiple videos per page
- Import / export favorites
- Export the download list from the home page
- Improved "New download" form flow
- Open the app and add downloads via URL scheme
- Various bug fixes and UX improvements

Tech Stack Copy Chapter

- React
- Electron
- Koa
- Vite
- Ant Design
- Tailwind CSS
- shadcn/ui
- Inversify

Acknowledgements Copy Chapter

- N_m3u8DL-RE
- BBDown
- yt-dlp
- mediago-core

Disclaimer Copy Chapter

This project is for educational and research purposes only. Do not use it for any commercial or illegal purposes.

> 1. All code and functionality provided by this project are intended solely as a reference for learning about streaming media technologies. Users must comply with the laws and regulations of their jurisdiction.

2. Any content downloaded using this project remains the property of its original copyright holders. Users should delete downloaded content within 24 hours or obtain proper authorization.

3. The developers of this project are not responsible for any actions taken by users, including but not limited to downloading copyrighted content or impacting third-party platforms.

4. Using this project for mass scraping, disrupting platform services, or any activity that infringes upon the legitimate rights of others is strictly prohibited.

5. By using this project you acknowledge that you have read and agree to this disclaimer. If you do not agree, stop using the project and delete it immediately.