4Charm

██╗  ██╗ ██████╗██╗  ██╗ █████╗ ██████╗ ███╗   ███╗
██║  ██║██╔════╝██║  ██║██╔══██╗██╔══██╗████╗ ████║
███████║██║     ███████║███████║██████╔╝██╔████╔██║
╚════██║██║     ██╔══██║██╔══██║██╔══██╗██║╚██╔╝██║
     ██║╚██████╗██║  ██║██║  ██║██║  ██║██║ ╚═╝ ██║
     ╚═╝ ╚═════╝╚═╝  ╚═╝╚═╝  ╚═╝╚═╝  ╚═╝╚═╝     ╚═╝

High-performance native macOS 4chan media downloader. Download entire threads, catalogs, or boards with intelligent organization, fail-safe resume, and zero duplicates.

---

Features

• Bulk Downloading — queue up to 20 threads or catalogs simultaneously
• Smart Organization — automatic folder structure with WEBM separation
• Fail-Safe Resume — automatically resumes interrupted downloads
• Duplicate Prevention — SHA-256 hashing prevents re-downloading files
• Rate Limiting — adaptive throttling with exponential backoff prevents IP bans
• Download Verification — MD5 checksum validation ensures file integrity
• Connection Pooling — 4× connection pooling for faster concurrent downloads
• Real-Time Progress — live bandwidth monitoring with ETA display
• Apple Silicon Native — arm64 build optimized for M1/M2/M3/M4 chips

---

Installation

1. Download the latest 4Charm.dmg from Releases
2. Open the DMG and drag 4Charm.app to /Applications
3. First launch — right-click the app → Open to bypass Gatekeeper on the ad-hoc signed build

---

Usage

1. Add URLs — paste any 4chan thread, catalog, or board URL
2. Start — click Download and watch the live progress log
3. Enjoy — files are saved to your chosen download folder with automatic organization

---

Development

Requirements

• Python 3.14
• macOS 12.0+
• uv

Setup

git clone https://github.com/RazorBackRoar/4Charm.git
cd 4Charm
uv sync
uv run python -m four_charm.main

Build

razorbuild 4Charm
# Output: dist/4Charm.dmg

Lint & Test

uv run ruff check .
uv run ty check src --python-version 3.14
uv run pytest tests/ -q

---

License

MIT License — see LICENSE for details. Copyright © 2026 RazorBackRoar

Runtime Requirements

For users:

• Download the macOS .dmg or .app release. Python does not need to be installed.

For developers:

• Primary development/build target: Python 3.14 with uv.
• Source compatibility goal: Python 3.12-3.14 (best effort).
• Setup: uv sync
• Run: uv run python -m four_charm