asmr-tg-backup

English documentation · 简体中文文档 · Telegram showcase

asmr-tg-backup is an extensible background service for discovering ASMR media, archiving it with yt-dlp, and optionally delivering the archived files to Telegram. The core includes YouTube channel uploads plus Twitch VOD and live recording; optional packages can add source providers and scoped network routing without taking over durable job state.

Highlights

• One long-running process with SQLite-backed discovery, download, delivery, and Telegram control-panel state.
• Direct MTProto media upload is the default for official PyPI and GHCR releases; no separate Telegram Bot API server is required.
• Twitch channels can download published VODs or begin recording while a stream is live.
• A typed extension host can add source providers or task-scoped connection routing; extensions are installed and enabled explicitly.
• Downloads and Telegram delivery are independent jobs, so an upload failure does not discard or repeat a completed download.
• The optional Telegram panel manages sources, filters, status, and tracked local resources, with source changes persisted in an editable TOML catalog.
• Opt-in channel reaction tracking persists totals, pins reacted deliveries, and adds total/personal favorite rankings with message links to the panel.

Quick start with PyPI

Native installations require Python 3.11 or newer. Install ffmpeg and ffprobe for the default audio workflow and Twitch live recording. curl is required only when the media transport is Bot API.

The recommended install includes cryptg for faster large-file encryption:

pipx install "asmr-tg-backup[performance]"
asmr-tg-backup --version
asmr-tg-backup setup
asmr-tg-backup service install

The guided setup defaults to MTProto and asks for:

1. a BotFather token;
2. the destination chat ID or @channel;
3. the Telegram user ID allowed to open the control panel.

Quick links: create the bot with BotFather · find your numeric user ID

This is a bot login, not a personal Telegram user login. The first actual MTProto delivery signs the bot in non-interactively with its token and creates a reusable local session.

The service command generates a unit for the current pipx/virtualenv path, starts it, and enables boot-time user services. Remove only that unit later with:

asmr-tg-backup service uninstall

Send /panel to the bot after the service starts. The panel is the recommended way to add the first YouTube or Twitch source and change the source filter. After the service loads a source extension, send a new /panel or refresh the current active panel to show its provider button, such as ➕ Niconico.

For a persistent native service, continue with the systemd user-service guide.

Quick start with Docker Compose

Clone or download the repository, then use its Compose files with the official GHCR image and persistent asmr-data volume:

git clone https://github.com/dreaifekks/asmr-tg-backup.git
cd asmr-tg-backup
cp .env.example .env
cp config.example.toml config.toml
mkdir -p settings
cp sources.example.toml settings/sources.toml
chmod 700 settings
chmod 600 .env config.toml settings/sources.toml
id -u
id -g

Set PUID and PGID in .env to the two printed values, then set the bot token and destination. Enable Telegram delivery in config.toml and start the application:

docker compose pull asmr-tg-backup
docker compose up -d asmr-tg-backup
docker compose logs --tail=100 asmr-tg-backup

The example sources are disabled. Send /panel to add or enable a source after the service starts.

See the Docker Compose guide for UID/GID handling, derived extension images, source builds, upgrades, and the optional local Bot API profile.

Sources: panel first, file when needed

Send /panel to add, enable, disable, or remove a source, switch Twitch mode, and change the global source filter. The same bot accepts /origin rename and /origin history for renaming and backfill requests. These changes are written atomically to sources.toml; SQLite holds only the synchronized runtime mirror plus cursors, jobs, and history. config.toml is reserved for global runtime settings.

For batch changes or complete field control, edit the same catalog:

version = 1
source_filter = "ASMR"

[[origins]]
id = "youtube-example"
provider = "youtube"
kind = "uploads"
name = "Example channel"
external_id = "UC_CHANNEL_ID"
bootstrap = "latest"
enabled = true

bootstrap = "latest" starts with the newest matching item. Use "all" for a history backfill. Validate and apply manual edits with:

asmr-tg-backup sources validate \
  --config ~/.config/asmr-tg-backup/config.toml
asmr-tg-backup sources apply \
  --config ~/.config/asmr-tg-backup/config.toml

On an upgrade, legacy [[origins]], [[channels]], or [[feeds]] declarations are used only to create a missing sources.toml. Once the catalog exists they are ignored with a startup warning, so review the migrated catalog and remove the old declarations instead of maintaining two copies.

Twitch sources require a Client ID plus a Client Secret or app access token. See Sources and downloads for the Twitch developer-console link, vod/live behavior, credentials, and download profiles.

Optional extensions

Extensions are ordinary Python packages discovered from the same environment as the core. For the built-in trusted catalog, one command handles same-environment installation, minimal private setup, enablement, validation, and a safe restart of the matching managed user service:

asmr-tg-backup extensions enable proxy-router
asmr-tg-backup extensions enable niconico-origin

The command keeps config.toml unchanged. Here <config-stem> means the main config filename without its final .toml. It stores managed state in <config-stem>.extensions.toml and private extension settings in extensions/<config-stem>/<filename>. Containers follow the derived-image workflow: install selected packages while building the image, enable their IDs in the mounted config.toml, and mount any private extension config. Advanced and third-party extensions can be installed and configured manually, then checked with extensions list and extensions doctor. Enabled source extensions are also discovered by the Telegram panel: it adds a provider-specific origin button and shows created origins as provider/kind. You decide when to create the source and begin polling by submitting its identifier in the panel.

The first optional repositories using the 0.6 one-command setup layer are:

• asmr-tg-backup-ext-proxy-router: independent routing for notification, discovery, probe, download, Telegram control, Bot API delivery, and MTProto scopes using HTTP/SOCKS endpoints or a Clash-compatible subscription through Mihomo;
• asmr-tg-backup-ext-niconico-origin: public Niconico live-search discovery, with the resulting live probe/download handled by the core.

See the extension guide for installation, configuration, route boundaries, and the API contract.

Telegram delivery

Official packages and images can use the default MTProto path after the local bot token and destination are configured. Source builds need their own complete Telegram application ID/hash pair. In every installation, the bot token and MTProto session stay in the local runtime directories.

Source-build application settings are created from Telegram API development tools.

Bot API can be used with:

• an existing Bot API URL;
• a preinstalled native telegram-bot-api service;
• the optional Compose local-api profile; or
• api.telegram.org with playable audio splitting for its smaller file limit.

Cloud Bot API audio above the configured 49 MB limit can be split into 2–10 independently playable parts. Each part receives a distinct Part i/n title and its own cover. MTProto sends the file directly without splitting.

See Telegram delivery for complete transport configuration.

Telegram control panel

Send /panel or /start to manage sources, inspect status, change the source filter, and browse tracked local resources. Access is configured with allowed user, chat, and topic IDs.

Disk deletion is optional. When enabled, the panel manages downloaded files tracked in SQLite while retaining database history and Telegram messages.

Reaction favorites are also opt-in. Native channel reaction totals drive the ranking and pin state; because channel reactions are anonymous, personal favorites are recorded explicitly through authorized Panel buttons.

See Control panel for configuration and file-management behavior.

Automatic cleanup is configured separately from Panel deletion. New setup configs remove verified live-recording segments one day after merge, even if delivery is blocked. Telegram upload files are removed one day after a successful delivery:

[storage]
process_retention_hours = 24
backup_retention_hours = 0

backup_retention_hours = 0 keeps complete backup files. Set it to a positive number when those files should also expire.

To move complete backup files to mounted storage, set archive_dir to an existing directory. They move 24 hours after delivery by default. Mounted NAS, remote disks, and S3-compatible filesystems can all be used this way.

State and files

Native setup stores runtime configuration below ~/.config/asmr-tg-backup/ and application state below ~/.local/share/asmr-tg-backup/. Docker stores application state in /data and its editable source catalog in ./settings/sources.toml.

One-command extension setup also stores <config-stem>.extensions.toml beside the main config and private settings below extensions/<config-stem>/<filename>. With the default config.toml, these are config.extensions.toml and extensions/config/<filename>.

Before an upgrade, back up the main config, sources.toml, the environment file, managed extension state and private extension settings, the SQLite database, downloads, and the MTProto session. Run only one application process against a given database/session pair.

Keep runtime configuration, bot tokens, Twitch settings, SQLite/WAL files, downloads, and MTProto sessions in the local runtime directories rather than source control.

Architecture and development

The runtime flow is:

Panel / CLI -> sources.toml -> SQLite source runtime mirror
Built-in / extension providers -> provider discovery -> SQLite media and jobs
  -> yt-dlp / ffmpeg artifacts
  -> MTProto or Bot API delivery
  -> Telegram message records

External contributors should start with the bilingual contribution guide and architecture and development guide.

python3 -m venv .venv
.venv/bin/python -m pip install -e ".[docs]"
PYTHONDONTWRITEBYTECODE=1 PYTHONPATH=src \
  .venv/bin/python -m unittest discover -s tests
.venv/bin/mkdocs build --strict

License

Apache License 2.0. See LICENSE.