Terminal tool for batch-downloading and streaming anime from AnimePahe. Features a parallel HLS engine with segment-level crash recovery, Rich-powered live dashboard, and MPV streaming with mid-playback SUB/DUB switching.

• About
• Prerequisites
• Installation
• Quick Start
• Feature Tour
  • Download Mode
  • Stream Mode
  • Session Manager
  • Search Mode
  • Watchlist
  • Configuration
• CLI Reference
• Architecture
• Package Structure
• Development
• Troubleshooting
• Contributing
• License

Pahebatcher is a terminal application for batch-downloading anime from AnimePahe. It supports parallel episode downloads with per-episode HLS segment concurrency, segment-level crash recovery, interactive episode selection, and MPV streaming with mid-playback audio track switching.

Key characteristics:

• Single-site focus. Pahebatcher targets AnimePahe exclusively and does not support other sources.
• Self-hosted infrastructure. Cloudflare bypass uses a local FlareSolverr instance via Docker. All traffic stays on your machine — no third-party proxies. You can also inject your browser's cf_clearance cookie to skip challenge solving entirely.
• Atomic segment writes. HLS segments are written to .tmp and renamed to .ts after completion. A mid-download interruption picks up at the exact segment where it left off, without re-downloading completed work.
• Concurrent pipeline. A two-stage prefetch architecture resolves stream URLs ahead of downloaders via an asyncio.Queue. A configurable resolve_ahead throttle controls how many episodes the resolver stays ahead of downloaders to avoid Cloudflare request bursts. Episodes download in parallel (configurable 1–6), with per-episode segment concurrency (configurable 8–32).
• Rich terminal UI. Progress dashboard shows all episodes simultaneously with per-episode segment counts, transfer speeds, ETAs, file sizes, and color-coded state transitions. Interactive episode selection includes range input, a toggle checklist, and "latest N" mode.
• MPV streaming. Episodes can be streamed without downloading. A playback panel shows the current episode and playlist position. Audio tracks can be toggled between SUB and DUB mid-session.
• Session management. Previous download sessions can be resumed, deleted, or cleared from the cache. Cached segments are reused on restart. Scan results are cached to disk with a configurable TTL so re-running the tool skips all AnimePahe API calls for fresh data.
• Persistent configuration. Quality, audio, concurrency, and output directory are saved to pahebatcher.toml in the project directory. Set once via the interactive wizard or pahebatcher config set, reused on every subsequent run. CLI flags override persisted values when needed. Edit the file directly or use the config subcommand.
• MIT licensed. Free to use, modify, and redistribute.

FlareSolverr must be running before pahebatcher starts. The tool checks reachability on launch and prints the exact Docker command if it cannot connect. The default URL is http://localhost:8191/v1; override with the FLARESOLVERR_URL environment variable.

git clone https://github.com/smolfiddle/pahebatcher.git
cd pahebatcher

make run          # interactive wizard
make run "URL"    # skip search, go directly to series
make help         # show all targets
make config-show  # display current settings
make watchlist-list  # list watchlist
make watchlist-check # check watchlist for new episodes
make test         # run all 203 tests
make lint         # ruff check (0 errors)
make typecheck    # mypy strict (0 errors)
make benchmark    # full coherence benchmark
make help         # show all targets

After first run, set persistent defaults:

make config-show
venv/bin/python -m pahebatcher config set quality 720
venv/bin/python -m pahebatcher config set audio_lang eng

Pass a URL directly (positional or via URL=):

make run "https://animepahe.pw/anime/<uuid>"
make run URL="https://animepahe.pw/anime/<uuid>" ARGS="--all -q 720"

pipx install .
pahebatcher

pipx installs pahebatcher into an isolated venv at ~/.local/share/pipx/venvs/pahebatcher and symlinks ~/.local/bin/pahebatcher. That venv is not auto-updated when you git pull / git checkout.

Updating after git pull or switching branches (e.g. feature/watchlist):

# from the repo root, after git pull / git checkout:
pipx install . --force && hash -r
pahebatcher --help | grep watchlist   # should list watchlist commands
# alternative (same effect):
pipx reinstall pahebatcher

If you skip this, pahebatcher watchlist check will say unrecognized arguments: check (you're still running the old 3.0.0 binary) while make watchlist-check works (it uses venv).

pip install -e ".[dev]"
pahebatcher
# no --force needed: edits to src/ are live; only reinstall if pyproject.toml changes

Note: The developer has never tested pahebatcher on actual Windows. The Python code is OS-neutral (pathlib/asyncio, store.py:40 atomic .tmp→.ts, pyproject.toml:8 Operating System :: OS Independent), but Windows has only been reasoned about, not run. WSL2 is the safer bet if you hit edge cases.

Prerequisites (Windows):

Install & run:

git clone https://github.com/smolfiddle/pahebatcher.git
cd pahebatcher
py -3.11 -m venv venv
venv\Scripts\python -m pip install -e ".[dev]"
venv\Scripts\python -m pahebatcher --help
venv\Scripts\python -m pahebatcher watchlist add https://animepahe.pw/anime/<uuid> -q 720
venv\Scripts\python -m pahebatcher wl check
# pipx alternative (same isolated-venv caveat as Linux):
# pipx install .
# pahebatcher --help | findstr watchlist

Windows differences:

• No make — use venv\Scripts\python -m pahebatcher ... directly (Makefile:42 is Unix-only).
• No cron — use Task Scheduler: Create Task → Trigger daily/hourly → Action Start a program → Program C:\path\to\pahebatcher\venv\Scripts\python.exe → Arguments -m pahebatcher wl check → Start in C:\path\to\pahebatcher (so watchlist.json/pahe_cache resolve, WATCHLIST_PATH also works).
• Paths use .\ and venv\Scripts\ on Windows vs venv/bin/ on Linux/macOS.

If you hit Windows-specific issues (long paths, sanitize reserved names, console encoding), please open an issue mentioning Windows.

All three methods produce the pahebatcher command. You can also run via python -m pahebatcher.

Which binary am I running?

which -a pahebatcher          # pipx → ~/.local/bin/pahebatcher, venv → ./venv/bin/pahebatcher
pahebatcher --help | grep watchlist        # global: should list watchlist if up-to-date
make watchlist-list            # always uses venv → correct for your checkout
venv/bin/pahebatcher watchlist list        # direct venv binary
venv/bin/python -m pahebatcher watchlist list  # most explicit, never stale

If global is stale, use the venv/make form or refresh pipx as above.

# Interactive wizard -- search for a series or paste a URL
pahebatcher

# Download entire series, 720p, Japanese audio, 2 concurrent episodes
pahebatcher "https://animepahe.pw/anime/<uuid>" --all -q 720

# Download episodes 1 through 12, English dub, 1080p, custom output directory
pahebatcher "https://animepahe.pw/anime/<uuid>" --range 1-12 --audio eng -q 1080 -o ~/anime

# Download only the 3 most recently aired episodes
pahebatcher "https://animepahe.pw/anime/<uuid>" --latest 3

# List all episodes and exit (no download)
pahebatcher "https://animepahe.pw/anime/<uuid>" --list

# Stream episodes in MPV with on-the-fly SUB/DUB switching
pahebatcher "https://animepahe.pw/anime/<uuid>" --stream -q 1080

# 4 concurrent episodes, 32 HLS workers per episode
pahebatcher "https://animepahe.pw/anime/<uuid>" --all -q 1080 -j 4 -w 32

# Save default preferences so you don't need flags every time
pahebatcher config set quality 720

# Watchlist — follow a weekly airing show without re-running manually
pahebatcher watchlist add https://animepahe.pw/anime/<uuid> -q 1080 --audio jpn -o ~/anime
pahebatcher wl list                    # wl/w = shorthand for watchlist
pahebatcher check                      # shorthand for watchlist check (also: wl check, wl c, sync)

# Enable debug logging for troubleshooting
pahebatcher "https://animepahe.pw/anime/<uuid>" --all --verbose

Output files are saved as Ep 001 - Episode Title.mp4 in the output directory (default: ./downloads/<series_name>/).

Watchlist state lives at watchlist.json (cwd, git-ignored). Delete it or watchlist remove to stop tracking. Override location with WATCHLIST_PATH=/tmp/my.json.

The core workflow: scan a series, select episodes, configure settings, download.

Episode selection offers five modes accessible from the interactive wizard or CLI flags:

Settings wizard (interactive mode only) prompts for quality, audio language, output directory, and concurrency. Choices are automatically persisted to pahebatcher.toml and reused on future runs — run the wizard once, no need to reconfigure on subsequent sessions.

Download dashboard shows every episode simultaneously with live per-episode metrics: segment counter (M of N), percentage, transfer speed, ETA, and file size. Each episode transitions through color-coded states: resolving (cyan) -> queued (dim cyan) -> downloading (bold white) -> remuxing (yellow) -> done (green checkmark) / fail (red cross).

Segment-level crash recovery. HLS segments are written atomically (.tmp file renamed to .ts after write completes). On restart, the tool reads done_indices() and only fetches missing segments. Already-completed MP4 files in the output directory are skipped entirely.

Launches MPV with the resolved M3U8 URL and authentication headers. Displays a live "Now Playing" panel with episode title, audio track, quality, and playlist position.

Post-episode navigation:

• N / P — next / previous episode in playlist
• A — toggle SUB / DUB audio track mid-session (reloads playlist with new audio lane)
• R — replay current episode
• S — jump to any episode by number
• Q — quit

Post-episode controls appear after MPV closes, offering navigation, audio switching, replay, and episode selection.

Accessible from the main menu (option 3). Lists all cached sessions with:

• Anime title and URL
• Episode count and segment count
• Total cache size on disk
• Status (Paused)

Actions: Resume (restarts tool with that series URL), Delete (removes single session cache), Clear All (wipes entire pahe_cache/ directory).

Running pahebatcher without a URL opens interactive search. Type an anime title, browse results in a table (title, type, year, episodes, score), select by number. The tool auto-discovers SUB and DUB variants of the selected series.

Track weekly airing shows without re-running the tool manually. Add a series once with your preferred quality/audio/output, then run a single check command (e.g. from cron) — it scans every watched anime, downloads only episodes not already on disk, resumes partial downloads via the existing segment store, and is safe to run repeatedly.

Workflow:

1. add validates the AnimePahe URL (scanner.py:30), normalizes to https://<host>/anime/<uuid>, and saves prefs. Without flags it inherits pahebatcher.toml (config_manager.py:15).
2. list/show/remove/reset manage state. show/remove/reset accept 1-based index, full URL, session UUID, or title substring (watchlist.py:103).
3. check is one-shot: for each entry it scans with cache_ttl=0 (forces fresh, unlike normal 60 min cache), diffs against files on disk via BatchOrchestrator._find_existing() (downloader.py:154 — Ep 001 / Ep_001 prefix, size>0), plus remembers deleted episodes while the series folder exists (downloaded history watchlist.py:30), and reuses the 2-stage pipeline. Already-present MP4s are skipped, partial .ts segments are resumed. Running it again immediately downloads nothing.

# Add a series to the watchlist (mirrors download flags) — long or short
pahebatcher watchlist add https://animepahe.pw/anime/<uuid> -q 1080 --audio jpn -o ~/anime
pahebatcher wl add https://animepahe.pw/anime/<uuid> --audio eng -q 720 -j 2 -w 24 --keep-temp --retry 2  # wl/w = shorthand
pahebatcher w add https://animepahe.pw/anime/<uuid>          # uses pahebatcher.toml defaults

# List / inspect / remove / reset / relink ( --yes skips confirmation)
pahebatcher watchlist list  # or wl list, wl ls, wl l
pahebatcher wl show 1       # s/info also work: wl s 1
pahebatcher wl show https://animepahe.pw/anime/<uuid>
pahebatcher wl remove 1 --yes   # also rm/r/del
pahebatcher wl reset 1      # also rst/clear — clear deleted-history
pahebatcher wl relink 1 https://animepahe.pw/anime/<new-uuid>  # fix one dead link
pahebatcher wl relink 1     # auto — finds new UUID by title (no URL needed)
pahebatcher wl relink       # one command — auto-relinks ALL dead entries
pahebatcher wl relink       # one command — auto-relinks ALL dead entries

# Check for new episodes and download (one-shot, cron-friendly)
pahebatcher watchlist check
pahebatcher wl check        # same
pahebatcher wl c            # shortest: wl c
pahebatcher check           # top-level shorthand → watchlist check
pahebatcher sync            # alias for check
pahebatcher wl check --verbose
pahebatcher wl check https://animepahe.pw/anime/<uuid>  # single series

# Make wrappers (same as above, use project venv)
make watchlist-list      # or make run ARGS="wl ls"
make watchlist-check     # or make run ARGS="check" / ARGS="wl c"

State & persistence:

• File: watchlist.json in cwd (sibling to pahebatcher.toml), git-ignored, survives pahe_cache clear and restarts. Atomic write via .tmp→rename (watchlist.py:98). Corrupted JSON is treated as empty.
• Env: WATCHLIST_PATH=/tmp/custom.json pahebatcher watchlist list overrides location (useful for tests/cron isolation).
• Entry fields: url, session, host, title (auto-filled on check), quality, audio_lang, output_dir (base, sanitized title appended as os.path.join(output_dir, sanitize(title))), max_parallel, hls_workers, keep_temp, auto_retry, added_at, last_checked, downloaded (list of episode numbers ever seen on disk).
• Title is placeholder session on add and refreshed on first check via scan. Updating an existing URL keeps added_at and preserves a real title and downloaded history.

Cron / systemd (one-shot only — no daemon):

# hourly, append logs
0 * * * * cd /path/to/pahebatcher && venv/bin/python -m pahebatcher watchlist check >> watchlist.log 2>&1

# or with make
0 * * * * cd /path/to/pahebatcher && make watchlist-check >> watchlist.log 2>&1

# custom state location
0 * * * * WATCHLIST_PATH=/home/user/.config/pahebatcher/watchlist.json /home/user/pahebatcher/venv/bin/pahebatcher watchlist check >> /tmp/watchlist.log 2>&1

Idempotency: second check immediately is a no-op. Failures are per-series isolated — one