Douyin Voice Recorder

Browser-driven audio-only recorder for Douyin (live.douyin.com) live rooms. Pulls the stream with ffmpeg, segments every 30 minutes, auto-reconnects, and can watch a following.txt list to start/stop automatically.

基于浏览器的抖音直播（live.douyin.com）纯音频录制工具。通过 ffmpeg 拉流，每 30 分钟分段，断流自动重连，可监听 following.txt 列表自动启停。

Features

• Audio-only recording (no video) to .aac files
• 30-minute auto-segmentation (file suffix _segment2, _segment3, ...)
• Watch mode: poll following.txt and auto-record rooms that go live
• Douyin share short-URL parsing (v.douyin.com/CODE/ -> clean reflow URL)
• Short-URL cache persisted to short_url_mapping.json
• Multiple interfaces: CLI (main_V1.02.py), PyQt6 GUI (gui.py), tkinter dashboard (gui_dashboard.py), read-only HTTP server (web/server.py)
• Danmaku / viewer-list scrapers (Playwright-based, optional)
• Watchdog that auto-alerts when the monitor process or ffmpeg dies
• Real login cookies are never hardcoded; supply your own via cookies.json

Requirements

• Python 3.8 or later
• ffmpeg available on PATH (or set FFMPEG_PATH env var)
• For the danmaku scraper: playwright install chromium
• For the PyQt6 GUI: a working PyQt6 install (Windows / macOS / Linux with Qt libs)
• For the dashboard HTTP server: zero extra dependencies (Python stdlib only)

Install Python dependencies:

pip install -r requirements.txt
playwright install chromium

Quick Start

Watch mode (recommended)

cd /path/to/douyin-voice-recorder
echo "YOUR_ROOM_ID" > following.txt   # 12-digit web_rid, one per line
python main_V1.02.py -w

The recorder polls every 15 seconds and starts a new ffmpeg process the moment a watched room goes live.

Single room

python main_V1.02.py YOUR_ROOM_ID
# or
python main_V1.02.py https://live.douyin.com/YOUR_ROOM_ID
# or share short URL (resolved + cached automatically)
python main_V1.02.py -a "https://v.douyin.com/SHORT_CODE/"

GUI

python gui.py

A PyQt6 window with start / stop, status, and the recording list.

Dashboard (lightweight)

python gui_dashboard.py        # tkinter, no extra deps
# and/or
python web/server.py           # read-only HTTP API on http://localhost:8765/

Configuration

cookies.json (optional)

The audio recorder does not need cookies — ffmpeg pulls the public m3u8 directly. Cookies are only required for the danmaku / viewer-list scrapers.

To enable the danmaku scraper:

1. Log in to live.douyin.com in your browser.
2. Open DevTools -> Application -> Cookies.
3. Either paste the full Cookie: header value into cookie_str, or list each cookie as {name, value} in the cookies array.
4. Save as cookies.json in the project root. Do not commit it.

See cookies.example.json for the expected shape.

following.txt

One room per line. Lines starting with # are treated as comments. Accepts:

• 12-digit web_rid: 123456789012
• Full long URL: https://live.douyin.com/123456789012
• Short share URL: https://v.douyin.com/SHORT_CODE/

Manage the list with following.py:

python following.py --list
python following.py --add 123456789012
python following.py --remove 123456789012

Environment variables

Variable	Default	Description
FFMPEG_PATH	ffmpeg on PATH	Absolute path to the ffmpeg binary
PYTHONIOENCODING	unset	Set to utf-8 to avoid GBK output on Windows

CLI reference (main_V1.02.py)

Argument	Short	Default	Description
<url or room_id>	-	-	Record a single room
--watch	-w	off	Watch mode (poll following.txt rooms)
--interval <s>	-i	15	Poll interval in watch mode
--output <path>	-o	auto	Custom output file path
--add <room>	-a	-	Add a room to following.txt
--list	-l	-	List rooms in following.txt
--remove <room>	-r	-	Remove a room from following.txt
--status	-s	-	Show current recording status

Output

• Audio files land in downloads/<host>_<YYYYMMDD_HHMMSS>.aac (AAC, audio only).
• recording_status.txt shows the current state — pipe RECORDING|room_id|name|start|dur_sec.
• short_url_mapping.json is the V1.02 short-URL cache (regenerated on use).

File layout

douyin-voice-recorder/
  main_V1.02.py     # Recommended CLI: watch + short-URL cache
  main.py           # Legacy V1 single-room recorder
  gui.py            # PyQt6 desktop GUI
  gui_dashboard.py  # Lightweight tkinter status panel
  server.py         # Standalone recording supervisor
  danmaku.py        # Danmaku scraper (Playwright)
  danmaku_im.py     # IM Fetch API danmaku experiment
  danmaku_cdp.py    # CDP response interception experiment
  capture_ws.py     # WebSocket capture helper
  debug_live.py     # Live page DOM debug helper
  debug_ws.py       # WebSocket debug helper
  search_danmaku.py # Page structure analysis helper
  watchdog.py       # Process supervisor with Windows toast alerts
  following.py      # CLI tool for the following list
  test_scrapling.py # Smoke test for the scrapling framework
  web/              # Browser-based dashboard (HTML + read-only API)
  docs/             # Project documentation
  examples/         # Example cookies / following list
  tools/            # Helper scripts

24-hour continuous runs

The intended use case is recording for many hours at a time. For stable long-running sessions:

• Leave the monitor console open. Closing it stops the recording.
• Do not edit following.txt mid-session; use python main_V1.02.py -a ROOM instead.
• Do not kill the ffmpeg child process manually.
• Do not open recording_status.txt in a text editor (file lock).
• Use Ctrl+C for a graceful stop (ffmpeg flushes the .aac).

Auto-recovery matrix:

Issue	Behavior
Douyin API 503 / timeout	Next 15-second poll retries automatically
ffmpeg I/O error	ffmpeg reconnects (up to 10 attempts)
Room goes offline	ffmpeg stops; next live session auto-resumes
Cookie expires	API returns "off"; watcher keeps polling
ffmpeg crash	Python detects via process.poll()
Disk full	ffmpeg write fails; next poll retries

Documentation

• docs/danmaku_readme.md - danmaku scraper design
• docs/danmaku_research.md - danmaku capture research notes
• SKILL.md - structured skill description for AI agents
• examples/following.example.txt - sample following.txt format

License

Apache-2.0. See LICENSE.

Disclaimer

This project is not affiliated with ByteDance or Douyin. It is intended for personal and educational use only. Respect Douyin's Terms of Service and the rights of streamers when using this software. The authors are not responsible for any misuse.