Mr-funny/hbg-classical-poem-silk-video

Agent Skill for turning Chinese classical poems into vertical Chinese-art videos with ImageGen stills, Docker I2V, calligraphy captions, retained ambience, BGM and final MP4 QA.

무엇인가요

hbg‑classical‑poem‑silk‑video 는 Codex 또는 Claude Code와 같은 AI 코딩 에이전트용 에이전트 스킬(플러그인)로, 중국 고전 시를 세로형(1080 × 1920)의 "실크 비디오" — 즉, 짧고 고화질의 중국화 스타일 애니메이션 — 로 변환합니다. 이 스킬은 시를 분석하고 장면으로 분할하며, 내부 ImageGen 모델로 정지된 중국화 스타일 프레임을 생성하고, 이를 Gemini 기반의 이미지→비디오(I2V) Docker 컨테이너에 전달합니다. 워터 리플, 새, 말 발걸음 등의 움직임을 추가하고, 붓자국 자막을 오버레이하며, 원본 모델이 생성한 환경음과 선택적 배경 음악을 혼합한 후, 최종적으로 QA 검증된 MP4를 생성합니다.

어떻게 받을 수 있나요

리포지토리는 명령줄에서 직접 실행 가능한 install.sh 스크립트를 포함하고 있습니다. 이 스크립트는 사용자의 에이전트(Codex 또는 Claude Code)를 감지하고, 스킬 파일을 에이전트의 글로벌 skills 디렉터리(기본값 ~/.codex/skills/classical-poem-silk-video)로 복사합니다. 예시 단일 명령어:

curl -fsSL https://raw.githubusercontent.com/Mr-funny/hbg-classical-poem-silk-video/main/install.sh | sh

또한 수동으로 리포지토리를 클론하고 skill/classical-poem-silk-video 폴더를 적절한 위치로 복사할 수도 있습니다.

스킬 사용 방법

설치 후 자연어로 에이전트에게 지시하세요. 예시:

$classical-poem-silk-video 를 사용하여 《枫桥夜泊》을 제작하세요.
4행 시는 1행당 1장의 장면으로, 화면 톤은 시의 정서에 따라 변화시키세요. 카메라를 고정하고, 달빛, 물결, 까마귀, 이슬, 어부의 불빛이 그림 속에서 자연스럽게 움직이게 하세요.
AI 환경음은 유지하고, 붓글씨로 한 글자씩 나타나게 하며, 장면 간에는 자연스러운 크로스페이드 전환을 적용하세요.

에이전트는 다음을 수행합니다:

분석 – 시의 시대, 계절, 이미지, 감정의 흐름을 식별합니다.
스토리보드 작성 – 짧은 시는 1행당 1장, 긴 시는 2행당 1장으로 구성합니다.
중국화 스타일 선택 – 시의 분위기에 따라 인화, 공비, 청루, 말타기 등 스타일을 선택합니다.
정지 프레임 생성 – 내장된 ImageGen 모델을 사용하며, 세로형 붓자국 자막을 위한 안전 영역을 확보합니다.
Gemini I2V Docker 컨테이너 (gemini-flow-suite) 호출 – 카메라를 고정하고, 의도한 객체만 움직이도록 정교하게 설계된 움직임 프롬프트를 사용해 프레임을 애니메이션화합니다.
자막 추가 – Ma Shan Zheng 붓자국 폰트를 사용해 오른쪽 열부터 왼쪽 열로 자막을 배치하고, 글자별로 나타나게 합니다.
오디오 혼합 – 모델이 생성한 환경음은 유지하고, 선택적으로 사용자 제공 BGM을 겹쳐 넣습니다.
크로스페이드 전환(비디오 및 오디오 모두)을 적용하고, 최종 QA 스크립트를 실행해 블랙 프레임, 오디오 갭, 올바른 프레임 수, 시각적 일관성(예: 추가 새, 변형된 말 다리 등)을 확인합니다.

최종 결과물은 1080 × 1920, 30 fps, H.264 + AAC MP4로 공유할 수 있습니다.

주요 기술 구성 요소

구성 요소	기능
시 분석기	시대, 장소, 계절, 이미지, 행동, 감정 곡선을 추출합니다.
스토리보드 엔진	줄을 그룹화합니다(≤4행 → 1행당 1장; 더 긴 경우 → 2행당 1장).
스타일 선택기	인화, 공비, 청산, 말타기 등 스타일을 전환하면서도 통일된 중국화 DNA를 유지합니다.
정지 프레임 생성기	에이전트 내장 `ImageGen` 모델을 호출하며, 세로 자막용 안전 영역을 확보합니다.
Docker I2V	Gemini Flow Suite 컨테이너(`gemini-flow-suite`)를 실행해 프레임을 제어된 국부적 움직임을 가진 짧은 비디오 클립으로 변환합니다.
움직임 프롬프트 템플릿	고정된 앵커, 국부적 움직임 영역, 안정된 종료, 환각 방지 규칙의 4단계 프롬프트로, 그림을 의도치 않게 "재작성"하는 것을 방지합니다.
자막 렌더러	SIL‑OFL Ma Shan Zheng 붓자국 폰트를 사용해 세로 2열 레이아웃, 글자별로 나타나게 합니다.
오디오 믹서	모델 생성 환경음 유지, 사용자 제공 BGM을 선택적으로 혼합하고 크로스페이드 전환과 동기화합니다.
최종 QA 스크립트	`ffprobe`, `ffmpeg` 필터(`blackdetect`, `silencedetect`, `volumedetect`) 및 선택적 타임스탬프 TSV를 사용해 움직임 일관성, 프레임 무결성, 인코딩 사양을 검증합니다.

누구에게 적합한가요

SNS(Weibo, Douyin, Bilibili)용 AI 생성, 문화적으로 정확한 짧은 영상이 필요한 콘텐츠 크리에이터.
고전 시의 애니메이션 도해를 찾는 교육자.
텍스트 → 이미지 → 비디오 → 오디오의 다모달 생성을 시연할 수 있는 준비된 스킬이 필요한 AI 에이전트 개발자.
제어된 이미지→비디오 생성을 위한 프롬프트 엔지니어링에 관심 있는 연구자.

라이선스 및 준수 사항

모든 스크립트, 스킬 정의, 문서는 MIT 라이선스 하에 배포됩니다.
포함된 Ma Shan Zheng 폰트는 SIL Open Font License 1.1 하에 제공됩니다.
이 스킬은 비밀 토큰, 쿠키, 사용자 제공 미디어를 전혀 처리하지 않습니다. 사용자가 제공하는 시 텍스트와 선택적 BGM만을 사용합니다.

빠른 시작 체크리스트

위의 단일 명령어로 스킬을 설치합니다.
Docker가 실행 중이며 gemini-flow-suite 이미지가 사용 가능한지 확인합니다(README에 따라).
skill/classical-poem-silk-video/scripts/check_prerequisites.sh 를 실행해 환경을 검증합니다.
에이전트에게 원하는 시의 비디오 생성을 요청합니다.
MP4가 생성되면, 선택적으로 final_media_qa.sh 를 실행해 품질을 확인합니다.

예시 출력

리포지토리는 《钱塘湖春行》(8행 → 4장)에 대한 전체 길이 예제를 포함하고 있습니다. 최종 비디오(약 32초, 1080 × 1920)는 Releases 페이지에 있으며, docs/article.md 에서 설명됩니다.