# claude-video: cho Claude xem video bằng lệnh /watch — hướng dẫn cài đặt và dùng

> claude-video là skill/plugin có lệnh /watch. Nó tải video (link hoặc file), tách khung hình, lấy phụ đề hoặc chép lời, rồi đưa cho agent như Claude Code hay Codex đọc. Cài bằng hai lệnh plugin, nhưng cần có sẵn Python, FFmpeg và yt-dlp.

- Tác giả: Ông T (https://ongt.vn/gioi-thieu)
- Chủ đề: Repo & Skill
- Đăng: 2026-09-25 · Cập nhật: 2026-11-13
- URL: https://ongt.vn/bai-viet/claude-video-cho-claude-xem-video-lenh-watch

claude-video (lệnh `/watch`) là một skill cho các agent lập trình như Claude Code và Codex, giúp chúng "xem" được video. Bạn đưa một đường link hoặc một file video, nó tách video thành các khung hình có mốc thời gian cùng bản chép lời, rồi giao hết cho agent đọc. Agent chỉ biết đọc chữ và ảnh, nên cách này cho nó thứ để dựa vào khi tóm tắt hay trả lời về video.

Repo này hợp với người hay phải xem video dài mà chỉ cần ý chính: nhân viên văn phòng với video họp hoặc video đào tạo, chủ shop muốn học từ clip hướng dẫn, lập trình viên muốn hỏi "đoạn nào trong video này nói về lỗi X". Hiện repo có khoảng 20.628 sao và 2.195 fork, giấy phép MIT, viết bằng Python và vẫn được cập nhật trong vài tháng gần đây.

Điều đáng giá nhất là bạn có hai đường đi. Có khoá Gemini miễn phí thì Google xem cả hình lẫn tiếng cho bạn. Không có khoá, hoặc video riêng tư, thì mọi thứ chạy ngay trên máy bạn. Phần lớn bài này nói về đường chạy trên máy, vì đó là đường README mô tả kỹ nhất.

```repo
- repo | bradautomates/claude-video
- kind | Skill
- desc | claude-video thêm lệnh /watch: biến link hoặc file video thành khung hình có mốc thời gian và bản chép lời để Claude, Codex xem và tóm tắt.
- stars | 21k
- lang | Python
- license | MIT
```

## claude-video làm được gì

Lệnh `/watch` làm nhiều việc nhỏ nối với nhau, và mỗi việc có ích riêng.

- **Nhận link hoặc file có sẵn trên máy.** Bạn không cần tự tải video về rồi tách. Đưa tên file hoặc đường link là đủ.
- **Tách khung hình có mốc thời gian.** Agent biết "ở giây thứ 42 trên màn hình có bảng giá", nên bạn hỏi được những câu như "phút nào nhắc đến giá?".
- **Ưu tiên phụ đề có sẵn.** Nếu video có phụ đề gốc, tool đọc phụ đề trước, nhanh và không tốn thêm chi phí chép lời. README ghi rõ phụ đề luôn đứng đầu trong mọi lựa chọn.
- **Chép lời khi video không có phụ đề.** Có ba lựa chọn dự phòng: WhisperX chạy ngay trên máy (không cần khoá API), Groq hoặc OpenAI chạy trên đám mây (cần khoá). Hoặc chọn `none` để chỉ lấy phụ đề và hình.
- **Hai "động cơ" xử lý.** Động cơ `local` tách hình và chép lời trên máy bằng `ffmpeg` và `yt-dlp`. Động cơ Gemini đưa cả video cho mô hình video của Google rồi chuyển lại câu trả lời có mốc thời gian. Mặc định là `auto`: có khoá Gemini thì dùng Gemini, không thì dùng `local`.
- **Chọn mức chi tiết.** Trình hướng dẫn lần đầu hỏi bạn muốn mức chi tiết nào (ví dụ `balanced`) và dùng phương án chép lời nào.
- **Cắt đoạn cần xem.** Với động cơ Gemini, `--start` và `--end` giới hạn phần video được xem, đỡ phải gửi cả video dài.

Tool không tự đổi động cơ giữa chừng. Nếu Gemini lỗi, nó báo loại lỗi và bạn tự quyết có chạy lại với `--engine local` hay không. Như vậy bạn luôn biết video của mình đang đi đâu.

## Cần chuẩn bị gì

Phần này lấy đúng từ tư liệu của repo.

- **Chỗ chạy agent:** Claude Code (trong Claude Desktop ở chế độ Code, trong VS Code, hoặc trong terminal), hoặc Codex, hoặc agent khác hỗ trợ Agent Skills. **Claude Chat và Cowork không dùng được.** Claude Code trên web có môi trường đám mây riêng và không dùng được trình cài `/plugin` tương tác.
- **Phần mềm:** Python 3.10 trở lên, FFmpeg/ffprobe và bản yt-dlp mới nhất. Skill chỉ mang theo hướng dẫn và script, không kèm sẵn mấy chương trình này. Riêng YouTube cần thêm môi trường chạy JavaScript được hỗ trợ (README dùng Deno).
- **Node.js:** chỉ cần nếu bạn cài bằng `npx skills` cho agent khác. Với Codex qua hộp chat hoặc Claude Code thì không cần.
- **Khoá API (tuỳ chọn):** `GEMINI_API_KEY` từ Google AI Studio cho đường nhanh nhất. `GROQ_API_KEY` hoặc `OPENAI_API_KEY` nếu muốn chép lời bằng đám mây.
- **Nếu dùng WhisperX trên máy:** trống ổ đĩa ít nhất 3 GB, RAM ít nhất 8 GB. README nói máy Mac chip Apple đã được kiểm chứng, còn Windows, Linux và Mac Intel "chưa kiểm chứng".

```note
Khoá API là mật khẩu của bạn. Đừng dán vào repo, đừng đăng lên chỗ công khai. README khuyên điền khoá vào file cấu hình riêng hoặc biến môi trường. Với Gemini, file video trên máy sẽ được tải lên Google rồi xoá sau khi trả lời. Video nội bộ hoặc nhạy cảm thì chọn động cơ local.
```

## Cài đặt từng bước

```steps
- Mở Claude Code | Dùng Claude Desktop (phiên Code), VS Code hoặc terminal
- Thêm marketplace | Khai báo bradautomates/claude-video làm nguồn plugin
- Cài plugin watch | Cài watch@claude-video rồi mở phiên mới
- Cài công cụ nền | Python, FFmpeg, yt-dlp (và Deno nếu xem YouTube)
- Chạy lần đầu | Gõ /watch, trả lời trình hướng dẫn, thử một video ngắn
```

README cho nhiều cách cài tuỳ bạn dùng app nào. Hãy chọn **một** cách thôi. Mình đi qua cách phổ biến nhất là Claude Code, rồi nhắc ngắn các cách còn lại.

### Cài bằng Claude Code trong terminal

Mở terminal, gõ `claude` để vào Claude Code. Hai lệnh sau gõ **bên trong phiên Claude Code**, từng lệnh một:

```text
/plugin marketplace add bradautomates/claude-video
/plugin install watch@claude-video
```

Lệnh đầu khai báo repo này làm một "cửa hàng plugin". Lệnh sau cài plugin tên `watch` từ cửa hàng đó. Chỗ người mới hay vấp là chạy chỉ lệnh đầu mà quên lệnh sau. Thêm marketplace chưa phải là cài plugin.

Làm theo thông báo kích hoạt. Nếu `watch` chưa xuất hiện, mở một phiên Claude Code mới. Sau đó gõ `/watch` và chọn **`/watch:watch`** trong danh sách gợi ý.

Nếu bạn đang ở dấu nhắc terminal thường, chưa vào Claude Code, dùng bản lệnh thực thi:

```bash
claude plugin marketplace add bradautomates/claude-video
claude plugin install watch@claude-video
```

### Cài trong Claude Desktop hoặc VS Code

Claude Desktop (không cần terminal): bấm **Customize** ở thanh bên, chọn **Plugins**, mở **Add**, chọn **Add marketplace**, rồi **Add from a repository**. Ở ô URL dán địa chỉ sau rồi bấm **Sync**:

```text
https://github.com/bradautomates/claude-video
```

Sau đó tìm **Watch** trong marketplace vừa thêm và bấm cài. Cuối cùng mở một phiên **Code**, đừng dùng Cowork, rồi nhờ Claude dùng skill watch.

Với VS Code, mở bảng Claude Code, gõ `/plugins` để mở **Manage plugins**. Chọn **Marketplaces** và thêm `bradautomates/claude-video`. Quay lại **Plugins**, tìm **watch** và chọn **Install for you**. Xong thì gõ `/watch`.

### Cài bằng Codex hoặc agent khác

Với Codex, dán đoạn này vào hộp tin nhắn của Codex (app, CLI hay tiện ích IDE):

```text
Use $skill-installer to install the watch skill from:
https://github.com/bradautomates/claude-video/tree/main/skills/watch
```

Đợi Codex cài xong, mở phiên mới. Nếu skill chưa hiện, khởi động lại Codex. Nếu đã có Codex CLI, README còn ghi cách cài plugin:

```bash
codex plugin marketplace add bradautomates/claude-video
codex plugin add watch@claude-video
```

Với Cursor, Copilot hoặc agent khác hỗ trợ Agent Skills, cài [Node.js](https://nodejs.org/en/download) trước rồi chạy trong terminal:

```bash
npx skills add bradautomates/claude-video -g --skill watch
```

Chọn agent của bạn khi được hỏi, rồi khởi động lại agent.

### Cài công cụ nền (Python, FFmpeg, yt-dlp)

Cài skill xong vẫn chưa đủ, vì skill không kèm sẵn các chương trình này. Cách dễ nhất là hỏi thẳng agent:

```text
Use the watch skill's bundled setup.py to check dependencies in this session.
Tell me which tools are missing and help me install them here.
```

Nếu agent chạy trực tiếp trên máy Mac, nó có thể tự cài qua Homebrew. Hệ khác thì nó đưa lệnh cho bạn. Nếu muốn tự cài, README ghi như sau.

Trên macOS, cài [Homebrew](https://brew.sh) rồi:

```bash
brew install python ffmpeg yt-dlp
```

Trên Windows, cài Python 3.10 trở lên từ trang Python, rồi mở PowerShell chạy lần lượt:

```powershell
winget install --id Gyan.FFmpeg --exact
winget install --id yt-dlp.yt-dlp --exact
winget install --id DenoLand.Deno --exact
```

Trên Ubuntu/Debian:

```bash
sudo apt install python3 ffmpeg pipx
pipx install "yt-dlp[default,curl-cffi]"
pipx ensurepath
```

Với Ubuntu, README nói thêm là cần cài Deno cho YouTube, kèm đường dẫn hướng dẫn trên trang của Deno. **Cài xong, đóng và mở lại terminal lẫn agent** để chúng nhận ra chương trình mới. Đây là chỗ nhiều người vấp: cài rồi mà agent vẫn báo thiếu, chỉ vì chưa mở lại.

### Điền khoá Gemini (nếu muốn đường nhanh)

Lấy khoá miễn phí ở Google AI Studio. Khi trình hướng dẫn hỏi, bạn có thể dán khoá vào chat. README gợi ý cách an toàn hơn: nhờ agent mở file `~/.config/watch/.env`, bạn tự dán khoá sau `GEMINI_API_KEY=` rồi lưu. Không có khoá thì bỏ qua bước này, tool tự dùng động cơ local.

## Kiểm tra đã chạy được chưa

Cách thử theo README dùng đường không cần khoá. Đặt một video ngắn (ví dụ `example.mp4`) vào một thư mục, rồi mở thư mục đó làm dự án của agent. Dán vào hộp chat của agent:

```text
Use the watch skill on example.mp4 in the folder I shared.
For setup, choose balanced detail and captions only (none).
Summarize what is visible, with timestamps.
```

Đổi `example.mp4` thành tên file của bạn. Agent sẽ kiểm tra công cụ. Nếu nó báo thiếu chương trình nào, quay lại bước cài công cụ nền rồi thử lại.

**Thành công là khi bạn nhận được bản tóm tắt hình ảnh có mốc thời gian.** Lần chạy đầu này không cần khoá chép lời hay mô hình giọng nói. Vì bạn chọn `none`, file local sẽ không có bản chép lời giọng nói, và đó là bình thường.

Trên Windows, bạn có thể kiểm tra Python bằng `python --version` hoặc `py -3 --version`.

## Dùng vào việc thật

Các tình huống dưới đây bám theo những gì README mô tả. Câu lệnh mẫu là gợi ý của mình, bạn sửa lại cho hợp việc.

### Tóm tắt video họp để gửi lại cả nhóm

Chị Lan làm hành chính, có file ghi hình buổi họp tuần mà không ai kịp xem. Chị mở thư mục chứa file trong agent và gõ:

```text
Use the watch skill on hop-tuan.mp4 in the folder I shared.
Summarize what is visible and what is said, with timestamps.
```

Nếu file có phụ đề thì agent đọc phụ đề. Nếu chị muốn có cả lời nói, chị bật thêm một phương án chép lời (WhisperX hoặc khoá Groq/OpenAI) ở bước cài đặt lần đầu. Kết quả là bản tóm tắt theo mốc thời gian, chị dán thẳng vào email.

> Cho agent xem video, rồi hỏi nó "phút nào nói về giá" thay vì tự tua cả tiếng đồng hồ.
>
> — Ông T

### Học nhanh từ một video YouTube dài

Anh Minh mở shop online, muốn học cách chụp ảnh sản phẩm từ một video hướng dẫn dài trên YouTube. Anh dán link và hỏi:

```text
Use the watch skill on <đường link YouTube>.
Give me the transcript detail, then list the key steps with timestamps.
```

README nói phụ đề gốc có thể được đọc mà không cần tải cả video, nên việc này thường nhanh. Anh nhận được danh sách các bước có mốc giờ, và biết đoạn nào đáng xem lại. Lưu ý YouTube cần Deno đã cài, và việc truy cập link còn tuỳ vào nguồn video lẫn quyền mạng trong phiên của bạn.

### Hỏi đáp về video bằng Gemini, không cần cài nhiều

Bạn Hà là lập trình viên mới, không muốn cài FFmpeg ngay. Bạn lấy khoá Gemini miễn phí, điền vào `GEMINI_API_KEY`, rồi gửi link YouTube. Theo README, link YouTube lúc này gửi thẳng cho Google, không cần cài thêm gì cho nhánh đó. Bạn hỏi ví dụ "trong video, người nói dùng thư viện nào và ở giây thứ mấy?". Câu trả lời có mốc thời gian được chuyển lại trong chat. Nếu chỉ cần một đoạn, thêm `--start` và `--end` để giới hạn.

### Xem video riêng tư, giữ trên máy

Một bạn dev có video demo nội bộ, không muốn tải lên đâu cả. Bạn ép chạy local bằng `--engine local` và chọn `whisperx` làm phương án chép lời. README nói WhisperX chạy trên máy, không cần khoá API, và dùng mô hình `small` trên CPU theo mặc định. Việc này cần tối thiểu 3 GB ổ đĩa và 8 GB RAM. Bản chép lời và khung hình đều được xử lý trong máy bạn. Riêng WhisperX cần Watch v0.3.0 trở lên, nên nếu bản cài của bạn cũ thì cập nhật trước.

## Lỗi hay gặp và cách xử lý

**Agent báo thiếu ffmpeg, yt-dlp hoặc python.** Skill không kèm sẵn các chương trình này. Cài theo bảng ở trên, rồi đóng mở lại terminal và agent. Có thể hỏi agent chạy `setup.py` bundled để biết chính xác đang thiếu gì.

**Gõ `/watch` mà không thấy gì.** Thường là bạn mới thêm marketplace mà chưa chạy lệnh `install`, hoặc chưa mở phiên mới. Chạy lại lệnh cài, rồi bắt đầu một phiên Claude Code mới. Trong VS Code, tên thường hiện là `/watch:watch`.

**Dùng trong Claude Chat hoặc Cowork không chạy.** Đây là giới hạn đã được ghi rõ, kể cả khi bạn tải `watch.skill` lên làm skill tuỳ chỉnh. Hãy dùng phiên **Code** của Claude Desktop, VS Code, terminal hoặc Codex.

**Video YouTube không tải được.** README nhắc YouTube cần môi trường chạy JavaScript (Deno) và yt-dlp phải là bản mới nhất, vì các trang web hay làm hỏng bản cũ. Cập nhật yt-dlp và kiểm tra Deno đã cài. Nếu chạy trong môi trường đám mây, README cảnh báo phần lớn trang chặn yt-dlp từ đó.

**Không có bản chép lời giọng nói.** Nếu bạn chọn `none` và video không có phụ đề, bạn chỉ nhận hình ảnh. Bật `whisperx`, `groq` hoặc `openai` ở bước thiết lập. Hai cái sau cần khoá API tương ứng. Cũng đừng dùng đồng thời `--whisper` và `--no-whisper`, vì chúng xung đột nhau.

## Có nên dùng không

**Điểm mạnh:** cài bằng hai lệnh plugin, có đường chạy không cần khoá, có đường Gemini nhanh khi bạn muốn hỏi cả hình lẫn tiếng, và có phương án giữ dữ liệu trên máy. Giấy phép MIT, repo còn được cập nhật. README viết thẳng thắn về giới hạn, điều đó đáng tin hơn là hứa hẹn chung chung.

**Giới hạn:** bạn phải tự cài Python, FFmpeg và yt-dlp. Không dùng được trong Claude Chat hay Cowork. Với Gemini, video của bạn đi lên Google. Với WhisperX, máy cần đủ ổ đĩa và RAM, và chỉ Mac chip Apple được kiểm chứng. Windows, Linux và Mac Intel được nhắm tới nhưng README ghi là chưa kiểm chứng. Tốc độ phụ thuộc máy bạn: README đo 69 giây tiếng Anh xong trong 9,6 giây trên máy Apple M5 Pro, nên máy yếu hơn sẽ chậm hơn.

**Khi nào chọn cách khác:** nếu bạn chỉ cần phụ đề của một video YouTube và không cần xem hình, một công cụ tải phụ đề đơn giản là đủ. Nếu bạn không dùng agent lập trình nào, repo này không hợp, vì nó là skill cho agent chứ không phải ứng dụng riêng. Còn nếu bạn đã dùng Claude Code hoặc Codex hằng ngày, thêm `/watch` là một bước nhỏ mà tiết kiệm nhiều thời gian xem video.

## Câu hỏi thường gặp

### claude-video có miễn phí không?

Repo dùng giấy phép MIT nên bạn dùng và cài miễn phí. Đường chạy local không cần khoá API. Khoá Gemini lấy được miễn phí từ Google AI Studio, còn Groq và OpenAI cần khoá của từng nhà cung cấp, chi phí tuỳ gói của họ, tư liệu không nói rõ.

### Có cần GPU không?

README không yêu cầu GPU. Cấu hình WhisperX mặc định chạy trên CPU (`cpu`, `int8`, mô hình `small`). Bạn cần tối thiểu 3 GB ổ đĩa trống và 8 GB RAM nếu dùng WhisperX trên máy.

### Chạy được trên Windows không?

README có hướng dẫn cài Python, FFmpeg, yt-dlp và Deno bằng winget cho Windows 10 trở lên. Tuy nhiên với WhisperX, README ghi chỉ Mac chip Apple được kiểm chứng, còn Windows là mục tiêu nhưng chưa được kiểm chứng.

### Dùng được trong Claude Chat hay Cowork không?

Không. README nói rõ Claude Chat và Cowork không được hỗ trợ, kể cả tải watch.skill lên làm skill tuỳ chỉnh. Bạn cần dùng Claude Code (phiên Code trong Claude Desktop, VS Code hoặc terminal), Codex hoặc agent khác hỗ trợ Agent Skills.

### Video của tôi có bị gửi đi đâu không?

Với động cơ local, tách hình và chép lời bằng WhisperX diễn ra trên máy chạy agent, và động cơ này không liên hệ Google. Với động cơ Gemini, file local được tải lên Google rồi xoá sau khi trả lời; link YouTube gửi thẳng cho Google. Nếu chọn chép lời qua Groq hoặc OpenAI thì âm thanh đi lên dịch vụ đó.

### Nó khác gì việc tự tải phụ đề video?

Ngoài phụ đề, claude-video còn tách khung hình có mốc thời gian để agent nhìn được nội dung trên màn hình. Nó cũng có phương án chép lời khi video không có phụ đề. Tư liệu không so sánh với công cụ cụ thể nào khác.

### Cài có khó không?

Phần cài plugin chỉ cần hai lệnh hoặc vài lần bấm trong Claude Desktop. Phần khó hơn là cài Python, FFmpeg và yt-dlp, vì skill không kèm sẵn. Bạn có thể nhờ agent chạy setup.py để kiểm tra và hướng dẫn cài.
