[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-79933":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":10,"language":11,"languages":10,"totalLinesOfCode":10,"stars":12,"forks":13,"watchers":14,"openIssues":13,"contributorsCount":13,"subscribersCount":13,"size":13,"stars1d":13,"stars7d":15,"stars30d":16,"stars90d":13,"forks30d":13,"starsTrendScore":17,"compositeScore":13,"rankGlobal":10,"rankLanguage":10,"license":18,"archived":19,"fork":19,"defaultBranch":20,"hasWiki":21,"hasPages":19,"topics":22,"createdAt":10,"pushedAt":10,"updatedAt":23,"readmeContent":24,"aiSummary":25,"trendingCount":13,"starSnapshotCount":13,"syncStatus":15,"lastSyncTime":26,"discoverSource":27},79933,"manga-to-epub","0xH4KU\u002Fmanga-to-epub","0xH4KU","Lossless manga-source to EPUB tools for readers who care about page pairing, cover gaps, and Apple Books layout quirks.","",null,"Python",94,0,85,2,9,1,"MIT License",false,"main",true,[],"2026-06-12 02:03:55","# Manga to EPUB\n\nLossless manga-source to EPUB tools for readers who care about page pairing, cover gaps, and Apple Books layout quirks.\n\nThis project is not a general-purpose \"compress my book\" converter. It is for fixed-layout manga workflows where the source is a PDF, CBZ, or ZIP full of page images, and the goal is to preserve those images where possible while tuning the reading order for Apple Books.\n\n## Why This Exists\n\nApple Books can add a virtual blank page beside the cover. For manga, that small invisible choice can shift every following spread and break double-page artwork. Most converters produce technically valid EPUB files but give you no practical way to preview or correct that pairing.\n\nThis tool focuses on the boring-but-crucial details:\n\n- Import image-based PDF, CBZ, and ZIP sources.\n- Preserve original PDF and archive image bytes when possible.\n- Export EPUB 3 fixed-layout books for right-to-left manga reading.\n- Preview Apple Books' cover-side virtual blank page.\n- Insert or remove real blank pages at arbitrary positions.\n- Quick-delete the first N, last N, or a spine-position range.\n- Normalize exported EPUB internals so spine order, XHTML names, image names, and item IDs stay sequential after edits.\n- Set EPUB title, author, language, and cover image from the GUI.\n- Insert external JPEG\u002FPNG pages into the EPUB spine, including separately sourced covers.\n- Export selected spine images losslessly to a folder.\n- Save v2 layout presets with spine order, metadata, cover rule, blanks, deleted pages, and inserted-image references.\n- Apply presets to selected series volumes while keeping generated series titles such as `Series Title Vol.01`.\n- Import a manga series, review volumes individually, mark reviewed volumes ready, unready selected volumes when needed, and export ready volumes together.\n- Save and reopen series projects with volume status, active volume, and per-volume layout edits.\n- Validate generated EPUB structure before reporting export success.\n- Recover deleted pages during layout editing.\n\n## Features\n\n- PDF, CBZ, and ZIP to EPUB without image recompression for JPEG\u002FPNG archive pages.\n- PDF Flate image streams are wrapped into PNG containers.\n- Archive WebP, BMP, TIFF, GIF, AVIF, HEIC\u002FHEIF, and JPEG 2000 pages are converted to PNG for EPUB compatibility.\n- Tkinter GUI for manual manga layout tuning.\n- Preview-only Apple Books cover-gap mode with a virtual blank page on the right of the first spine item.\n- Arbitrary blank page insertion before or after selected pages.\n- Page deletion with recover support.\n- Preset save\u002Fload for applying layout corrections to one volume or a scoped set of series volumes.\n- Series import with generated `Vol.xx` titles, project save\u002Fload, multi-volume ready marking, selected-volume unready, and ready-only export.\n- Diagnose possible split double-page spreads from a linked single-volume Diagnose window.\n- Manually confirm true spreads, add missed spread pairs from Spine order, and check whether the current Apple Books preview layout damages them.\n- Review color-marked blank insertion suggestions before executing one insertion at a time.\n\n## Install\n\nUse Python 3.11 or newer. Tkinter is included with the standard Python.org macOS installer and most system Python builds.\n\n```bash\ncd ~\u002Fmanga-to-epub\nmake setup\n```\n\nThe equivalent manual setup is:\n\n```bash\npython3 -m venv .venv\n.venv\u002Fbin\u002Fpython -m pip install -U pip\n.venv\u002Fbin\u002Fpython -m pip install -r requirements.txt\n.venv\u002Fbin\u002Fpython -m pip install -e .\n```\n\n## GUI Workflow\n\nLaunch the layout editor:\n\n```bash\n.venv\u002Fbin\u002Fepub-layout-gui\n```\n\nTypical single-volume Apple Books manga workflow:\n\n1. Open a source volume: PDF, CBZ, or ZIP.\n2. Keep `Preview Apple Books cover gap` enabled.\n3. Inspect spreads in the preview.\n4. Insert blank pages where needed to realign double-page artwork.\n5. Delete unwanted pages if necessary. Use `Delete Selected Page` for normal edits; open the command palette for `Delete First...`, `Delete Last...`, or `Delete Range...`.\n6. Use `Recover Last Deleted` or `Cmd+Z` if a page or range was removed by mistake.\n7. Edit title, author, and language, then select any source or inserted image page and use `Set Selected As Cover` when the first image should not be the cover.\n8. Enable `Cover only, exclude from pages` when the cover should be used only as EPUB cover art and not appear as a reading page.\n9. Insert external JPEG\u002FPNG pages if needed. Inserted pages can be exported as reading pages, selected as cover art, or excluded from reading pages when used as cover-only art.\n10. Export EPUB and import it into Apple Books for final checking.\n\nThe GUI normalizes EPUB internals during export. For example, if source pages 1-3 are deleted and the visible list starts with source `Page 4`, the exported EPUB still uses sequential names such as `page-0001.xhtml` and `images\u002Fpage-0001.jpg`. The visible source labels remain unchanged so you can trace edits back to the original source.\n\n## Diagnosis Workflow\n\nThe `Diagnose` inspector entry opens a separate human-in-the-loop repair window.\nIt can run cross-page spread discovery, but it does not trust candidates\nautomatically. Mark each true spread manually, mark false positives as false when\nuseful, and add any missed adjacent spread pair by selecting the two real pages in\nthe Diagnose Spine order and clicking `Add Selected As Spread`.\n\nDamage checking uses the same Apple Books cover-gap preview flag as the main\nspread preview. When the flag is enabled, the virtual blank page beside the cover\nis included in the pairing check because it can shift later spreads.\n\nInsert-point scoring is a second manual step. Green spine markers show suggested\none-blank insertions that repair at least one damaged confirmed spread without\nbreaking currently intact confirmed spreads. Red markers show protected gaps.\nThe tool inserts only the selected suggestion, then marks diagnosis results stale\nuntil you click `Recheck Layout`.\n\nTypical diagnosis pass:\n\n1. Open a PDF volume, then click `Open Diagnose Window`.\n2. Click `Run Cross-Page Scan`.\n3. Review candidates visually and mark each relevant row true or false.\n4. Select exactly two adjacent real pages in the Diagnose Spine order and click `Add Selected As Spread` for any missed spread.\n5. Click `Check Damage Against Current Layout`.\n6. Click `Run Insert-Point Scoring`.\n7. Select one suggested insert row, click `Insert Selected Blank`, then click `Recheck Layout` before applying another insertion.\n\n## Series Project Workflow\n\nFor a manga series:\n\n1. Click `Import Series...` and choose the PDF, CBZ, or ZIP sources for the series.\n2. Review the `Series volumes` list. Files are naturally sorted, and EPUB titles are generated as `Series Title Vol.xx`.\n3. Select a volume to load it into the existing page editor.\n4. Fix blank pages, deletions, inserted images, and cover choices per volume.\n5. Select one or more volumes and click `Mark Selected Volume Ready` after reviewing them.\n6. If a ready volume needs more work, select it and click `Unready Selected`. Only the selected volumes are restored from ready history; the rest of the batch stays ready.\n7. Use `Save Project...` to save the series project when you want to continue later. Use `Open Project...` to restore the volume list, statuses, active volume, and saved per-volume layouts.\n8. Click `Export Ready Series...` to export only volumes marked `Ready`.\n\nThe series workflow avoids blindly applying a single correction template to every volume. If Vol.05 needs no blank page while Vol.06 needs two blanks, each volume can keep its own layout before it is marked ready.\n\nSeries export does not overwrite existing EPUB files. If the chosen output directory already contains a ready volume's target filename, the GUI warns during preflight and that volume will fail instead of replacing the file.\n\nSeries project files are JSON. Source paths, output paths, and inserted-image references are stored relative to the project file when possible, so keeping the project file near the source assets makes the workflow easier to move.\n\nWhen no deleted page is waiting to be recovered, `Cmd+Z` uses the same selected-first unready behavior as `Unready Selected`.\n\n## Presets\n\nNewly saved presets use `version: 2`. They preserve the edited spine order, blank pages, deleted source pages, metadata defaults, cover-only mode, selected cover rule, and paths to inserted JPEG\u002FPNG pages.\n\nIn series mode, `Load Preset` asks which volumes should receive the preset. Scope input supports comma-separated volumes such as `1,2,7`, ranges such as `1-7`, or `all`. After applying a preset, each target volume still uses the series title, author, language, and generated `Vol.xx` title instead of copying one volume's full metadata onto every book.\n\nVersion 1 presets from earlier builds still load. When a v2 preset references an inserted image, that image file must still exist at the saved path so it can be reinserted into the target layout.\n\n## Command Line\n\nConvert PDF, CBZ, or ZIP files to fixed-layout EPUB:\n\n```bash\n.venv\u002Fbin\u002Fmanga-to-epub \"Volume 01.pdf\" --overwrite\n```\n\n```bash\n.venv\u002Fbin\u002Fmanga-to-epub \"Volume 01.cbz\" --overwrite\n```\n\nThe older `pdf-to-epub-lossless` command remains available as a compatibility alias.\n\nInsert one real blank page before the cover:\n\n```bash\n.venv\u002Fbin\u002Fmanga-to-epub \"Volume 01.pdf\" \\\n  --blank-pages-before-cover 1 \\\n  --overwrite\n```\n\nExport multiple sources into a directory:\n\n```bash\n.venv\u002Fbin\u002Fmanga-to-epub *.pdf *.cbz *.zip \\\n  --output-dir .\u002Fepub-output \\\n  --overwrite\n```\n\nSet EPUB metadata and use source page 2 as cover art only:\n\n```bash\n.venv\u002Fbin\u002Fmanga-to-epub \"Volume 01.pdf\" \\\n  --title \"Series Vol.01\" \\\n  --author \"Author Name\" \\\n  --language ja \\\n  --cover-page 2 \\\n  --cover-only \\\n  --overwrite\n```\n\nApply a GUI layout preset or quick-delete pages without opening the GUI:\n\n```bash\n.venv\u002Fbin\u002Fmanga-to-epub \"Volume 01.pdf\" \\\n  --preset .\u002Flayout-preset.json \\\n  --delete-range 1-3 \\\n  --overwrite\n```\n\nInserted images use `POSITION=PATH` with 1-based spine positions:\n\n```bash\n.venv\u002Fbin\u002Fmanga-to-epub \"Volume 01.pdf\" \\\n  --insert-image-after 1=.\u002Fcover.png \\\n  --overwrite\n```\n\nFor series-style generated titles, use `--series-title` with either `--volume-number` or a filename that contains a volume number:\n\n```bash\n.venv\u002Fbin\u002Fmanga-to-epub \"Volume 07.pdf\" \\\n  --series-title \"Series Title\" \\\n  --volume-number 7 \\\n  --overwrite\n```\n\nFor OPF spread metadata, `--pair-first-two-pages` explicitly marks the first two source pages as a right-to-left spread pair. `--apple-books` instead writes centered single-page spread metadata for every reading page; these modes are mutually exclusive.\n\n## Apple Books Notes\n\nThe GUI preview deliberately models Apple Books' cover behavior by adding a virtual blank page on the right of the first spine item. This virtual page is not exported into the EPUB. It is only a preview aid so you can decide whether to insert a real blank page into the EPUB spine.\n\nIf Apple Books shifts spreads after import, try inserting a real blank page before the cover, then preview again with `Preview Apple Books cover gap` enabled.\n\n## EPUB Validation\n\nEvery EPUB export now runs a lightweight structure check before success is reported. The check verifies the `mimetype` entry, core container\u002FOPF files, manifest hrefs, spine idrefs, and cover-image references.\n\nThe OPF modified timestamp is intentionally deterministic so repeated exports are easier to compare.\n\n## Lossless Scope\n\nThe converter avoids recompressing source artwork where the PDF stores JPEG image streams or an archive stores JPEG\u002FPNG page files. Those bytes are copied directly into the EPUB.\n\nFor Flate-compressed PDF image streams, the tool wraps the image data into PNG. If the PDF uses PNG-style predictors, the compressed rows can be reused inside the PNG container. Unsupported PDF color spaces or filter chains raise an error instead of silently degrading output.\n\nFor CBZ\u002FZIP sources, entries are naturally sorted, common junk files such as `__MACOSX\u002F` and `.DS_Store` are ignored, JPEG\u002FJFIF and PNG\u002FAPNG pages are preserved, and WebP\u002FBMP\u002FTIFF\u002FGIF\u002FAVIF\u002FHEIC\u002FHEIF\u002FJPEG 2000 pages are decoded and written as PNG. Animated GIFs and multi-page TIFFs use the first frame\u002Fpage.\n\n## Project Files\n\n- `src\u002Fmanga_pdf_to_epub\u002F` - installable package grouped into `pdf\u002F`, `epub\u002F`, `models\u002F`, `gui\u002F`, and `cli\u002F` subpackages.\n- `src\u002Fmanga_pdf_to_epub\u002Fpdf\u002F` - PDF image discovery, object parsing, image stream types, and PNG wrapping.\n- `src\u002Fmanga_pdf_to_epub\u002Fsources\u002F` - archive source discovery and image normalization for CBZ\u002FZIP import.\n- `src\u002Fmanga_pdf_to_epub\u002Fepub\u002F` - EPUB page construction, writing, naming, and validation.\n- `src\u002Fmanga_pdf_to_epub\u002Fmodels\u002F` - layout, series, and deprecated batch project models.\n- `src\u002Fmanga_pdf_to_epub\u002Fgui\u002F` - Tkinter layout editor, diagnosis window, preview helpers, and series GUI workflow.\n- `src\u002Fmanga_pdf_to_epub\u002Fcli\u002F` - command-line entrypoints.\n- `scripts\u002F` - compatibility wrappers for direct script usage during development; installed commands live in `.venv\u002Fbin\u002F` after setup.\n- `tests\u002F` - unit tests for conversion, layout, series workflows, GUI behavior, and project guardrails.\n\n## Test\n\n```bash\nmake test\n```\n\nSmoke-check the CLI entrypoints:\n\n```bash\nmake smoke\n```\n\n## Limitations\n\n- Designed for image-based comic PDFs and image archives, not text-first PDFs or general ebooks.\n- Multi-image PDF pages may need more validation.\n- CBR\u002FRAR, MOBI, AZW3, and EPUB import are intentionally out of scope.\n- Apple Books behavior is modeled from observed behavior and should still be checked with real imports.\n- The GUI is intentionally utilitarian; it prioritizes reliable layout correction over visual polish.\n\n## Positioning\n\nThis is a specialist tool for manga collectors and readers who want Apple Books to preserve intentional spreads. If Calibre\u002FKCC-style conversion is enough for a book, use that. This project earns its keep when a volume needs page-level correction, Apple Books preview assumptions, and lossless source-image handling.\n","0xH4KU\u002Fmanga-to-epub 是一个专为漫画爱好者设计的无损转换工具，能够将漫画源文件（如PDF、CBZ或ZIP格式）转换成EPUB电子书，特别关注页面配对、封面空白页以及Apple Books布局特性。项目使用Python语言编写，具备导入图像为基础的多种源文件、保持原始图像质量、导出适合从右至左阅读的固定布局EPUB书籍等功能，并通过Tkinter GUI提供手动调整漫画布局的选项。该工具非常适合需要精确控制电子书版面排列的场景，尤其是当目标是优化在Apple Books上的阅读体验时。此外，它还支持预览虚拟空白页、插入或删除实际空白页、快速删除指定范围内的页面等操作，确保最终生成的EPUB文件结构合理且符合预期。","2026-06-11 03:58:36","CREATED_QUERY"]