2. FunASR（核心 ASR 引擎，中文语音转录）

pip install funasr modelscope torch torchaudio

3. RapidOCR（烧录字幕识别，可选）

pip install rapidocr-onnxruntime


### ⚠️ FunASR 首次运行注意事项

FunASR 首次运行时会**自动下载约 2-3GB 模型文件**到 `~/.cache/modelscope/`：

| 模型 | 大小 | 用途 |
|------|------|------|
| paraformer-zh | ~1.05GB | 中文语音识别（ASR） |
| fsmn-vad | ~20MB | 语音活动检测（长音频分段） |
| ct-punc | ~1GB | 标点恢复 |

- **首次下载可能需要 1-5 分钟**（取决于网速），期间看起来像是卡住，请耐心等待
- 下载完成后会缓存到本地，后续运行秒级加载
- 如果下载失败，可手动从 ModelScope 下载模型放到 `~/.cache/modelscope/hub/models/iic/` 目录

### 环境验证

```bash
# 验证所有依赖
python scripts/check_environment.py

# 或手动检查关键组件
yt-dlp --version
ffmpeg -version
python -c "from funasr import AutoModel; print('FunASR OK')"
python -c "from rapidocr_onnxruntime import RapidOCR; print('RapidOCR OK')"

首次使用设置

首次使用时，询问用户：

"请设置默认工作目录（用于保存下载的视频和分析报告）：

A. 使用默认目录：~/video-analysis/ B. 每次手动指定目录 C. 指定一个固定目录：[请输入路径]"

保存用户选择供后续使用。

工作流程（5 阶段）

重要：你必须严格按照以下 5 个阶段顺序执行，每个阶段完成后再进入下一个阶段。不要跳过任何阶段。

阶段 1: 下载视频

目标：将用户提供的视频 URL 下载为本地 MP4 文件。

执行步骤：

获取用户提供的视频 URL 和输出目录
如果输出目录不存在，创建它：mkdir -p <输出目录>
判断视频平台并选择下载方式：

抖音视频（URL 包含 `douyin.com` 或 `v.douyin.com`）

使用专用下载脚本：

python scripts/download_douyin.py "<抖音链接>" "<输出目录>/<文件名>.mp4"

支持的链接格式：v.douyin.com/xxx、www.douyin.com/video/xxx、douyin.com/jingxuan?modal_id=xxx

其他平台（B站、YouTube 等）

使用 yt-dlp：

yt-dlp -f "bestvideo[height<=1080]+bestaudio/best[height<=1080]" \
  --merge-output-format mp4 \
  -o "<输出目录>/%(id)s.%(ext)s" \
  "<视频URL>"

确认下载成功：检查 MP4 文件是否存在且大小 > 0

阶段 2: 字幕提取

目标：从视频中提取 SRT 格式字幕文件。

执行步骤：

⚠️ 重要：不要调用 extract_subtitle_funasr.py 的 main() 函数或直接运行整个脚本（它包含 B站 API 调用会因 cookies 问题卡住）。直接调用 extract_with_funasr 函数。

使用以下 Python 代码直接调用 FunASR 提取字幕：

import sys, os
sys.path.insert(0, '<skill_scripts_目录的绝对路径>')
from extract_subtitle_funasr import extract_with_funasr
success = extract_with_funasr('<视频文件绝对路径>', '<输出SRT文件绝对路径>')

执行方式：将上述代码写入临时 Python 脚本文件（如 /tmp/run_funasr.py），然后运行：

python3 -u /tmp/run_funasr.py 2>&1 | tee /tmp/funasr_output.log

注意事项：

必须使用绝对路径，不要使用相对路径
首次运行需下载 2-3GB 模型，耐心等待（后续秒级加载）
转录速度极快：10 分钟音频约 22 秒完成
命令运行后需要等待 30-120 秒（取决于视频长度）

确认成功：检查 SRT 文件是否存在且大小 > 0

字幕提取的内部逻辑（三层优先级，脚本自动处理）：

优先级	方法	适用场景	准确度	速度
L1	内嵌字幕提取	视频自带字幕流	⭐⭐⭐⭐⭐	⚡ 极快
L2	RapidOCR 烧录字幕识别	字幕烧录在画面中	⭐⭐⭐⭐	🚀 快
L3	FunASR 语音转录	无字幕，纯语音	⭐⭐⭐⭐	⚡ 极快

阶段 3: 文稿校正

目标：将 SRT 字幕合并为连续文本，基于语义进行校正，输出 <视频ID>_文字稿.md。

执行步骤：

读取 SRT 字幕文件
提取所有文本行（跳过序号和时间戳行）
合并为连续文本
基于上下文语义进行智能校正：
- 修正 ASR 产生的同音字错误（如"旗下"→"棋下"）
- 修正专业术语和人名
- 确保标点符号正确
保存为 Markdown 文件

输出文件：<输出目录>/<视频ID>_文字稿.md

输出格式：

# <视频ID> 原始文字稿

<校正后的完整文本>

阶段 4: 三维度综合分析

目标：对文字稿内容进行深度分析，应用三个分析框架，输出 <视频ID>_分析报告.md。

执行步骤：

读取阶段 3 生成的文字稿内容
依次应用以下三个分析框架
将分析结果保存为 Markdown 文件

三个分析框架：

4.1 TextContent Analysis 视角

你必须分析以下维度：

叙事结构分析：开场、发展、高潮、转折、结尾的结构
叙事声音分析：基调、节奏、独特金句
修辞手法识别：比喻、反转、呼应、隐喻等
词库提取：关键词列表

4.2 Viral-Abstract-Script 视角

你必须分析以下维度：

Viral-5D 框架诊断：对 Hook、Emotion、爆点、CTA、社交货币分别给出⭐评分和分析
风格定位：该视频的内容风格标签
爆款潜力评估：完播率、互动率、转发率预期
优化建议：1-3 条具体可执行的改进建议

4.3 Brainstorming 视角

你必须分析以下维度：

核心价值拆解：该文案的核心传播价值是什么
创意方向探索：2-3 种衍生创意方向
增量验证点：可测试的优化实验

输出文件：<输出目录>/<视频ID>_分析报告.md

输出格式：

# 视频文案综合分析报告（三维度）

## 一、TextContent Analysis 视角
[叙事结构、修辞手法、词库]

## 二、Viral-Abstract-Script 视角
[Viral-5D诊断、风格定位、优化建议]

## 三、Brainstorming 视角
[价值拆解、创意方向、验证点]

阶段 5: 结构化文字稿

目标：基于阶段 3 的文字稿，按照视频内容的叙事逻辑重新分段整理，输出格式清晰、层次分明的 <视频ID>_结构化文字稿.md。

执行步骤：

读取阶段 3 生成的文字稿，以及阶段 4 分析报告中的叙事结构分析
按照视频内容的自然叙事段落进行切分
为每个段落添加简洁的小标题（## 一、xxx、## 二、xxx 格式）
在段落内部按语义进行合理分行（每段不宜过长，3-5 句为宜）
修正 ASR 错误的同时保留口语化风格
对关键金句或重点内容使用加粗标注
保存为 Markdown 文件

输出文件：<输出目录>/<视频ID>_结构化文字稿.md

输出格式：

# <视频标题或ID> 结构化文字稿

## 一、<第一段小标题>

<分行后的段落文本，3-5 句一段>

<继续...>

## 二、<第二段小标题>

<分行后的段落文本>

...

注意事项：

小标题应简洁有力，概括该段核心内容
保留视频原始的口语表达风格，不要过度书面化
关键金句或亮点用加粗突出
每个段落之间用空行分隔，提高可读性

完成后输出

完成所有 5 个阶段后，向用户播报：

✅ 视频文案分析完成！

📁 输出目录: <用户指定的目录>

📄 生成文件:
  - <视频ID>.mp4              (原始视频)
  - <视频ID>.srt              (原始字幕)
  - <视频ID>_文字稿.md         (校正后纯文本文字稿)
  - <视频ID>_分析报告.md       (三维度分析报告)
  - <视频ID>_结构化文字稿.md   (按叙事逻辑分段的结构化文字稿)

🔗 快速打开:
  [文字稿](<文字稿路径>)
  [分析报告](<分析报告路径>)
  [结构化文字稿](<结构化文字稿路径>)

参考文件

文件	说明	状态
download_douyin.py	抖音视频下载脚本	✅ 可用
extract_subtitle_funasr.py	智能字幕提取（FunASR + RapidOCR）	✅ 可用
check_environment.py	环境依赖检测	✅ 可用
analysis-frameworks.md	三个分析框架详解	✅ 参考

FunASR 技术细节

本 skill 使用 FunASR 的 Paraformer 系列模型组合：

from funasr import AutoModel

model = AutoModel(
    model="paraformer-zh",        # 中文 ASR（含 SeACo 增强）
    vad_model="fsmn-vad",         # 语音活动检测（自动分段长音频）
    vad_kwargs={"max_single_segment_time": 60000},  # 每段最长 60 秒
    punc_model="ct-punc",         # 标点恢复
    disable_update=True,          # 禁用版本检查
)

result = model.generate(
    input="audio.wav",
    batch_size_s=300,             # 动态 batch
    cache={},                     # 官方推荐参数
)

性能参考（MacBook Pro M 系列 CPU）：

音频时长	转录耗时	RTF	字幕条数
42 秒	2 秒	0.049	~11 条
9 分钟	22 秒	0.036	~137 条
10 分钟	22 秒	0.035	~142 条

故障排除

FunASR 首次运行很慢 / 看起来卡住

首次运行需下载约 2-3GB 模型文件，这是正常现象。在网速 30MB/s 的环境下约需 1-2 分钟。下载完成后后续运行秒级加载。

FunASR 模型下载失败

如果 ModelScope 下载速度慢或中断，可手动从 ModelScope 下载以下模型到 ~/.cache/modelscope/hub/models/iic/ 目录：

speech_seaco_paraformer_large_asr_nat-zh-cn-16k-common-vocab8404-pytorch
speech_fsmn_vad_zh-cn-16k-common-pytorch
punc_ct-transformer_cn-en-common-vocab471067-large

torch 版本不兼容

FunASR 需要 PyTorch 2.0+，建议：

pip install torch torchaudio --upgrade

字幕提取脚本直接运行卡住

不要直接运行 python extract_subtitle_funasr.py video.mp4 output.srt（它会调用 B站 API 获取字幕并因 cookies 问题卡住）。请按照阶段 2的说明，直接调用 extract_with_funasr() 函数。

2. FunASR（核心 ASR 引擎，中文语音转录）

3. RapidOCR（烧录字幕识别，可选）

首次使用设置

工作流程（5 阶段）

阶段 1: 下载视频

抖音视频（URL 包含 douyin.com 或 v.douyin.com）

其他平台（B站、YouTube 等）

阶段 2: 字幕提取

阶段 3: 文稿校正

阶段 4: 三维度综合分析

4.1 TextContent Analysis 视角

4.2 Viral-Abstract-Script 视角

4.3 Brainstorming 视角

阶段 5: 结构化文字稿

完成后输出

参考文件

FunASR 技术细节

故障排除

FunASR 首次运行很慢 / 看起来卡住

FunASR 模型下载失败

torch 版本不兼容

字幕提取脚本直接运行卡住

抖音视频（URL 包含 `douyin.com` 或 `v.douyin.com`）

video-copy-analyzer

视频文案分析工具

安装部署

系统要求

一键安装