A polished desktop app and self-hostable server for downloading any media from any website*

Download · Features · Self-hosting · API · Building from Source · Disclaimer

---

Overview

MediaMagnet puts the power of gallery-dl, yt-dlp and spotdl behind a clean GUI.

It ships as two variants for the same interface:

• Desktop: a Tauri 2 application for Windows, Linux and macOS, with native window controls, notifications and file pickers.
• Server: a single Rust binary that serves the same web UI to a browser and exposes a versioned REST API at /api/v1. Anything the browser stores (settings, cookies, API keys) stays in that browser's localStorage and is sent with each job, so the server keeps no per-user configuration.

Paste a URL, configure your options, and let MediaMagnet handle the rest.

Features

• Unified downloader: smart selection between gallery-dl, yt-dlp and spotdl
• Headless mode: one click to download as you browse through sites
• REST API: OpenAPI 3.1 specification and a typed TypeScript client
• Custom arguments: pass global or per-site arguments directly to the backends (API keys, user IDs, anything supported by the backend)
• Cookie manager: supports both JSON and Netscape formats, with per-job cookies over the API
• Settings import / export: back up and share your configuration with a single click
• Cross-platform: native binaries for Windows, Linux and macOS; the server runs anywhere Rust does
• Lightweight: built on Tauri and a single Axum server

---

Installation

Pre-built Binaries

Head to the Releases page and grab the installer for your platform.

For step-by-step instructions for every platform, architecture and installation method, see INSTALLATION.md.

Platform	Format
Windows	.msi / .exe
Linux (Debian/Ubuntu)	.deb
Linux (Fedora/RHEL)	.rpm
Linux (universal)	.AppImage
macOS (Apple Silicon)	.dmg
macOS (Intel)	.dmg

Linux users: The .AppImage works on most distributions without installation. Just mark it executable and run it.

Arch Linux: Download PKGBUILD and install to your system!

Standalone server archives for Linux (x86_64/aarch64), macOS and Windows are attached to server-v* releases. Each archive contains the self-contained binary, the LICENSE and the API docs; the web UI is embedded.

---

Self-hosting

The server needs the same download tools as the desktop app: yt-dlp, gallery-dl and spotdl on PATH (or a directory set in MM_BINARIES_DIR), plus ffmpeg for merging. Desktop release builds, the Docker image and the -tools server archives install the latest versions from PyPI at build time; the plain server archive expects the tools on PATH.

Docker

docker build -t mediamagnet .
docker run -d --name mediamagnet \
  -p 8080:8080 \
  -v mediamagnet:/data \
  -e MM_TOKEN=change-me \
  mediamagnet

Then open http://localhost:8080. Downloads and settings live in the /data volume. The image installs yt-dlp, gallery-dl, spotdl and ffmpeg from the repositories, plus Deno.

Standalone binary

Download the archive for your platform from a server-v* release, extract it and run the binary:

tar -xzf mediamagnet-server-0.6.1-x86_64-unknown-linux-gnu-tools.tar.gz
./mediamagnet-server-0.6.1-x86_64-unknown-linux-gnu-tools/mediamagnet-server

The server picks up the backends from PATH or binaries/ directory beside the executable automatically.

Desktop binary as a server

The desktop executable embeds the same server and web UI. Pass --launch-server to serve the SPA and /api/v1 without opening a window:

MediaMagnet --launch-server

It listens on 0.0.0.0:8080 and honors the same MM_* variables as the standalone server (including MM_TOKEN). The bundled Python tools are found relative to the installed executable. Server mode keeps its data in the standalone server's directory ($XDG_DATA_HOME/mediamagnet), separate from the desktop app's own settings.

Variable	Default	Purpose
MM_BIND	0.0.0.0:8080	Listen address.
MM_DATA_DIR	$XDG_DATA_HOME/mediamagnet	Settings, cookies and runtime data.
MM_DOWNLOAD_ROOT	$MM_DATA_DIR/downloads	Download directory, also served by /files.
MM_FILE_TTL_SECS	3600	Seconds an undelivered job output may remain before the server deletes it.
MM_STATIC_DIR	embedded UI	Serve the web UI from this directory instead.
MM_TOKEN	unset	Require this bearer token on every request.
MM_ALLOW_CUSTOM_ARGS	off	Accept user-supplied tool arguments (deny-list filtered). When off, jobs carrying them fail; see the API docs.

The binary speaks plain HTTP. Put it behind a TLS reverse proxy before exposing it, and set MM_TOKEN if anyone else can reach it. Without a token the API is open.

---

Building from Source

Requirements

• Bun
• Rust (stable toolchain)
• The Tauri platform prerequisites for your OS

Steps

# Clone the repository
git clone https://github.com/NullCode1337/MediaMagnet.git
cd MediaMagnet

# Install frontend dependencies
bun install

# Run the desktop app in development mode
bun run tauri dev

# Build a release binary
bun run tauri build

# Build the server (web UI + Rust binary)
bun run build:server
./target/release/mediamagnet-server

---

API

The full reference is in docs/API.md; the machine-readable specification is docs/openapi.yaml.

curl -X POST http://localhost:8080/api/v1/downloads \
  -H 'Content-Type: application/json' \
  -d '{"url":"https://www.youtube.com/watch?v=..."}'

curl -N http://localhost:8080/api/v1/events   # Server-Sent Events

A typed client lives in packages/client:

import { createMediaMagnetClient, subscribeEvents } from "@mediamagnet/client";

const api = createMediaMagnetClient({ baseUrl: "http://localhost:8080" });
await api.POST("/downloads", { body: { url } });

Regenerate its types after changing the spec with bun run generate:api.

---

Roadmap

• gallery-dl integration
• yt-dlp integration
• spotdl integration
• Custom argument templates (global & site-wide)
• Settings import / export
• macOS Apple Silicon support
• Self-hosted server and web UI
• REST API with an OpenAPI spec and typed client
• aria2 integration
• Torrent streaming
• AUR package

Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature/my-feature
3. Commit your changes: git commit -m 'Add my feature'
4. Push and open a Pull Request

Please open an issue first for larger changes so we can discuss before you start working on the changes.

DISCLAIMER

MediaMagnet is a GUI frontend for numerous backends and does not itself host, cache, or redistribute any media, or provide any means to obtain said media. Users are responsible for ensuring their downloads comply with the terms of service of the sites they download from and applicable copyright law.

---

⚠️ Alpha software. MediaMagnet is in active development. Please report any bugs that you might encounter.

Software designed by NullCode