Media Downloader

A cross-platform desktop application for downloading media from 8 platforms — videos, music, podcasts, and playlists — with a modern, themeable UI.

Supported Platforms

Platform Capabilities

Platform	Content Types	Features
YouTube	Videos, Playlists, Shorts, Music	Quality selection (144p–8K), audio-only extraction, subtitle downloads, automatic cookie generation for age-restricted content
Instagram	Posts, Reels	Automatic session/cookie authentication (imported from your logged-in browser), caption preservation, carousel support
Twitter/X	Tweets, Spaces	Image/video extraction from tweets; public live and replayable Spaces audio via ffmpeg
Pinterest	Pins	High-quality image retrieval with smart file naming
SoundCloud	Tracks, Sets	Best available audio, metadata and thumbnails, playlist support (free tracks only)
Spotify	Tracks, Albums, Playlists, Artists	Full metadata display, YouTube-backed audio with match selection
TikTok	Videos	Best quality video with metadata and thumbnail preservation
RadioJavan	Songs, Videos, Playlists, Podcasts, Albums	Direct MP3/MP4 downloads, playlist and podcast support, auto-cookie generation, CDN fallback across 5 hosts

Screenshots

Key Features

• 8 platforms — YouTube, Spotify, TikTok, Instagram, Twitter/X, Pinterest, SoundCloud, RadioJavan
• Smart URL detection — paste any supported link and the app detects the platform automatically
• Quality & format control — choose resolution (144p–8K), extract audio-only, or download video-only tracks
• Batch downloads — queue multiple items and process them concurrently with configurable worker count
• Subtitle support — download manual and auto-generated YouTube subtitles in any available language
• Playlist & album support — download entire playlists or albums with a single click
• 22 color themes — dark and light modes with instant switching, no restart required
• Custom themes — drop a JSON file into themes/ and it appears in the UI (see docs/themes.md)
• Auto cookie generation — Playwright-based browser cookies for YouTube, SoundCloud, Spotify, and RadioJavan (handles age-restricted and region-locked content)
• Real-time progress — live download speed, ETA, and status indicators
• Network monitoring — check connectivity to all platforms from the Tools menu
• Cross-platform — Windows (with installer), macOS, and Linux
• Configurable — YAML/JSON config files for all settings (download paths, concurrency, timeouts, platform options)

Requirements

• Python 3.10 or higher (Windows users: use the installer below — no Python needed)
• Playwright (for YouTube cookie generation)
• Internet connection

Development Requirements (Linting + LSP)

The local quality gates in this repo require these tools:

• ruff for linting (uv run ruff check .)
• basedpyright for strict editor/LSP parity (npx basedpyright --outputjson and npx basedpyright tests --outputjson)
• pytest for test validation (uv run pytest -q)

Install development dependencies with:

pip install -r requirements-dev.txt

If you use uv, the project dependencies are managed from pyproject.toml and uv.lock:

uv sync

For npx basedpyright ..., install Node.js 18+ if it is not already available.

Installation

Option 1: Windows Installer (Windows Only — Recommended)

The easiest way to run Media Downloader on Windows. No Python installation required.

1. Download the latest installer from the Releases page

   • MediaDownloaderSetup-1.2.2-x64.exe for 64-bit Intel/AMD PCs
   • MediaDownloaderSetup-1.2.2-arm64.exe for Windows on ARM devices

2. Run the installer — it will install:

   • The application (MediaDownloader.exe) with a Start Menu shortcut
   • ffmpeg (required for video processing) — downloaded automatically during setup
   • All Python dependencies (bundled by PyInstaller)

3. Launch from the Start Menu or desktop shortcut

Note on Windows SmartScreen: The installer is not code-signed, so Windows may show a blue "Windows protected your PC" warning. Click "More info" → "Run anyway" to proceed. This is normal for unsigned open-source software.

System requirements: Windows 10 or later, 64-bit (x64 or ARM64).

Option 2: Using uv (Recommended — Python Required)

# Clone the repository
git clone https://github.com/MSC72m/media_downloader.git
cd media_downloader

# Install uv if not already installed
# On macOS/Linux:
curl -LsSf https://astral.sh/uv/install.sh | sh
# On Windows:
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

# Install dependencies and run
uv sync
uv run playwright install chromium
uv run -m src.main

Option 3: Using pip

# Clone the repository
git clone https://github.com/MSC72m/media_downloader.git
cd media_downloader

# Create virtual environment
python -m venv venv

# Activate virtual environment
# On Windows:
venv\Scripts\activate
# On Linux/macOS:
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Install Playwright browser
playwright install chromium

Launch Application

# With uv:
uv run -m src.main

# With pip:
python -m src.main

Creating Desktop Shortcuts

Windows

1. Create a batch file media_downloader.bat in the project directory:

@echo off
cd /d "C:\path\to\media_downloader"
call venv\Scripts\activate
python -m src.main
pause

Replace C:\path\to\media_downloader with your actual installation path.

2. Create a shortcut:
   • Right-click the batch file → "Create shortcut"
   • Move shortcut to Desktop or Start Menu
   • Right-click shortcut → Properties → Change Icon → Browse to assets/media_downloader.ico

Linux

Create a .desktop file in ~/.local/share/applications/:

vim ~/.local/share/applications/media_downloader.desktop

Add the following content (adjust paths as needed):

[Desktop Entry]
Name=Media Downloader
Exec=/path/to/venv/bin/python /path/to/media_downloader/src/main.py
Icon=/path/to/media_downloader/assets/media_downloader.ico
Type=Application
Categories=Utility;
Terminal=false

Make it executable:

chmod +x ~/.local/share/applications/media_downloader.desktop

macOS

Option A: Automator App (Recommended)

1. Open Automator → New Application
2. Add a "Run Shell Script" action with:

cd /path/to/media_downloader && source venv/bin/activate && python -m src.main

3. Save as Media Downloader.app to /Applications/
4. Set the app icon:
   • Right-click the .app → Get Info
   • Drag assets/media_downloader.ico onto the icon in the top-left corner

Option B: Shell Alias

alias media-downloader='cd /path/to/media_downloader && source venv/bin/activate && python -m src.main'

Add this to your ~/.zshrc or ~/.bash_profile for persistence.

Option C: macOS Launch Agent

Create ~/Library/LaunchAgents/com.msc72m.mediadownloader.plist:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.msc72m.mediadownloader</string>
    <key>ProgramArguments</key>
    <array>
        <string>/path/to/venv/bin/python</string>
        <string>-m</string>
        <string>src.main</string>
    </array>
    <key>WorkingDirectory</key>
    <string>/path/to/media_downloader</string>
    <key>RunAtLoad</key>
    <false/>
</dict>
</plist>

Launch with: launchctl load ~/Library/LaunchAgents/com.msc72m.mediadownloader.plist

Usage

Basic Workflow

1. Launch the application using one of the methods above
2. Paste URL into the input field at the top
3. Configure options (for YouTube: quality, format, subtitles, etc.)
4. Add to queue or download immediately
5. Monitor progress in the download list with real-time status updates

Adding Downloads

• Paste any supported platform URL into the input field
• Click "Add" button
• For YouTube: A dialog will appear with quality and format options
• For other platforms: Downloads are added directly to the queue

Managing Queue

• Remove Selected: Select items in the download list (click and drag to select multiple) and click "Remove Selected"
• Clear All: Removes all items from the queue
• Download All: Starts processing all queued downloads

Platform-Specific Instructions

YouTube

• Quality selection: Choose from 144p to 8K (availability depends on source)
• Format options: Video+Audio, Audio Only, or Video Only
• Playlist support: Enable "Download Playlist" option
• Subtitles: Select languages and download subtitles
• Auto-cookies: Automatically generated for age-restricted content (requires Playwright)

Instagram

• No username/password login: Instagram blocks scripted credential logins, so Media Downloader never asks for your Instagram password.
• Public posts download directly with no setup.
• Private or login-gated content requires an existing logged-in session, resolved automatically in this order:
  1. Browser cookies — if you are logged in to Instagram in a supported browser (Chrome, Firefox, Edge, Brave, and others), your session cookies are imported automatically. This reuses the same browser-cookie subsystem as YouTube.
  2. Saved session file — alternatively, run instaloader --login=YOUR_USERNAME once and copy the generated session-YOUR_USERNAME file into the instagram folder of the app's cookie storage directory (~/.media_downloader/instagram/ by default).
• Once a session is imported it is saved and reused for subsequent downloads.
• If login is required but no browser session or session file is found, the download fails with a clear message explaining both options above.
• Supports posts and reels; captions are preserved when available.

Twitter/X

• Paste a tweet URL to extract its text and available images or videos
• Paste a Space URL (x.com/i/spaces/...) to download public live or replayable audio
  • Supports current X GraphQL API with automatic fallback
  • Downloads HLS audio streams via ffmpeg
  • Real-time progress and status indicators
• Limitations: Private, deleted, login-gated, or replay-disabled Spaces cannot be downloaded. Some Spaces may be unavailable due to X API restrictions even if previously accessible.

Pinterest

• Paste pin URL
• High-quality images are retrieved automatically

SoundCloud

• Paste track or set URL
• Downloads at best available quality automatically (no format/quality selection)
• Only free tracks are supported (premium/Go+ subscription tracks cannot be downloaded)

Spotify

• Paste track, album, playlist, or artist URLs
• Spotify metadata is resolved first, then matching audio is downloaded from YouTube
• Track selection is available when multiple matches are found

TikTok

• Paste video URLs
• Downloads best available video quality automatically
• Metadata and thumbnails are preserved when available

RadioJavan

• Paste any RadioJavan URL — songs, videos, playlists, podcasts, albums, or artist pages
• Supports play.radiojavan.com and rj.app short links (e.g. rj.app/m/..., rj.app/v/...)
• Downloads direct MP3 or MP4 media when available
• Session cookies are generated automatically using Playwright when needed

Theme Customization

The theme switcher is located in the header:

• Appearance toggle: Switch between Dark and Light modes
• Color theme dropdown: Select from 22 color themes (Amber, Blue, Coral, Cyberpunk, Cyan, Emerald, Espresso, Glacier, Gold, Green, Indigo, Lime, Navy, Orange, Pink, Purple, Red, Rose, Slate, Sunset, Teal, Violet)
• Changes apply instantly without restart
• Preferences are saved automatically to config file

File Management

• Click "Manage Files" button to open file browser dialog
• Navigate and select download directory
• Selected path is saved and used for all downloads

Network Status

• Access via Tools → Network Status menu
• Shows current connectivity status
• Displays detailed network information and diagnostics

Configuration

Configuration files are automatically created in ~/.media_downloader/ on first run. The application supports both YAML and JSON formats:

• config.yaml (recommended)
• config.json

Configuration Options

• Paths: Download directory, config directory
• Downloads: Concurrent download limits, retry counts, timeouts
• Network: Timeouts, user agents, service domains
• YouTube: Default quality, supported qualities, subtitle languages
• Theme: Appearance mode, color theme, persistence
• Platform-specific: YouTube, Spotify, TikTok, Instagram, Twitter/X, Pinterest, SoundCloud, and RadioJavan settings

Edit the config file directly or use the application's UI to change settings. Changes take effect on next launch (some settings may require restart).

Known Limitations

• Twitter/X Spaces availability — Public live and replayable Spaces are supported; private, deleted, login-gated, or replay-disabled Spaces are unavailable
• SoundCloud Premium — Only free tracks can be downloaded (Go+ subscription tracks are blocked by SoundCloud)
• Spotify Audio — Audio is sourced from YouTube, so quality depends on YouTube availability
• Instagram Auth — Private/login-gated content needs a logged-in browser session or a saved instaloader session file; public posts work without setup (no password login)
• macOS Desktop Shortcut — No .app bundle provided; see Creating Desktop Shortcuts for manual setup
• Windows SmartScreen — The installer is unsigned; see Windows Installer for how to bypass
• Windows ARM64 — Only the ARM64 installer works on ARM devices (x64 installer requires emulation)

Troubleshooting

Playwright Not Installed

If you see an error about Playwright not being installed:

# With uv:
uv run playwright install chromium

# With pip:
playwright install chromium

Network Errors

• Check internet connection
• Verify URL is from a supported platform
• Check network status via Tools → Network Status

Authentication Failures (Instagram)

• Media Downloader does not use username/password login (Instagram blocks it) — you are never asked for a password.
• Public posts download without any setup.
• For private/login-gated content, make sure you are logged in to Instagram in a supported browser (Chrome, Firefox, Edge, Brave, etc.); the app imports your session cookies automatically.
• Alternatively, run instaloader --login=YOUR_USERNAME and copy the generated session-YOUR_USERNAME file into ~/.media_downloader/instagram/.
• Once a session is imported it is saved and reused automatically.

Download Errors

• Check application logs for detailed error messages
• Verify URL is valid and accessible
• Ensure sufficient disk space in download directory
• For YouTube, SoundCloud, Spotify, or RadioJavan: Wait for cookie generation to complete if prompted

Contributing

We welcome contributions! Please see our Contributing Guidelines for details on:

• Code of Conduct
• Branch protection policy (no direct PRs to main)
• Development setup and workflow
• Commit message conventions
• Pull request process

Security

For security concerns, please read our Security Policy and report vulnerabilities responsibly.

License

GNU General Public License v3.0 - See LICENSE file for details.

Disclaimer

This software is for personal use only. Users are responsible for:

• Adhering to platform terms of service
• Complying with applicable copyright laws
• Using the software responsibly

The developers assume no liability for misuse of this software.