xiaohongshu-downloader v2.0.0A

Immutable. This exact content is served forever at /api/v1/blob/725f535bebcfa733.

---
name: xiaohongshu-downloader
description: |
  Download a Xiaohongshu (小红书 / RedNote) video from a xiaohongshu.com or xhslink.com link and transcribe its voice-over with Whisper into a local Markdown transcript (Chinese kept verbatim, English translated to Chinese), saved in a complete folder structure. Use when the user shares a Xiaohongshu video link and wants the spoken content as text for analysis, summary or translation, or says 下载小红书, 小红书视频转文字, 小红书口播稿, 提取口播, xiaohongshu transcript, RedNote video to text.
version: 2.0.0
author: doing
metadata:
  hermes:
    tags: [小红书, xiaohongshu, 下载, 视频, 转录, Whisper, Markdown, 逐字稿]
    category: media
---

# 小红书视频下载器 + 口播文案转录

将小红书视频下载到本地，自动用 Whisper 转录口播内容，生成 Markdown 逐字稿。中文视频直接保存中文，英文视频翻译成中文后保存。

## 触发条件

- 用户发送 `xiaohongshu.com/discovery/item/xxx` 或 `xhslink.com/xxx` 链接
- 用户说"下载这个小红书视频"、"扒一下这个文案"、"存下来"且链接是小红书的

## 前置依赖

| 工具 | 用途 | 安装检查 |
|------|------|---------|
| yt-dlp | 视频下载 | `which yt-dlp` |
| whisper (openai-whisper) | 语音转文字 | `which whisper` |
| ffmpeg | 音频处理 | `which ffmpeg` |

## 工作流程

### 阶段 A：下载视频

#### 第 1 步：用脚本下载视频

```bash
SKILL_DIR="$(cd "$(dirname "$0")" && pwd)"
bash "${SKILL_DIR}/scripts/download_xiaohongshu.sh" '<XIAOHONGSHU_URL>' '<OUTPUT_DIR>'
```

脚本会输出下载的文件路径。

#### 第 2 步：确认下载成功

验证文件存在且大小 > 0。记录文件路径和视频标题（如果 yt-dlp 能提取到）。

### 阶段 B：视频转录

#### 第 3 步：创建目录结构

```
<OUTPUT_DIR>/小红书-{视频标题或简短描述}/
├── transcript.md              ← 格式化的逐字稿 Markdown
├── videos/
│   └── video.mp4              ← 原始视频
└── transcripts/
    ├── audio.srt              ← SRT 字幕文件
    └── audio.txt              ← 纯文本逐字稿
```

标题来源优先级：
1. yt-dlp 提取的标题
2. 视频前几句口播内容的概括
3. 默认用 `小红书-视频`

#### 第 4 步：移动视频到目录结构中

```bash
mv {下载的mp4} {output_dir}/videos/video.mp4
```

#### 第 5 步：Whisper 转录

```bash
whisper "{output_dir}/videos/video.mp4" \
  --model medium \
  --output_format srt \
  --output_dir /tmp/xhs_transcribe
```

**语言检测策略**：
- 先不指定 `--language`，让 Whisper 自动检测
- 如果自动检测为中文 → 中文视频，直接保存
- 如果自动检测为英文 → 英文视频，转录后翻译成中文

**模型选择**：
- `base`：快速但准确率差，不推荐
- `medium`：平衡选择，中文效果好（推荐）
- `large`：最佳效果但很慢，长视频慎用

**注意**：
- ~8 分钟视频用 medium 模型约需 15-20 分钟
- 用 `background=true` + `notify_on_complete=true` 后台运行
- 转录完成后继续后续步骤

#### 第 6 步：整理转录文件

```bash
# 移动 SRT
cp /tmp/xhs_transcribe/*.srt "{output_dir}/transcripts/audio.srt"

# 从 SRT 提取纯文本
awk '!/^[0-9]+$/ && !/^[0-9]{2}:[0-9]{2}/ && !/^$/' \
  "{output_dir}/transcripts/audio.srt" > "{output_dir}/transcripts/audio.txt"
```

#### 第 7 步：检测语言 + 翻译（如需）

**中文视频**（绝大多数小红书视频）：
- 直接使用 Whisper 转录的中文文本
- 无需翻译

**英文视频**（少数情况）：
1. 读取 `transcripts/audio.txt` 英文逐字稿
2. 分段用 LLM 翻译成中文（每段不超过 2000 字）
3. 生成 `transcripts/audio-zh.md` 中文翻译逐字稿

翻译提示词：
```
将以下英文视频逐字稿翻译为中文，保持口语化风格，专业术语保留英文原文并加括号注释：
{segment}
```

### 阶段 C：组装最终输出

#### 第 8 步：生成 transcript.md

中文视频模板：
```markdown
# 小红书视频逐字稿 - {标题}

> **来源**: 小红书  
> **类型**: 视频  
> **语言**: 中文  
> **时长**: {时长}  
> **视频文件**: [video.mp4](videos/video.mp4)

---

## 逐字稿

{纯文本逐字稿}

---

*Generated by xiaohongshu-downloader skill · Whisper medium model*
```

英文视频模板（额外包含中文翻译）：
```markdown
# 小红书视频逐字稿 - {标题}

> **来源**: 小红书  
> **类型**: 视频  
> **语言**: English → 中文翻译  
> **时长**: {时长}  
> **视频文件**: [video.mp4](videos/video.mp4)

---

## 中文翻译

{翻译后的中文文本}

---

## English Transcript

{英文原文}

---

*Generated by xiaohongshu-downloader skill · Whisper medium model*
```

#### 第 9 步：清理临时文件

```bash
rm -rf /tmp/xhs_transcribe
```

#### 第 10 步：向用户报告

报告：
- 视频标题
- 目录路径
- transcript.md 路径
- 语言（中文/英文→中文翻译）

## 输出示例

### 中文视频

```
<OUTPUT_DIR>/小红书-Obsidian加CloudCode打造个人生活操作系统/
├── transcript.md
├── videos/
│   └── video.mp4
└── transcripts/
    ├── audio.srt
    └── audio.txt
```

### 英文视频（含翻译）

```
<OUTPUT_DIR>/小红书-Some English Video/
├── transcript.md
├── videos/
│   └── video.mp4
└── transcripts/
    ├── audio.srt
    ├── audio.txt
    └── audio-zh.md
```

## 已验证有效的路径

| 步骤 | 方法 | 状态 |
|------|------|------|
| 下载视频 | yt-dlp + bundled script | ✅ 有效 |
| 转录中文 | whisper --model medium | ✅ 有效，质量好 |
| 提取纯文本 | awk 过滤 SRT | ✅ 有效 |
| 组装 Markdown | heredoc 模板 | ✅ 有效 |

## 无效的方法（不要再试）

| 方法 | 为什么不行 |
|------|-----------|
| yt-dlp --print title 获取小红书标题 | 经常失败，Extractor 不稳定 |
| whisper base 模型做中文 | 准确率太差，至少用 medium |
| whisper --task translate 做英→中 | translate 只输出英文，不支持中文翻译 |
| whisper --language zh 对英文视频 | 会把英文识别成乱码 |

## 与 x-article-download skill 的复用关系

本 skill 的转录+Markdown生成逻辑与 x-article-download 的阶段 B/C 高度一致：
- 相同的 Whisper 模型和参数
- 相同的 SRT → 纯文本提取方式
- 相同的目录结构规范
- 相同的语言检测 + 条件翻译逻辑

主要差异：
- 小红书视频大多为中文，不需要翻译（x 的视频多为英文需要翻译）
- 标题获取方式不同（yt-dlp 对小红书不稳定）
- 视频下载方式不同（使用 bundled script 而非直接 yt-dlp）

## 边界情况

- 如果 yt-dlp 下载失败 → 报错，尝试 browser fallback
- 如果视频很短（<30s）→ 转录很快，但可能只有几句话
- 如果视频无语音 → Whisper 会输出空文本，报告"无语音内容"
- 如果是图文笔记（非视频）→ 只下载图片，不做转录
- 如果标题获取失败 → 用口播前几句概括作为标题

## Notes

- 默认保存到 `<OUTPUT_DIR>`（默认为 `~/Downloads`）
- 如果用户指定其他路径，使用用户指定的路径
- 适合单条链接处理，不适合批量爬取
- 图片笔记暂不支持转录（无语音内容）