# Repository: caorushizi/mediago # Stars: 8936 ## CLAUDE.md # CLAUDE.md This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. ## Project Overview 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 ```bash 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 ### Monorepo Layout **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 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 - **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 - **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 - 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

MediaGo

Quick Start   •   Website   •   Docs   •   Discussions
中文   •   日本語
MediaGo Pro Try Now
GitHub Downloads (all assets, all releases) GitHub Downloads (all assets, latest release) GitHub Repo stars GitHub forks GitCode
caorushizi%2Fmediago | Trendshift
## What is MediaGo? A cross-platform streaming media downloader with built-in browser sniffing — grab m3u8, HLS, and more with zero packet-capture hassle. - **✅  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. - **📱  Watch on mobile** — Seamlessly switch between PC and mobile. Once a video is downloaded, scan a QR code to watch it on your phone. - **⚡️  Batch downloads** — Download multiple videos and live streams at the same time — no wasted bandwidth. - **🎉  Docker support** — Deploy the web UI via Docker for quick, headless operation. - **🦞  OpenClaw Skill** — Download videos with natural language through AI coding assistants (OpenClaw, Claude Code, etc.). Install with `npx clawhub@latest install mediago`. ## Quick Start You need **Node.js** and **pnpm**. Install Node.js from the [official site](https://nodejs.org/), then install pnpm: ```shell npm i -g pnpm ``` ## Running locally ```shell # 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 ### v3.5.0-beta.0 (Apr 3, 2026) #### Downloads - [Windows (installer) v3.5.0-beta.0](https://github.com/caorushizi/mediago/releases/download/v3.5.0-beta.0/mediago-community-setup-win32-x64-3.5.0-beta.0.exe) - [Windows (portable) v3.5.0-beta.0](https://github.com/caorushizi/mediago/releases/download/v3.5.0-beta.0/mediago-community-portable-win32-x64-3.5.0-beta.0.exe) - [macOS ARM64 (Apple Silicon) v3.5.0-beta.0](https://github.com/caorushizi/mediago/releases/download/v3.5.0-beta.0/mediago-community-setup-darwin-arm64-3.5.0-beta.0.dmg) - [macOS x64 (Intel) v3.5.0-beta.0](https://github.com/caorushizi/mediago/releases/download/v3.5.0-beta.0/mediago-community-setup-darwin-x64-3.5.0-beta.0.dmg) - [Linux v3.5.0-beta.0](https://github.com/caorushizi/mediago/releases/download/v3.5.0-beta.0/mediago-community-setup-linux-amd64-3.5.0-beta.0.deb) - 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) #### Downloads - [Windows (installer) v3.0.0](https://github.com/caorushizi/mediago/releases/download/v3.0.0/mediago-setup-win32-x64-3.0.0.exe) - [Windows (portable) v3.0.0](https://github.com/caorushizi/mediago/releases/download/v3.0.0/mediago-portable-win32-x64-3.0.0.exe) - [macOS ARM64 (Apple Silicon) v3.0.0](https://github.com/caorushizi/mediago/releases/download/v3.0.0/mediago-setup-darwin-arm64-3.0.0.dmg) - [macOS x64 (Intel) v3.0.0](https://github.com/caorushizi/mediago/releases/download/v3.0.0/mediago-setup-darwin-x64-3.0.0.dmg) - [Linux v3.0.0](https://github.com/caorushizi/mediago/releases/download/v3.0.0/mediago-setup-linux-amd64-3.0.0.deb) - 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 1. Install [BT Panel](https://www.bt.cn/new/download.html?r=dk_mediago) 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 ![Home](./images/home.png) ![Home — dark mode](./images/home-dark.png) ![Settings](./images/settings.png) ![Resource extraction](./images/browser.png) ## Changelog (v3.0.0) - 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 - [React](https://react.dev/) - [Electron](https://www.electronjs.org) - [Koa](https://koajs.com) - [Vite](https://vitejs.dev) - [Ant Design](https://ant.design) - [Tailwind CSS](https://tailwindcss.com) - [shadcn/ui](https://ui.shadcn.com/) - [Inversify](https://inversify.io) ## Acknowledgements - [N_m3u8DL-RE](https://github.com/nilaoda/N_m3u8DL-RE) - [BBDown](https://github.com/nilaoda/BBDown) - [yt-dlp](https://github.com/yt-dlp/yt-dlp) - [mediago-core](https://github.com/caorushizi/mediago-core) ## Disclaimer > **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.