A clean, open-source multimedia downloader for Windows and Linux

Overview

Freedom Loader is a desktop application built with Electron that provides a straightforward way to download video and audio content with full metadata support. The application focuses on reliability, transparency, and user privacy-no ads, no tracking, no questionable third-party services.

The primary goal is to make media downloading accessible to users who want offline access to their favorite content, particularly in situations where internet connectivity is unreliable or unavailable.

See related repo:

• Website - Official project website and documentation
• Workshop - Theme creation tool and theme browser

Table of Contents

• Features
• Installation
• Usage
• Preview
• Configuration
• Theme Workshop
• Technology Stack
• Development
• Roadmap
• Contributing
• Submitting a community theme
• License

Features

Core Functionality

• Multi-format downloads - MP4 video with full metadata or MP3 audio with embedded artwork
• Video information preview - Fetch and display video metadata before downloading
• Quality selection - Choose from best, medium, lowest quality or specific resolutions (1080p, 720p, 480p)
• Playlist support - Download entire playlists with optional auto-download mode
• Metadata embedding - Automatic retrieval and embedding of title, artist, duration, and thumbnail
• Video codec options - Support for H.264, H.265, AV1, VP9, VP9.2, and Theora codecs
• Custom output directory - User-configurable download location with path validation
• Cookie integration - Firefox cookie support for accessing age-restricted and member-only content

User Interface

• Custom window controls - Frameless window with custom top bar (optional)
• Custom themes - ZIP-based theme system with live preview
• Theme Workshop - web-based theme creator and browser
• Toast notifications - in-app feedback system
• Real-time progress tracking - Live download progress bar with network speed indicator
• Server-Sent Events (SSE) - Non-blocking progress updates via event streaming
• Settings panel - In-app configuration interface with live updates
• Quick access toolbar - Direct links to logs, website, wiki, and developer tools

System Features

• Automatic updates - Electron-updater integration with GitHub releases
• YT-DLP auto-update - Keeps the download engine up-to-date on startup
• Structured logging - Winston-based logging with daily file rotation (7-day retention)
• Discord Rich Presence - Optional integration showing current download activity
• Single instance enforcement - Prevents multiple app instances from running simultaneously
• Native dependency validation - Startup checks for yt-dlp, FFmpeg, FFprobe, and Deno binaries
• Rate limiting - Express-based request throttling to prevent server overload
• Graceful shutdown - Proper cleanup of servers, logs, and RPC connections
• System notifications - Windows notifications on download completion (clickable to open folder)
• Splash screen - animated loading screen on startup
• Stop download - ability to cancel in-progress downloads
• Playlist folders - dedicated folder creation per playlist
• Keep Playlist Order - Add an Index before the title, could be useful for an album for example.
• System Tray - Could minimize the application in the system Tray, allow it to run in the background.

Installation

Requirements

• Windows: Windows 10 or later
• Linux: any modern x86_64 distribution
• Browser: Mozilla Firefox (download) required for cookie extraction, on both platforms

Windows

1. Download the latest .exe from the Releases page
2. Run the installer (click "More info" → "Run anyway" if Windows Defender warns you)
3. Follow the installation wizard

Linux

Fedora (via Copr - recommended)

Installing via Copr lets dnf handle future updates automatically:

sudo dnf copr enable masteracnolo/freedom-loader
sudo dnf install freedom-loader

Debian / Ubuntu (.deb)

# Download the latest .deb from the Releases page, then:
sudo apt install ./freedom-loader_1.x.x_amd64.deb

Snap (any distro with snapd)

sudo snap install freedom-loader

RPM (Fedora/RHEL/openSUSE, without Copr)

# Download the latest .rpm from the Releases page, then:
sudo dnf install ./freedom-loader-1.x.y.x86_64.rpm

AppImage (any distro, no installation needed)

# Download the latest .AppImage from the Releases page, then:
chmod +x Freedom-Loader-1.x.y.AppImage
./Freedom-Loader-1.x.y.AppImage

Once installed via any method, launch Freedom Loader from your application menu, or from a terminal with:

freedom-loader

File Locations

	Windows	Linux
Downloads	C:\Users\[USERNAME]\Downloads\Freedom Loader	~/Downloads/Freedom Loader
Logs	C:\Users\[USERNAME]\AppData\Local\FreedomLoader\logs\	~/.local/share/FreedomLoader/logs/

Note

The download folder can be changed anytime via the "Edit" button in the UI, on both platforms.

Usage

Tip

On Linux, you can start Freedom Loader using freedom-loader command

Basic Download

1. Launch Freedom Loader
2. Paste a video or playlist URL into the input field
3. Select the desired format (Video MP4 or Audio MP3)
4. Click the download button
5. Monitor progress in real-time
6. Receive a notification when the download completes

Advanced Configuration

The application supports various configuration options:

• Custom download directory selection
• Discord Rich Presence activation
• Theme customization
• Log level
• And somes to see in the list Configuration Options available

Troubleshooting

If you encounter issues:

1. Restart the application
2. Check the logs in AppData\Local\FreedomLoader\logs\ or ~/.local/share/FreedomLoader/logs
3. Open the developer console: CTRL + SHIFT + I → "Toggle Developer Tools"
4. Create an issue on GitHub with logs and reproduction steps

Preview

Real-time download progress with network speed indicator

Settings panel with theme and feature customization

Configuration

Freedom Loader can be configured either through the settings panel in the UI or by directly editing the config.json file located in the application data directory.

Configuration File Location

Windows

%APPDATA%\Freedom Loader\config.json

Linux

~/.config/Freedom\ Loader/config.json

Available Options

{
  "autoUpdate": true,
  "systemTray": true,
  "discordRPC": true,
  "customTopBar": true,
  "autoCheckInfo": true,
  "addThumbnail": true,
  "addMetadata": true,
  "verboseLogs": false,
  "autoDownloadPlaylist": true,
  "keepPlaylistOrder": false,
  "createPlaylistFolders": true,
  "customCodec": "h264",
  "logSystem": true,
  "outputTitleCheck": true,
  "downloadSystem": true,
  "notifySystem": true,
  "enableHardwareAcceleration": true,
  "theme": "dark" 
}

Configuration Options

Option	Type	Default	Description
autoUpdate	boolean	true	Enable automatic application updates
systemTray	boolean	false	Allow app to minimize on close [EXPERIMENTAL]
discordRPC	boolean	true	Enable Discord Rich Presence integration
customTopBar	boolean	true	Use custom application top bar
autoCheckInfo	boolean	true	Automatically fetch video information on URL paste
addThumbnail	boolean	true	Embed thumbnail in downloaded audio files
addMetadata	boolean	true	Add metadata tags to downloaded files
verboseLogs	boolean	false	Enable detailed logging for debugging
autoDownloadPlaylist	boolean	true	Automatically download entire playlists
keepPlaylistOrder	boolean	false	Add index before title, usefull for album
createPlaylistFolders	boolean	false	Automatically create a folder for a playlist
customCodec	string	"h264"	Video codec for encoding (supported: h264, h265, vp9, av1)
logSystem	boolean	true	Enable application logging
outputTitleCheck	boolean	true	Verify output file titles
downloadSystem	boolean	true	Enable download system
notifySystem	boolean	true	Enable system notifications
enableHardwareAcceleration	boolean	true	Enable Hardware Acceleration
theme	string	dark	Current Theme Name

Supported Codecs

• h264 - H.264/AVC (widely compatible, recommended default)
• h265 - H.265/HEVC (better compression, less compatible)
• av1 - AV1 (modern codec, excellent compression)
• av01 - AV1 variant
• vp9 - VP9 (open format, good quality)
• vp9.2 - VP9 Profile 2 (HDR support)
• theora - Theora (legacy open codec)

Note

Some configuration changes may require an application restart to take effect.

Architecture Overview

Freedom Loader uses a client-server architecture within a single Electron application:

• Frontend: HTML/CSS/JavaScript served via Electron's renderer process
• Backend: Express.js server running locally for download management
• App modules: Electron-specific logic (window, IPC, updates, RPC) isolated in app/
• IPC Bridge: Secure communication via Electron's preload script
• Logging: Winston-based structured logging with file rotation
• Updates: Automatic checking and installation via electron-updater

Theme Workshop

Freedom Loader includes a web-based theme creator available at Freedom Loader Workshop.

• Create custom themes with a live preview of the actual UI
• Browse and download community themes
• Export themes as .zip files ready to drop into the theme/ folder
• Supports background images, custom colors for every UI element

Installing a custom theme

1. Download a .zip theme file
2. Drop it in the theme/ folder of your Freedom Loader installation
3. Restart the app - your theme appears in the settings panel

Technology Stack

Core Technologies

Key Dependencies

• Electron: Cross-platform desktop application framework
• Express: Web framework for local HTTP server
• yt-dlp: Media download engine
• FFmpeg: Media processing and conversion
• Winston: Logging library
• discord-rpc: Discord Rich Presence integration
• electron-updater: Automatic application updates

Development

If you are interested by running a local non compiled version of Freedom Loader or just interested by contributing, see DEVELOPMENT

Additional Dependencies

This project relies on several external binaries.
Some of them are not included in the public repository and must be added manually.

You must download the required binaries and place them in the resources folder, using the exact filenames listed below.

Required binaries

See BINARIES.md for how to setup the binaries.

Development Guidelines

• Follow existing code style and conventions
• Write clear, imperative commit messages (e.g., "Add playlist indexing" not "Added")
• Test thoroughly on both Windows and Linux before submitting changes
• Update documentation (README, DEVELOPMENT.md) when adding features
• Maintain compatibility with:
  • Windows 10+
  • Fedora 43+ / Debian 11+ / Ubuntu 20.04+
  • GNOME and KDE desktop environments (when possible)
• Consider Linux distribution differences early (see DEVELOPMENT.md)

Roadmap

See the most recent Roadmap Here.

Contributing

Contributions are welcome and appreciated. This project benefits from community involvement.

Submitting a community theme

Want your theme featured in the Workshop? Please do not open an issue on this repository for theme submissions.
Head over to the Freedom Loader Workshop repository and open an issue there with your theme files, preview screenshots, and description.

Bug Reports

Use the GitHub Issues system and include:

• Clear description of the issue
• Steps to reproduce
• Expected vs actual behavior
• Relevant logs from AppData\Local\FreedomLoader\logs\ or ~/.local/share/FreedomLoader/logs/
• Screenshots if applicable

Feature Requests

Open a feature request issue with:

• Clear description of the proposed feature
• Use cases and benefits
• Potential implementation approach (if applicable)

Pull Requests

1. Fork the repository
2. Create a feature branch (git checkout -b feature/your-feature)
3. Make your changes with clear, descriptive commits
4. Test thoroughly
5. Update documentation as needed
6. Submit a pull request with a detailed description

Please read CONTRIBUTING.md, DEVELOPMENT.md and CODE_OF_CONDUCT.md before contributing.

License

Freedom Loader is released under the GNU General Public License v3.0 (GPLv3).

You are free to use, modify, and redistribute this software under the terms of the GPL-3.0 license. See the LICENSE file for complete details.

Acknowledgments

• yt-dlp for the robust download engine
• FFmpeg for media processing capabilities
• Deno for helping me to bypass challenges
• Electron for the desktop application framework
• The open-source community for continuous support and contributions
• @SpicyFire21 to be the spiciest one
• @AureCX for being the Official Windows Tester!
• Zakaria for the website icon
• All users who test, report issues, and help improve the application

---

Freedom Loader - Put freedom in your downloads

Website • Download • Documentation • Report Bug