Cruncharr

Cruncharr is a self-hosted app for organizing and maintaining your personal anime media library. It provides a headless backend, a REST API, and a single-page web interface.

Quick Deploy

Option 1: Docker Run (Recommended)

# Create directories
mkdir -p Cruncharr/config Cruncharr/downloads Cruncharr/widevine

# Run the container
docker run -d \
  --name cruncharr \
  -p 8585:8585 \
  -v $(pwd)/Cruncharr/config:/config \
  -v $(pwd)/Cruncharr/downloads:/downloads \
  -v $(pwd)/Cruncharr/widevine:/widevine \
  ghcr.io/mediavybz/cruncharr:latest

# Access the web interface
open http://localhost:8585

Option 2: Docker Compose

version: '3.8'

services:
  cruncharr:
    image: ghcr.io/mediavybz/cruncharr:latest
    container_name: cruncharr
    ports:
      - "8585:8585"
    volumes:
      - ./config:/config
      - ./downloads:/downloads
      - ./widevine:/widevine
    environment:
      - CRUNCHYROLL_CONFIG_PATH=/config/cruncharr.yaml
    restart: unless-stopped

docker-compose up -d

First Time Setup

1. Open the web interface at http://your-server:8585
2. Browse or search without signing in. Direct Cruncharr downloads require Premium. With Sonarr enabled, guest and free-account requests can use Sonarr instead.
3. Configure settings:
   • Library directory: /downloads (inside container)
   • Temp directory: /tmp/cruncharr
   • Endpoints: use defaults (recommended)
   • Audio languages: ja-JP (Japanese) by default
   • Subtitles: en-US (English) by default
   • Adjust these in Settings; changes save automatically

See Sonarr requests for automatic series registration, completed-file imports, and guest requests.

Stable and beta versions

master contains the stable release; testing contains beta changes. Compare the same branch on Forgejo and GitHub when checking sync. Use ghcr.io/mediavybz/cruncharr:testing to test beta fixes. The latest image follows the stable release. See repository backups for sync checks.

Volume Mounts

Hardware Acceleration (GPU)

The image ships a full-GPU ffmpeg build (NVIDIA NVENC/CUDA, Intel QSV, AMD VAAPI/AMF, Vulkan). It is used by the Sync HW Accel option (Settings → Muxing). The dropdown lists only the GPUs currently available to the container — if you don't pass a GPU in, only "None (CPU)" appears.

Intel / AMD (VAAPI, QSV, AMF) — pass the render device:

    devices:
      - /dev/dri:/dev/dri
    group_add:
      - "video"
      - "render"

NVIDIA (NVENC/CUDA) — requires the NVIDIA Container Toolkit on the host:

    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: all
              capabilities: [gpu]

After (re)creating the container, open Settings → Muxing → Sync HW Accel and the detected GPU(s) will be listed (e.g. NVIDIA (CUDA) or Intel / AMD (VAAPI) (/dev/dri/renderD128)).

The runtime image is Debian-based; ffmpeg is a BtbN GPL build. NVIDIA encode needs the host driver injected by the NVIDIA Container Toolkit — the image alone does not bundle the driver.

Configuration

Config File

Create config/cruncharr.yaml:

crunchyroll:
  email: "your@email.com"
  password: "yourpassword"
  use_beta_api: true
  stream_endpoint:
    endpoint: tv/android_tv
    use_default: true
    video: true
    audio: true
download:
  output_dir: /downloads
  temp_dir: /tmp/cruncharr
  filename: "${seriesTitle} - S${season}E${episode} [${height}p]"
  quality_video: best
  quality_audio: best
  dub_languages:
    - ja-JP  # Default: Japanese only
  soft_subs:
    - en-US  # Default: English only
  simultaneous_downloads: 2
  simultaneous_processing_jobs: 2
queue:
  persist_queue: false
  auto_download: false
history:
  enabled: true
  remove_missing_episodes: true

Building Images

All production and testing Docker builds run exclusively on the self-hosted Unraid Forgejo docker-build runner. Pushes to testing validate AMD64 and ARM64, load the AMD64 image, and run a container health check. The workflow is .forgejo/workflows/docker-testing.yml.

To publish ghcr.io/mediavybz/cruncharr:testing, manually run that workflow with its publish input enabled. scripts/publish-docker.sh is invoked by the runner workflow and is not a supported local fallback. Do not build or publish Docker images from a developer or agent workstation.

API Endpoints

The backend exposes a REST API at http://localhost:8585/api/v1/:

• GET /api/v1/auth/status - Auth status
• POST /api/v1/auth/login - Sign in with credentials
• GET /api/v1/queue - Activity queue
• POST /api/v1/queue - Add to queue
• GET /api/v1/series/search?query=QUERY - Search catalog
• GET /api/v1/series/{id}/episodes - Get episodes
• GET /api/v1/config - Get configuration
• POST /api/v1/config - Update configuration

Features

• Web interface: Single-page app at / - search the catalog, browse episodes, manage activity, configure settings
• Sign-in: Account login with automatic token refresh
• Library: Select episodes with multi-track support and concurrent processing with progress tracking
• Queue: Add episodes to a queue, optional automatic processing, activity management
• History: Track your catalog, Sonarr integration, refresh series data
• Calendar: View upcoming release schedule
• Endpoints: Configurable device endpoints (Android TV, Web, Console) with working defaults
• Languages: Select audio and subtitle languages (default: Japanese audio, English subtitles)
• Muxing: Automatic muxing with ffmpeg/mkvtoolnix, MP4/MP3 output options
• Hardware acceleration: Full-GPU ffmpeg (NVENC/CUDA, QSV, VAAPI/AMF, Vulkan); GPU picker for sync that lists only the devices passed into the container
• Themes: Multiple selectable UI themes (Dark, Light, Cinematic, AMOLED, Nebula, Seerr) with a centralized design-token system
• Settings: Full settings panel with library, queue, history, notifications, and appearance options
• Notifications: Webhook support for completion/failure events

Troubleshooting

No Audio Track

• Check that dub_languages in config includes the item's audio language
• Default is ja-JP only - add more languages in Settings if needed

Sign-in Issues

• Delete config/token.json to force a fresh sign-in
• Check that the stream endpoint "Use Default" is enabled

Reset All Settings

• Stop the container
• Delete config/cruncharr.yaml
• Restart the container - it will recreate with defaults

Device Files

• Some sources require device_private_key.pem and device_client_id_blob.bin in the widevine/ directory

Security

Cruncharr is built for private, self-hosted use (your LAN, or behind a reverse proxy). Before exposing it more widely:

• API key. The API is unauthenticated by default. If the container is reachable from an untrusted network, set the CRUNCHARR_API_KEY env var — every /api/* request must then present it via the X-Api-Key header, Authorization: Bearer <key>, or (only for the browser Server-Sent-Events stream, which cannot send headers) the ?apiKey= query param. The web interface prompts for the key once and stores it locally. Health checks stay exempt.
• TLS. The container serves plain HTTP. Terminate HTTPS at a reverse proxy (Caddy / nginx / Traefik) if it leaves your host.
• Credentials at rest. Your account login and any Sonarr/proxy keys live in config/cruncharr.yaml in plaintext (file mode 600) — the same model as Sonarr/Radarr. Protect the /config volume accordingly. The config API never returns secrets (they read back as [configured]), and credentials are never written to logs.
• CORS. Cross-origin API access defaults to http://localhost:8585; override with the CORS_ORIGINS env var (comma-separated) if you serve the UI elsewhere.
• Outbound calls are guarded. Webhook URLs are rejected if they resolve to private/loopback/link-local addresses (SSRF protection); catalog images are proxied and cached server-side only from the source's own image host over HTTPS.

Credits

This project is based on the original Crunchy-Downloader desktop application by Crunchy-DL. All core logic and media processing is ported from the upstream source, as required by its license.

• Upstream: https://github.com/Crunchy-DL/Crunchy-Downloader
• Upstream License: MIT License (Copyright (c) 2024 Crunchy DL)
• Port: Dockerized web interface with REST API and headless backend

License

MIT License - See upstream LICENSE for full text.