video-quality-auditor

name	video-quality-auditor
description	Audit code-first cho Remotion source và render plan (ưu tiên overlay readability + safe-area), gom toàn bộ lỗi mỗi pass rồi áp dụng batch fix một thể, lặp tối đa 3 pass và xuất báo cáo TOML + HTML tiếng Việt.

Video Quality Auditor

Quy tắc đầu ra (BẮT BUỘC)

• Mọi mô tả do AI sinh ra trong report phải viết bằng tiếng Việt có dấu.
• Key, enum, path, tên field TOML/JSON giữ nguyên tiếng Anh.
• Mỗi pass phải gom đủ lỗi trước khi fix (fix_mode = batch_all_findings).
• Không vượt quá max_audit_passes = 3.

Mục tiêu

Audit theo hướng code-first trên source Remotion và plan hiện có để cải thiện chất lượng overlay:

1. Audit toàn bộ vấn đề của pass hiện tại.
2. Tạo 1 gói fix duy nhất cho cả pass.
3. Áp dụng fix + render lại.
4. Lặp cho đến khi đạt chuẩn hoặc tối đa 3 pass.

Khi nào dùng

• User yêu cầu kiểm tra/chỉnh chất lượng overlay nhanh trước khi render full video.
• Cần tự cân lại font_size, top_percent, offset, tilt để tránh lỗi hiển thị.
• Cần báo cáo tiếng Việt để review nhanh trước khi chốt final.

Input tối thiểu

• --job jobs/<job_id>
• source/render_plan.toml
• remotion/src/composition.tsx
• remotion/src/Root.tsx
• (khuyến nghị) source/audit_config.toml

Artifact đầu ra

• logs/audit_pass_0N.toml (machine-readable findings + batch fix)
• logs/audit_report_vi_pass_0N.html (human-readable tiếng Việt)
• logs/audit_report_vi_final.html (tổng hợp cuối)

Quy tắc pass/fix

1. Chạy audit_video.py để ghi findings (rule cứng + tính toán deterministic).
2. Chỉ khi có lỗi severity = "error" mới chạy apply_fix_batch.py.
3. Mỗi pass chỉ áp dụng một batch fix.
4. Sau fix có thể chạy lint/typecheck trước; render full chỉ khi cần xác nhận cuối.
5. Dừng nếu:
   • Không còn lỗi mức error, hoặc
   • Đã đến pass 3.

Script tiện ích

# Pass 1: Audit deterministic + HTML
.venv/bin/python skills/video-quality-auditor/scripts/audit_video.py \
  --job jobs/<job_id> \
  --pass-index 1

.venv/bin/python skills/video-quality-auditor/scripts/render_html_report.py \
  --job jobs/<job_id> \
  --pass-index 1

# Áp dụng batch fix (nếu còn lỗi error)
.venv/bin/python skills/video-quality-auditor/scripts/apply_fix_batch.py \
  --job jobs/<job_id> \
  --pass-index 1

Mô hình hybrid (khuyến nghị)

• Script xử lý phần cứng: validate schema, safe-area math, range checks, xuất report chuẩn.
• AI Agent xử lý phần mềm: chọn chiến lược fix tối ưu, patch code đồng bộ giữa render_plan.toml, Root.tsx, composition.tsx.

Quy ước đánh giá

• error: phải fix trước khi coi là pass.
• warning: ghi nhận để người vận hành quyết định.
• info: chỉ ghi chú.

Scope mặc định profile overlay_readability_safearea

• Safe-area cứng 9:16:
  • x >= 100, y >= 100, x + w <= 980, y + h <= 1720
• Font size hợp lý cho short-form:
  • 28 <= font_size <= 72
• Tilt hợp lý:
  • abs(tilt_deg) <= 15
• Contrast tối thiểu:
  • text trắng nền đen hoặc text đen nền trắng (mức cơ bản)

Ngoài phạm vi

• Không thay đổi nội dung script/storyline.
• Không tự thay đổi asset nguồn.
• Không tự thêm stage mới ngoài pipeline chuẩn.