Hoàn thành phân tích video và đồng bộ storyboard trong Claude Code và Codex với reelbench-skills

Giới thiệu dự án

reelbench-skills là một bộ skill Claude Code và Codex dành cho công việc video. Hiện dự án gồm video-shots và video-sync, lần lượt dùng để phân tích video theo từng cảnh và tạo video hiển thị thông tin storyboard được cập nhật đồng bộ theo chuyển cảnh.

Dự án chỉ yêu cầu Node.js 18 trở lên cùng ffmpeg và ffprobe. Dự án không có dependency npm và không yêu cầu cấu hình API Key bổ sung, mà sử dụng hạn mức của phiên Claude Code hoặc Codex hiện tại.

Hai khả năng cốt lõi

video-shots: Phân tích video theo từng cảnh

video-shots chuyển toàn bộ video thành bảng phân tích từng cảnh, ghi lại thời lượng, cỡ cảnh, thể loại, chuyển động máy quay, hình ảnh và nhịp điệu. Điểm cắt cảnh và thời lượng được đo bằng ffmpeg, còn mô hình chịu trách nhiệm đánh giá các nội dung cần hiểu về ngữ nghĩa. Cuối cùng, kết quả được kiểm tra lần lượt qua 15 cổng chất lượng.

Báo cáo được tạo là một trang tương tác độc lập không phụ thuộc bên ngoài và có thể mở ngoại tuyến bằng cách nhấp đúp. Trang bao gồm trình phát tích hợp, tô sáng đồng bộ với video, chuyển đến cảnh khi nhấp, dải nhịp điệu cảnh, tìm kiếm, lọc, sắp xếp, chế độ xem danh sách và thẻ, khung hình đầu và cuối, phân bố thống kê, nhân vật xuất hiện và kiểm tra chất lượng.

Thiết bị màn hình hẹp cũng có thể duyệt bảng cảnh, thuận tiện cho việc kiểm tra kết quả phân tích trên các kích thước màn hình khác nhau.

video-sync: Tạo video kèm thông tin storyboard

video-sync dùng để kết hợp video hoàn chỉnh với thông tin storyboard trên cùng một khung hình. Khi video chuyển cảnh, thông tin tương ứng cũng được cập nhật đồng bộ; danh sách cảnh tự động cuộn và tô sáng mục hiện tại.

• Tài liệu ngang có thể sử dụng bố cục xếp trên dưới.
• Tài liệu dọc có thể sử dụng bố cục đặt cạnh nhau.
• Bố cục được tập trung trong một tệp CSS để dễ dàng điều chỉnh thống nhất.

Chuẩn bị trước khi cài đặt

Trước khi bắt đầu, hãy xác nhận hệ thống đã cài đặt các công cụ sau:

• Node.js: phiên bản từ 18 trở lên.
• ffmpeg: dùng để xử lý video và đo điểm cắt cảnh.
• ffprobe: thường được cài cùng ffmpeg, dùng để đọc thông tin media.

Người dùng macOS có thể cài đặt qua Homebrew:

brew install node ffmpeg

Bạn cũng cần cài đặt ít nhất một trong hai công cụ Claude Code hoặc Codex. Tập lệnh cài đặt sẽ kiểm tra môi trường hiện tại và liên kết skill đến thư mục tương ứng đã tồn tại.

Cài đặt reelbench-skills

Clone và cài đặt tự động

Trước tiên, hãy clone kho lưu trữ rồi chạy tập lệnh cài đặt:

git clone https://github.com/eternityspring/reelbench-skills.git
cd reelbench-skills
./scripts/install.sh

Theo mặc định, tập lệnh sẽ dựa trên môi trường máy để liên kết mềm skill đến ~/.claude/skills/ và／hoặc ~/.codex/skills/.

Chọn mục tiêu cài đặt

Nếu chỉ muốn cài đặt cho một công cụ cụ thể, hãy sử dụng tham số tương ứng:

./scripts/install.sh --claude
./scripts/install.sh --codex

Lệnh đầu tiên chỉ cài đặt cho Claude Code, lệnh thứ hai chỉ cài đặt cho Codex.

Chỉ cài đặt một skill

Nếu hiện tại chỉ cần khả năng phân tích video, bạn có thể cài đặt theo tên:

./scripts/install.sh video-shots

Tương tự, bạn có thể chọn các skill khác có trong kho lưu trữ tùy theo nhu cầu thực tế.

Không sử dụng liên kết mềm

Mỗi skill đều độc lập, vì vậy bạn cũng có thể sao chép trực tiếp vào thư mục đích:

cp -r skills/video-shots ~/.claude/skills/

Cách sao chép đơn giản và trực tiếp, nhưng sau khi kho lưu trữ được cập nhật, bạn cần sao chép lại; còn liên kết mềm giúp các bản cập nhật được phản ánh ngay vào thư mục skill của Claude Code hoặc Codex.

Quy trình sử dụng cơ bản

Phân tích video hoàn chỉnh bằng video-shots

1. Xác nhận video-shots đã được cài đặt vào Claude Code hoặc Codex đang sử dụng.
2. Chuẩn bị tệp video cần phân tích.
3. Trong phiên hiện tại, yêu cầu rõ ràng sử dụng video-shots để phân tích video theo từng cảnh và nêu ngôn ngữ đầu ra mong muốn.
4. Sau khi quy trình hoàn tất, ưu tiên mở báo cáo HTML được tạo để kiểm tra cách chia cảnh, khung hình chính và kết quả chất lượng.
5. Nếu cần xử lý tiếp, có thể đọc dữ liệu JSON, Markdown hoặc đường cong chuyển động.

Bạn có thể sử dụng nội dung yêu cầu tương tự sau trong phiên:

Hãy sử dụng video-shots để phân tích video này theo từng cảnh, xuất thời lượng, cỡ cảnh, thể loại, chuyển động máy quay, hình ảnh và phân tích nhịp điệu, đồng thời kiểm tra các cổng chất lượng.

Ví dụ quảng cáo tiếng Anh trong kho lưu trữ sử dụng --lang en, nên nội dung báo cáo được tạo bằng tiếng Anh. Khi cần sản phẩm đầu ra bằng tiếng Anh, hãy nêu rõ ngôn ngữ trong tác vụ và tham khảo thiết lập tham số này.

Hiểu các sản phẩm phân tích

demo-report do kho lưu trữ cung cấp đến từ một phim ngắn AI dài 202.9 giây có tên 《啥是AI》. Ví dụ này nhận diện tổng cộng 53 cảnh, thời lượng cảnh trung bình là 3.83 giây, có 15.7 lần chuyển cảnh mỗi phút và vượt qua toàn bộ 15 cổng chất lượng.

Thư mục ví dụ thể hiện cách tổ chức điển hình của các sản phẩm đầu ra:

demo-report/
├── shots-report.html
├── shots.json
├── shots.md
├── track.json
└── frames/

• shots-report.html: báo cáo phân tích video tương tác độc lập, có thể mở trực tiếp bằng cách nhấp đúp.
• shots.json: dữ liệu chính của phân tích theo từng cảnh.
• shots.md: bảng cảnh ở định dạng Markdown.
• track.json: đường cong chuyển động thu được từ sai khác từng khung hình, làm bằng chứng đo lường máy.
• frames/: khung hình chính đầu và cuối của mỗi cảnh; ví dụ 53 cảnh có tổng cộng 106 hình ảnh.

Nên hoàn tất kiểm tra trực quan trong báo cáo HTML trước, sau đó sử dụng shots.json hoặc track.json tùy theo nhu cầu tự động hóa tiếp theo.

Sử dụng video-sync để tạo video hiển thị đồng bộ

1. Chuẩn bị video hoàn chỉnh và thông tin storyboard tương ứng.
2. Xác nhận video-sync đã được cài đặt.
3. Trong phiên Claude Code hoặc Codex, yêu cầu sử dụng skill này để tổng hợp video.
4. Chọn bố cục xếp trên dưới hoặc đặt cạnh nhau tùy theo tài liệu ngang hay dọc.
5. Sau khi tạo, kiểm tra chuyển cảnh, cập nhật thông tin, thao tác cuộn danh sách và tô sáng có đồng bộ hay không.

Nội dung yêu cầu có thể viết như sau:

Hãy sử dụng video-sync để tổng hợp video này với thông tin storyboard. Đồng bộ cập nhật thông tin khi chuyển cảnh, đồng thời để danh sách cảnh tự động cuộn và tô sáng.

Ví dụ trong kho lưu trữ trình bày kết quả tổng hợp một quảng cáo tiếng Anh dài 30 giây với thông tin storyboard gồm 5 cảnh, kích thước đầu ra là 1280×1296. Bạn có thể xem các tệp liên quan trong thư mục ví dụ demo-sync.

Mẹo nâng cao

Cập nhật nhanh bằng liên kết mềm

Nếu đã tạo liên kết mềm bằng tập lệnh cài đặt, chỉ cần thực hiện:

git pull

Nội dung cập nhật sẽ có hiệu lực ngay đối với các skill đã liên kết, không cần sao chép tệp lại. Cách này đặc biệt phù hợp để liên tục theo dõi phiên bản dự án.

Cài đặt theo nhu cầu để giảm ảnh hưởng đến môi trường

Chỉ sử dụng Claude Code thì thêm --claude, chỉ sử dụng Codex thì thêm --codex. Nếu chỉ xử lý tác vụ phân tích video, bạn cũng có thể chỉ cài đặt video-shots để giữ thư mục skill gọn gàng.

Ưu tiên kiểm tra bằng chứng máy đo

Khi nghi ngờ về kết quả phân tích, bạn có thể kết hợp đường cong chuyển động sai khác từng khung hình trong track.json với khung hình chính đầu và cuối của từng cảnh để kiểm tra lại. Dự án giao việc đo điểm cắt và thời lượng cho ffmpeg, giúp tách biệt phần có thể định lượng với phần do mô hình đánh giá.

Tận dụng báo cáo để kiểm tra nhanh

Khi phát video, hãy quan sát xem cảnh hiện tại có được tô sáng chính xác hay không, sau đó dùng tìm kiếm, lọc và sắp xếp để định vị cỡ cảnh, thể loại hoặc nhân vật cụ thể. Nhấp vào cảnh để chuyển đến thời điểm tương ứng, nhấp vào khung hình chính để xem ảnh lớn. Sau khi kiểm tra, hãy xem khu vực kiểm tra chất lượng để xác nhận tất cả đều đạt.

Điều chỉnh bố cục video-sync

Bố cục của video-sync được tập trung trong một tệp CSS. Khi cần thích ứng với các tỷ lệ khung hình khác nhau, bạn có thể bắt đầu điều chỉnh từ bố cục trên dưới cho tài liệu ngang hoặc bố cục trái phải cho tài liệu dọc, thay vì sửa đổi nhiều kiểu ở các vị trí khác nhau.

Gỡ liên kết mềm

Nếu không còn cần các skill này, bạn có thể thực hiện:

./scripts/install.sh --uninstall

Lệnh này dùng để hủy các liên kết mềm do tập lệnh cài đặt tạo ra.

Tổng kết

reelbench-skills đóng gói việc phân tích video và hiển thị storyboard đồng bộ thành các skill có thể sử dụng trong Claude Code và Codex. Với video-shots, bạn có thể nhận báo cáo tương tác kèm bằng chứng đo lường máy, khung hình chính và kiểm tra chất lượng; với video-sync, bạn có thể tạo video đồng bộ giữa chuyển cảnh và thông tin storyboard. Dự án có ít dependency, không cần API Key bổ sung, đồng thời hỗ trợ cập nhật bằng liên kết mềm và xem báo cáo ngoại tuyến, phù hợp để xây dựng quy trình phân tích video có thể kiểm tra lại.