KO | EN

GitLite

Minimalist Open Source Repository Search Engine

gitlite — search

#dsh #dsh-plugin #typescript #developer-tools #claude-code #ai-agent #codex #deepseek-harness #ai-agents #cli #react #mcp

asmr.one-downloader

★ 17 Open GitHub ↗

Python-based CLI tool for downloading ASMR content from asmr.one, featuring tqdm progress bars, automatic retries, file type filtering, and pause/resume support.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

<div align="center">
  <h1>🎙️ ASMR.ONE Downloader</h1>
  <p><strong>An asynchronous, terminal-based downloader for <a href="https://asmr.one">ASMR.ONE</a> — persistent, resumable, bandwidth-throttled, and fully scriptable.</strong></p>

[![Version](https://img.shields.io/badge/version-1.5.06082026-blueviolet.svg?style=for-the-badge)](https://github.com/takoyune/asmr.one-downloader/releases)
  [![Python](https://img.shields.io/badge/python-3.10+-blue.svg?style=for-the-badge&logo=python&logoColor=white)](https://www.python.org/)
  [![License](https://img.shields.io/badge/License-MIT-yellow.svg?style=for-the-badge)](https://raw.githubusercontent.com/takoyune/asmr.one-downloader/main/LICENSE)
  [![Platform](https://img.shields.io/badge/platform-Windows%20%7C%20Linux%20%7C%20macOS-lightgrey.svg?style=for-the-badge)](https://raw.githubusercontent.com/takoyune/asmr.one-downloader/main/)
  [![CI](https://github.com/takoyune/asmr.one-downloader/actions/workflows/ci.yml/badge.svg?style=for-the-badge)](https://github.com/takoyune/asmr.one-downloader/actions/workflows/ci.yml)
</div>

<p align="center">
  <a href="README.md">English</a> •
  <a href="README_ja.md">日本語</a> •
  <a href="README_zh-CN.md">简体中文</a> •
  <a href="README_zh-TW.md">繁體中文</a> •
  <a href="README_ko.md">한국어</a>
</p>

---

## <img src="docs/assets/icons/camera.svg" width="20" align="top"> Preview

---

## <img src="docs/assets/icons/clipboard-list.svg" width="20" align="top"> Table of Contents

| | | |
|:---:|:---:|:---:|
| [<img src="docs/assets/icons/camera.svg" width="20" align="top"> Preview](#-preview) | [<img src="docs/assets/icons/sparkles.svg" width="20" align="top"> What's New](#-whats-new-in-v1401082036-media-ecosystem--audio-processing-upgrade) | [<img src="docs/assets/icons/lock.svg" width="20" align="top"> Previous Updates](#-previous-major-updates) |
| [<img src="docs/assets/icons/sparkles.svg" width="20" align="top"> Features](#-features) | [<img src="docs/assets/icons/package.svg" width="20" align="top"> Requirements](#-requirements) | [<img src="docs/assets/icons/rocket.svg" width="20" align="top"> Installation](#-installation) |
| [<img src="docs/assets/icons/play.svg" width="20" align="top"> Running the App](#️-running-the-app) | [<img src="docs/assets/icons/monitor.svg" width="20" align="top"> Interactive Menu](#️-usage--interactive-menu) | [<img src="docs/assets/icons/wrench.svg" width="20" align="top"> CLI Flags](#-usage--cli-flags) |
| [<img src="docs/assets/icons/settings.svg" width="20" align="top"> Configuration](#️-configuration) | [<img src="docs/assets/icons/archive.svg" width="20" align="top"> Data & Files](#️-data--files) | [<img src="docs/assets/icons/folder.svg" width="20" align="top"> Project Structure](#-project-structure) |
| [<img src="docs/assets/icons/help-circle.svg" width="20" align="top"> FAQ / Known Limitations](#-faq--known-limitations) | [<img src="docs/assets/icons/search.svg" width="20" align="top"> Troubleshooting](#-troubleshooting) | [<img src="docs/assets/icons/handshake.svg" width="20" align="top"> Contributing](#-contributing) |
| [<img src="docs/assets/icons/alert-triangle.svg" width="20" align="top"> Disclaimer](#️-disclaimer) | [<img src="docs/assets/icons/heart.svg" width="20" align="top"> Acknowledgments](#-acknowledgments) | [<img src="docs/assets/icons/file-text.svg" width="20" align="top"> License](#-license) |

</div>

---

## <img src="docs/assets/icons/sparkles.svg" width="20" align="top"> What's New in v1.5.06082026 (The TUI & System Overhaul)

This major release replaces legacy command-line menus with beautiful, responsive, full-screen Terminal User Interfaces (TUIs) powered by `Textual`, and upgrades the core system architecture.

### <img src="docs/assets/icons/monitor.svg" width="20" align="top"> Terminal UI Overhaul
- **Mission Control TUI** — Batch processing now opens a live dashboard with queue management, a scrolling event stream, and real-time ASCII sparkline bandwidth graphs.
- **Search TUI** — Online searches are now performed in a full-screen app featuring an interactive search bar, mode selector, and a scrollable `DataTable` of ASMR.ONE results with pagination.
- **Media Player TUI** — The audio player was rebuilt into a visual interface with a playlist `Tree`, live playback `ProgressBar`, and dynamic status bar.

### <img src="docs/assets/icons/zap.svg" width="20" align="top"> System & Architecture Upgrades
- **Typer CLI** — Replaced `argparse` with `Typer` for a robust, strict, and beautifully documented subcommand interface.
- **Fuzzy Search Integration** — Added `rapidfuzz` for typo-tolerant local database queries.
- **Enterprise Logging** — Migrated background logging to `Loguru` for robust stack traces in `singularity.log`.
- **Fair Bandwidth Shaping** — Concurrent active streams now mathematically divide the global bandwidth limit evenly among themselves, preventing uneven download speeds.

---

## <img src="docs/assets/icons/lock.svg" width="20" align="top"> Previous Major Updates

<details>
<summary><strong>v1.4.01082036 (Media Ecosystem & Audio Processing Upgrade)</strong></summary>

This monumental update transforms the downloader into a full-fledged media ecosystem, introducing advanced FFmpeg audio processing, intelligent library management, multi-threaded downloading, and a built-in terminal media player.

### <img src="docs/assets/icons/headphones.svg" width="20" align="top"> Audio Processing & FFmpeg Engine
- **EBU R128 Loudness Normalization** — Automatically normalizes audio tracks to -16 LUFS target loudness to prevent deafening volume jumps between different works.
- **Auto-Transcoder** — Lossless formats (WAV/FLAC) can be automatically transcoded to space-saving MP3 320k post-download.
- **Synced LRC Lyrics Embedder** — Automatically parses `.lrc` subtitle files and embeds them as synchronized `USLT` / `LYRICS` ID3 tags inside the audio file.
- **Cover Art Transcoder** — WebP and AVIF cover images are automatically transcoded to universally-supported JPG format.

### <img src="docs/assets/icons/library.svg" width="20" align="top"> Advanced Library Management
- **Library Health Auditor** — Scans your physical disk against the SQLite database to instantly detect missing folders, corrupted 0-byte tracks, or duplicate paths.
- **Auto-Import Scanner** — Point the app to your existing ASMR library directory. It will scan for RJ codes, fetch official ASMR.ONE metadata, and register them into the database automatically.
- **Smart Playlist Generator** — Generate standard `.m3u` playlists on-the-fly using SQL-based tag or voice actor filters.

### <img src="docs/assets/icons/rocket.svg" width="20" align="top"> Next-Gen Download Engine
- **Segmented Multi-Threading** — Files larger than 5MB are automatically split into multiple concurrent HTTP chunk requests, massively boosting download speeds.
- **Active Hours Bandwidth Throttling** — Configure different download speed caps based on the time of day (e.g., limit to 2MB/s during work hours, unlimited at night).
- **Archive Auto-Extraction** — Downloaded `.zip`, `.rar`, and `.7z` archives are automatically extracted and flattened into the root work folder.

### <img src="docs/assets/icons/music.svg" width="20" align="top"> Built-In CLI Media Player
- **Terminal Audio Player** — Listen to downloaded works directly from the command line using the new `pygame-ce` powered interactive terminal player.
</details>

<details>
<summary><strong>v1.3.22072026 (Search & Language Overhaul)</strong></summary>

A major quality-of-life update focused on smarter online search, tag filtering that mirrors the official website, and full multilingual tag/audio language configuration.

### <img src="docs/assets/icons/search.svg" width="20" align="top"> Online Search — Full Overhaul
- **Interactive Search Sub-Menu** — Option `[3] Search ASMR.ONE Online` opens a dedicated sub-menu for Keywords, Tags, CVs, and Circles.
- **Tags Column in Results Table** — Search results now include a **Tags** column.

### <img src="docs/assets/icons/tag.svg" width="20" align="top"> Official Website Tag Syntax
- Tag searches now use the exact same filter format as the ASMR.ONE website: **`$tagw:TAG$`**

### <img src="docs/assets/icons/globe.svg" width="20" align="top"> Dual Language Priority Settings
- `audio_language_priority` & `tag_language_priority` (e.g., `["ja-jp", "en-us"]`).

</details>

<details>
<summary><strong>v1.2.07072026 (Library & Queue Stability)</strong></summary>

### <img src="docs/assets/icons/database.svg" width="20" align="top"> Download Engine
- **Async concurrent downloads** with configurable concurrency (default: 3 parallel files)
- **Resume support** using HTTP `Range` headers — `.tmp` files persist between sessions
- **3-attempt retry loop** per file with per-failure reason logging (HTTP status, exception type)
- **Token-bucket bandwidth limiter** via `bandwidth_limit_mbps` in config
- **Mirror speed test on startup** — all mirrors pinged in parallel, fastest selected automatically

### <img src="docs/assets/icons/library.svg" width="20" align="top"> Library & Queue
- **SQLite library** (`history.db`) tracking every completed download
- **Duplicate detection** — already-owned works are skipped automatically
- **Persistent queue** — survives interruptions; continue with `--resume`
- **Format priority deduplication** — when WAV and MP3 exist for the same track, only the preferred format is downloaded

### <img src="docs/assets/icons/monitor.svg" width="20" align="top"> CLI & UI
- **`--list`** — print full folder/file tree without downloading
- **`--dry-run`** — simulate a download and show file sizes
- **`--all`** — skip file-selection prompt
- **`--batch`** — load a `.txt` file of work codes (RJ/VJ)
- **Session Report** — success/fail/skipped counts, elapsed time, average speed
- **Windows completion beep** on queue finish

### <img src="docs/assets/icons/music.svg" width="20" align="top"> Metadata & Organization
- **Audio tagging** via `mutagen` — title, artist, album, cover art for MP3/FLAC/OGG
- **Flexible folder naming** via `dir_template` using `{rj_id}`, `{title}`, `{circle}`, `{year}`
- **Optional file sorting** into `Audio/`, `Images/`, `Text/` subdirectories

</details>

---

## <img src="docs/assets/icons/sparkles.svg" width="20" align="top"> Features

### Download Engine
- **Async concurrent downloads** via `asyncio` + `aiohttp`. Configurable concurrency (default: 3 parallel files).
- **Resume support** — downloads use HTTP `Range` headers. A `.tmp` file is kept between sessions and extended on restart.
- **3-attempt retry loop** per file. Failures are recorded with reason and displayed in the Session Report.
- **Token-bucket bandwidth limiter** — set `bandwidth_limit_mbps` to cap download speed globally. `0` = unlimited.
- **Mirror speed test on startup** — all configured API mirrors are pinged in parallel and the fastest is selected automatically.

### Library & Queue
- **SQLite library** (`history.db`) tracks every completed download: work code, title, local path, file size, date.
- **Duplicate detection** — already-owned works are skipped before queuing.
- **Persistent queue** — the download queue lives in the database. Interrupted sessions survive a restart. Use `--resume` to continue.
- **Format priority deduplication** — only the preferred format is downloaded when a work includes multiple format versions.

### Online Search
- **Keyword / Title search** — search ASMR.ONE and get an interactive numbered result table.
- **Tag search** — uses official ASMR.ONE website syntax (`$tagw:TAG$`), supports multiple tags.
- **Voice Actor & Circle search** — dedicated filters via CLI flags or the interactive sub-menu.
- **Custom syntax filter** — full support for `$rate:`, `$duration:`, `$tagw:`, and other ASMR.ONE query operators.
- **Tags column in search results** — displayed in your configured language (Japanese, English, or Chinese).

### CLI & UI
- **`--search`** — search online from the command line.
- **`--tag`** — tag filter search using official website syntax.
- **`--list`** — print full folder/file tree without downloading.
- **`--dry-run`** — simulate a download; shows files and total size, writes nothing.
- **`--all`** — skip file-selection prompt; download everything.
- **`--batch`** — load a `.txt` file of work codes.
- **Session Report** — after each job: success/fail/skipped counts, elapsed time, average speed.
- **Windows completion beep** — system sound plays when the full queue finishes.

### Metadata & Multilingual Support
- **Audio tagging** (`mutagen`) — title, artist, album, and cover art written to MP3, FLAC, and OGG.
- **Flexible folder naming** — configurable `dir_template` using `{rj_id}`, `{title}`, `{circle}`, `{year}`.
- **Optional file sorting** — enable `sort_files` to organize into `Audio/`, `Images/`, `Text/`.
- **Dual language priority config** — separately control the language for audio editions and tag display.

---

## <img src="docs/assets/icons/package.svg" width="20" align="top"> Requirements

- **Python 3.10 or higher** — [python.org](https://www.python.org/downloads/)
- A terminal with ANSI color support:
  - Windows: **Windows Terminal** (recommended), VS Code terminal, or PowerShell 7+
  - macOS/Linux: any modern terminal emulator
- **Git** (for cloning) — [git-scm.com](https://git-scm.com/)

Installed automatically by `setup.bat` or `pip install -r requirements.txt`. 
For optional features (like extraction, player, or documentation), run `pip install -r requirements-optional.txt`.

<details>
<summary><strong>Python Dependencies & System Packages Table</strong></summary>

| Package / Tool | Purpose | Required? |
|----------------|---------|-----------|
| `aiohttp` | Async HTTP client for downloads and API calls | **Yes** |
| `aiofiles` | Async file I/O for writing download chunks | **Yes** |
| `rich` | Terminal UI — progress bars, tables, panels, color | **Yes** |
| `pydantic` | Config validation and schema enforcement | **Yes** |
| `packaging` | Version string parsing for update comparison | **Yes** |
| `textual` | Full-screen Terminal User Interfaces (TUIs) | **Yes** |
| `typer` | Robust and strictly typed CLI subcommands | **Yes** |
| `loguru` | Enterprise-grade background logging | **Yes** |
| `aiohttp_socks` | SOCKS4/5 proxy support | *Optional* |
| `aiodns` | Custom DNS resolver (bypasses ISP-level blocking) | *Optional* |
| `mutagen` | Audio metadata tagging (MP3, FLAC, OGG) | *Optional* |
| `requests` | Synchronous GitHub update check | *Optional* |
| `pygame-ce` | Media Player audio playback engine | *Optional* |
| `pillow` | Cover Art Transcoder (WebP/AVIF to JPG) | *Optional* |
| `py7zr` | `.7z` Archive Auto-Extraction | *Optional* |
| `rarfile` | `.rar` Archive Auto-Extraction | *Optional* |
| `rapidfuzz` | Typo-tolerant local database queries | *Optional* |
| `ffmpeg` | **System Tool**: Audio loudness normalization & transcoding | *Optional* |

</details>

---

## <img src="docs/assets/icons/rocket.svg" width="20" align="top"> Installation

### Step 1 — Clone the repository

```bash
git clone https://github.com/takoyune/asmr.one-downloader.git
cd asmr.one-downloader
```

Or download the ZIP directly from GitHub and extract to a folder of your choice.

### Step 2 — Install dependencies

**Option A: Automated (Windows)**

```bat
setup.bat
```

Runs once — creates a virtual environment and installs all dependencies. All future `./asmr` launches use the venv automatically.

**Option B: Manual (Windows / Linux / macOS)**

```bash
# (Optional but recommended) Create a virtual environment
python -m venv venv

# Activate it
# Windows (PowerShell):
.\venv\Scripts\Activate.ps1
# Windows (CMD):
venv\Scripts\activate.bat
# macOS / Linux:
source venv/bin/activate

# Install core dependencies
pip install -r requirements.txt

# (Optional) Install advanced features (Audio tagging, Player, Fuzzy search)
pip install -r requirements-optional.txt
```

### Step 3 — Verify the install

```bash
python main.py --version
```

---

## <img src="docs/assets/icons/play.svg" width="20" align="top"> Running the App

### Windows

```powershell
./asmr              # Open interactive menu
./asmr RJ123456     # Download directly
./asmr --help       # All available flags
```

> CMD users: `asmr.bat` works the same way.

### Linux / macOS

```bash
chmod +x asmr       # One-time step after cloning

./asmr              # Open interactive menu
./asmr RJ123456     # Download directly
./asmr --list RJ123456      # Preview file tree
./asmr --dry-run RJ123456   # Simulate a download
./asmr --help               # All available flags
```

---

## <img src="docs/assets/icons/monitor.svg" width="20" align="top"> Usage — Interactive Menu

Launch `./asmr` with no arguments:

```
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃                    ASMR.ONE DOWNLOADER                        ┃
┃                       by Takoyune                             ┃
┃               https://github.com/takoyune                     ┃
┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 📚 Library: 11 works ━┛

[1] Download (Work Codes)
  [2] Batch Download from File
  [3] Search ASMR.ONE Online
  ─────────────────────────
  [4] Library Browser
  [5] Queue Manager
  [6] Settings
  [7] Statistics Dashboard
  [8] System Utilities
  [9] ⭐ Favorites
  [10] 🎵 Media Player
  [11] 📚 Library Tools
  [12] 🎛️ Audio Transcoder & Normalizer
  ─────────────────────────
  [X] Exit
```

#### [1] Download (Work Codes)
Enter one or more work codes (e.g. `RJ123456 VJ01002074`). The app fetches metadata, presents the full file tree, and lets you select specific files by number or range (e.g. `1 3-5 7`). Leave blank to download everything.

#### [2] Batch Download from File
Enter a path to a `.txt` file with one work code (RJ or VJ) per line. Once validated and queued, this will launch the full-screen **Mission Control TUI** to manage the batch download.

#### [3] Search ASMR.ONE Online
Launches the full-screen **Search TUI**, featuring:
- An interactive search bar for Keywords, Tags, CVs, and Circles.
- A scrollable `DataTable` populated with results directly from the ASMR.ONE API.
- Seamless pagination and integration to queue downloads or preview audio natively.

#### [4] Library Browser
Search your local download history by title or circle name. Open work folders, toggle favorites (`[F <code>]`), or play tracks in the built-in media player (`[P <code>]`).

#### [5] Queue Manager
View all items currently in the queue (pending / active / error status). Add new codes, change priority, start processing, or clear items.

#### [6] Settings
Edit all configuration options interactively:
- Output directory, proxy, mirror, max concurrent downloads, bandwidth limits
- **Scheduled Auto-Throttling** — define active time window (e.g., `09:00-18:00`) and limit
- **Segmented Chunk Threshold** — split large files (>50MB) into parallel chunks
- **Archive Extraction** — toggle auto-extract for `.zip`, `.rar`, and `.7z`
- **Language Priorities** — `audio_language_priority` & `tag_language_priority` (`ja-jp`, `en-us`, `zh-cn`)

#### [7] Statistics Dashboard
Overview of your library: total works, total size on disk, queue length, average work size.

#### [8] System Utilities
- **Preflight Diagnostic** — system integrity and dependency check.
- **Database Repair & Optimize** — `PRAGMA integrity_check` & `VACUUM`.
- **Cache Cleaner** — clear `.tmp` chunks and selection states.
- **Network Mirror Test** — ping all API mirrors with global status checks.
- **GitHub Release Notes & Issues** — view latest GitHub releases & open issues.

#### [9] <img src="docs/assets/icons/star.svg" width="20" align="top"> Favorites
Quick access list of your favorited works. Re-queue or manage favorites with simple indices.

#### [10] <img src="docs/assets/icons/music.svg" width="20" align="top"> Media Player
Launches the full-screen **Media Player TUI** powered by `pygame-ce` and `Textual`:
- Visual `Tree` view for managing the current playlist of local tracks or online preview streams.
- Live `ProgressBar` and playback status dashboard.
- Full keyboard controls (`[Space]` Play/Pause, `[N]` Next, `[R]` Auto-Loop, `[+]`/`[-]` Volume).

#### [11] <img src="docs/assets/icons/library.svg" width="20" align="top"> Library Tools
- **Auto-Sync Online Metadata** — update tags, ratings, and CV information for local works
- **Library Health Auditor** — scan disk vs DB to find missing folders, 0-byte tracks, and duplicates
- **Generate Smart Playlist (.m3u)** — filter library by keyword, favorites, or rating to generate `.m3u` playlists
- **Local Storage Auto-Import Scanner** — scan existing directories for RJ folders and register them into DB

#### [12] <img src="docs/assets/icons/sliders.svg" width="20" align="top"> Audio Transcoder & Normalizer
- **Work Folder Transcoding** — batch transcode work directories to MP3/AAC/FLAC/WAV
- **EBU R128 Loudness Normalization** — target loudness normalization (-16 LUFS default)
- **Single Track Transcoding** — quick conversion for individual audio tracks
- **Transcoder Configuration** — toggle auto post-download transcoding and default bitrates

---

## <img src="docs/assets/icons/wrench.svg" width="20" align="top"> Usage — CLI Flags

```bash
Usage: asmr [OPTIONS] COMMAND [ARGS]...
```

**Global Options:**
| Option | Description |
|--------|-------------|
| `--verbose` | Enable verbose (DEBUG) logging |
| `-u, --update` | Check and apply updates from GitHub |
| `--check-code` | Run the automated test suite |
| `-v, --version` | Show version information |
| `--resume` | Resume pending downloads from queue |

**Commands:**
| Command | Description |
|---------|-------------|
| `download` | Download specific ASMR works or a batch from a file (`-b`) |
| `search` | Search ASMR.ONE online for works (`--tag`, `--va`, `--circle`) |
| `player` | Launch Media Player TUI for a work code or folder path |
| `export` | Export the library to a CSV or JSON file |
| `test` | Test all API mirrors and display detailed latency |

**Note on `--update`:** This flag downloads the latest GitHub release and extracts it directly over your current installation directory. Your `config.json`, `history.db`, and `singularity.log` files are preserved. It is highly recommended to close any other running instances of the app before starting a self-update to avoid file lock issues.

### CLI Examples

```bash
# Download a work directly
./asmr download RJ01234567

# Batch download from a text file
./asmr download -b queue.txt

# Launch the Media Player TUI for a specific work
./asmr player RJ01234567
./asmr player "/path/to/ASMR_Folder"

# Search online by tag or Voice Actor
./asmr search --tag "耳かき 睡眠"
./asmr search --va "本渡楓"

# Export local library to CSV
./asmr export library.csv

# Run automated system integrity verification
./asmr --check-code
```

---

## <img src="docs/assets/icons/settings.svg" width="20" align="top"> Configuration

`config.json` is created automatically on first launch. Edit it directly or through **[6] Settings** in the interactive menu.

```json
{
    "output_dir": "Downloads",
    "max_concurrent": 3,
    "proxy": null,
    "mirror": "https://api.asmr-200.com",
    "tag_audio": true,
    "sort_files": false,
    "dir_template": "{rj_id} {title}",
    "timeout": 60,
    "dns": "1.1.1.1",
    "bandwidth_limit_mbps": 0.0,
    "create_playlist": true,
    "audio_language_priority": ["ja-jp", "en-us", "zh-cn"],
    "tag_language_priority": ["en-us"],
    "format_priority": ["flac", "wav", "mp3", "m4a", "ogg"],
    "segmented_download_threshold_mb": 50,
    "segmented_download_chunks": 4,
    "auto_extract_archives": true,
    "throttle_enabled": false,
    "throttle_active_hours": "09:00-18:00",
    "throttle_limit_mbps": 2.0,
    "auto_transcode_enabled": false,
    "transcode_format": "mp3",
    "transcode_bitrate": "320k",
    "normalize_loudness": true,
    "target_lufs": -16.0,
    "delete_original_after_transcode": false,
    "last_update_check": 0.0
}
```

<details>
<summary><b><img src="docs/assets/icons/settings.svg" width="20" align="top"> Complete Configuration Key Reference (Click to Expand / Collapse)</b></summary>

<br>

| Key | Default | Description |
|-----|---------|-------------|
| <img src="docs/assets/icons/folder.svg" width="20" align="top"> `output_dir` | `"Downloads"` | Where downloaded works are saved |
| <img src="docs/assets/icons/zap.svg" width="20" align="top"> `max_concurrent` | `3` | Parallel file downloads (1–20) |
| <img src="docs/assets/icons/globe.svg" width="20" align="top"> `proxy` | `null` | HTTP or SOCKS5 proxy URL. Note: SOCKS proxies require `aiohttp_socks` (installed automatically via `requirements.txt`) |
| <img src="docs/assets/icons/link.svg" width="20" align="top"> `mirror` | auto | API mirror URL — set automatically on startup |
| <img src="docs/assets/icons/music.svg" width="20" align="top"> `tag_audio` | `true` | Write metadata tags to MP3 / FLAC / OGG |
| <img src="docs/assets/icons/folder-open.svg" width="20" align="top"> `sort_files` | `false` | Organize into `Audio/`, `Images/`, `Text/` subfolders |
| <img src="docs/assets/icons/tag.svg" width="20" align="top"> `dir_template` | `"{rj_id} {title}"` | Folder name template |
| <img src="docs/assets/icons/clock.svg" width="20" align="top"> `timeout` | `60` | HTTP request timeout in seconds |
| <img src="docs/assets/icons/shield.svg" width="20" align="top"> `dns` | `"1.1.1.1"` | DNS server — use `1.1.1.1` or `8.8.8.8` to bypass ISP blocks |
| <img src="docs/assets/icons/signal.svg" width="20" align="top"> `bandwidth_limit_mbps` | `0.0` | Global speed cap in MB/s — `0` = unlimited |
| <img src="docs/assets/icons/music.svg" width="20" align="top"> `create_playlist` | `true` | Generate `.m3u` playlist file after download |
| <img src="docs/assets/icons/globe.svg" width="20" align="top"> `audio_language_priority` | `["ja-jp","en-us","zh-cn"]` | Preferred language for audio editions |
| <img src="docs/assets/icons/tag.svg" width="20" align="top"> `tag_language_priority` | `["en-us"]` | Language to display tags in search results |
| <img src="docs/assets/icons/sliders.svg" width="20" align="top"> `format_priority` | `["flac","wav","mp3",…]` | Preferred format when a track has multiple versions |
| <img src="docs/assets/icons/puzzle.svg" width="20" align="top"> `segmented_download_threshold_mb` | `50` | File size threshold (MB) to trigger multi-threaded chunk downloads |
| <img src="docs/assets/icons/zap.svg" width="20" align="top"> `segmented_download_chunks` | `4` | Number of parallel chunk connections for segmented downloading |
| <img src="docs/assets/icons/package.svg" width="20" align="top"> `auto_extract_archives` | `true` | Auto-extract `.zip`, `.rar`, and `.7z` archives post-download |
| <img src="docs/assets/icons/clock.svg" width="20" align="top"> `throttle_enabled` | `false` | Enable schedule-based active hours bandwidth throttling |
| <img src="docs/assets/icons/clock.svg" width="20" align="top"> `throttle_active_hours` | `"09:00-18:00"` | Active time window (HH:MM-HH:MM) for speed throttling |
| <img src="docs/assets/icons/trending-down.svg" width="20" align="top"> `throttle_limit_mbps` | `2.0` | Speed cap in MB/s during active throttle hours |
| <img src="docs/assets/icons/sliders.svg" width="20" align="top"> `auto_transcode_enabled` | `false` | Automatically transcode lossless audio post-download |
| <img src="docs/assets/icons/music.svg" width="20" align="top"> `transcode_format` | `"mp3"` | Target format for audio transcoder (`mp3`, `aac`, `flac`, `wav`) |
| <img src="docs/assets/icons/sliders.svg" width="20" align="top"> `transcode_bitrate` | `"320k"` | Target bitrate for lossy audio transcoding |
| <img src="docs/assets/icons/volume-2.svg" width="20" align="top"> `normalize_loudness` | `true` | Enable EBU R128 loudness normalization |
| <img src="docs/assets/icons/target.svg" width="20" align="top"> `target_lufs` | `-16.0` | Target LUFS for loudness normalization |
| <img src="docs/assets/icons/trash-2.svg" width="20" align="top"> `delete_original_after_transcode` | `false` | Remove original WAV/FLAC files after successful transcode |
| <img src="docs/assets/icons/clock.svg" width="20" align="top"> `last_update_check` | `0.0` | Auto-managed — timestamp of last GitHub update check |

</details>

### `dir_template` Examples

| Template | Result folder name |
|----------|--------------------|
| `"{rj_id} {title}"` | `RJ01234567 Some Work Title` |
| `"{circle} - {title}"` | `SomeCircle - Some Work Title` |
| `"{year}/{circle}/{title}"` | `2024/SomeCircle/Some Work Title` |

### Language Priority Values

| Value | Language |
|-------|----------|
| `ja-jp` | Japanese |
| `en-us` | English |
| `zh-cn` | Chinese (Simplified) |

---

## <img src="docs/assets/icons/archive.svg" width="20" align="top"> Data & Files

The application maintains several stateful files in its root directory. Before a self-update or major version jump, it is good practice to back up `config.json` and `history.db`.

- `config.json` — User settings (see [Configuration](#️-configuration)).
- `history.db` — The SQLite library database tracking your download history, queue, favorites, and search history. This is a standard SQLite file that can be inspected or backed up directly. The app also has a repair tool for it (see **Database Repair & Optimize** under [System Utilities](#8-system-utilities)).
- `singularity.log` — The application log file. By default, it logs INFO, WARNING, and ERROR. Using the `--verbose` flag adds DEBUG output (see [Troubleshooting](#-troubleshooting)).

---

## <img src="docs/assets/icons/folder.svg" width="20" align="top"> Project Structure

```
asmr.one-downloader/
│
├── main.py                    # Main CLI entry point
├── asmr                       # Linux/macOS script launcher
├── asmr.bat                   # Windows CMD launcher
├── asmr.ps1                   # Windows PowerShell launcher
├── setup.bat                  # Dependency installer script
├── verify.py                  # System integrity test suite
├── requirements.txt           # Python package requirements
├── config.json                # User settings configuration
├── history.db                 # SQLite database & queue
├── singularity.log            # Application runtime log
│
└── main/
    ├── app.py                 # UI & interactive menus
    ├── orchestrator.py        # Core download engine
    ├── network.py             # HTTP client & DNS resolver
    ├── db.py                  # SQLite database manager
    ├── config.py              # Configuration manager
    ├── models.py              # Data structures & models
    ├── player.py              # Audio playback backend
    ├── library.py             # Library audit & sync tools
    ├── audio.py               # Audio & LRC metadata tagger
    ├── constants.py           # System constants & mirrors
    ├── tui/                   # Textual Terminal UIs
    │   ├── __init__.py
    │   ├── mission_control.py # Batch processing dashboard
    │   ├── search_app.py      # Interactive online search TUI
    │   └── player_app.py      # Media Player visual interface
    └── transcoder/
        ├── __init__.py        # Transcoder package init
        ├── ffmpeg_engine.py   # FFmpeg wrapper & R128 engine
        └── processor.py       # Audio & cover art transcoder
```

---

## <img src="docs/assets/icons/help-circle.svg" width="20" align="top"> FAQ / Known Limitations

- **Region Blocking**: ASMR.ONE actively blocks connections outside East Asia. If you encounter connection timeouts or mirror test failures, you must use a proxy or a VPN (Cloudflare WARP is recommended).
- **Resume Support Limits**: The resume functionality relies on HTTP `Range` requests supported by the ASMR.ONE servers. While robust, if a file chunk becomes corrupted locally, it will automatically restart that segment.
- **Format Deduplication**: When downloading a work with multiple audio formats (e.g., both WAV and MP3), the downloader will automatically skip the lower-priority format based on your `format_priority` configuration to save disk space and bandwidth.

---

## <img src="docs/assets/icons/search.svg" width="20" align="top"> Troubleshooting

### "All API mirrors are unreachable" or Connection Errors
**ASMR.ONE is actively region-blocked outside of East Asia (Japan, China, etc.).**
If the startup mirror test fails, your connection is being blocked. Use **Cloudflare WARP**:

1. Download from [https://one.one.one.one/](https://one.one.one.one/)
2. Open WARP settings → choose **Traffic and DNS (UDP)**
3. Turn on the connection and restart the downloader.

Or set the `proxy` field in `config.json` (e.g. `"http://user:pass@ip:port"`).

### FFmpeg Engine & Loudness Normalization Issues
- **System FFmpeg required**: EBU R128 loudness normalization and audio transcoding require `ffmpeg` to be installed and available in your system `PATH`.
- **Windows**: Install via `winget install FFmpeg` or download from [ffmpeg.org](https://ffmpeg.org/download.html) and add `bin` to PATH.
- **Linux**: Install via `sudo apt install ffmpeg` or `sudo dnf install ffmpeg`.
- **macOS**: Install via `brew install ffmpeg`.

### Media Player TUI & Audio Output (`pygame-ce`)
- If the Media Player TUI fails to play audio, verify that your system audio output device is active and not muted.
- `pygame-ce` automatically initializes the default audio mixer. If no audio device is detected, the Media Player TUI will print a warning message.

### Archive Extraction (.rar, .7z) Support
- `.zip` extraction works out-of-the-box using Python standard libraries.
- `.7z` and `.rar` auto-extraction require the `py7zr` and `rarfile` packages (installed via `pip install -r requirements.txt`). For `.rar` archives, `unrar` or `bsdtar` must be present on your system.

### Downloads hang or time out repeatedly
- Increase `timeout` in `config.json` (e.g. `120`)
- Reduce `max_concurrent` to `1` or `2`
- Try a different DNS or enable a proxy

### Tags appear in the wrong language
Set `tag_language_priority` in `config.json` to your preferred language:
```json
"tag_language_priority": ["en-us"]          // English only
"tag_language_priority": ["ja-jp", "en-us"] // Japanese, fallback to English
```

### Progress bar starts at wrong percentage on resume
This is a known visual issue. The download is still resuming correctly from the correct byte offset — the visual corrects itself as data flows in.

### `singularity.log` is too noisy
By default, only `INFO`, `WARNING`, and `ERROR` messages are logged. The `--verbose` flag adds `DEBUG` output (every HTTP request, byte offsets, retry attempts). Only use `--verbose` when actively debugging.

### "Fatal error" on startup with a cryptic message
Check `singularity.log` in the project root for the full traceback, or run `./asmr --check-code` to execute the automated test suite.

---

## <img src="docs/assets/icons/handshake.svg" width="20" align="top"> Contributing

We welcome issues and pull requests!

- Please check the Issue Templates to submit a Bug Report (`bug_report.yml`) or a Feature Request (`feature_request.yml`).
- Pull requests should follow the existing PR template.
- Before submitting a PR, ensure that the automated integrity suite passes locally by running:

```bash
  python verify.py
  ```

---

## <img src="docs/assets/icons/alert-triangle.svg" width="20" align="top"> Disclaimer

- This tool is intended for personal use and for accessing content the user has legitimately obtained access to.
- Users are responsible for complying with ASMR.ONE's terms of service and applicable law in their jurisdiction.
- The project is not affiliated with ASMR.ONE or the circles/creators whose works are indexed there.
- Redistribution of downloaded paid content is discouraged. The tool should not be used to circumvent purchases.

---

## <img src="docs/assets/icons/heart.svg" width="20" align="top"> Acknowledgments

- **[ASMR.ONE](https://asmr.one/)** — the platform this tool interacts with.
- **[FFmpeg](https://ffmpeg.org/)** — for audio transcoding and EBU R128 normalization.
- Key third-party Python libraries: `rich`, `pygame-ce`, `mutagen`, `py7zr`, `rarfile`, `aiohttp`.

---

## <img src="docs/assets/icons/file-text.svg" width="20" align="top"> License

MIT License — see [LICENSE](LICENSE) for details.

*Created by [Takoyune](https://github.com/takoyune)*

asmr.one-downloader

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README