mirror of
https://github.com/MasterAcnolo/Freedom-Loader.git
synced 2026-07-29 18:25:47 +02:00
Revise README for improved structure and clarity
Updated README with new structure and content for clarity and organization.
This commit is contained in:
MasterAcnolo
408
README.md
408
README.md
@@ -1,150 +1,378 @@
|
|||||||
<div align="center">
|
<div align="center">
|
||||||
|
|
||||||
<a href="https://masteracnolo.github.io/FreedomLoader/"><img
|
<a href="https://masteracnolo.github.io/FreedomLoader/"><img
|
||||||
src="./build/banner.png"
|
src="./build/banner.png"
|
||||||
alt="Banner"
|
alt="Banner"
|
||||||
style="width: 50%;;"/></a>
|
style="width: 50%;"/></a>
|
||||||
</div>
|
|
||||||
|
|
||||||
<div align="center">
|
### **A clean, open-source multimedia downloader for Windows**
|
||||||
<a href="https://github.com/MasterAcnolo/Freedom-Loader/releases"><img src="https://img.shields.io/badge/Release-1.4.1-blue?style=for-the-badge"></a>
|
|
||||||
<a href="https://masteracnolo.github.io/FreedomLoader/index.html"><img src="https://img.shields.io/badge/Freedom%20Loader-Open%20Page-111111?style=for-the-badge&logo=terminal&logoColor=white"></a>
|
[](https://github.com/MasterAcnolo/Freedom-Loader/releases)
|
||||||
|
[](https://www.gnu.org/licenses/gpl-3.0)
|
||||||
|
[](https://masteracnolo.github.io/FreedomLoader/)
|
||||||
<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>
|
<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>
|
|
||||||
<br>
|
|
||||||
|
|
||||||
Freedom Loader is a **Windows desktop** application built with **Electron**.
|
</div>
|
||||||
It provides a simple and reliable way to download video or audio content with metadata and advanced options, without ads or questionable third-party services.
|
|
||||||
The goal is to offer a clean, user-friendly, and transparent download experience. It's important for me to make media content downloading accessible to people who love music or videos and don’t always have an internet connection.
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
|
## 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.
|
||||||
|
|
||||||
|
## Table of Contents
|
||||||
|
|
||||||
|
- [Features](#features)
|
||||||
|
- [Installation](#installation)
|
||||||
|
- [Usage](#usage)
|
||||||
|
- [Preview](#preview)
|
||||||
|
- [Configuration](#configuration)
|
||||||
|
- [Project Structure](#project-structure)
|
||||||
|
- [Technology Stack](#technology-stack)
|
||||||
|
- [Development](#development)
|
||||||
|
- [Roadmap](#roadmap)
|
||||||
|
- [Contributing](#contributing)
|
||||||
|
- [Support](#support)
|
||||||
|
- [License](#license)
|
||||||
|
|
||||||
## Features
|
## Features
|
||||||
|
|
||||||
- Video download with metadata (MP4)
|
### Core Functionality
|
||||||
- Audio-only download with thumbnail and tags (MP3)
|
|
||||||
- Full playlist support and better display in UI
|
|
||||||
- Automatic metadata retrieval (title, duration, author, etc.)
|
|
||||||
- Detailed logs (console + rotating files for 7 days)
|
|
||||||
- Progress Bar for download and network speed indicator
|
|
||||||
- Better UX when fetching info
|
|
||||||
- Custom output path with persistence
|
|
||||||
- Automatic dependency updates (YT-DLP)
|
|
||||||
- Automatic Application Update
|
|
||||||
- Multiple UI themes
|
|
||||||
- Simple, responsive interface
|
|
||||||
- Notifications on download completion (click to open folder)
|
|
||||||
- Discord Rich Presence
|
|
||||||
|
|
||||||
---
|
- Video downloads with full metadata (MP4 format)
|
||||||
|
- Audio-only downloads with embedded thumbnails and tags (MP3 format)
|
||||||
|
- Complete playlist support with improved UI display
|
||||||
|
- Automatic metadata retrieval (title, duration, author, thumbnail, etc.)
|
||||||
|
- Native chapter extraction for video splitting
|
||||||
|
- Custom output directory with persistent configuration
|
||||||
|
|
||||||
|
### User Interface
|
||||||
|
|
||||||
|
- Multiple theme support
|
||||||
|
- Real-time download progress with network speed indicator
|
||||||
|
- Responsive, modern design
|
||||||
|
- System notifications on download completion (click to open folder)
|
||||||
|
- Enhanced loading states during metadata fetching
|
||||||
|
|
||||||
|
### System Features
|
||||||
|
|
||||||
|
- Automatic YT-DLP updates
|
||||||
|
- Automatic application updates via electron-updater
|
||||||
|
- Structured logging system with 7-day rotation
|
||||||
|
- Discord Rich Presence integration (optional)
|
||||||
|
- Firefox cookie integration for protected content
|
||||||
|
- Custom Top Bar
|
||||||
|
|
||||||
## Installation
|
## Installation
|
||||||
|
|
||||||
Download the latest installer from the **Releases** page and run it (Defender could stop you but click on "Run Anyway" and it's good).
|
### Requirements
|
||||||
Actually, **Firefox Browser** is the only browser supported for get cookies. You should install it. Follow the tutorial in the wiki page if you need some help, Firefox Section. [Link](https://masteracnolo.github.io/FreedomLoader/pages/wiki.html)
|
|
||||||
|
|
||||||
---
|
- **Operating System**: Windows 10 or later
|
||||||
|
- **Browser**: Mozilla Firefox (required for cookie extraction)
|
||||||
|
- [Download Firefox](https://www.firefox.com)
|
||||||
|
|
||||||
## FAQ
|
### Standard Installation
|
||||||
|
|
||||||
### Where are my downloaded files stored?
|
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
|
||||||
|
|
||||||
In your **Downloads** folder, inside **Freedom Loader**.
|
### File Locations
|
||||||
Example path:
|
|
||||||
`C:\Users\[YOUR NAME]\Downloads\Freedom Loader`
|
|
||||||
|
|
||||||
### I get an error after launching the app
|
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.*
|
||||||
|
|
||||||
Try restarting the application, checking the logs, or opening the developer console:
|
Application logs can be found at:
|
||||||
`CTRL + SHIFT + I` -> “Toggle Developer Tools”.
|
```
|
||||||
|
C:\Users\[USERNAME]\AppData\Local\FreedomLoader\logs\
|
||||||
|
```
|
||||||
|
|
||||||
<p align="center">
|
## Usage
|
||||||
<img src="build/example-developertools.png" width="20%" />
|
|
||||||
</p>
|
|
||||||
|
|
||||||
---
|
### Basic Download
|
||||||
|
|
||||||
## Roadmap
|
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
|
||||||
|
|
||||||
- [x] ~~Website for Freedom Loader~~
|
### Advanced Configuration
|
||||||
- [ ] More format options
|
|
||||||
- [ ] Linux version
|
|
||||||
- [x] ~~Auto-updating YT-DLP~~
|
|
||||||
- [x] ~~Automatic project updates~~
|
|
||||||
- [x] ~~Better download status~~
|
|
||||||
- [ ] Better website support (currently only YouTube is fully supported, other site could work but i can't prove it)
|
|
||||||
- [ ] Subtitle support
|
|
||||||
- [x] ~~UI/UX improvements~~
|
|
||||||
- [ ] Language selection
|
|
||||||
- [ ] Download specific parts of a video
|
|
||||||
- [ ] Custom file naming
|
|
||||||
- [ ] Parallel downloads
|
|
||||||
- [ ] Automatic sponsor skipping
|
|
||||||
- [x] ~~Extract/split video using native chapters~~
|
|
||||||
- [x] ~~Custom output path selection~~
|
|
||||||
|
|
||||||
---
|
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
|
## Preview
|
||||||
|
|
||||||
<p align="center">
|
<div align="center">
|
||||||
<img src="build/apercu1.2.4.png" width="40%" />
|
<table>
|
||||||
</p>
|
<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
|
||||||
|
|
||||||
## Technologies
|
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.
|
||||||
|
|
||||||
This project uses:
|
### Configuration File Location
|
||||||
|
```
|
||||||
|
C:\Users\[USERNAME]\AppData\Roaming\FreedomLoader\config.json
|
||||||
|
```
|
||||||
|
|
||||||
<p>
|
### Available Options
|
||||||
<a href="https://github.com/yt-dlp/yt-dlp"><img src="https://img.shields.io/badge/yt--dlp-Visit%20Repo-cf0000?style=for-the-badge&logo=github&logoColor=white"></a>
|
```json
|
||||||
<a href="https://github.com/FFmpeg/FFmpeg"><img src="https://img.shields.io/badge/FFmpeg-Visit%20Repo-666666?style=for-the-badge&logo=ffmpeg&logoColor=white"></a>
|
{
|
||||||
<a href="https://nodejs.org/"><img src="https://img.shields.io/badge/Node.js-Visit%20Repo-339933?style=for-the-badge&logo=node.js&logoColor=white"></a>
|
"autoUpdate": true,
|
||||||
<a href="https://github.com/electron/electron"><img src="https://img.shields.io/badge/Electron-Visit%20Repo-47848F?style=for-the-badge&logo=electron&logoColor=white"></a>
|
"discordRPC": true,
|
||||||
<a href="https://github.com/denoland/deno/"><img src="https://img.shields.io/badge/Deno-Visit%20Repo-14e0cc?style=for-the-badge&logo=deno&logoColor=white"></a>
|
"customTopBar": true,
|
||||||
</p>
|
"autoCheckInfo": true,
|
||||||
|
"addThumbnail": true,
|
||||||
|
"addMetadata": true,
|
||||||
|
"verboseLogs": false,
|
||||||
|
"autoDownloadPlaylist": true,
|
||||||
|
"customCodec": "h264",
|
||||||
|
"logSystem": true,
|
||||||
|
"outputTitleCheck": true,
|
||||||
|
"downloadSystem": true,
|
||||||
|
"notifySystem": true
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
---
|
### 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 |
|
||||||
|
| `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 |
|
||||||
|
|
||||||
|
### 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/
|
||||||
|
├── build/ # Build resources and assets
|
||||||
|
├── config/ # Configuration files
|
||||||
|
├── public/ # Frontend assets (HTML, CSS, JavaScript)
|
||||||
|
├── ressources/ # Internal resources (icons, binaries)
|
||||||
|
├── server/ # Express server code
|
||||||
|
│ ├── routes/ # API route handlers
|
||||||
|
│ ├── services/ # Business logic
|
||||||
|
│ └── utils/ # Server utilities
|
||||||
|
├── .github/ # GitHub configuration and workflows
|
||||||
|
├── main.js # Electron main process
|
||||||
|
├── preload.js # Electron preload script
|
||||||
|
├── config.js # Global application configuration
|
||||||
|
└── package.json # Dependencies and npm scripts
|
||||||
|
```
|
||||||
|
|
||||||
|
### 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
|
||||||
|
- **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
|
||||||
|
|
||||||
|
## 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
|
||||||
|
```
|
||||||
|
|
||||||
|
### 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
|
||||||
|
|
||||||
|
### Completed
|
||||||
|
|
||||||
|
- [x] Website and documentation
|
||||||
|
- [x] Automatic YT-DLP updates
|
||||||
|
- [x] Automatic application updates
|
||||||
|
- [x] Enhanced download status display
|
||||||
|
- [x] Video chapter extraction
|
||||||
|
- [x] Custom output path selection
|
||||||
|
- [x] Custom codec selection
|
||||||
|
- [x] Settings Panel with toggle switch for features.
|
||||||
|
|
||||||
|
### In Progress
|
||||||
|
|
||||||
|
- [ ] Additional format support (WebM, OGG, etc.)
|
||||||
|
- [ ] Refactoring and cleaning the code base.
|
||||||
|
- [ ] Chrome/Edge cookie support
|
||||||
|
- [ ] Improved multi-site support
|
||||||
|
|
||||||
|
### Planned
|
||||||
|
|
||||||
|
- [ ] Subtitle download and embedding
|
||||||
|
- [ ] Multiple language support
|
||||||
|
- [ ] Partial video downloads
|
||||||
|
- [ ] Custom file naming patterns
|
||||||
|
- [ ] Parallel downloads
|
||||||
|
- [ ] Automatic sponsor detection (SponsorBlock integration)
|
||||||
|
- [ ] Download history
|
||||||
|
- [ ] Linux version
|
||||||
|
|
||||||
## Contributing
|
## Contributing
|
||||||
|
|
||||||
Contributions are welcome.
|
Contributions are welcome and appreciated. This project benefits from community involvement.
|
||||||
|
|
||||||
### Bug Reports
|
### Bug Reports
|
||||||
|
|
||||||
Use the GitHub Issues system and include reproduction steps and logs when possible.
|
Use the GitHub Issues system and include:
|
||||||
Logs can be found here:
|
|
||||||
`C:\Users\[USERNAME]\AppData\Local\FreedomLoader\logs\LOGS-20xx-xx-xx.log`
|
- Clear description of the issue
|
||||||
|
- Steps to reproduce
|
||||||
|
- Expected vs actual behavior
|
||||||
|
- Relevant logs from `AppData\Local\FreedomLoader\logs\`
|
||||||
|
- Screenshots if applicable
|
||||||
|
|
||||||
### Feature Requests
|
### Feature Requests
|
||||||
|
|
||||||
Open a feature request issue with a clear description and use cases.
|
Open a feature request issue with:
|
||||||
|
|
||||||
|
- Clear description of the proposed feature
|
||||||
|
- Use cases and benefits
|
||||||
|
- Potential implementation approach (if applicable)
|
||||||
|
|
||||||
### Pull Requests
|
### Pull Requests
|
||||||
|
|
||||||
Fork the repository, make your changes, and submit a PR once everything is tested and clean.
|
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 the Project
|
## Support
|
||||||
|
|
||||||
If you'd like to support development:
|
If you find this project useful and want to support its development:
|
||||||
|
|
||||||
<a href="https://paypal.me/axelnicolas25">
|
[](https://paypal.me/axelnicolas25)
|
||||||
<img src="https://img.shields.io/badge/PayPal-00457C?style=for-the-badge&logo=paypal&logoColor=white" />
|
|
||||||
</a>
|
|
||||||
|
|
||||||
---
|
Your support helps maintain infrastructure, develop new features, and keep the project free and ad-free.
|
||||||
|
|
||||||
## License
|
## License
|
||||||
|
|
||||||
Freedom Loader is released under the **GNU General Public License v3.0 (GPLv3)**.
|
Freedom Loader is released under the **GNU General Public License v3.0 (GPLv3)**.
|
||||||
You are free to use, modify, and redistribute the software under the terms of this license.
|
|
||||||
|
|
||||||
See the full license in the [LICENSE](./LICENSE) file.
|
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
|
||||||
|
- [Electron](https://www.electronjs.org/) for the desktop application framework
|
||||||
|
- The open-source community for continuous support and contributions
|
||||||
|
- @SpicyFire21 to be the spiciest one
|
||||||
|
- All users who test, report issues, and help improve the application
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Note
|
<div align="center">
|
||||||
|
|
||||||
AI assistance was used occasionally to speed up development, but all code and decisions were reviewed and validated manually.
|
**Freedom Loader** - Put freedom in your downloads
|
||||||
|
|
||||||
|
[Website](https://masteracnolo.github.io/FreedomLoader/) • [Download](https://github.com/MasterAcnolo/Freedom-Loader/releases) • [Documentation](https://masteracnolo.github.io/FreedomLoader/pages/wiki.html) • [Report Bug](https://github.com/MasterAcnolo/Freedom-Loader/issues)
|
||||||
|
|
||||||
|
</div>
|
||||||
|
|||||||
Reference in New Issue
Block a user