insaneyilin/html-video-demo

HTML 비디오 및 로컬 내레이션

재생 가능한 MP4, 자막, 수정 가능한 HTML 스토리보드 및 생성 구성을 제공합니다. 사용자의 현재 프로젝트, 자료, 음색 및 스타일을 기준으로 합니다. 이 스크립트는 어떤 AI 에이전트, 계정 또는 모델 서비스 API에도 바인딩되지 않습니다.

시작하기 전에

• 대상 프로젝트 설명, 기존 결과물 및 로컬 작업 규칙을 읽고 실제 기능과 데모 범위를 확인합니다. 계획된 기능을 이미 구현된 인터페이스처럼 보여주지 마십시오.
• 독립적인 비디오 프로젝트 디렉토리를 지정하고 원본 코드, 프로덕션 데이터 및 이전 버전 결과물을 복구할 수 있도록 유지합니다. 기존 비디오를 수정할 때는 먼저 최신 구성을 읽고 관련 출력을 백업합니다.
• 이미 확인된 음색은 그대로 사용합니다. 새 음색을 선택할 때는 우선 동일한 짧은 대본으로 동등한 음량으로 미리 들어봅니다. 이미 선택한 옵션을 사용자에게 다시 확인하도록 요구하지 마십시오.
• 처음 실행하거나 머신을 변경할 때는 환경 및 명령을 읽습니다. 이 패키지의 더빙 구현은 Apple Silicon / MLX가 필요합니다. Node 렌더링 진입점은 더빙 구현과 독립적입니다.

제작流程

1. 내용 결정. 시청자가 이해해야 할 작업을 인과 관계가 명확한 스토리보드로 연결합니다. 각 장면은 하나의 주요 정보를 전달하고, 내레이션은 구어체로, 화면은 핵심 텍스트를 유지합니다. 내용에 따라 장면 수와 총 시간을 결정하며, 고정된 9장면이나 2분 템플릿을 사용하지 않습니다.
2. 실제 자료 준비. 데모 데이터를 사용하여 인터페이스, 부분 스크린샷 또는 실제 작업을 캡처합니다. 브라우저 제어 방식은 현재 에이전트 및 프로젝트 요구 사항을 따릅니다. 화면 및 자료를 읽고, 다른 프로젝트의 스크린샷, 개인 정보 또는 내부 주소를 재사용하지 마십시오.
3. 음성 결정. project.json에서 음색, 스타일 및 언어를 구성합니다. 먼저 새 음색의 짧은 샘플을 듣고 일괄 생성합니다. 인접한 의미 단락으로 경계가 있는 이야기 그룹을 만들고 동일한 음색, 스타일 및 샘플링 매개변수를 사용합니다. 문장마다 무작위로 시드를 변경하지 말고 기본적으로 전체 텍스트를 무한 길이로 합성하지 마십시오. 그룹화 원칙은 내레이션 및 정렬을 참조하십시오.
4. 내용 및 타이밍 확인. 독립적인 ASR로 누락된 문장이나 중복을 찾고, 강제 정렬로 원본 텍스트를 찾습니다. 두 기능은 다릅니다. 정렬은 시간을 제공할 수 있지만 실제로 모든 텍스트를 올바르게 말했음을 증명할 수는 없습니다. 동음이의어, 영어 용어 및 마지막 몇 글자를 확인합니다.
5. 음성에 따라 화면 배치. 실제 일시 중지 지점에서 장을 나누고 마지막 글자가 완전히 끝나도록 하며 내용에 맞는 종료 시간을 남깁니다. 기본적으로 약 1초가 기술 설명의 시작점이 될 수 있습니다. 로컬 강조 및 작업 녹화는 음성 마커를 따르며, 이전 버전의 고정 초 수를 사용하지 않습니다.
6. html-video로 렌더링. 먼저 HTML 프레임 드롭을 확인한 다음 ContentGraph, ProjectOrchestrator 및 Hyperframes를 통해 내보냅니다. 외부 리소스는 로컬화되거나 임베드되어야 합니다. 애니메이션은 window.__hvPlayAll()을 사용하고, 폰트 로딩 중 조기 재생을 방지합니다. 프로토콜은 화면 및 자료를 참조하십시오.
7. 결과물 확인. MP4를 완전히 디코딩하고, 오디오 및 비디오 길이와 각 컷 지점의 오디오 트랙을 확인한 다음, 브라우저 재생, 탐색 및 화면을 확인합니다. WAV 또는 자막 파일만 확인하는 것으로는 최종 비디오가 올바른지 증명할 수 없습니다. 통과 후 로컬 미리보기, MP4, 자막 및 소스 파일을 제공합니다.

실행 가능한 진입점

모든 경로는 매개변수로 제공됩니다. 전체 필드는 프로젝트 형식을 참조하십시오. 아래 SKILL_DIR은 이 스킬 디렉토리를, DEMO_PROJECT는 독립적인 비디오 프로젝트를 나타냅니다.

python "$SKILL_DIR/scripts/audio.py" init --project "$DEMO_PROJECT"
# project.json을 편집하고, assets/를 준비합니다. 필요한 경우 먼저 audition을 실행합니다.
python "$SKILL_DIR/scripts/audio.py" validate --project "$DEMO_PROJECT"
python "$SKILL_DIR/scripts/audio.py" synthesize --project "$DEMO_PROJECT"
python "$SKILL_DIR/scripts/audio.py" check-text --project "$DEMO_PROJECT"
python "$SKILL_DIR/scripts/audio.py" align --project "$DEMO_PROJECT"
node "$SKILL_DIR/scripts/compose.mjs" --project "$DEMO_PROJECT"
node "$SKILL_DIR/scripts/verify.mjs" --project "$DEMO_PROJECT" --stage scenes
node "$SKILL_DIR/scripts/render.mjs" --project "$DEMO_PROJECT"
node "$SKILL_DIR/scripts/verify.mjs" --project "$DEMO_PROJECT" --stage export
node "$SKILL_DIR/scripts/serve.mjs" --project "$DEMO_PROJECT"

Node의 렌더링, 브라우저 확인 및 스크린샷 명령은 HTML_VIDEO_ROOT 또는 --html-video를 통해 설치된 html-video를 찾습니다. 격리된 환경의 Python을 사용하고 시스템 Python에 종속성을 설치하지 마십시오.

수정 및 문제 해결

• 문서 변경: 영향을 받는 그룹 재합성, 확인, 정렬, 빌드 및 렌더링. 이미지 또는 레이아웃 변경: 다시 빌드, 화면 확인, 렌더링. 음색 변경: 음성 및 타이밍流程 재수행.
• 음성 토큰 상한 도달 또는 출력 반복: 문제가 있는 그룹을 줄이고 이미 확인된 나머지 그룹을 우선 유지합니다. 불완전한 결과를 성공으로 전달하지 마십시오. 연속 실패 시 진단 및 사용 가능한 자료를 보존하고 특정 차단 사항을 설명합니다.
• 끝음절 불완전: "원본 합성 → 디코딩 길이 → 정규화 → 연결 → MP4" 순서로 문제를 해결합니다. 무음을 추가해도 이미 잘린 음절을 복구할 수 없습니다. 현재 스크립트는 Qwen3-12Hz에 패딩 없는 길이 이상이 감지된 경우에만 로컬 수정을 활성화하며, 타사 설치 디렉토리는 수정하지 않습니다. 끝음절 회귀 및 오디오 문제 해결을 읽으십시오.
• 이번 작업의 음색, 색상, 그룹 수 또는 특정 라이브러리의 결함을 모든 작업의 고정 요구 사항으로 만들지 마십시오. 다른 TTS를 사용하거나 기존 더빙이 있는 경우 동일한 시간, 샘플 및 내보내기 검증 제약을 유지합니다.
• 결과물을 외부 플랫폼에 게시, 업무 자료 업로드 또는 다른 사람에게 알리는 것은 기본 로컬 제작 단계가 아닙니다. 사용자의 실제 승인에 따라 수행됩니다.