| 1 | <!-- Parent: ../AGENTS.md --> |
| 2 | <!-- Generated: 2026-03-27 | Updated: 2026-03-27 --> |
| 3 | |
| 4 | # core |
| 5 | |
| 6 | ## Purpose |
| 7 | Core business logic — Douyin API client, URL parsing, download orchestration, and specialized downloaders for videos, users, mixes, and music. Uses factory and strategy patterns for extensibility. |
| 8 | |
| 9 | ## Key Files |
| 10 | |
| 11 | | File | Description | |
| 12 | |------|-------------| |
| 13 | | `__init__.py` | Exports `DouyinAPIClient`, `URLParser`, `DownloaderFactory`, `MixDownloader`, `MusicDownloader` | |
| 14 | | `api_client.py` | Async HTTP client for Douyin API — fetches video details, user posts, mix lists, music | |
| 15 | | `url_parser.py` | Regex-based URL classifier — detects video, user, gallery, collection, music URL types | |
| 16 | | `downloader_base.py` | `BaseDownloader` ABC and `DownloadResult` dataclass — shared download logic | |
| 17 | | `downloader_factory.py` | Factory mapping URL types to downloader classes | |
| 18 | | `video_downloader.py` | Downloads single videos and gallery images (handles both `video` and `gallery` types) | |
| 19 | | `user_downloader.py` | Downloads all content for a user — delegates to mode strategies via registry | |
| 20 | | `mix_downloader.py` | Downloads Douyin "mix" (collection) content | |
| 21 | | `music_downloader.py` | Downloads music-related content | |
| 22 | | `user_mode_registry.py` | Auto-discovers and registers user mode strategies from `user_modes/` | |
| 23 | | `transcript_manager.py` | Manages Whisper transcription for downloaded audio | |
| 24 | |
| 25 | ## Subdirectories |
| 26 | |
| 27 | | Directory | Purpose | |
| 28 | |-----------|---------| |
| 29 | | `user_modes/` | Strategy pattern implementations for user download modes (see `user_modes/AGENTS.md`) | |
| 30 | |
| 31 | ## For AI Agents |
| 32 | |
| 33 | ### Working In This Directory |
| 34 | - `DownloaderFactory.create()` maps URL type strings to downloader instances |
| 35 | - All downloaders share the same constructor signature (config, api_client, file_manager, cookie_manager, database, rate_limiter, retry_handler, queue_manager, progress_reporter) |
| 36 | - `UserDownloader` uses `UserModeRegistry` to discover strategies and runs enabled modes |
| 37 | - `VideoDownloader` handles both `video` and `gallery` URL types |
| 38 | - API client uses anti-bot signatures from `utils/xbogus.py` and `utils/abogus.py` |
| 39 | - Gallery downloads prefer no-watermark fields (`origin_image`/`display_image`/`url_list`) before watermark fallback fields (`download_url_list`/`owner_watermark_image`) |
| 40 | |
| 41 | ### Testing Requirements |
| 42 | - Tests: `tests/test_api_client.py`, `tests/test_url_parser.py`, `tests/test_downloader_factory.py`, `tests/test_video_downloader.py`, `tests/test_user_downloader.py`, `tests/test_mix_downloader.py`, `tests/test_music_downloader.py`, `tests/test_user_mode_registry.py`, `tests/test_user_downloader_modes.py` |
| 43 | |
| 44 | ### Common Patterns |
| 45 | - Factory pattern: `DownloaderFactory` → concrete downloader |
| 46 | - Strategy pattern: `BaseUserModeStrategy` → concrete mode strategies |
| 47 | - Registry pattern: `UserModeRegistry` auto-discovers strategies |
| 48 | - Paged API collection with cursor-based pagination and stall detection |
| 49 | - `DownloadResult` tracks total/success/failed/skipped counts |
| 50 | |
| 51 | ## Dependencies |
| 52 | |
| 53 | ### Internal |
| 54 | - `auth/` — `CookieManager` for authenticated requests |
| 55 | - `config/` — `ConfigLoader` for download settings |
| 56 | - `control/` — rate limiting, retry, queue management |
| 57 | - `storage/` — `Database` for history, `FileManager` for file I/O |
| 58 | - `utils/` — logging, anti-bot signatures, helpers |
| 59 | |
| 60 | ### External |
| 61 | - `aiohttp` — async HTTP |
| 62 | - `aiofiles` — async file writes |
| 63 | |
| 64 | <!-- MANUAL: --> |
| 65 |