meowDFer

A CLI tool for processing image collections and converting compressed archives into structured, organized PDF chapters and volumes.

• Multi-Format Archive Extraction: Supports .zip, .cbz, .rar, .cbr, .tar, .tar.gz, .tar.bz2, .tar.xz, and .tgz.
• Pipeline Workflows: Run complete batch chains seamlessly (Extract -> Convert -> Merge).
• Transactional File Safety: Results are processed in temporary staging zones and moved to the final destination directory only upon success.
• Fault-Tolerant Processing (--skip): Automatically logs corrupted archives or broken folders and skips to the next item instead of aborting the entire batch.
• Automated Web Scraping: Scrapes Wikipedia or Fandom tables to generate volume interval mapping files (vols.txt) automatically.
• Cross-Platform: Runs natively on Linux, macOS, and Windows or via an isolated Docker container environment.

• Docker Desktop (Windows/macOS) or the Docker Engine (Linux), running
• Permission to talk to the Docker daemon (docker info succeeds)

• Python 3.10 or newer
• System archive tools used by patool (e.g. p7zip-full / 7z, unzip, unrar, tar)

Docker ships all extraction backends inside the image, so you do not need Python or archive tools on the host. The install scripts build meowdfer:latest and register a meowdfer launcher that mounts your home directory and current working directory into the container.

1. Clone the repository (or unpack a GitHub Release setup zip):

   git clone https://github.com/v1nc3t/meowDFer.git
   cd meowDFer

2. Run the setup script for your OS:

   • Linux / macOS:

     chmod +x install.sh
     ./install.sh

     Builds the image and installs a launcher at /usr/local/bin/meowdfer (may prompt for sudo).

   • Windows (PowerShell):

     powershell -ExecutionPolicy Bypass -File .\install.ps1

     Builds the image and adds the project folder to your User PATH (uses meowdfer.bat). Restart the terminal afterward.

3. Verify:

   meowdfer --help

1. Clone the repository:

   git clone https://github.com/v1nc3t/meowDFer.git
   cd meowDFer

2. Create and activate a virtual environment:

   • Linux / macOS:

     python3 -m venv .venv
     source .venv/bin/activate

   • Windows (PowerShell):

     python -m venv .venv
     .\.venv\Scripts\Activate.ps1

   • Windows (Command Prompt):

     python -m venv .venv
     .\.venv\Scripts\activate.bat

3. Install the package:

   pip install .

4. Verify the CLI:

   meowdfer --help
   # equivalent:
   python -m meowdfer --help

After either install path, invoke the same CLI:

meowdfer (-e SRC DEST | -c SRC DEST | -m SRC DEST | -cm SRC DEST | -a SRC DEST | -sc URL DEST) [OPTIONS]

Relative paths are resolved from your current working directory. With the Docker launcher, absolute paths under your home directory also work.

Extract supported archive files into structured folders:

meowdfer -e ./downloads/zips ./extracted_folders --skip

Convert folders containing images into individual chapter PDFs:

meowdfer -c ./extracted_folders ./chapter_pdfs --type chapter

Expected folder conventions:

• Volumes: v001, volume 1, vol 1
• Chapters: c 1, ch 1, chapter 1, 001
• Pages: 1.jpg, 13.png, 21.jpeg

Scrape a Wikipedia or Fandom entry to output a vols.txt mapping file:

meowdfer -sc "https://en.wikipedia.org/wiki/List_of_Manga_Volumes" ./vols.txt -v

The generated vols.txt output file format:

1, 7, 12, 19, 25

Merge chapter PDFs using the interval mapping file:

meowdfer -m ./chapter_pdfs ./volume_pdfs --file ./vols.txt

Run extraction, image-to-PDF conversion, and volume merging in one continuous run:

meowdfer -a ./zips_dir ./final_volumes --type volume --file ./vols.txt --skip

Build the image once:

docker build -t meowdfer:latest .

docker run --rm -it \
    --user "$(id -u):$(id -g)" \
    -e HOME=/tmp \
    -v "$HOME:$HOME" \
    -v "$(pwd):$(pwd)" \
    -w "$(pwd)" \
    meowdfer:latest -a ./zips_dir ./final_volumes -t volume -f ./vols.txt

docker run --rm -it ^
    -e HOME=/tmp ^
    -v "%USERPROFILE%:%USERPROFILE%" ^
    -v "%CD%:%CD%" ^
    -w "%CD%" ^
    meowdfer:latest -a .\zips_dir .\final_volumes -t volume -f .\vols.txt

Mounts the current directory into the container at /data and runs meowdfer there:

# Linux / macOS: keep output files owned by you
export UID="$(id -u)" GID="$(id -g)"

docker compose run --rm meowdfer --help
docker compose run --rm meowdfer -e ./zips_dir ./out
docker compose run --rm meowdfer -a ./zips_dir ./final_volumes -t volume -f ./vols.txt

pip install -e ".[dev]"
pytest tests/ -v

GitHub Actions runs tests on:

• All pull requests
• Pushes to main or master

Workflow: .github/workflows/ci.yml

Pushing a v* tag runs .github/workflows/release.yml. It runs tests, builds meowDFer-v<version>-setup.zip, and publishes a GitHub Release with auto-generated notes.

git tag v1.0.1
git push origin v1.0.1

Or run manually: Actions → Release → Run workflow, then enter an existing tag.

Distributed under the terms of the GNU General Public License v3. See LICENSE for more information.