Skip to content

Commit eb6e71d

Browse files
ZeroHackzZeroHackz
committed
Merge branch 'main' into development/latest
2 parents bdcb363 + 1daa888 commit eb6e71d

File tree

1 file changed

+164
-64
lines changed

1 file changed

+164
-64
lines changed

‎README.md‎

Lines changed: 164 additions & 64 deletions
Original file line numberDiff line numberDiff line change
@@ -1,96 +1,196 @@
1-
# Bunkr Downloader - GUI Edition
1+
# Bunkr Downloader
22

3-
This project is a fork of the original [BunkrDownloader by Lysagxra](https://github.com/Lysagxra/BunkrDownloader). Huge thanks to her for creating and maintaining the powerful core of this application!
3+
> A Python Bunkr downloader that fetches images and videos from URLs. It supports both Bunkr albums and individual file URLs, logs issues, and enables concurrent downloads for efficiency.
44
5-
This version focuses on providing an user-friendly **Graphical User Interface (GUI)** for Windows users and includes other features to make downloading as simple as possible.
5+
![Screenshot](https://github.com/Lysagxra/BunkrDownloader/blob/3bc786d91f2950fbc1df120b7ebbb6ff90e4e6fd/misc/DemoV2.gif)
66

7-
### Screenshots
8-
*Screen application `BunkrDownloader-portable-GUI.exe` in single mode.*
7+
## Features
98

10-
![Bunkr Downloader GUI](screenshots/screenshot-single-mode.PNG)
9+
- Downloads multiple files from an album concurrently.
10+
- Supports [batch downloading](https://github.com/Lysagxra/BunkrDownloader?tab=readme-ov-file#batch-download) via a list of URLs.
11+
- Supports [selective files downloading](https://github.com/Lysagxra/BunkrDownloader/tree/main?tab=readme-ov-file#selective-download) based on filename criteria.
12+
- Supports [custom download location](https://github.com/Lysagxra/BunkrDownloader/tree/main?tab=readme-ov-file#file-download-location).
13+
- Provides [minimal UI](https://github.com/Lysagxra/BunkrDownloader/tree/main?tab=readme-ov-file#disable-ui-for-notebooks) for notebook environments.
14+
- Provides progress indication during downloads.
15+
- Automatically creates a directory structure for organized storage.
16+
- Logs URLs that encounter errors for troubleshooting.
1117

12-
*Screen of an completed request interface in single mode `BunkrDownloader-portable-GUI.exe`.*
18+
## Dependencies
1319

14-
![Download in progress](screenshots/screenshot-single-mode-active.PNG)
20+
- Python 3
21+
- `BeautifulSoup` (bs4) - for HTML parsing
22+
- `requests` - for HTTP requests
23+
- `rich` - for progress display in the terminal
1524

16-
*Screen application `BunkrDownloader-portable-GUI.exe` in load from file mode.*
25+
## Directory Structure
1726

18-
![Download in progress](screenshots/screenshot-load-from-file.PNG)
27+
<details>
1928

20-
*Screen of an completed request interface in load from file mode `BunkrDownloader-portable-GUI.exe`.*
29+
<summary>Expand Directory Structure</summary>
2130

22-
![Download in progress](screenshots/screenshot-load-from-file-active.PNG)
31+
```
32+
project-root/
33+
├── helpers/
34+
│ ├── crawlers/
35+
│ │ └── crawler_utils.py # Utilities for extracting media download links
36+
│ ├── downloaders/
37+
│ │ ├── album_downloader.py # Manages the downloading of entire albums
38+
│ │ ├── download_utils.py # Utilities for managing the download process
39+
│ │ └── media_downloader.py # Manages the downloading of individual media files
40+
│ ├── managers/
41+
│ │ ├── live_manager.py # Manages a real-time live display
42+
│ │ ├── log_manager.py # Manages real-time log updates
43+
│ │ └── progress_manager.py # Manages progress bars
44+
│ ├── bunkr_utils.py # Utilities for checking Bunkr status
45+
│ ├── config.py # Manages constants and settings used across the project
46+
│ ├── file_utils.py # Utilities for managing file operations
47+
│ ├── general_utils.py # Miscellaneous utility functions
48+
│ └── url_utils.py # Utilities for Bunkr URLs
49+
├── downloader.py # Module for initiating downloads from specified Bunkr URLs
50+
├── main.py # Main script to run the downloader
51+
├── URLs.txt # Text file listing album URLs to be downloaded
52+
└── session_log.txt # Log file for recording session details
53+
```
2354

24-
*Real-time download progress and logs.*
55+
</details>
2556

26-
## ✨ Features
57+
## Installation
2758

28-
This fork includes all the powerful core features from the original, plus:
59+
1. Clone the repository:
2960

30-
* **Dual Download Modes:** Easily switch between downloading a single URL or batch downloading from a `.txt` file using a simple toggle.
31-
* **Graphical User Interface (GUI):** A simple and intuitive interface for downloading. No command line needed!
32-
* **Portable Windows Executable:** Download and run the application directly without needing to install Python or any dependencies.
33-
* **Easy URL Pasting:** A convenient "Paste" button to quickly insert a Bunkr URL from your clipboard.
34-
* **File Browser:** A "Browse" button to easily select your URL list file when in "From File" mode.
35-
* **Automatic Folder Opening:** Once your download is complete, the folder containing the files will automatically open.
36-
* **Build & Setup Scripts:** Comes with `.bat` scripts to easily set up the environment and build the executable from source.
61+
```bash
62+
git clone https://github.com/Lysagxra/BunkrDownloader.git
63+
```
3764

38-
### Core Features
65+
2. Navigate to the project directory:
3966

40-
- Downloads multiple files from an album concurrently.
41-
- Supports batch downloading via a list of URLs.
42-
- Supports selective file downloading based on filename criteria.
43-
- Provides progress indication during downloads.
44-
- Automatically creates a directory structure for organized storage.
45-
- Logs URLs that encounter errors for troubleshooting.
67+
```bash
68+
cd BunkrDownloader
69+
```
70+
71+
3. Install the required dependencies:
72+
73+
```bash
74+
pip install -r requirements.txt
75+
```
76+
77+
## Single Download
78+
79+
To download a single media from an URL, you can use `downloader.py`, running the script with a valid album or media URL.
80+
81+
### Usage
82+
83+
```bash
84+
python3 downloader.py <bunkr_url>
85+
```
86+
87+
### Examples
88+
89+
You can either download an entire album or a specific file:
90+
91+
```
92+
python3 downloader.py https://bunkr.si/a/PUK068QE # Download album
93+
python3 downloader.py https://bunkr.fi/f/gBrv5f8tAGlGW # Download single media
94+
```
95+
96+
## Selective Download
97+
98+
The script supports selective file downloads from an album, allowing you to exclude files using the [Ignore List](https://github.com/Lysagxra/BunkrDownloader?tab=readme-ov-file#ignore-list) and include specific files with the [Include List](https://github.com/Lysagxra/BunkrDownloader?tab=readme-ov-file#include-list).
99+
100+
## Ignore List
101+
102+
The Ignore List is specified using the `--ignore` argument in the command line. This allows you to skip the download of any file from an album if its filename contains at least one of the specified strings in the list. Item in the list should be separated by a space.
103+
104+
### Usage
105+
106+
```bash
107+
python3 downloader.py <bunkr_album_url> --ignore <ignore_list>
108+
```
46109

47-
## 💻 How to Use (Easy Way)
110+
### Example
48111

49-
1. Go to the [**Releases**](https://github.com/ZeroHackz/BunkrDownloader-Portable/releases) page.
50-
2. Download the latest `BunkrDownloader-portable-GUI.exe` file.
51-
3. Run the application.
52-
4. **Choose your download mode:**
53-
* **For a single link:** Leave it on "Single URL", paste your Bunkr URL, and click **Download**.
54-
* **For multiple links:** Select "From File", click **Browse** to select your `.txt` file, and then click **Download**.
55-
5. That's it!
112+
This feature is particularly useful when you want to skip files with certain extensions, such as `.zip` files. For instance:
56113

57-
## 🛠️ For Developers (Building from Source)
114+
```bash
115+
python3 downloader.py https://bunkr.si/a/PUK068QE --ignore .zip
116+
```
58117

59-
If you want to build the application yourself:
118+
## Include List
60119

61-
1. Clone this repository:
62-
```bash
63-
git clone https://github.com/ZeroHackz/BunkrDownloader-Portable.git
64-
```
65-
2. Navigate to the project directory:
66-
```bash
67-
cd BunkrDownloader-Portable
68-
```
69-
3. Run the setup script. This will create a virtual environment and install the required dependencies.
70-
```bat
71-
setup_launcher.bat
72-
```
73-
4. To build the executable, run the build script:
74-
```bat
75-
build.bat
76-
```
77-
The `.exe` will be available in the `dist` folder.
120+
The Include List is specified using the `--include` argument in the command line. This allows you to download a file from an album only if its filename contains at least one of the specified strings in the list. Items in the list should be separated by a space.
78121

79-
## CLI Usage
122+
### Usage
80123

81-
The original command-line interface is still available and fully functional.
124+
```bash
125+
python3 downloader.py <bunkr_album_url> --include <include_list>
126+
```
82127

83-
### Single Download
128+
### Example
84129

85130
```bash
86-
python downloader.py <bunkr_url>
131+
python3 downloader.py https://bunkr.si/a/PUK068QE --include FullSizeRender
87132
```
88133

89-
### Selective & Batch Downloads
134+
## Batch Download
135+
136+
To batch download from multiple URLs, you can use the `main.py` script. This script reads URLs from a file named `URLs.txt` and downloads each one using the media downloader.
137+
138+
### Usage
139+
140+
1. Create a file named `URLs.txt` in the root of your project, listing each URL on a new line.
141+
142+
- Example of `URLs.txt`:
143+
144+
```
145+
https://bunkr.si/a/PUK068QE
146+
https://bunkr.fi/f/gBrv5f8tAGlGW
147+
https://bunkr.fi/a/kVYLh49Q
148+
```
149+
150+
- Ensure that each URL is on its own line without any extra spaces.
151+
- You can add as many URLs as you need, following the same format.
152+
153+
2. Run the batch download script:
154+
155+
```
156+
python3 main.py
157+
```
158+
159+
## File Download Location
160+
161+
If the `--custom-path <custom_path>` argument is used, the downloaded files will be saved in `<custom_path>/Downloads`. Otherwise, the files will be saved in a `Downloads` folder created within the script's directory
162+
163+
### Usage
90164

91-
All the original flags like `--ignore`, `--include`, and batch downloading via `URLs.txt` are still supported.
92-
93-
For more details, please refer to the [Lysagxra README](https://github.com/Lysagxra/BunkrDownloader/blob/main/README.md).
165+
```bash
166+
python3 main.py --custom-path <custom_path>
167+
```
168+
169+
### Example
170+
171+
```bash
172+
python3 main.py --custom-path /path/to/external/drive
173+
```
174+
175+
## Disable UI for Notebooks
176+
177+
When the script is executed in a notebook environment (such as Jupyter), excessive output may lead to performance issues or crashes.
178+
179+
### Usage
180+
181+
You can run the script with the `--disable-ui` argument to disable the progress bar and minimize log messages.
182+
183+
To disable the UI, use the following command:
184+
185+
```
186+
python3 main.py --disable-ui
187+
```
188+
189+
To download a single file or album without the UI, you can use this command:
190+
191+
```bash
192+
python3 downloader.py <bunkr_url> --disable-ui
193+
```
94194

95195
## Logging
96196

0 commit comments

Comments
 (0)