yueying 0.1.0__tar.gz

yueying-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 yueying contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

yueying-0.1.0/PKG-INFO

@@ -0,0 +1,142 @@
+Metadata-Version: 2.4
+Name: yueying
+Version: 0.1.0
+Summary: 阅影：把视频变成 AI 能读的文字稿和关键帧，让 Claude Code / Cursor 等编程助手看懂视频
+Author: vsh5dvsch7-png
+License: MIT
+Project-URL: Homepage, https://github.com/vsh5dvsch7-png/yueying
+Project-URL: Repository, https://github.com/vsh5dvsch7-png/yueying
+Project-URL: Issues, https://github.com/vsh5dvsch7-png/yueying/issues
+Keywords: video,whisper,claude-code,agent-skill,transcript,keyframes,bilibili,youtube
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Multimedia :: Video
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: faster-whisper>=1.1
+Requires-Dist: yt-dlp>=2025.1.1
+Requires-Dist: imageio-ffmpeg>=0.5
+Requires-Dist: pillow>=10.1
+Provides-Extra: cuda
+Requires-Dist: nvidia-cublas-cu12; extra == "cuda"
+Requires-Dist: nvidia-cudnn-cu12; extra == "cuda"
+Dynamic: license-file
+
+# 阅影 yueying
+
+**让 AI 编程助手看懂视频。** Claude Code、Cursor 这些工具读得了图片和文字，却读不了视频。阅影把一段视频（本地文件，或 B站 / YouTube / 抖音 / 小红书等链接）拆成 AI 能读的东西：
+
+- **文字稿**：优先抓平台自带字幕；没有就用本地语音识别（faster-whisper），中、英、日、韩、法、德、俄等几十种语言自动检测，全程离线，不上传、不花钱
+- **关键帧**：在画面明显变化的地方抽帧，每张左下角烧上编号和时间；再拼成九宫格总览图，AI 一眼看完全片走向
+- **一份 report.md**：简介、章节、画面总览、关键帧清单、按段落带时间戳的文字稿，AI 读这一个文件就能开始干活
+
+然后你就可以对 Claude 说：「帮我看看这个视频，把里面的步骤整理成笔记」「照着这个教程把代码写出来」「这个视频 10 分钟处讲了什么」。
+
+## 安装
+
+需要 Python 3.9 以上。ffmpeg 会自动带上，不用单独装。
+
+**Windows**：下载本仓库，双击 `install.cmd`。它会创建独立的 Python 环境、装好依赖、把 Claude Code 技能放到 `~/.claude/skills/yueying`。
+
+**手动安装（任何系统）**：
+
+```bash
+pip install yueying                 # 或 pipx install yueying
+pip install "yueying[cuda]"         # 有 NVIDIA 显卡再加这个，语音识别快很多
+yueying --install-skill             # 把 Claude Code 技能装到 ~/.claude/skills/yueying
+```
+
+想装 GitHub 上的最新版：`pip install git+https://github.com/vsh5dvsch7-png/yueying.git`。
+
+装好技能后，Claude Code 会在需要看视频时自动调用它。Cursor 等支持 Agent Skills 标准的工具，把 `~/.claude/skills/yueying/SKILL.md` 复制到对应目录即可。
+
+第一次做语音识别会下载模型（默认 large-v3-turbo，约 1.6 GB）。国内访问 HuggingFace 慢的话，程序会自动切换到 hf-mirror.com 镜像。
+
+## 用法
+
+```bash
+yueying 视频.mp4
+yueying "https://www.bilibili.com/video/BVxxxx"
+yueying "https://www.youtube.com/watch?v=xxxx" --out ./notes/xxx
+```
+
+输出目录默认是 `./yueying_out/<视频名>/`：
+
+```
+report.md          给 AI 读的总索引
+transcript.txt     按段落、带时间戳的文字稿
+transcript.srt     字幕文件，可直接给播放器用
+grid_01.jpg ...    九宫格总览图
+frames/            单帧大图，f003_00m15s.jpg 这样命名
+manifest.json      给程序读的结构化结果
+```
+
+常用参数：
+
+| 参数 | 作用 |
+|---|---|
+| `--lang zh` | 指定语言（默认自动检测） |
+| `--model small` | 换小模型，没显卡的机器快很多；可选 tiny / base / small / medium / large-v3 / large-v3-turbo |
+| `--device cpu` | 强制用 CPU |
+| `--frames 30` | 最多抽多少帧（默认按时长自动，上限 60） |
+| `--scene 0.2` | 场景切换灵敏度，越小越敏感 |
+| `--no-asr` | 没字幕也不做语音识别（只要画面） |
+| `--no-frames` | 不抽画面（只要文字） |
+| `--force-asr` | 有字幕也重新识别 |
+| `--cookies-from-browser chrome` | 用浏览器登录态下载（B站 高清 / 会员视频） |
+| `--keep` | 保留下载的原视频 |
+
+## 在 Claude Code 里用
+
+装好技能后，直接说：
+
+> 帮我看看 D:\课程\第3课.mp4，把知识点整理成笔记
+
+> 这个视频 https://www.bilibili.com/video/BVxxxx 里的代码帮我抄下来
+
+Claude 会自己跑 `yueying`，读 report.md 和关键帧，然后按你的要求整理。引用视频内容时它会带上时间点，方便你回看。
+
+## 工作原理
+
+```
+视频/链接 ──► yt-dlp 下载（≤720p）+ 抓字幕
+          ──► ffmpeg 抽 16k 音频 ──► faster-whisper 识别（有字幕则跳过）
+          ──► ffmpeg 场景检测 ──► 抽帧 ──► Pillow 烧时间戳、拼九宫格
+          ──► report.md / transcript / manifest.json
+```
+
+代码都在 `src/yueying/`，每个文件一件事：
+
+| 文件 | 管什么 |
+|---|---|
+| `cli.py` | 命令行入口，串起下面几步 |
+| `download.py` | yt-dlp 下载、挑字幕语言 |
+| `ffm.py` | ffmpeg 封装：探测时长分辨率、抽音频、导内嵌字幕 |
+| `subs.py` | 解析 srt / vtt / B站 json 字幕，去掉 YouTube 自动字幕的重复 |
+| `asr.py` | faster-whisper 语音识别，自动选 GPU / CPU，失败回退 |
+| `frames.py` | 场景检测、定抽帧时间点、抽帧、烧时间戳、拼九宫格 |
+| `report.py` | 生成 report.md、transcript、manifest |
+
+## 常见问题
+
+**识别不准？** 换大模型 `--model large-v3`，或指定语言 `--lang ja`。专有名词和代码容易听错，以画面为准，AI 会对照关键帧。
+
+**B站 下载失败？** 试试 `--cookies-from-browser chrome`（先在 Chrome 里登录 B站）。
+
+**没有 NVIDIA 显卡很慢？** 用 `--model small`，一段 10 分钟的视频大约 1 到 2 分钟识别完。
+
+**想要更多画面？** `--frames 60 --scene 0.2`。
+
+## 致谢
+
+- [faster-whisper](https://github.com/SYSTRAN/faster-whisper)、[yt-dlp](https://github.com/yt-dlp/yt-dlp)、[imageio-ffmpeg](https://github.com/imageio/imageio-ffmpeg)、[Pillow](https://python-pillow.org/)
+- 九宫格烧时间戳的做法参考了 [video-vision-mcp](https://github.com/OAMaestro/video-vision-mcp)，按时长分档抽帧参考了 [video-analyzer-skill](https://github.com/bsisduck/video-analyzer-skill)
+
+## 许可
+
+MIT

yueying-0.1.0/README.md

@@ -0,0 +1,113 @@
+# 阅影 yueying
+
+**让 AI 编程助手看懂视频。** Claude Code、Cursor 这些工具读得了图片和文字，却读不了视频。阅影把一段视频（本地文件，或 B站 / YouTube / 抖音 / 小红书等链接）拆成 AI 能读的东西：
+
+- **文字稿**：优先抓平台自带字幕；没有就用本地语音识别（faster-whisper），中、英、日、韩、法、德、俄等几十种语言自动检测，全程离线，不上传、不花钱
+- **关键帧**：在画面明显变化的地方抽帧，每张左下角烧上编号和时间；再拼成九宫格总览图，AI 一眼看完全片走向
+- **一份 report.md**：简介、章节、画面总览、关键帧清单、按段落带时间戳的文字稿，AI 读这一个文件就能开始干活
+
+然后你就可以对 Claude 说：「帮我看看这个视频，把里面的步骤整理成笔记」「照着这个教程把代码写出来」「这个视频 10 分钟处讲了什么」。
+
+## 安装
+
+需要 Python 3.9 以上。ffmpeg 会自动带上，不用单独装。
+
+**Windows**：下载本仓库，双击 `install.cmd`。它会创建独立的 Python 环境、装好依赖、把 Claude Code 技能放到 `~/.claude/skills/yueying`。
+
+**手动安装（任何系统）**：
+
+```bash
+pip install yueying                 # 或 pipx install yueying
+pip install "yueying[cuda]"         # 有 NVIDIA 显卡再加这个，语音识别快很多
+yueying --install-skill             # 把 Claude Code 技能装到 ~/.claude/skills/yueying
+```
+
+想装 GitHub 上的最新版：`pip install git+https://github.com/vsh5dvsch7-png/yueying.git`。
+
+装好技能后，Claude Code 会在需要看视频时自动调用它。Cursor 等支持 Agent Skills 标准的工具，把 `~/.claude/skills/yueying/SKILL.md` 复制到对应目录即可。
+
+第一次做语音识别会下载模型（默认 large-v3-turbo，约 1.6 GB）。国内访问 HuggingFace 慢的话，程序会自动切换到 hf-mirror.com 镜像。
+
+## 用法
+
+```bash
+yueying 视频.mp4
+yueying "https://www.bilibili.com/video/BVxxxx"
+yueying "https://www.youtube.com/watch?v=xxxx" --out ./notes/xxx
+```
+
+输出目录默认是 `./yueying_out/<视频名>/`：
+
+```
+report.md          给 AI 读的总索引
+transcript.txt     按段落、带时间戳的文字稿
+transcript.srt     字幕文件，可直接给播放器用
+grid_01.jpg ...    九宫格总览图
+frames/            单帧大图，f003_00m15s.jpg 这样命名
+manifest.json      给程序读的结构化结果
+```
+
+常用参数：
+
+| 参数 | 作用 |
+|---|---|
+| `--lang zh` | 指定语言（默认自动检测） |
+| `--model small` | 换小模型，没显卡的机器快很多；可选 tiny / base / small / medium / large-v3 / large-v3-turbo |
+| `--device cpu` | 强制用 CPU |
+| `--frames 30` | 最多抽多少帧（默认按时长自动，上限 60） |
+| `--scene 0.2` | 场景切换灵敏度，越小越敏感 |
+| `--no-asr` | 没字幕也不做语音识别（只要画面） |
+| `--no-frames` | 不抽画面（只要文字） |
+| `--force-asr` | 有字幕也重新识别 |
+| `--cookies-from-browser chrome` | 用浏览器登录态下载（B站 高清 / 会员视频） |
+| `--keep` | 保留下载的原视频 |
+
+## 在 Claude Code 里用
+
+装好技能后，直接说：
+
+> 帮我看看 D:\课程\第3课.mp4，把知识点整理成笔记
+
+> 这个视频 https://www.bilibili.com/video/BVxxxx 里的代码帮我抄下来
+
+Claude 会自己跑 `yueying`，读 report.md 和关键帧，然后按你的要求整理。引用视频内容时它会带上时间点，方便你回看。
+
+## 工作原理
+
+```
+视频/链接 ──► yt-dlp 下载（≤720p）+ 抓字幕
+          ──► ffmpeg 抽 16k 音频 ──► faster-whisper 识别（有字幕则跳过）
+          ──► ffmpeg 场景检测 ──► 抽帧 ──► Pillow 烧时间戳、拼九宫格
+          ──► report.md / transcript / manifest.json
+```
+
+代码都在 `src/yueying/`，每个文件一件事：
+
+| 文件 | 管什么 |
+|---|---|
+| `cli.py` | 命令行入口，串起下面几步 |
+| `download.py` | yt-dlp 下载、挑字幕语言 |
+| `ffm.py` | ffmpeg 封装：探测时长分辨率、抽音频、导内嵌字幕 |
+| `subs.py` | 解析 srt / vtt / B站 json 字幕，去掉 YouTube 自动字幕的重复 |
+| `asr.py` | faster-whisper 语音识别，自动选 GPU / CPU，失败回退 |
+| `frames.py` | 场景检测、定抽帧时间点、抽帧、烧时间戳、拼九宫格 |
+| `report.py` | 生成 report.md、transcript、manifest |
+
+## 常见问题
+
+**识别不准？** 换大模型 `--model large-v3`，或指定语言 `--lang ja`。专有名词和代码容易听错，以画面为准，AI 会对照关键帧。
+
+**B站 下载失败？** 试试 `--cookies-from-browser chrome`（先在 Chrome 里登录 B站）。
+
+**没有 NVIDIA 显卡很慢？** 用 `--model small`，一段 10 分钟的视频大约 1 到 2 分钟识别完。
+
+**想要更多画面？** `--frames 60 --scene 0.2`。
+
+## 致谢
+
+- [faster-whisper](https://github.com/SYSTRAN/faster-whisper)、[yt-dlp](https://github.com/yt-dlp/yt-dlp)、[imageio-ffmpeg](https://github.com/imageio/imageio-ffmpeg)、[Pillow](https://python-pillow.org/)
+- 九宫格烧时间戳的做法参考了 [video-vision-mcp](https://github.com/OAMaestro/video-vision-mcp)，按时长分档抽帧参考了 [video-analyzer-skill](https://github.com/bsisduck/video-analyzer-skill)
+
+## 许可
+
+MIT

yueying-0.1.0/pyproject.toml

@@ -0,0 +1,45 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "yueying"
+version = "0.1.0"
+description = "阅影：把视频变成 AI 能读的文字稿和关键帧，让 Claude Code / Cursor 等编程助手看懂视频"
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "vsh5dvsch7-png" }]
+keywords = ["video", "whisper", "claude-code", "agent-skill", "transcript", "keyframes", "bilibili", "youtube"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Environment :: Console",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Topic :: Multimedia :: Video",
+]
+dependencies = [
+  "faster-whisper>=1.1",
+  "yt-dlp>=2025.1.1",
+  "imageio-ffmpeg>=0.5",
+  "pillow>=10.1",
+]
+
+[project.optional-dependencies]
+cuda = ["nvidia-cublas-cu12", "nvidia-cudnn-cu12"]
+
+[project.urls]
+Homepage = "https://github.com/vsh5dvsch7-png/yueying"
+Repository = "https://github.com/vsh5dvsch7-png/yueying"
+Issues = "https://github.com/vsh5dvsch7-png/yueying/issues"
+
+[project.scripts]
+yueying = "yueying.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+yueying = ["skill/SKILL.md"]

yueying-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

yueying-0.1.0/src/yueying/__init__.py

@@ -0,0 +1,2 @@
+"""阅影 (yueying)：把视频变成 AI 能读的文字稿和关键帧。"""
+__version__ = "0.1.0"

yueying-0.1.0/src/yueying/asr.py

@@ -0,0 +1,105 @@
+"""语音识别：faster-whisper，本地离线；有 NVIDIA 显卡自动用 GPU，失败退回 CPU。"""
+import glob
+import os
+import sys
+
+
+def _add_cuda_dlls() -> None:
+    """pip 装的 nvidia-cublas-cu12 / nvidia-cudnn-cu12 把 DLL 放在 site-packages/nvidia/*/bin，
+    Windows 下要手动加进搜索路径 ctranslate2 才找得到。"""
+    if not sys.platform.startswith("win"):
+        return
+    for sp in sys.path:
+        for d in glob.glob(os.path.join(sp, "nvidia", "*", "bin")):
+            try:
+                os.add_dll_directory(d)
+            except Exception:
+                pass
+            if d not in os.environ.get("PATH", ""):
+                os.environ["PATH"] = d + os.pathsep + os.environ.get("PATH", "")
+
+
+def pick_device(device: str):
+    """返回 (device, compute_type)。"""
+    if device in ("cuda", "cpu"):
+        return device, ("float16" if device == "cuda" else "int8")
+    try:
+        import ctranslate2
+        if ctranslate2.get_cuda_device_count() > 0:
+            return "cuda", "float16"
+    except Exception:
+        pass
+    return "cpu", "int8"
+
+
+def _load(model_name: str, device: str, compute_type: str, log):
+    from faster_whisper import WhisperModel
+    try:
+        return WhisperModel(model_name, device=device, compute_type=compute_type)
+    except Exception as e:
+        msg = str(e).lower()
+        # 国内访问 HuggingFace 常失败，自动换镜像再试一次
+        if "HF_ENDPOINT" not in os.environ and ("huggingface" in msg or "connect" in msg or "timed out" in msg):
+            log("  下载模型失败，改用镜像 hf-mirror.com 重试…")
+            os.environ["HF_ENDPOINT"] = "https://hf-mirror.com"
+            return WhisperModel(model_name, device=device, compute_type=compute_type)
+        raise
+
+
+# whisper 输出中文时经常不带标点，用 hotwords 在每个窗口都塞一句带标点的提示，引导它加标点
+STYLE_HINT = {
+    "zh": "以下是普通话的句子，带有标点符号。",
+    "yue": "以下係廣東話嘅句子，有標點符號。",
+    "ja": "以下は日本語の文章です。句読点があります。",
+}
+
+
+def _run(model, wav, language):
+    from faster_whisper.audio import decode_audio
+    audio = decode_audio(wav, sampling_rate=16000)
+    if not language:
+        language, _, _ = model.detect_language(audio, vad_filter=True)
+    return model.transcribe(audio, language=language, beam_size=5, vad_filter=True,
+                            condition_on_previous_text=False, hotwords=STYLE_HINT.get(language))
+
+
+def _chain(first, rest):
+    if first is not None:
+        yield first
+    yield from rest
+
+
+def transcribe(wav: str, model_name: str, device: str, language, duration: float, log=print) -> tuple:
+    """返回 (segments, info)。segments = [{start, end, text}]。"""
+    _add_cuda_dlls()
+    dev, ct = pick_device(device)
+    log(f"  模型 {model_name}，设备 {dev} ({ct})；首次使用会下载模型，请耐心等待")
+    model = gen = info = None
+    if dev == "cuda":
+        try:
+            model = _load(model_name, dev, ct, log)
+            gen, info = _run(model, wav, language)
+            # 真正算出第一段才知道 GPU 能不能用
+            gen = iter(gen)
+            gen = _chain(next(gen, None), gen)
+        except Exception as e:
+            log(f"  GPU 不可用（{type(e).__name__}: {str(e)[:150]}），退回 CPU")
+            dev, ct = "cpu", "int8"
+            model = None
+    if model is None:
+        model = _load(model_name, dev, ct, log)
+        gen, info = _run(model, wav, language)
+    log(f"  检测语言 {info.language}（置信度 {info.language_probability:.0%}）")
+    segs = []
+    last_pct = -1
+    for s in gen:
+        text = s.text.strip()
+        if text:
+            segs.append({"start": float(s.start), "end": float(s.end), "text": text})
+        if duration:
+            pct = int(min(s.end, duration) / duration * 100)
+            if pct // 10 != last_pct // 10:
+                last_pct = pct
+                log(f"  识别进度 {pct}%")
+    return segs, {"language": info.language, "language_probability": float(info.language_probability),
+                  "model": model_name, "device": dev, "compute_type": ct}

yueying-0.1.0/src/yueying/cli.py

@@ -0,0 +1,183 @@
+"""命令行入口：yueying <视频文件或链接> [--out 目录] ..."""
+import argparse
+import glob
+import json
+import os
+import re
+import sys
+import time
+
+from . import __version__, ffm, subs, frames as fr, report
+from .download import is_url, download
+
+
+def log(msg: str) -> None:
+    print(msg, flush=True)
+
+
+def slug(s: str) -> str:
+    s = re.sub(r"[\\/:*?\"<>|\s]+", "_", s).strip("._")
+    return s[:60] or "video"
+
+
+def find_sidecar_subs(video: str) -> list:
+    base = os.path.splitext(video)[0]
+    found = []
+    for ext in (".srt", ".vtt", ".ass", ".json"):
+        found += glob.glob(glob.escape(base) + "*" + ext)
+    return sorted(found)
+
+
+def find_exe() -> str:
+    """找到 yueying 命令的绝对路径，写进技能文件，免得 Claude 的 shell 里 PATH 不一样找不到。"""
+    import shutil
+    exe = shutil.which("yueying")
+    if exe:
+        return os.path.abspath(exe)
+    cand = os.path.join(os.path.dirname(sys.executable), "yueying.exe" if os.name == "nt" else "yueying")
+    return cand if os.path.exists(cand) else "yueying"
+
+
+def install_skill() -> int:
+    """把 SKILL.md 装到 ~/.claude/skills/yueying/，Claude Code 需要看视频时就会自动用。"""
+    from importlib import resources
+    text = resources.files("yueying").joinpath("skill/SKILL.md").read_text(encoding="utf-8")
+    exe = find_exe()
+    if exe != "yueying":
+        text = text.replace('   yueying "<', f'   "{exe}" "<')
+    dst_dir = os.path.join(os.path.expanduser("~"), ".claude", "skills", "yueying")
+    os.makedirs(dst_dir, exist_ok=True)
+    dst = os.path.join(dst_dir, "SKILL.md")
+    with open(dst, "w", encoding="utf-8") as f:
+        f.write(text)
+    log(f"技能已安装：{dst}")
+    log(f"技能里使用的命令：{exe}")
+    log("现在可以在 Claude Code 里说：帮我看看这个视频 <路径或链接>")
+    return 0
+
+
+def main(argv=None) -> int:
+    for stream in (sys.stdout, sys.stderr):
+        try:
+            stream.reconfigure(encoding="utf-8", errors="replace")
+        except Exception:
+            pass
+
+    ap = argparse.ArgumentParser(prog="yueying", description="阅影：把视频变成 AI 能读的文字稿和关键帧")
+    ap.add_argument("input", nargs="?", help="本地视频文件，或 B站 / YouTube / 抖音等视频链接")
+    ap.add_argument("--install-skill", action="store_true", help="把 Claude Code 技能装到 ~/.claude/skills/yueying，装一次即可")
+    ap.add_argument("--out", help="输出目录（默认 ./yueying_out/<视频名>）")
+    ap.add_argument("--lang", help="语音语言代码，如 zh / en / ja；默认自动检测")
+    ap.add_argument("--model", default="large-v3-turbo", help="whisper 模型：tiny/base/small/medium/large-v3/large-v3-turbo（默认）")
+    ap.add_argument("--device", default="auto", choices=["auto", "cuda", "cpu"], help="识别设备，默认有显卡用显卡")
+    ap.add_argument("--frames", type=int, help="最多抽多少关键帧（默认按时长自动，上限 60）")
+    ap.add_argument("--scene", type=float, default=0.3, help="场景切换灵敏度 0~1，越小越敏感（默认 0.3）")
+    ap.add_argument("--no-frames", action="store_true", help="不抽画面")
+    ap.add_argument("--no-asr", action="store_true", help="没有字幕也不做语音识别")
+    ap.add_argument("--force-asr", action="store_true", help="即使有字幕也重新做语音识别")
+    ap.add_argument("--cookies-from-browser", metavar="BROWSER", help="从浏览器读登录 cookie（chrome/edge/firefox），B站高清或会员视频需要")
+    ap.add_argument("--keep", action="store_true", help="保留下载的原视频（默认处理完删掉）")
+    ap.add_argument("--json", action="store_true", help="最后额外打印一行 manifest JSON")
+    ap.add_argument("--version", action="version", version=f"yueying {__version__}")
+    a = ap.parse_args(argv)
+    if a.install_skill:
+        return install_skill()
+    if not a.input:
+        ap.error("请给出视频文件路径或链接，例如：yueying 视频.mp4")
+
+    t0 = time.time()
+    meta = {"source": a.input}
+    downloaded = None
+    if is_url(a.input):
+        out_dir = a.out or os.path.join("yueying_out", "pending")
+        log(f"[1/4] 下载 {a.input}")
+        tmp_dir = os.path.join(a.out or "yueying_out", "_download")
+        downloaded = download(a.input, tmp_dir, a.cookies_from_browser, log)
+        video = downloaded["video"]
+        meta.update({k: downloaded[k] for k in ("title", "uploader", "url", "description", "chapters", "language")})
+        out_dir = a.out or os.path.join("yueying_out", slug(meta["title"]))
+        sub_files = downloaded["subs"]
+    else:
+        video = os.path.abspath(a.input)
+        if not os.path.exists(video):
+            log(f"找不到文件：{video}")
+            return 2
+        log(f"[1/4] 本地文件 {video}")
+        meta["title"] = os.path.splitext(os.path.basename(video))[0]
+        out_dir = a.out or os.path.join("yueying_out", slug(meta["title"]))
+        sub_files = find_sidecar_subs(video)
+    out_dir = os.path.abspath(out_dir)
+    os.makedirs(out_dir, exist_ok=True)
+
+    info = ffm.probe(video)
+    meta.update(info)
+    if downloaded and downloaded.get("duration") and not info["duration"]:
+        meta["duration"] = downloaded["duration"]
+    log(f"      时长 {fr.fmt_time(meta['duration'])}，{info['width']}x{info['height']}，"
+        f"{'有' if info['has_audio'] else '无'}音轨，内嵌字幕 {info['subtitle_streams']} 条")
+
+    # ---- 文字 ----
+    segs, text_source = [], {"kind": "none", "desc": "无"}
+    log("[2/4] 文字")
+    if not a.force_asr:
+        if not sub_files and info["subtitle_streams"]:
+            emb = os.path.join(out_dir, "embedded.srt")
+            if ffm.extract_embedded_subtitle(video, emb):
+                sub_files = [emb]
+        for sf in sub_files:
+            try:
+                segs = subs.parse_file(sf)
+            except Exception as e:
+                log(f"      字幕 {os.path.basename(sf)} 解析失败：{e}")
+                continue
+            if segs:
+                text_source = {"kind": "subtitle", "file": sf, "desc": f"字幕文件 {os.path.basename(sf)}（{len(segs)} 条）"}
+                log(f"      用字幕 {os.path.basename(sf)}，{len(segs)} 条")
+                break
+    if not segs and not a.no_asr:
+        if not info["has_audio"]:
+            log("      没有音轨，跳过语音识别")
+        else:
+            log("      没有可用字幕，做本地语音识别")
+            from . import asr
+            wav = os.path.join(out_dir, "audio.wav")
+            ffm.extract_audio(video, wav)
+            segs, ainfo = asr.transcribe(wav, a.model, a.device, a.lang, meta["duration"], log)
+            try:
+                os.remove(wav)
+            except OSError:
+                pass
+            text_source = {"kind": "asr", **ainfo,
+                           "desc": f"本地语音识别 faster-whisper {ainfo['model']}（{ainfo['device']}），"
+                                   f"检测语言 {ainfo['language']}（{ainfo['language_probability']:.0%}），{len(segs)} 段"}
+    elif not segs:
+        log("      无字幕且已跳过语音识别")
+
+    # ---- 画面 ----
+    frame_list, grids = [], []
+    log("[3/4] 画面")
+    if a.no_frames or not info["width"]:
+        log("      跳过")
+    else:
+        target = a.frames or fr.default_target(meta["duration"])
+        scenes = fr.scene_times(video, a.scene)
+        times = fr.plan_times(meta["duration"], scenes, target)
+        log(f"      场景切换 {len(scenes)} 处，抽 {len(times)} 帧")
+        frame_list = fr.extract(video, times, os.path.join(out_dir, "frames"), log=log)
+        grids = fr.make_grids(frame_list, out_dir)
+
+    # ---- 报告 ----
+    log("[4/4] 写报告")
+    manifest = report.write_all(out_dir, meta, segs, frame_list, grids, text_source)
+    if downloaded and not a.keep:
+        import shutil
+        shutil.rmtree(os.path.dirname(downloaded["video"]), ignore_errors=True)
+    log(f"完成，用时 {time.time() - t0:.0f} 秒")
+    log(f"报告：{manifest['report']}")
+    if a.json:
+        print(json.dumps({k: v for k, v in manifest.items() if k != "segments"}, ensure_ascii=False))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())