minhhoasqtt-prog/hmhshare-mkt-bien-tap-vlog-hyperframes

Biên tập vlog bằng HyperFrames

Biến một video nói chuyện quay thô (kèm vài cảnh trám) thành video 16:9 gọn, trúng ý, màu đẹp, có chữ.

Triết lý gốc / Nguồn

• Walter Murch, Rule of Six (In the Blink of an Eye): cảm xúc 51% > câu chuyện 23% > nhịp 10% > đường mắt > 2D > 3D. Chọn đoạn theo cảm xúc và mạch chuyện trước, lỗi hình xử lý sau.
• Casey Neistat: mở → bối cảnh → nội dung → kết; jump cut có chủ đích; dùng nhiều cảnh trám.
• Talking-head: lời nói là xương sống (L-cut), cảnh trám phủ lên, punch-in che jump cut.
• Đã chạy thật: vlog quay trên xe 11:22 → 5:22, 23 đoạn, 29 khối chữ (plan mẫu ở references/vi-du-plan.json).

Khi nào dùng / KHÔNG dùng

• Dùng: video dài một người nói (vlog, chia sẻ, livestream ghi lại, quay trên xe) cần rút gọn + trám + chữ, khung ngang 16:9.
• Không dùng: short dọc 9:16 kiểu TikTok có phụ đề chạy từng chữ; video avatar AI / lồng tiếng; chỉ cần phụ đề mà giữ nguyên video (dùng /embedded-captions của HyperFrames).

Tiền điều kiện

Cài theo HUONG-DAN-CAI-DAT.md, rồi chạy node <skill>/scripts/kiem-tra-may.mjs phải ra đủ ✓.

• ffmpeg/ffprobe, Node ≥ 18, npx hyperframes (đã kiểm với 0.8.168–0.8.169).
• whisper-cli (whisper.cpp) + model ~/.whisper-models/ggml-large-v3-turbo.bin (đổi bằng biến WHISPER_BIN, WHISPER_MODEL).
• Mac dùng VideoToolbox nên cắt nhanh (~2 lần thời gian thực với 2.7K HEVC 10-bit); Windows/Linux tự chuyển sang libx264 (chậm hơn).
• Ổ đĩa trống ≥ 0,6 GB mỗi phút video ra + 3 GB. Lần render đầu tải chrome-headless-shell (~150 MB).
• Font Be Vietnam Pro có sẵn trong assets/fonts/ (giấy phép SIL OFL, không cần mạng).

Quy trình thực thi

S=<thư mục skill>/scripts (thường là .claude/skills/hmhshare-mkt-bien-tap-vlog-hyperframes/scripts) W=<thư mục làm việc>, ví dụ ~/vlog-lam-viec/<slug>. Media nặng để ở đây, KHÔNG để trong thư mục đồng bộ đám mây (Google Drive, OneDrive, Dropbox…), sẽ chậm và lỗi.

Bước 1 — Chuẩn bị (máy, ~1–3 phút).

node $S/01-chuan-bi.mjs --work $W --main "<video chính>" --broll "<trám1>,<trám2>,..."

Kết quả: probe.json, contact.jpg, loi-thoai.txt (mốc từng chữ), main_clean.wav, proxy cảnh trám hfproj/media/bNN*.mp4 + broll.json. Chạy lại thì bỏ qua phần đã có (--force để làm lại).

Bước 2 — AI biên tập (đọc kỹ references/chon-doan-bien-tap.md). Xem contact.jpg (vị trí người nói → tam_zoom, chỗ đặt chữ), đọc hết loi-thoai.txt, chốt khán giả + thông điệp (hỏi người dùng nếu chưa rõ), rồi viết $W/plan.json mục doan theo references/plan-json.md. Thử nhanh tổng thời lượng:

node $S/02-cat-doan.mjs --work $W --main "<video chính>" --chi-tinh   # chỉ in ban-cat.txt, không cắt

→ Cổng duyệt (người): nếu người dùng muốn duyệt trước, gửi bảng ban-cat.txt và dừng. Mặc định: làm tiếp, đưa bảng mạch vào báo cáo cuối.

Bước 3 — Cắt + lọc âm + soát chỗ nối (máy).

node $S/02-cat-doan.mjs --work $W --main "<video chính>"

Ra hfproj/media/main_cut.mp4/.wav, segs.json, kiem-tra-noi.json. Đoạn nào bị cảnh báo hụt chữ thì đối chiếu cut-words.json (Whisper hay báo nhầm), lỗi thật thì thêm lui_dau/them_cuoi rồi chạy lại.

Bước 4 — AI viết chữ + dựng composition. Đọc ban-cat.txt, viết plan.json mục chu (bám doan + sau), canh_tram (mặc định {"nhip":20}), rồi:

node $S/03-dung-hyperframes.mjs --work $W
cd $W/hfproj && npx hyperframes check --json        # phải: lint 0 lỗi, layout 0, contrast đạt hết
npx hyperframes snapshot --at <các mốc script in ra>  # AI XEM contact sheet: chữ xuống dòng xấu, che mặt, màu

Sửa plan/chữ → chạy lại 03 cho tới khi khung hình sạch (chữ dài thì rút gọn câu, đừng thu nhỏ font).

Bước 5 — Render + xuất (máy, ~1,5 lần thời lượng video trên Mac M1 Pro).

node $S/04-render-xuat.mjs --work $W --out "<thư mục kết quả>" --quality delivery

Kiểm thời lượng khớp, có tiếng, LUFS, ra soat.jpg, rồi chép video + du-an-hyperframes/ + plan/segs/lời thoại vào thư mục kết quả. AI xem soat.jpg lần cuối.

Bước 6 — Báo cáo. Trả người dùng: đường dẫn video, thời lượng trước/sau, bảng mạch theo mốc (đoạn giữ, ý chính), đã bỏ gì, muốn sửa thì sửa chỗ nào trong plan.json. Xoá cache render (xem Lưu ý).

Tham chiếu

• scripts/lib.mjs: ffmpeg/whisper/tìm cụm chữ, chọn bộ mã hoá theo máy.
• scripts/01-chuan-bi.mjs · 02-cat-doan.mjs · 03-dung-hyperframes.mjs · 04-render-xuat.mjs · kiem-tra-may.mjs.
• scripts/template.tpl: khung HTML + GSAP (9 loại chữ, punch-in, hoà cảnh trám, Ken Burns).
• references/plan-json.md: định dạng plan + bảng loại chữ · references/vi-du-plan.json: plan thật 23 đoạn / 29 chữ.
• references/chon-doan-bien-tap.md: luật chọn đoạn, khung mạch, nhịp hình.
• Tài liệu HyperFrames: https://hyperframes.heygen.com (nếu máy có sẵn skill hyperframes, hyperframes-cli thì đọc thêm).

Lưu ý / gotcha

• Mốc chữ Whisper trễ ~0,3–0,5s so với tiếng thật: script đã lùi điểm vào 0,3s; vẫn hụt thì thêm lui_dau.
• Đừng tạo proxy toàn bộ video gốc 2.7K/4K (11 phút mất ~40 phút): chỉ cắt các đoạn đã chọn (bước 3).
• Không để file .html thứ hai ở gốc hfproj/: HyperFrames báo multiple_root_compositions. Template nằm trong scripts/.
• Cảnh báo lint nested_structure_needs_subcomposition / timeline_track_too_dense là gợi ý tổ chức, bỏ qua được.
• Render ghi cache giải mã vào thư mục tạm của máy ($TMPDIR/hyperframes-extract-cache-* trên Mac/Linux, %TEMP% trên Windows; ~2 GB với 5 phút video): render xong thì xoá.
• Giai đoạn "Checking browser" kéo dài vài phút ở lần đầu là đang tải trình duyệt, không phải treo.
• Bóc lời có nhiều chữ sai: chữ trên màn hình phải viết đúng chính tả, không chép nguyên lời bóc. Phụ đề chạy toàn bài chưa có trong skill.
• Video HDR/LOG: chuyển SDR trước (bước 1 sẽ cảnh báo); bộ chỉnh màu realtime chỉ làm Rec.709.
• Thẻ nhớ camera phải còn cắm từ bước 1 tới hết bước 3 (bước 3 đọc lại file gốc). Tốt nhất chép video vào máy trước.
• Windows: đường dẫn có dấu cách thì luôn bọc trong ngoặc kép.

Output

<thư mục kết quả>/: <slug>.mp4, du-an-hyperframes/ (index.html + config, không kèm media), plan.json, segs.json, ban-cat.txt, loi-thoai.txt, kiem-tra-noi.json, broll.json, soat.jpg.