Metadata-Version: 2.4
Name: withvideo
Version: 0.1.0
Summary: Turn tutorial videos into reproducible Repeat Guides — and let agents run them.
Project-URL: Homepage, https://github.com/nds15763/withvideo
Project-URL: Issues, https://github.com/nds15763/withvideo/issues
Project-URL: Repository, https://github.com/nds15763/withvideo
Author: Xya Kim
License: MIT
License-File: LICENSE
Keywords: agent,automation,claude,cli,llm,tutorial,video,whisper
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Multimedia :: Video
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Utilities
Requires-Python: >=3.11
Requires-Dist: anthropic
Requires-Dist: av
Requires-Dist: click
Requires-Dist: imagehash
Requires-Dist: joblib
Requires-Dist: numpy
Requires-Dist: pillow
Requires-Dist: yt-dlp>=2025.1.1
Provides-Extra: bilibili
Requires-Dist: bilibili-api-python; extra == 'bilibili'
Provides-Extra: dev
Requires-Dist: pytest; extra == 'dev'
Provides-Extra: faster-whisper
Requires-Dist: faster-whisper; extra == 'faster-whisper'
Provides-Extra: mcp
Requires-Dist: mcp[cli]>=1.0; extra == 'mcp'
Provides-Extra: ollama
Requires-Dist: ollama; extra == 'ollama'
Provides-Extra: ssim
Requires-Dist: scikit-image; extra == 'ssim'
Provides-Extra: whisper
Requires-Dist: mlx-whisper; extra == 'whisper'
Provides-Extra: youtube
Requires-Dist: youtube-transcript-api; extra == 'youtube'
Description-Content-Type: text/markdown

# WithVideo

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Python](https://img.shields.io/badge/python-3.11%2B-blue.svg)](https://www.python.org/downloads/)
[![PyPI](https://img.shields.io/pypi/v/withvideo.svg)](https://pypi.org/project/withvideo/)

`WithVideo` 是一个把教程视频转成可复现操作指南的命令行工具。

它接受本地视频文件或在线视频地址，自动完成媒体获取、字幕/转录、活动检测、语义判断、可选视觉分析，最后输出两份结果：

- `guide.md`：给人读的 Repeat Guide
- `semantic.json`：给机器消费的结构化语义结果

当前仓库同时包含两条链路：

- `withvideo/`：`wv learn` 主工具
- `act_with_video/`：读取 `guide.md` / `semantic.json` 的执行侧原型

## 现在能做什么

- 支持两类输入：
  - 本地原始视频文件
  - 网络 URL
- 已验证的 URL 平台：
  - YouTube
  - Bilibili
- 本地视频会自动吸收同目录 sidecar：
  - `source.info.json`
  - `.srt` / `.vtt`
- YouTube 会优先下载原始语言字幕，而不是默认拉取所有字幕语言
- Bilibili 支持站点级 cookies 缓存，减少反复触发浏览器钥匙串授权
- `--transcript auto` 会根据实际 `SourceMeta` 在平台字幕和 Whisper 间动态选择
- 长视频活动检测会自动降采样，避免 `ffmpeg` 抽帧阶段轻易超时
- 语义与 Guide 生成支持自定义 `llm_command`，可接 `codex`、`claude` 或后续其他命令

## 当前边界

- `wv act` 已支持 Tier 0/1 真实执行（ShellExecutor、FileWriteExecutor、URLOpenExecutor、ClaudeCodeExecutor）；Tier 2/3（Browser / ComputerUse）仍在 roadmap
- `--vision none` 是当前最稳的跑法；视觉链路仍在持续演进
- 很长的视频在 LLM 阶段仍可能比较慢，建议配合 `--llm-timeout`

## 环境要求

- Python `3.11+`
- `ffmpeg` / `ffprobe`（见下面"系统依赖"）
- 建议使用 `uv`

### 系统依赖

`ffmpeg` / `ffprobe` 不会被 `pip` 自动安装，请先在系统层装好：

| 平台 | 安装命令 |
|------|---------|
| macOS | `brew install ffmpeg` |
| Ubuntu/Debian | `sudo apt install -y ffmpeg` |
| Windows | `choco install ffmpeg` 或从 [ffmpeg.org](https://ffmpeg.org/download.html) 下载 |

装好后 `ffmpeg -version` 能正常输出即可。`wv preflight` 会自动检测。

### Python 依赖

跑完整 URL 链路的常见组合：

```bash
# Apple Silicon（mlx-whisper 更快）
uv pip install "withvideo[whisper,youtube,bilibili]"

# 其他平台（faster-whisper，CPU/CUDA 通用）
uv pip install "withvideo[faster-whisper,youtube,bilibili]"
```

如果你只想本地开发运行，也可以直接用 `uv run --with ...` 临时补依赖。

> **YouTube / Bilibili 下载出错？** 先 `pip install -U yt-dlp`——反爬规则频繁变化，保持 yt-dlp 最新通常就能解决。

## 快速开始

### 1. 分析本地视频

```bash
uv run --python 3.11 --with mlx-whisper python -m withvideo.cli learn \
  "/path/to/source.mp4" \
  -o .withvideo/demo-local \
  --vision none \
  -v
```

### 2. 分析 YouTube 视频

```bash
uv run --python 3.11 --with youtube-transcript-api --with mlx-whisper python -m withvideo.cli learn \
  "https://www.youtube.com/watch?v=xZaSPw14Cfo" \
  -o .withvideo/demo-youtube \
  --vision none \
  --llm-timeout 600 \
  -v
```

### 3. 分析 Bilibili 视频

匿名下载：

```bash
uv run --python 3.11 --with mlx-whisper python -m withvideo.cli learn \
  "https://www.bilibili.com/video/BV1StX3B7E9X/" \
  -o .withvideo/demo-bilibili \
  --vision none \
  -v
```

使用浏览器登录态：

```bash
uv run --python 3.11 --with mlx-whisper python -m withvideo.cli learn \
  "https://www.bilibili.com/video/BV1StX3B7E9X/" \
  -o .withvideo/demo-bilibili-login \
  --cookies-from-browser chrome:Default \
  --vision none \
  -v
```

第一次读取浏览器 cookies 时，macOS 可能会弹钥匙串授权。后续默认会复用项目内缓存的站点级 cookies。

### 4. 直接用安装后的 `wv`

如果你已经把项目装成可执行脚本，可以直接：

```bash
wv learn "https://www.youtube.com/watch?v=xZaSPw14Cfo" -o .withvideo/demo --vision none
```

## 典型输出

一次成功运行后，输出目录通常类似这样：

```text
.withvideo/demo/
└── 10_Months_of_Unity_Dev_with_Claude_Code/
    ├── guide.md
    ├── semantic.json
    ├── source.mp4
    ├── source.info.json
    ├── source.en-orig.vtt
    ├── source.en.vtt
    └── keyframes/
```

其中：

- `guide.md` 是给人看的复现指南
- `semantic.json` 是 `wv act` 和后续自动化的权威输入
- `source.*` 是 Stage 0 获取到的媒体与 sidecar
- `keyframes/` 是活动检测 / 视觉分析阶段的中间产物

## 常用参数

- `--transcript auto|platform-subs|mlx-whisper`
- `--vision cli|claude|ollama:<model>|none`
- `--activity auto|mv|ssim`
- `--media-access download|remote`
- `--llm-command 'codex exec -'`
- `--llm-command 'claude -p {prompt}'`
- `--llm-timeout 600`
- `--cookies /path/to/cookies.txt`
- `--cookies-from-browser chrome:Default`
- `--event-stream jsonl`
- `--decision-mode auto|prompt|fail`
- `--force`

`llm_command` 默认会自动探测：

1. `WITHVIDEO_LLM_COMMAND` / `WV_LLM_COMMAND`
2. `codex exec -`
3. `claude -p {prompt}`

## `wv act`

`wv act` 会读取 `guide.md` 或 `semantic.json`，并生成执行计划。

```bash
wv act .withvideo/demo/10_Months_of_Unity_Dev_with_Claude_Code/guide.md --dry-run
```

当前状态：

- 已能解析 guide
- 已能生成 action plan
- Tier 0/1 执行器可真实执行（Shell / FileWrite / URLOpen / ClaudeCode）；Tier 2/3（Browser / ComputerUse）未实现
- 首次执行建议用 `--dry-run` 预览路由决策

## 运行策略

`wv learn` 的大致流水线是：

1. Stage 0：获取媒体与平台元数据
2. Stage 1：字幕读取或 Whisper 转录
3. Stage 1c：活动检测
4. Stage 2：语义判断
5. Stage 3：视觉分析
6. Stage 4：生成 `guide.md` 和 `semantic.json`

当前实现里，平台字幕优先于 Whisper，但只有在字幕文件真实可用时才会走平台字幕链路。

## 开发与验证

跑测试：

```bash
uv run --python 3.11 -m unittest discover -s tests -v
```

检查语法：

```bash
uv run --python 3.11 python -m compileall withvideo tests
```

## 仓库结构

```text
withvideo/       # learn pipeline
act_with_video/  # act-side prototype
design/          # design docs
```

如果你把它当工具来用，重点先看 `withvideo/cli.py`、`withvideo/pipeline.py` 和本 README。
