mirror of
https://github.com/MasterAcnolo/Freedom-Loader.git
synced 2026-07-29 18:25:47 +02:00
505 lines
19 KiB
Markdown
505 lines
19 KiB
Markdown
<div align="center">
|
|
|
|
<a href="https://masteracnolo.github.io/Freedom-Loader-Site/"><img
|
|
src="./build/banner.png"
|
|
alt="Banner"
|
|
style="width: 50%;"/></a>
|
|
|
|
### **A clean, open-source multimedia downloader for Windows**
|
|
|
|
[](https://github.com/MasterAcnolo/Freedom-Loader/releases)
|
|
[](https://www.gnu.org/licenses/gpl-3.0)
|
|
[](https://masteracnolo.github.io/Freedom-Loader-Site/)
|
|
[](https://masteracnolo.github.io/Freedom-Loader-Workshop/)
|
|
<a href="https://www.firefox.com/fr/?utm_campaign=SET_DEFAULT_BROWSER"><img src="https://img.shields.io/badge/Require Firefox-E66000?style=for-the-badge&logo=Firefox-Browser&logoColor=white"></a>
|
|
|
|
</div>
|
|
|
|
---
|
|
|
|
## 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](https://masteracnolo.github.io/Freedom-Loader-Site/)** - Official project website and documentation
|
|
- **[Workshop](https://github.com/MasterAcnolo/Freedom-Loader-Workshop)** - Theme creation tool and theme browser
|
|
|
|
## Table of Contents
|
|
|
|
- [Features](#features)
|
|
- [Installation](#installation)
|
|
- [Usage](#usage)
|
|
- [Preview](#preview)
|
|
- [Configuration](#configuration)
|
|
- [Project Structure](#project-structure)
|
|
- [Theme Workshop](#Theme-Workshop)
|
|
- [Technology Stack](#technology-stack)
|
|
- [Development](#development)
|
|
- [Roadmap](#roadmap)
|
|
- [Contributing](#contributing)
|
|
- [Submitting a community theme](#Submitting-a-community-theme)
|
|
- [Support](#support)
|
|
- [License](#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
|
|
|
|
## Installation
|
|
|
|
### Requirements
|
|
|
|
- **Operating System**: Windows 10 or later
|
|
- **Browser**: Mozilla Firefox (required for cookie extraction)
|
|
- [Download Firefox](https://www.firefox.com)
|
|
|
|
### Standard Installation
|
|
|
|
1. Download the latest release from the [Releases page](https://github.com/MasterAcnolo/Freedom-Loader/releases)
|
|
2. Run the downloaded `.exe` installer
|
|
3. If Windows Defender shows a warning, click "More info" then "Run anyway"
|
|
4. Follow the installation wizard
|
|
|
|
### File Locations
|
|
|
|
Downloaded files are stored in:
|
|
```
|
|
C:\Users\[USERNAME]\Downloads\Freedom Loader
|
|
```
|
|
> [!NOTE]
|
|
> *You can change it whenever you want. Just click the "Edit" button in the UI.*
|
|
|
|
Application logs can be found at:
|
|
```
|
|
C:\Users\[USERNAME]\AppData\Local\FreedomLoader\logs\
|
|
```
|
|
|
|
## Usage
|
|
|
|
### 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 configuration
|
|
|
|
### Troubleshooting
|
|
|
|
If you encounter issues:
|
|
|
|
1. Restart the application
|
|
2. Check the logs in `AppData\Local\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
|
|
|
|
<div align="center">
|
|
<table>
|
|
<tr>
|
|
<td width="50%" align="center">
|
|
<img src="https://github.com/user-attachments/assets/d4de9079-7c82-44d3-ba22-8246bb467db3" alt="Download Preview" width="75%" />
|
|
<p><em>Real-time download progress with network speed indicator</em></p>
|
|
</td>
|
|
<td width="50%" align="center">
|
|
<img src="https://github.com/user-attachments/assets/d59aff95-6754-486a-b880-d70730146dc3" alt="Settings Panel" width="40%" />
|
|
<p><em>Settings panel with theme and feature customization</em></p>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
|
|
## 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
|
|
```
|
|
%APPDATA%\Freedom Loader\config.json
|
|
```
|
|
|
|
### Available Options
|
|
```json
|
|
{
|
|
"autoUpdate": true,
|
|
"discordRPC": true,
|
|
"customTopBar": true,
|
|
"autoCheckInfo": true,
|
|
"addThumbnail": true,
|
|
"addMetadata": true,
|
|
"verboseLogs": false,
|
|
"autoDownloadPlaylist": true,
|
|
"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 |
|
|
| `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 |
|
|
| `createPlaylistFolders` | boolean | `true` | 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]
|
|
> Configuration changes may require an application restart to take effect.
|
|
|
|
## Project Structure
|
|
|
|
```
|
|
Freedom-Loader/
|
|
├── app/ # Electron main process modules
|
|
│ ├── autoUpdater.js
|
|
│ ├── dependencyCheck.js
|
|
│ ├── discordRPC.js
|
|
│ ├── ipcHandlers.js
|
|
│ ├── pathValidator.js
|
|
│ ├── splashManager.js
|
|
│ ├── themeManager.js
|
|
│ ├── windowManager.js
|
|
│ └── ytDlpUpdater.js
|
|
├── build/ # Build resources and assets
|
|
├── config/ # Configuration files
|
|
│ ├── config.default.json
|
|
│ └── config.dev.json
|
|
├── public/ # Frontend assets and UI
|
|
│ ├── index.html
|
|
│ ├── splash.html
|
|
│ ├── assets/
|
|
│ │ ├── icon/ # Application icons
|
|
│ │ └── logo/ # Logo assets
|
|
│ ├── script/ # Frontend JavaScript modules
|
|
│ │ ├── appVersion.js
|
|
│ │ ├── clipboardPaste.js
|
|
│ │ ├── custompath.js
|
|
│ │ ├── customthemes.js
|
|
│ │ ├── downloadstatus.js
|
|
│ │ ├── fetchinfo.js
|
|
│ │ ├── progressBar.js
|
|
│ │ ├── settingsPanel.js
|
|
│ │ ├── toast.js
|
|
│ │ └── topbar.js
|
|
│ └── styles/ # CSS stylesheets
|
|
│ ├── styles.css
|
|
│ ├── variables.css
|
|
│ ├── components/ # Component-specific styles
|
|
│ │ ├── checkbox.css
|
|
│ │ ├── editpathbutton.css
|
|
│ │ ├── loader.css
|
|
│ │ ├── progressBar.css
|
|
│ │ └── toast.css
|
|
│ └── layout/ # Layout styles
|
|
│ ├── container.css
|
|
│ ├── form.css
|
|
│ ├── header.css
|
|
│ ├── settingsPanel.css
|
|
│ ├── topbar.css
|
|
│ └── videoinfo.css
|
|
├── resources/ # Internal resources (binaries)
|
|
├── server/ # Express backend server
|
|
│ ├── logger.js
|
|
│ ├── server.js
|
|
│ ├── controller/ # Request handlers
|
|
│ │ ├── download.controller.js
|
|
│ │ └── info.controller.js
|
|
│ ├── helpers/ # Utility functions
|
|
│ │ ├── buildArgs.helpers.js
|
|
│ │ ├── getBrowser.helpers.js
|
|
│ │ ├── notify.helpers.js
|
|
│ │ ├── parseInfo.helpers.js
|
|
│ │ ├── path.helpers.js
|
|
│ │ ├── rateLimit.helpers.js
|
|
│ │ └── validation.helpers.js
|
|
│ ├── routes/ # API route definitions
|
|
│ │ ├── download.route.js
|
|
│ │ └── info.route.js
|
|
│ └── services/ # Business logic layer
|
|
│ ├── download.services.js
|
|
│ └── info.services.js
|
|
├── theme/ # Theme system
|
|
│ ├── template.theme.json # Theme template
|
|
│ ├── Dark/ # Default dark theme
|
|
│ │ └── dark.theme.json
|
|
│ └── Light/ # Default light theme
|
|
│ └── light.theme.json
|
|
├── main.js # Electron main process entry point
|
|
├── preload.js # Electron preload script (IPC bridge)
|
|
├── config.js # Global configuration loader
|
|
├── package.json # Project metadata and dependencies
|
|
├── CODE_OF_CONDUCT.md # Community guidelines
|
|
├── CONTRIBUTING.md # Contribution guidelines
|
|
├── LICENSE # GPLv3 license
|
|
└── README.md # This file
|
|
```
|
|
|
|
### 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](https://masteracnolo.github.io/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
|
|
|
|
[](https://github.com/yt-dlp/yt-dlp)
|
|
[](https://ffmpeg.org/)
|
|
[](https://www.electronjs.org/)
|
|
[](https://nodejs.org/)
|
|
|
|
### 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
|
|
|
|
### Prerequisites
|
|
|
|
- Node.js 16.x or higher
|
|
- npm or yarn
|
|
- Git
|
|
|
|
### Setup
|
|
|
|
```bash
|
|
# Clone the repository
|
|
git clone https://github.com/MasterAcnolo/Freedom-Loader.git
|
|
cd Freedom-Loader
|
|
|
|
# Install dependencies
|
|
npm install
|
|
|
|
# Run in development mode
|
|
npm start
|
|
|
|
# Build for production
|
|
npm run build
|
|
```
|
|
|
|
### 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
|
|
|
|
- **Deno**
|
|
- Download from: https://sourceforge.net/projects/deno.mirror/files/latest/download
|
|
- Rename to: `deno.exe`
|
|
|
|
- **FFmpeg**
|
|
- Download from: https://www.ffmpeg.org/download.html
|
|
- Required files:
|
|
- `ffmpeg.exe`
|
|
- `ffprobe.exe`
|
|
|
|
- **yt-dlp**
|
|
- Already bundled with the project
|
|
- No manual installation required
|
|
|
|
Final folder structure:
|
|
|
|
```
|
|
resources/
|
|
├── deno.exe
|
|
├── ffmpeg.exe
|
|
├── ffprobe.exe
|
|
└── yt-dlp.exe
|
|
```
|
|
|
|
> These binaries are required for the application to start correctly.
|
|
> If any of them are missing, an error message will be displayed at application startup.
|
|
|
|
### Development Guidelines
|
|
|
|
- Follow existing code style and conventions
|
|
- Write clear commit messages
|
|
- Test thoroughly before submitting changes
|
|
- Update documentation when adding features
|
|
- Maintain compatibility with Windows 10+
|
|
|
|
## Roadmap
|
|
|
|
See the most recent Roadmap [Here](https://masteracnolo.github.io/Freedom-Loader-Site/Roadmap).
|
|
|
|
## 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](https://github.com/MasterAcnolo/Freedom-Loader-Workshop) 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\`
|
|
- 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](CONTRIBUTING.md) and [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) before contributing.
|
|
|
|
## Support
|
|
|
|
If you find this project useful and want to support its development:
|
|
|
|
[](https://paypal.me/axelnicolas25)
|
|
|
|
Your support helps maintain infrastructure, develop new features, and keep the project free and ad-free.
|
|
|
|
## 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](LICENSE) file for complete details.
|
|
|
|
## Acknowledgments
|
|
|
|
- [yt-dlp](https://github.com/yt-dlp/yt-dlp) for the robust download engine
|
|
- [FFmpeg](https://ffmpeg.org/) for media processing capabilities
|
|
- [Deno](https://deno.com/) for helping me bypassing challenges
|
|
- [Electron](https://www.electronjs.org/) for the desktop application framework
|
|
- The open-source community for continuous support and contributions
|
|
- [@SpicyFire21](https://github.com/SpicyFire21) to be the spiciest one
|
|
- Zakaria for the website icon
|
|
- Jacques Chirac to love Apples
|
|
- All users who test, report issues, and help improve the application
|
|
|
|
---
|
|
|
|
<div align="center">
|
|
|
|
**Freedom Loader** - Put freedom in your downloads
|
|
|
|
[Website](https://masteracnolo.github.io/Freedom-Loader-Site/) • [Download](https://github.com/MasterAcnolo/Freedom-Loader/releases) • [Documentation](https://masteracnolo.github.io/Freedom-Loader-Site/wiki) • [Report Bug](https://github.com/MasterAcnolo/Freedom-Loader/issues)
|
|
|
|
</div>
|