| name | vidgen-clips |
| description | STAGE 3 của pipeline vidgen — GEN CLIP HÀNG LOẠT qua flow-agent (omniflash): ảnh khung đầu từng cảnh (T2I miễn phí) → duyệt → I2V/T2V/R2V/FL (tốn credit), tự poll + tải + xóa watermark + resume theo manifest. Dùng khi cần "gen clip các cảnh", "gen lại cảnh 5", "chạy tiếp phần gen video", "batch gen video AI", hoặc khi vidgen-flow gọi STEP 3. Cần Chrome + extension Flow Agent đã kết nối. |
Vidgen Clips (storyboard → clip từng cảnh, resume được)
Kinh tế của stage này: ảnh miễn phí, video tốn credit. Vì vậy image-first:
gen ảnh khung đầu → user duyệt ảnh (rẻ) → mới I2V (đắt, 1 lần/cảnh). Mọi tiến độ ghi vào
project.json sau TỪNG cảnh — đứt giữa chừng chạy lại không mất gì, không gen trùng.
WORKFLOW V2 — SHOT là đơn vị sản xuất (cảnh shot-first khai shots[] separate trong manifest):
- Master-first rồi derive:
scene-images gen ảnh khung đầu shot MASTER trước (anchor refs)
→ NGƯỜI DUYỆT master (image.approved=true trên shot) → chạy lại: shot con gen với
ref = frame master + anchor nhân vật (không gian/ánh sáng từ master, danh tính từ anchor gốc).
scene-clips gen clip TỪNG shot (i2v từ ảnh shot đã duyệt; duration Veo lấy mức 4/6/8/10
nhỏ nhất đủ) → đủ shot thì TỰ stitch (trim theo duration lấy đoạn ĐẦU, cắt cứng nội cảnh)
ra 04_clips/sceneNN.mp4 đúng hợp đồng cũ — assemble không cần biết shot tồn tại.
Regen shot lẻ xong chạy stitch-shots --project ... --scene N để ghép lại.
ĐƯỜNG GEN per shot theo số thực thể cần neo (ngân sách 3 ref/generation — bảng đầy đủ + luật
ưu tiên slot: project-schema.md mục "Ba đường gen"):
- Shot thường (≤2 nhân vật mặt rõ + location) → i2v từ ảnh đã duyệt (Bước 1-2 dưới).
- Micro-cut timestamp (
shots[] kiểu from/to) → r2v + anchor (nhân vật > hero-prop >
location; ref_prev thay location anchor khi cắt đổi góc cùng không gian).
- Cảnh/shot ĐÔNG (
composite: true) → compose-frame ghép dần từng thực thể vào khung đầu
(miễn phí, mỗi lượt ≤3 ref TÍCH LŨY) → duyệt khung → i2v như thường:
$PY $GEN compose-frame --project projects/<tên> --scene 4
Khung cuối lệch → soi từng lượt 03_images/sceneNN_comp_K.png tìm lượt hỏng, sửa rồi chạy lại.
LUẬT chất lượng: mọi khung đầu (master, shot con, composite, khung chain) phải NGƯỜI duyệt
trước khi đốt credit.
Craft prompt (đọc trước khi gen/soi): công thức prompt Veo 5 phần, vựng camera/cỡ cảnh, negative
prompt tránh AI-tell, cách né chặn nội dung → references/veo-prompt-craft.md. Veo 3 còn sinh
audio (SFX/ambience) ngay từ prompt — hữu ích cho cảnh không lời đọc.
PY=~/.venv/claude/bin/python
GEN=.agents/skills/vidgen-clips/scripts/flowgen.py
Điều kiện chạy
- Chrome mở + extension Flow Agent kết nối (script tự mở tab Flow, tự retry 3 lần).
gates.script_lock = true (kịch bản đã duyệt); gen hàng loạt cần thêm character_lock = true
(script tự chặn, --force chỉ dùng cho clip thử ở stage 2).- Port 9222/8100 rảnh (bận =
python -m cli.api hoặc flowgen cũ còn treo; flowgen nay báo rõ cách kill).
- Đang batch thì hạn chế sửa tay
project.json: script re-load + chỉ ghi field nó sở hữu
(image/clip) nên sửa field/cảnh KHÁC vẫn an toàn — chỉ tránh sửa đúng cảnh đang gen dở.
Bước 1 · Ảnh khung đầu (miễn phí — vòng lặp duyệt)
$PY $GEN scene-images --project projects/<tên>
$PY $GEN scene-images --project projects/<tên> --scene 3 7
Script tự lấy anchor nhân vật (đúng góc angle) làm ref, tối đa 3 ref/cảnh.
Trình ảnh cho user theo LÔ (mọi cảnh một lượt) — ưng cảnh nào set image.approved=true
cảnh đó, chưa ưng thì sửa prompt trong manifest rồi gen lại đúng cảnh ấy.
Bước 2 · Gen clip hàng loạt (TỐN credit — báo số lượng trước khi chạy)
Trước khi chạy, nói rõ với user: sẽ gen N clip ≈ N lần credit. Rồi:
$PY $GEN scene-clips --project projects/<tên>
$PY $GEN scene-clips --project projects/<tên> --scene 5 --regen
Mỗi cảnh: submit → poll (~44s-vài phút) → tải → xóa watermark → ghi manifest.
Lỗi tự retry 1 lần; vẫn hỏng → status: "failed", chạy tiếp cảnh khác (không chết cả batch).
Xong batch báo user danh sách failed để quyết: gen lại / sửa prompt / bỏ cảnh.
Frame-chaining (chuyển cảnh LIỀN MẠCH): cảnh nào đặt link_prev: true trong manifest thì
scene-clips tự trích khung cuối NÉT nhất của clip cảnh trước (chọn theo độ nét, chống
motion-blur) → dùng làm khung đầu cảnh này → không gian/chuyển động nối liền, chỉ cần xfade nhẹ là
mượt. Ràng buộc: gen TUẦN TỰ (cảnh trước phải xong trước — cùng run hoặc run trước), nên tránh
--scene N lẻ làm đứt chuỗi. Chỉ bật cho cặp cảnh CÙNG mạch/bối cảnh; đổi cảnh hoàn toàn thì để false
và dùng transition biên tập (cut/match cut) ở Stage 4.
Duyệt khung chain TRƯỚC khi đốt credit (luật khung-đầu-phải-qua-mắt-người):
$PY $GEN extract-chain --project projects/<tên>
Khung xấu (mờ, AI-tell, sai bối cảnh) → xoá file để trích lại hoặc tắt link_prev cảnh đó.
scene-clips thấy file đã tồn tại thì DÙNG LẠI (không trích đè); chạy thẳng scene-clips không
extract trước vẫn được nhưng sẽ in ⚠ "chưa qua duyệt".
ref_prev (đồng bộ ánh sáng/layout khi CẮT ĐỔI GÓC cùng không gian, mode r2v): frame cuối nét
cảnh trước vào slot ref, THAY location anchor. 2 luật an toàn: danh tính LUÔN từ anchor gốc
(chống trôi photocopy qua nhiều đời frame); chỉ chain/ref từ clip đã qua qc-clips (chống AI-tell
lây lan). Khác link_prev: không ép liền mạch chuyển động, chỉ mượn không gian.
Bước 3 · QC CONTINUITY trên clip thật (chốt chặn cuối trước ráp — máy trích, Claude soi, người quyết)
$PY $GEN qc-clips --project projects/<tên>
Rồi Claude Read qc_clips/ledger.md + các frame PNG, đối chiếu theo checklist trong ledger:
mặt khớp anchor? trang phục khớp state.wardrobe? prop đúng desc registry? ánh sáng khớp
time_of_day VÀ khớp cảnh liền kề cùng location? layout bối cảnh liền? AI-tell? → báo user danh
sách lệch per cảnh (lệch gì, so với nguồn sự thật nào) — NGƯỜI quyết regen (mandate chất lượng:
credit đổi lấy đồng bộ, regen không tiếc nhưng người bấm nút).
Soi tay bổ sung mỗi clip: ☐ chuyển động không giật ☐ không chữ lạ trong hình ☐ đúng aspect
☐ không còn dấu watermark.
Clip hỏng → sửa prompt cảnh đó → --scene N --regen; hoặc CHỈ lỗi nhỏ → sửa bằng v2v (mục "Lệnh lẻ").
Regen xong CHẠY LẠI qc-clips cho cảnh đó (regen là xúc xắc — có thể lệch kiểu khác).
Watermark Veo sót → delogo trước khi ráp (bài học ranh giới, vị trí CỐ ĐỊNH): dù pipeline đã "xóa
watermark", Veo/Flow vẫn để sót ngôi sao 4 cánh (sparkle ✦) góc dưới–phải. Vị trí ổn định trên khung
gốc 720×1280: delogo=x=572:y=1128:w=92:h=104. Trước khi assemble, delogo mọi clip (backup gốc):
ffmpeg -i raw.mp4 -vf "delogo=x=572:y=1128:w=92:h=104" -c:v libx264 -crf 18 out.mp4. Soi lại 2-3 clip
sau delogo (crop góc dưới–phải) để chắc phủ đúng — Flow đổi version có thể dịch vị trí. Regen clip là phải
delogo LẠI (clip mới có watermark).
Lệnh lẻ (ngoài pipeline)
flowgen.py cũng dùng độc lập được: t2i (ảnh nhanh), upload-image, clip --mode t2v|i2v|r2v|fl|v2v
(1 clip lẻ). Xem $PY $GEN --help.
Sửa clip đã có (v2v) — khỏi gen lại từ đầu, tiết kiệm credit:
clip --mode v2v --video-id <media_id> --prompt "đổi X thành Y" (media_id lấy từ
scenes[].clip.media_id trong manifest), hoặc --video-file clip.mp4 (upload video local rồi sửa).
Sự cố hay gặp
| Hiện tượng | Xử lý |
|---|
| Extension không kết nối | Mở Chrome, đăng nhập Flow, chờ badge xanh |
No media in response | Prompt bị chặn — viết lại prompt trung tính hơn |
500 Failed to download LẶP ≥2 lần cùng 1 cảnh | Veo chặn NGẦM nội dung ảnh (người trong suốt/ma/spirit, phát sáng xuyên thấu…). KHÔNG retry quá 2-3 lần — đổi concept ảnh cảnh đó, hoặc cứ để failed: vidgen-assemble tự fallback Ken Burns từ ảnh tĩnh |
| Hết credit | Báo user; ảnh (T2I) vẫn gen được, chỉ video dừng |
| TIMEOUT khi poll | Reload tab Flow, chạy lại — manifest giữ tiến độ |
| Nhầm port khi dùng API server | Bridge callback ở 8100, FastAPI ở 8000 — đừng đoán: lsof -p <pid> + đọc /openapi.json lấy route thật |
Đặc tính output Flow (biết trước đỡ ngạc nhiên): clip trả về 720×1280 (không phải
1080×1920 — assemble tự scale cover lên) và Veo tự gắn audio gốc vào clip (assemble tự -an).
