douyin-downloader

Product Introduction

1. Definition: The Douyin Downloader is an open-source, Python-based command-line tool and desktop application backend designed for the programmatic downloading and archival of content from the Chinese short-video platform Douyin (TikTok). It functions as a media scraper and batch downloader.
2. Core Value Proposition: This tool exists to solve the problem of efficiently saving Douyin content at scale for personal archiving, research, or content analysis, bypassing platform restrictions by supporting batch operations, watermark removal, and structured metadata preservation.

Main Features

1. Multi-Source Batch Downloading: The downloader supports batch downloading from user profiles (/user/{sec_uid}), individual collections (/collection/{mix_id}), and personal favorites. It operates in distinct modes (post, like, mix, music, collect, collectmix) to target specific content types, using concurrent threading (configurable, default 5) for efficiency. It parses short links (v.douyin.com) and utilizes Douyin's internal APIs to fetch media URLs.
2. Watermark Removal & High-Quality Media Fetching: The tool automatically selects the watermark-free video source when available. For videos, it parses the video.bit_rate ladder to select the highest bitrate stream. For photo sets (image-notes), it downloads all original images. It also extracts and saves original audio tracks separately as MP3 files.
3. Robust Download Management with SQLite Deduplication: It implements a dual-layer skip logic. First, it checks for existing local files by scanning for aweme_id in filenames. Second, it records all successful downloads in a SQLite database (dy_downloader.db) with metadata (aweme_id, title, author, timestamp). This prevents duplicate downloads across different modes (e.g., the same video from post and like queues) within the same session.
4. Browser Fallback for Pagination Limits: To circumvent Douyin's anti-scraping measures that often limit API pagination to ~20 items, the tool integrates a Playwright-based browser automation fallback. When triggered, it launches a Chromium browser (headless or headed) to simulate user scrolling, manually solve CAPTCHAs if presented, and extract item data directly from the rendered page, enabling full-profile crawls.
5. Extended Functionality Suite: The tool includes several auxiliary features: live stream recording (experimental, saves FLV/HLS streams), comment collection (saves per-video comments as JSON), hot search board dumping, keyword search, an optional REST API server (FastAPI), and post-download video transcription using the OpenAI Whisper API.

Problems Solved

1. Pain Point: The inability to efficiently archive large volumes of Douyin content (videos, photo sets, audio) due to manual, one-by-one saving, platform download restrictions, and persistent watermarks.
2. Target Audience: Digital archivists, social media researchers, content analysts, journalists needing to preserve evidence, and power users who wish to maintain a personal offline library of their favorite Douyin creators or curated collections.
3. Use Cases: A researcher compiling a dataset of viral trends needs to download the top 500 videos from a trending hashtag. An archivist wants to preserve the complete video history of a cultural commentator's Douyin profile. A user wishes to save all videos from their private "liked" list before deleting their account.

Unique Advantages

1. Differentiation: Unlike simple online "Douyin video downloader" websites, this is a self-hosted, programmable tool offering batch operations, metadata preservation, and no item limits. Compared to other CLI downloaders, it uniquely combines browser fallback for reliability, SQLite for cross-session state management, and a comprehensive feature set (collections, music, comments, transcription) in one package.
2. Key Innovation: Its hybrid download strategy is key. It primarily uses efficient direct API calls for speed but seamlessly falls back to browser automation when blocked, ensuring robustness against platform changes. The increase configuration allows for intelligent, disk-based incremental updates, and the modular design allows features like the transcription engine to be plugged in post-download.

Frequently Asked Questions (FAQ)

1. How do I fix the Douyin Downloader only getting 20 videos? This is caused by Douyin's pagination limit. Enable browser_fallback in config.yml, set headless: false, and manually complete any verification (like a CAPTCHA) in the launched browser window to allow the tool to scroll and collect all items.
2. Does the Douyin Downloader keep watermarks on videos? No, a core feature is watermark removal. The tool preferentially fetches the original, watermark-free video stream from Douyin's CDN when it is available through the API.
3. Can I use this TikTok downloader for YouTube or Instagram? No, this tool is specifically engineered for the Douyin (Chinese TikTok) platform. Its logic, API calls, and parsing are tailored to Douyin's infrastructure. The related desktop app "Douzy" has separate workspaces for TikTok and YouTube.
4. Is it legal to use a Douyin video downloader? The tool is for personal, educational, and research purposes under fair use principles. Users are solely responsible for complying with copyright law, Douyin's Terms of Service, and respecting creators' rights. The disclaimer explicitly states it must not be used for infringement.
5. How do I re-download a specific video I already have? The tool skips downloads if the file exists. To force re-download, you must delete the local file folder (e.g., Downloaded/AuthorName/post/*_<aweme_id>/) and optionally remove its record from the SQLite database: sqlite3 dy_downloader.db "DELETE FROM aweme WHERE aweme_id = '<aweme_id>';".