Media Downloader

Cross-platform desktop application for downloading media content from social media platforms.

• Multi-platform support for YouTube, Spotify, TikTok, Instagram, Twitter/X, Pinterest, SoundCloud, and RadioJavan
• Bulk download queue with concurrent processing
• Video quality selection (144p to 8K) and audio-only extraction
• Real-time theme switching between dark/light modes with 18 color themes
• Custom themes — drop a JSON file into themes/ and it appears in the UI (see docs/themes.md)
• Automatic cookie generation using Playwright for YouTube, SoundCloud, Spotify, and RadioJavan
• Live progress tracking with status indicators and speed metrics
• Network connectivity monitoring and validation
• Configurable retry mechanisms and error handling
• YAML/JSON configuration files with customizable settings

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

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.

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

1. Download the latest installer from the Releases page

   • MediaDownloaderSetup-1.1.1-x64.exe for 64-bit Intel/AMD PCs
   • MediaDownloaderSetup-1.1.1-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).

# 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

# 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

# With uv:
uv run -m src.main

# With pip:
python -m src.main

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

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

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

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.

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

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

• 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

• 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

• 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)

• Authentication required: First Instagram URL will prompt authentication window
• After successful authentication, session is saved and reused for subsequent downloads
• Supports posts and reels
• Captions are preserved when available

• Paste tweet URL containing images or videos
• Media is automatically extracted and added to queue
• Note: Spaces are not currently supported

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

• 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)

• 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

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

• Paste song or video URLs
• Downloads direct MP3 or MP4 media when available
• Session cookies are generated automatically using Playwright when needed

The theme switcher is located in the header:

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

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

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

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

• config.yaml (recommended)
• config.json

• 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).

• Twitter Spaces — Audio spaces are not currently supported
• 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 — First Instagram download requires browser-based authentication
• 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)

If you see an error about Playwright not being installed:

# With uv:
uv run playwright install chromium

# With pip:
playwright install chromium

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

• Authentication window appears automatically when adding first Instagram URL
• Check credentials are correct
• Wait for authentication to complete before adding more URLs
• Session is saved after successful authentication

• 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

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

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.