Both must be available. If missing, instruct the user to install:

brew install yt-dlp (macOS) or pip install yt-dlp
brew install ffmpeg (macOS)

Step 2: Get Video Information

/opt/homebrew/Caskroom/miniconda/base/envs/myenv/bin/python scripts/download_xiaohongshu.py "URL" --list-formats

This shows available formats and verifies the URL works with cookie authentication.

Step 3: Download Video + Extract Audio

For basic download (video only, backward compatible with v1.0):

/opt/homebrew/Caskroom/miniconda/base/envs/myenv/bin/python scripts/download_xiaohongshu.py "URL"

For full resource pack (video + audio + subtitles + transcript):

/opt/homebrew/Caskroom/miniconda/base/envs/myenv/bin/python scripts/download_xiaohongshu.py "URL" --full

For full resource pack + AI summary preparation:

/opt/homebrew/Caskroom/miniconda/base/envs/myenv/bin/python scripts/download_xiaohongshu.py "URL" --summary

The --full flag creates a folder ~/Downloads/<video title>/ containing:

video.mp4 — original video
audio.mp3 — extracted audio
subtitle.vtt — WebVTT subtitles (via 3-tier strategy)
transcript.txt — plain text transcription

The --summary flag implies --full and additionally saves .meta.json for AI summary generation.

Step 4: Subtitle Acquisition (Automatic — 3-Tier Strategy)

The script automatically tries these strategies in order:

Manual subtitles — yt-dlp --write-subs --sub-lang zh,en,zh-Hans,zh-CN
Auto-generated subtitles — yt-dlp --write-auto-subs
Whisper local transcription — Falls back to parallel_transcribe.py using faster-whisper

Step 5: Generate Transcript (Automatic)

The script automatically strips timestamps from VTT to produce transcript.txt.

Step 6: AI Summary (Claude generates summary.md)

If the user requested a summary (via --summary flag or by asking to "summarize"):

Read the transcript file:

~/Downloads/<video title>/transcript.txt

Read the metadata file:
```
~/Downloads/<video title>/.meta.json
```
Read the summary prompt template:
```
reference/summary-prompt.md
```
Replace the template placeholders with actual values:
- {{TITLE}} — from .meta.json
- {{URL}} — from .meta.json
- {{DURATION}} — from .meta.json
- {{PLATFORM}} — "Xiaohongshu (小红书)"
- {{TRANSCRIPT}} — contents of transcript.txt
Generate the summary following the template structure.
Save the result to:
```
~/Downloads/<video title>/summary.md
```

Options Reference

Option	Description	Default
`-o, --output`	Output directory	`~/Downloads`
`-q, --quality`	Video quality (`best`, `1080p`, `720p`, `480p`)	`best`
`--browser`	Browser for cookies (`chrome`, `firefox`, `safari`, `none`)	`chrome`
`-a, --audio-only`	Download audio only as MP3	`false`
`--list-formats`	List available formats	`false`
`--full`	Full resource pack mode	`false`
`--summary`	AI summary mode (implies `--full`)	`false`

Output Structure

Basic mode (default)

~/Downloads/
└── <title> [<id>].mp4

Full resource pack mode (`--full` or `--summary`)

~/Downloads/<video title>/
├── video.mp4          # Original video
├── audio.mp3          # Extracted audio
├── subtitle.vtt       # WebVTT subtitles
├── transcript.txt     # Plain text transcript
├── .meta.json         # Video metadata (--summary only)
└── summary.md         # AI-generated summary (--summary only, written by Claude)

Supported URL Formats

Format	Example
Explore link	`https://www.xiaohongshu.com/explore/676a35670000000013002578`
Discovery link	`https://www.xiaohongshu.com/discovery/item/676a35670000000013002578?xsec_token=TOKEN`
Short link	`http://xhslink.com/a/xxxxx`

Troubleshooting

Problem	Solution
`No video formats found`	Log into xiaohongshu.com in browser first, use `--browser chrome`
`Unable to extract initial state`	CAPTCHA triggered — open URL in browser, solve it, retry
Link expired	Copy fresh share link (tokens expire)
No subtitles found	Script will fall back to Whisper transcription automatically
Whisper not available	Install uv (`brew install uv`) for automatic dependency management

Important Notes

Always use the full share URL (with xsec_token) for best results
Log into xiaohongshu.com in your browser before downloading
Maximum video quality is typically 1080p (platform limitation)
Whisper transcription requires uv for automatic dependency management, or faster-whisper installed manually
Respect copyright and Xiaohongshu's terms of service

xiaohongshu-downloader

Xiaohongshu Video Downloader & Summarizer

Workflow

Step 1: Check Dependencies