douyin-research-kit

Douyin (抖音) Research Kit

Extract structured data from Douyin videos, profiles, and content for research. Powered by yt-dlp locally — no API key required.

Version: 1.0.0 Prerequisite: yt-dlp >= 2024.01.01

Prerequisites

# macOS
brew install yt-dlp
pip
pip install yt-dlp
Verify
yt-dlp --version

Authentication

Douyin often requires cookies for stable access. Export browser cookies:

yt-dlp --cookies-from-browser chrome "URL"

Operations

1. Video Metadata

Extract title, creator, engagement stats from a single video.

yt-dlp --dump-json --skip-download --cookies-from-browser chrome \
  "https://www.douyin.com/video/VIDEO_ID"

Key JSON fields:

| Field | JSON path | |-------|-----------| | Title / Caption | .title / .description | | Creator | .uploader | | Creator ID | .uploader_id | | Upload date | .upload_date (YYYYMMDD → YYYY-MM-DD) | | Duration | .duration (seconds) | | Views | .view_count | | Likes | .like_count (点赞) | | Comments | .comment_count | | Shares | .repost_count (转发) | | Music/Sound | .track | | Music author | .artist | | Thumbnail | .thumbnail |

Short links:

yt-dlp --dump-json --skip-download --cookies-from-browser chrome \
  "https://v.douyin.com/SHORTCODE/"

yt-dlp auto-resolves v.douyin.com short links.

2. User Profile / Video Feed

Extract recent videos from a creator's profile.

yt-dlp --flat-playlist --dump-json --playlist-end 20 \
  --cookies-from-browser chrome \
  "https://www.douyin.com/user/USER_SEC_UID"

Output is one JSON per line. Parse for .title, .upload_date, .view_count, .like_count, .duration.

Output format: Table with columns: #, Date, Title (first 40 chars), Duration, Views, Likes.

3. Subtitles / Captions

Some Douyin videos have embedded subtitles:

# List available subtitles
yt-dlp --list-subs --skip-download --cookies-from-browser chrome \
  "https://www.douyin.com/video/VIDEO_ID"
Download subtitles
yt-dlp --skip-download --write-sub --write-auto-sub \
  --sub-lang zh --sub-format vtt --convert-subs srt \
  --cookies-from-browser chrome \
  -o "/tmp/douyin-%(id)s.%(ext)s" \
  "https://www.douyin.com/video/VIDEO_ID"

After download, read .srt and clean: 1. Remove sequence numbers 2. Extract timestamps 3. Deduplicate consecutive identical lines

Output format: [HH:MM:SS] subtitle text

4. Music / Sound Page

yt-dlp --flat-playlist --dump-json --playlist-end 20 \
  --cookies-from-browser chrome \
  "https://www.douyin.com/music/MUSIC_ID"

5. Hashtag / Challenge (挑战)

yt-dlp --flat-playlist --dump-json --playlist-end 20 \
  --cookies-from-browser chrome \
  "https://www.douyin.com/hashtag/HASHTAG_ID"

6. Live Stream Info

yt-dlp --dump-json --skip-download --cookies-from-browser chrome \
  "https://live.douyin.com/ROOM_ID"

Returns stream title, host info, viewer count, and stream status.

URL Patterns

| Pattern | Type | |---------|------| | douyin.com/video/ID | Single video | | v.douyin.com/SHORTCODE/ | Short link (auto-resolves) | | douyin.com/user/SEC_UID | User profile | | douyin.com/music/ID | Music/sound page | | douyin.com/hashtag/ID | Hashtag page | | live.douyin.com/ROOM_ID | Live stream |

Number Formatting

Workflow Guide

When user provides a Douyin URL:

1. Identify URL type (video, profile, music, live, hashtag) 2. Ensure cookies are available (almost always needed) 3. Run the appropriate yt-dlp command with --cookies-from-browser 4. Parse JSON and present formatted Markdown 5. Highlight music/sound info (trending sounds are key on Douyin) 6. Offer follow-ups: "Want me to analyze this creator's content strategy?" / "Extract subtitles?"

When user asks to download a video:

Error Handling

Notes

About

Douyin Research Kit is an open-source project by SnapVee.

# macOS
brew install yt-dlp
pip
pip install yt-dlp
Verify
yt-dlp --version