🎙️ ASMR.ONE Downloader

English • 日本語 • 简体中文 • 繁體中文 • 한국어

Preview	What's New	Previous Updates
Features	Requirements	Installation
Running the App	Interactive Menu	CLI Flags
Configuration	Data & Files	Project Structure
FAQ / Known Limitations	Troubleshooting	Contributing
Disclaimer	Acknowledgments	License

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.

• 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.

• 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.

• 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.

• 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.

• 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).

• --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.

• 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.

• Python 3.10 or higher — python.org
• 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

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.

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.

Option A: Automated (Windows)

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)

# (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

python main.py --version

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

CMD users: asmr.bat works the same way.

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

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

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.

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.

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.

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>]).

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

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)

Overview of your library: total works, total size on disk, queue length, average work size.

• 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.

Quick access list of your favorited works. Re-queue or manage favorites with simple indices.

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).

• 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

• 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

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

Global Options:

Commands:

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.

# 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

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

{
    "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
}

Complete Configuration Key Reference (Click to Expand / Collapse)

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

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).
• 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).
• singularity.log — The application log file. By default, it logs INFO, WARNING, and ERROR. Using the --verbose flag adds DEBUG output (see Troubleshooting).

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

• 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.

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/
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").

• 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 and add bin to PATH.
• Linux: Install via sudo apt install ffmpeg or sudo dnf install ffmpeg.
• macOS: Install via brew install ffmpeg.

• 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.

• .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.

• Increase timeout in config.json (e.g. 120)
• Reduce max_concurrent to 1 or 2
• Try a different DNS or enable a proxy

Set tag_language_priority in config.json to your preferred language:

"tag_language_priority": ["en-us"]          // English only
"tag_language_priority": ["ja-jp", "en-us"] // Japanese, fallback to English

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.

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.

Check singularity.log in the project root for the full traceback, or run ./asmr --check-code to execute the automated test suite.

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:

  python verify.py

• 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.

• ASMR.ONE — the platform this tool interacts with.
• FFmpeg — for audio transcoding and EBU R128 normalization.
• Key third-party Python libraries: rich, pygame-ce, mutagen, py7zr, rarfile, aiohttp.

MIT License — see LICENSE for details.

Created by Takoyune