douyin-downloader

# Douyin Downloader V2.0

中文文档 (Chinese): [README.zh-CN.md](./README.zh-CN.md) A practical Douyin downloader supporting videos, image-notes, collections, music, favorites collections, and profile batch downloads, with progress display, retries, SQLite deduplication, download integrity checks, and browser fallback support. ## Desktop App (Douzy) A desktop GUI built on the same backend, with dedicated workspaces for Douyin, TikTok, and YouTube. Paste a link to start, sync account content, follow every task, and manage downloaded works in a local archive. - **Three platforms:** Douyin videos, galleries, profiles, and collections; TikTok videos, photos, and profiles; YouTube videos, Shorts, channels, and playlists - **Account content:** sync Douyin following, favorites collections, collected series, and likes - **Visual workflow:** multi-link queue, task status and retry controls, local download archive, filters, and quick re-download > **Beta:** The desktop app is currently in closed beta. To try it, download the build from the [Releases](https://github.com/jiji262/douyin-downloader/releases) page. | **Douyin link download** | **TikTok download workspace** | **YouTube workbench** | |:---:|:---:|:---:| | | | | | Paste a video, gallery, profile, or collection link and start in one click. | Download public videos, photo posts, and profiles without signing in. | Scan videos, Shorts, channels, and playlists, then configure video, MP3, or subtitle downloads. | | **Following management** | **Favorites and likes** | **Task Center** | | | | | | Sync creators, filter new works, add notes, and download directly from the list. | Browse collected videos, series, and liked works from the current Douyin account. | Track job results, retry failures, and open output folders. | _Screenshots were captured from the current desktop `main` build. Demonstration data is used for privacy._ ## Feature Overview > **⚠️ Douyin's anti-bot gate blocks the CLI from downloading likes / favorites / favorite collections (since 2026-08) and single videos / notes, collections and music (since 2026-09); profile posts can only rely on the browser fallback.** See [Current Limitations](#current-limitations) for the cause and what still works; use the Douzy desktop app for these downloads. ### Supported | Feature | Description | |---------|-------------| | Single video download | `/video/{aweme_id}` | | Single image-note download | `/note/{note_id}` and `/gallery/{note_id}` | | Single collection download | `/collection/{mix_id}` and `/mix/{mix_id}` | | Single music download | `/music/{music_id}` (prefers direct audio, fallback to first related aweme) | | Short link parsing | `https://v.douyin.com/...`, `v.iesdouyin.com`, bare hosts | | Profile batch download | `/user/{sec_uid}` + `mode: [post, like, mix, music]` | | Logged-in favorites collections | `/user/self?showTab=favorite_collection` + `mode: [collect, collectmix]` | | No-watermark preferred | Automatically selects watermark-free video source | | Highest-quality selection | Auto-picks highest bitrate from `video.bit_rate` ladder (video + live-photo) | | **Live stream recording** | `live.douyin.com/{room_id}` → FLV/HLS, preserves partial data on stream end | | **Comments collection** | Per-aweme comments (+ optional replies) saved as `*_comments.json` | | **Hot search + keyword search** | `--hot-board [N]` / `--search "keyword"` dumps to JSONL | | **REST API server mode** | `--serve --serve-port 8000` (optional `fastapi + uvicorn`) | | **Notification push** | Bark / Telegram / Webhook on download completion | | Extra assets | Cover, music, avatar, JSON metadata | | Video transcription | Optional, using OpenAI Transcriptions API | | Concurrent downloads | Configurable concurrency, default 5 | | Retry with backoff | Exponential backoff (1s, 2s, 5s) | | Rate limiting | Default 2 req/s | | SQLite history | Records download metadata; does not decide incremental skips | | Incremental downloads | Disk-based skip/redownload via `increase.post/like/mix/music` | | Time filters | `start_time` / `end_time` | | Browser fallback | Launches browser when pagination is blocked, manual CAPTCHA supported | | Download integrity check | Content-Length validation, auto-cleanup of incomplete files | | Progress display | Rich progress bars, supports `progress.quiet_logs` quiet mode | | Docker deployment | Dockerfile included | | CI/CD | GitHub Actions for testing and linting | ### Current Limitations - **Douyin Argus gate:** Douyin's edge `ArgusSecurityPlugin` answers every non-browser request to these endpoints with HTTP 403 `Blocked by ArgusSecurityPlugin Uifid Not Found`, with or without cookies and no matter how often you retry: - since 2026-08: `aweme/favorite`, `collects/*`, `aweme/listcollection`, `mix/listcollection` (likes / favorites / favorite collections) - since 2026-09-10: `mix/aweme` (collection items) - since 2026-09-14: `aweme/detail` (single video / note), `aweme/post` (profile posts), `mix/detail`, `mix/list`, `music/detail`, `music/aweme`, `music/list` The required `x-secsdk-web-signature` can only be produced by the SDK inside a real Douyin web page, which the CLI's direct API requests cannot carry, so single videos / notes, collections, music and likes / favorites **cannot be downloaded** in the CLI. Profile-post (`post`) API paging is rejected as well; with `playwright` installed and `browser_fallback` left on (headed by default), the browser fallback reads the page's own post-list requests and may still work, but it has not been tested against this gate. The Douzy desktop app sends these requests through its built-in login window and is not affected. Endpoints still reachable directly as of 2026-09-14: user profile, following list, comments, live rooms (webcast), hot board and search. - Browser fallback is fully validated for `post`; `like/mix/music` currently relies on API pagination - `number.allmix` / `increase.allmix` are retained as compatibility aliases and normalized to `mix` - `collect` / `collectmix` currently work for the account represented by the logged-in cookies only - `collect` / `collectmix` must be used alone and cannot be combined with `post` / `like` / `mix` / `music` - `increase` currently applies to `post` / `like` / `mix` / `music`; favorites collection modes do not support incremental stop - Live stream recording saves FLV natively; HLS sources only save the playlist (use ffmpeg for playable output) - The webcast room endpoint is not verified against every live scenario — treat as experimental ## Quick Start ### 1) Requirements - Python 3.8+ - macOS / Linux / Windows ### 2) Install dependencies ```bash pip install -r requirements.txt ``` For browser fallback and automatic cookie capture: ```bash pip install playwright python -m playwright install chromium ``` ### 3) Copy config file ```bash cp config.example.yml config.yml ``` ### 4) Get cookies (recommended: automatic) ```bash python -m tools.cookie_fetcher --config config.yml ``` After logging into Douyin, return to the terminal and press Enter. Cookies will be written to your config automatically. ### 5) Docker deployment (optional) ```bash docker build -t douyin-downloader . docker run -v $(pwd)/config.yml:/app/config.yml -v $(pwd)/Downloaded:/app/Downloaded douyin-downloader ``` ## Minimal Working Config ``` … ``` ## Usage ### Run with a config file ```bash python run.py -c config.yml ``` ### Append CLI arguments ```bash python run.py -c config.yml \ -u "https://www.douyin.com/video/7604129988555574538" \ -t 8 \ -p ./Downloaded ``` ### Arguments | Argument | Description | |----------|-------------| | `-u, --url` | Append download link(s), can be repeated | | `-c, --config` | Specify config file (default: `config.yml`) | | `-p, --path` | Specify download directory | | `-t, --thread` | Specify concurrency | | `--show-warnings` | Show warning/error logs | | `-v, --verbose` | Show info/warning/error logs | | `--hot-board [N]` | Fetch Douyin hot search board and write JSONL; optional top-N | | `--search KEYWORD` | Search videos by keyword, write JSONL | | `--search-max N` | Max items for `--search` (default 50) | | `--serve` | Run as REST API server (requires `pip install fastapi uvicorn`) | | `--serve-host HOST` | REST server listen host (default 127.0.0.1) | | `--serve-port PORT` | REST server listen port (default 8000) | | `--version` | Show version number | ## Typical Scenarios ### Download one video ```yaml link: - https://www.douyin.com/video/7604129988555574538 ``` ### Download one image-note ```yaml link: - https://www.douyin.com/note/7341234567890123456 ``` ### Download a collection ```yaml link: - https://www.douyin.com/collection/7341234567890123456 ``` ### Download a music track ```yaml link: - https://www.douyin.com/music/7341234567890123456 ``` ### Batch download a creator's posts ```yaml link: - https://www.douyin.com/user/MS4wLjABAAAAxxxx mode: - post number: post: 50 ``` ### Batch download a creator's liked posts ```yaml link: - https://www.douyin.com/user/MS4wLjABAAAAxxxx mode: - like number: like: 0 # 0 means download all ``` ### Download multiple modes at once ```yaml link: - https://www.douyin.com/user/MS4wLjABAAAAxxxx mode: - post - like - mix - music ``` Cross-mode deduplication: the same aweme_id won't be downloaded twice across different modes. ### Download logged-in favorites collection items ```yaml link: - https://www.douyin.com/user/self?showTab=favorite_collection mode: - collect number: collect: 0 ``` ### Download logged-in collected mixes ```yaml link: - https://www.douyin.com/user/self?showTab=favorite_collection mode: - collectmix number: collectmix: 0 ``` ### Record a live stream (experimental) ```yaml link: - https://live.douyin.com/123456789 # or /follow/live/{room_id} live: max_duration_seconds: 3600 # 0 = record until broadcaster ends chunk_size: 65536 idle_timeout_seconds: 30 ``` The recorder saves an FLV file under `Downloaded/{author}/live/` plus a `*_room.json` metadata snapshot. If the broadcaster ends the stream, network goes idle, or you Ctrl+C, any already-recorded bytes are preserved (the `.tmp` file is promoted to the final file). ### Collect comments per aweme ```yaml comments: enabled: true include_replies: false # true will fetch each comment's second-level replies (extra API calls) max_comments: 500 # 0 = no cap page_size: 20 ``` Generates a `{date}_{title}_{aweme_id}_comments.json` next to the media file. ### Dump the hot search board ```bash python run.py --hot-board 30 -p ./Downloaded # Output: ./Downloaded/hot_board/20260424_221530.jsonl ``` ### Search by keyword ```bash python run.py --search "猫咪" --search-max 100 -p ./Downloaded # Output: ./Downloaded/search/猫咪_20260424_221530.jsonl ``` ### Run as REST API server ```bash pip install fastapi uvicorn # one-time optional dep python run.py --serve --serve-port 8000 ``` Endpoints: | Method | Path | Description | |--------|------|-------------| | POST | `/api/v1/download` | Submit `{"url": "..."}`, returns `{job_id, status}` | | GET | `/api/v1/jobs/{job_id}` | Get a specific job's status/counts | | GET | `/api/v1/jobs` | List recent jobs (TTL + capacity capped) | | GET | `/api/v1/health` | Health probe | Finished jobs are pruned by TTL (default 24h) and max-jobs (default 500) — in-flight jobs are never pruned. Configure via `server.max_jobs` / `server.job_ttl_seconds`. ### Send a notification on completion ```yaml notifications: enabled: true on_success: true on_failure: true providers: - type: bark url: https://api.day.app/YOUR_DEVICE_KEY sound: bell - type: telegram bot_token: "123456:ABC..." chat_id: "987654321" - type: webhook