Metadata-Version: 2.5
Name: mangabinder
Version: 0.1.2
Summary: Download manga chapters, convert them to PDF, bind them into volumes and export CBZ - from the command line or a local web UI.
Project-URL: Homepage, https://github.com/Preygle/manga-downloader
Project-URL: Issues, https://github.com/Preygle/manga-downloader/issues
Project-URL: Releases, https://github.com/Preygle/manga-downloader/releases
Author: Mohammad Owais
License-Expression: MIT
License-File: LICENSE
Keywords: cbz,comics,downloader,manga,pdf,scraper,volumes
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Environment :: Web Environment
Classifier: Intended Audience :: End Users/Desktop
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Multimedia :: Graphics :: Graphics Conversion
Classifier: Topic :: Utilities
Requires-Python: >=3.9
Requires-Dist: pillow>=9.1
Requires-Dist: pypdf>=3.9
Requires-Dist: pypdfium2>=4.0
Requires-Dist: tqdm>=4.60
Provides-Extra: dev
Requires-Dist: build; extra == 'dev'
Requires-Dist: pytest>=7; extra == 'dev'
Requires-Dist: twine; extra == 'dev'
Description-Content-Type: text/markdown

<p align="center">
  <img src="https://raw.githubusercontent.com/Preygle/manga-downloader/master/docs/logo.png" width="84" alt="MangaBinder logo">
</p>

<h1 align="center">MangaBinder</h1>

<p align="center">
  Download manga chapters, convert them to PDF, bind them into volumes and export CBZ,<br>
  from a friendly browser interface or a single command.
</p>

<p align="center">
  <a href="https://pypi.org/project/mangabinder/"><img src="https://img.shields.io/pypi/v/mangabinder?color=3b5bdb" alt="PyPI"></a>
  <a href="https://github.com/Preygle/manga-downloader/releases/latest"><img src="https://img.shields.io/github/v/release/Preygle/manga-downloader?label=windows%20.exe&color=3b5bdb" alt="Windows download"></a>
  <img src="https://img.shields.io/pypi/pyversions/mangabinder" alt="Python versions">
  <a href="https://github.com/Preygle/manga-downloader/actions/workflows/ci.yml"><img src="https://github.com/Preygle/manga-downloader/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-green" alt="MIT license"></a>
</p>

<p align="center">
  <img src="https://raw.githubusercontent.com/Preygle/manga-downloader/master/docs/screenshot-overview.png" width="900" alt="MangaBinder web interface with the main features annotated">
</p>

## Features

- **Parallel downloads.** Finds every chapter on a series page and downloads many chapters at once.
- **Resume anywhere.** Progress is saved, so an interrupted download picks up where it stopped.
- **Chapter PDFs.** Each chapter becomes one PDF. Re-runs only rebuild chapters that changed.
- **Volume PDFs.** Chapters are bound into volumes using real volume data from MangaDex / AniList, with a bookmark for every chapter.
- **CBZ export.** For e-readers and comic apps. Two-page spreads are split in right-to-left order.
- **Browser interface.** Run everything, watch live progress, and read your volumes in the browser.
- **Nothing extra to install.** A standalone Windows `.exe`, or `pip install` on Windows, macOS and Linux. No Poppler, no Ghostscript.

## Install

### Windows app (web interface)

1. Download **`mangabinder.exe`** from the [latest release](https://github.com/Preygle/manga-downloader/releases/latest).
2. Double-click it. The web interface opens in your browser, and your downloads go to `Documents\MangaBinder`.

> Windows SmartScreen may warn about an unrecognised app because the `.exe` isn't code-signed.
> Click **More info → Run anyway**.

### Command line (any OS, from PyPI)

Requires Python 3.9 or newer.

```bash
pipx install mangabinder        # recommended: isolated install, adds the command to PATH
# or
pip install mangabinder
```

Then use the [command line](#command-line). `mangabinder web` opens the same browser interface as the `.exe`.

## Using the web interface

```bash
mangabinder web                          # opens http://127.0.0.1:8765
mangabinder web --library D:\Manga       # keep downloads somewhere else
mangabinder web --host 0.0.0.0           # also reachable from other devices (no login!)
```

### 1. Download

Paste the **series page**, the page on the site that links to every chapter. Then press **Download + convert to PDF**.

<img src="https://raw.githubusercontent.com/Preygle/manga-downloader/master/docs/screenshot-download.png" width="820" alt="Download form with each option numbered and explained">

Chapter links like `…/chapter-12` are detected automatically. Fill in **Chapter link pattern** only if a site names its chapters differently (see [Supported sites](#supported-sites)).

### 2. Watch it run

The **Activity** panel streams the output of every job live. **Stop** cancels the current job. Resume is on by default, so pressing the button again later continues from where it stopped.

### 3. Read, merge and export

Everything you've downloaded appears in the **Library**:

<img src="https://raw.githubusercontent.com/Preygle/manga-downloader/master/docs/screenshot-library.png" width="820" alt="Library panel with each action numbered and explained">

Click a volume to read it in your browser's PDF viewer. Each chapter is bookmarked:

<img src="https://raw.githubusercontent.com/Preygle/manga-downloader/master/docs/screenshot-reader.png" width="820" alt="A merged volume open in the browser PDF viewer">

<details>
<summary><b>Dark mode</b> follows your system setting</summary>
<br>
<img src="https://raw.githubusercontent.com/Preygle/manga-downloader/master/docs/screenshot-dark.png" width="700" alt="MangaBinder in dark mode">
</details>

## Command line

One command runs the whole pipeline: download, then chapter PDFs, then volumes.

```bash
mangabinder download https://example.com/manga/series-name/ --volumes
```

<img src="https://raw.githubusercontent.com/Preygle/manga-downloader/master/docs/screenshot-cli.png" width="900" alt="Terminal output of a full download, convert and merge run, annotated">

Or run each step on its own:

| Command | What it does |
| --- | --- |
| `mangabinder download URL` | Download every chapter into `./<site>/<chapter>/` |
| `mangabinder convert FOLDER` | Build `FOLDER_pdf/<chapter>.pdf` from the chapter images |
| `mangabinder merge FOLDER_pdf` | Bind chapter PDFs into `FOLDER_pdf_volumes/<Title> v01.pdf`, … |
| `mangabinder cbz PDF_FOLDER` | Convert PDFs (chapters or volumes) to CBZ in `PDF_FOLDER_cbz/` |
| `mangabinder web` | Open the browser interface |
| `mangabinder gui` | Small desktop window for PDF → CBZ |

Useful options (run `mangabinder <command> --help` for all of them):

```bash
# download
mangabinder download URL --pattern title-chapter-   # only follow links containing this text
mangabinder download URL --start 120                # skip chapters before 120
mangabinder download URL --threads 8                # gentler on the site (default 16)
mangabinder download URL --fresh                    # ignore saved progress
mangabinder download URL --convert                  # also make chapter PDFs

# volumes
mangabinder merge example.com_pdf --dry-run         # print the volume plan only
mangabinder merge example.com_pdf --title "Monster"  # when the guessed title is wrong
mangabinder merge example.com_pdf --series-id <id> --source mangadex

# cbz
mangabinder cbz example.com_pdf_volumes --dpi 200 --no-split
```

## How it works

### Output layout

```
Documents/MangaBinder/                 (or the folder you ran the command in)
├── example.com/                       downloaded images, one folder per chapter
│   ├── series-chapter-1/1.jpg, 2.jpg, …
│   └── download_state.txt             finished chapters, used to resume
├── example.com_pdf/                   one PDF per chapter
├── example.com_pdf_volumes/           one PDF per volume + volume_map.json
└── example.com_pdf_volumes_cbz/       CBZ files
```

### Supported sites

MangaBinder works with the common "online reader" layout:

- The series page links to each chapter with a normal link (`<a href="…/chapter-12/">`).
- Each chapter page shows its pages as images (`<img src>`, or lazy-loaded `data-src`).

If **no chapters are found**, open any chapter, look at its address, and pass the part every chapter link shares as the pattern. For example, for `https://site.com/manga/monster-chapter-162/` use `--pattern monster-chapter-`. Sites that load pages with JavaScript only, or that need a login, aren't supported.

> **Git Bash users:** a pattern starting with `/` gets rewritten into a Windows path by Git Bash.
> Leave off the leading slash (`monster-chapter-`) or run the command from PowerShell / cmd.

### Volume mapping

The series title is guessed from the chapter names (`monster-chapter-1` → *Monster*) and looked up on **MangaDex** and **AniList**. No API key is needed.

1. **MangaDex per-chapter volume data** is used when it covers at least 70% of the chapters. This is the accurate path.
2. **Even split** across the published volume count is the fallback when no per-chapter data exists. This is *approximate*, and the run prints a warning.

Each run writes `volume_map.json` into the volumes folder. **Edit the `mapping` (chapter → volume) and re-run**. A map file always wins over a new lookup, so your corrections stick. Lookups are cached in your user cache folder.

## Troubleshooting

| Problem | Fix |
| --- | --- |
| "No chapters found" | Pass `--pattern` (see [Supported sites](#supported-sites)), and check the URL is the series page, not a chapter |
| Some chapters failed | Run the same command again. Finished chapters and pages are skipped |
| Wrong series picked for volumes | `--title "Exact Name"`, or `--series-id` with the MangaDex id |
| Volume boundaries slightly off | Edit `volume_map.json` in the volumes folder and run `merge --overwrite` |
| Port 8765 already in use | `mangabinder web --port 9000` (it also tries the next 9 ports automatically) |

## Development

```bash
git clone https://github.com/Preygle/manga-downloader.git
cd manga-downloader
python -m venv .venv && .venv/Scripts/activate      # macOS/Linux: source .venv/bin/activate
pip install -e ".[dev]"
pytest
```

Build the Windows executable locally:

```bash
pip install pyinstaller
pyinstaller --onefile --console --name mangabinder --icon packaging/icon.ico \
  --collect-all pypdfium2 --collect-all pypdfium2_raw packaging/entry.py
```

### Releasing

1. Bump `__version__` in `src/mangabinder/__init__.py` and merge to `master`.
2. `gh release create vX.Y.Z --generate-notes`

Publishing the release runs [`release.yml`](.github/workflows/release.yml), which builds the wheel, sdist and
`mangabinder.exe`, attaches them to the release, and uploads the wheel and sdist to PyPI with
[trusted publishing](https://docs.pypi.org/trusted-publishers/), so no API token is stored.

## Responsible use

MangaBinder is a general-purpose tool. Only download content you have the right to download, respect each site's terms of service, and support the creators by buying official releases where they're available.

## License

[MIT](LICENSE) © Mohammad Owais
