html-video 딥다이브
— 코딩 에이전트에게 "영상 만들어줘"라고 말하면 진짜 MP4가 나오는 메타레이어

1프로젝트 한줄 요약

한 문장으로 이 프로젝트가 뭘 하는지부터.

html-video = "영상 제작을, 영상 편집기가 아니라 '코딩 에이전트'에게 시키는 오케스트레이션 도구". 보통 모션 그래픽 영상을 만들려면 After Effects를 배우거나, Remotion·Motion Canvas 같은 코드 기반 영상 엔진의 고유한 작성법(DSL)을 익혀야 한다. html-video는 그 사이에 에이전트라는 한 겹을 끼워 넣어, 사람은 자연어로 지시만 하고 실제 "어떤 엔진으로, 어떤 템플릿에, 어떤 내용을 채울지"는 에이전트가 결정하게 한다. 결과물은 웹 화면이 아니라 디스크에 떨어지는 실제 .mp4 파일이다.

핵심을 한 번 더 못 박자. html-video가 파는 가치는 "또 하나의 영상 엔진"이 아니라 ① 여러 엔진을 갈아끼울 수 있는 어댑터 구조, ② 코딩 에이전트를 영상 제작의 두뇌로 쓰는 워크플로, ③ 글/레포 링크 한 줄을 통째로 영상으로 바꾸는 '소스→영상' 파이프라인이다. 모든 게 내 컴퓨터에서 돌아가고(로컬), 렌더링 횟수당 과금이 없으며, Apache-2.0이라 상업 작업에 넣어도 된다.

2왜 주목받는가

TrendShift 일간 23위 — 갓 공개된 신생 레포가 급부상한 배경.

공개 직후 빠르게 성장 중인 신생 프로젝트인데도 트렌딩에 올랐다. 별 개수가 아니라 '개념의 신선함'과 'AI 코딩 에이전트 생태계의 흐름'에 정확히 올라탄 케이스다. 다섯 가지로 정리한다.

① "에이전트가 영상을 만든다"는 발상 자체의 화제성

2025~2026년은 코딩 에이전트(Claude Code·Cursor·Codex)가 폭발한 시기다. html-video는 이 에이전트들을 코드가 아니라 '영상'을 뽑는 도구로 재활용한다. "내가 이미 쓰는 에이전트에게 영상까지 시킬 수 있다"는 메시지가 개발자 타임라인에서 즉시 먹혔다.

② 링크 한 줄 → 영상: 진입 장벽을 0에 가깝게

가장 많이 쓰는 기능은 "기사·레포 링크를 던지면 해설 영상이 나온다"이다. 서버가 URL을 대신 가져와(server-side fetch) 본문을 마크다운으로 펴고, 그걸 영상의 실제 재료로 쓴다. 위챗 공중계정(WeChat 公众号)처럼 로그인 없이 서버 렌더되는 글도 그대로 처리된다. "복붙도 필요 없다"는 점이 강력하다.

③ 벤더 락인 없는 오픈소스 — 로컬·무과금·Apache-2.0

상용 HTML→영상 서비스(클라우드 렌더 + 클립당 과금)와 정면으로 대비된다. html-video는 렌더가 전부 내 머신에서 일어나고, 시트(좌석) 제한·기여자 협약·렌더당 요금이 없다. 영상 양산이 잦은 팀에게 비용 구조가 매력적이다.

④ 'Open Design' 패밀리의 모션 버전 — 검증된 팀

제작사 nexu-io는 디자인 영역에서 에이전트 메타레이어를 표방한 Open Design, 정적 HTML 산출물용 HTML Anything을 운영하는 팀이다. html-video는 그 같은 철학("에이전트 + 다(多)엔진 메타레이어")을 영상이라는 새 축으로 확장한 자매 프로젝트라, 기존 생태계의 관심을 자연히 흡수했다.

⑤ '엔진 중립' 설계가 주는 미래 보장

기본 엔진은 Hyperframes이며, Remotion 어댑터(adapter-remotion)는 실제 구현 코드가 존재하나 README에는 아직 Planned로 표시된다(2026-06-05 기준). Motion Canvas·Manim 어댑터는 로드맵 항목이다. 어댑터 하나를 추가하면 모든 템플릿·에이전트·스튜디오가 공짜로 그 엔진을 얻는 구조라, "엔진 전쟁에서 어느 편에 설지" 고민하는 사람들에게 안전한 선택지로 비친다.

3기술 스택 전체 지도

package.json · pnpm-workspace.yaml · 8개 패키지에서 뽑아낸 실제 구성.

html-video는 웹 백엔드+프론트엔드가 한 저장소에 섞인 TypeScript 모노레포(monorepo)다. 언어 구성은 HTML 89.7%(=대부분이 템플릿 영상 파일), TypeScript 6.6%, JavaScript 3.6%로, "코드보다 콘텐츠(템플릿)가 많은" 도구형 레포의 전형이다. 크게 ⓐ 모노레포 토대 ⓑ 코어 도메인 ⓒ 에이전트 런타임 ⓓ 렌더 엔진 어댑터 ⓔ 스튜디오 UI ⓕ 외부 서비스 여섯 축으로 읽으면 된다.

ⓐ 모노레포 토대 — pnpm Workspaces + Biome

ⓑ 코어 도메인 — core · content-graph

ⓒ 에이전트 런타임 — runtime

@html-video/runtime은 사용자 PATH에 깔린 코딩 에이전트 CLI를 감지(detect)·실행(spawn)·스트리밍(stream)한다. README 기준 14개 백엔드를 지원하며, 아래는 대표 6개다(전체 목록: Windsurf CLI·Trae CLI·Gemini CLI·Grok Build·Qwen Code·OpenCode·GitHub Copilot CLI·Aider 등 포함).

ⓓ 렌더 엔진 어댑터 — adapter-hyperframes

ⓔ 스튜디오 UI + CLI — project-studio · cli

@html-video/cli는 html-video 명령어와 스튜디오 HTTP 서버 + 소스 페칭(URL/레포 가져오기)을 담는다. @html-video/project-studio는 브라우저에서 도는 스튜디오 UI(채팅·템플릿 갤러리·프레임 편집·사운드트랙·내보내기)다. 스튜디오는 http://127.0.0.1:3071에서 열린다.

ⓕ 외부 서비스 (선택)

영상에 음악·내레이션을 입히는 MiniMax(배경음 생성 + TTS)는 옵션이다. Settings → Audio에서 키를 넣으면 export 시 ffmpeg가 음성 아래로 음악을 깔아(ducking) MP4에 섞는다. 키가 없어도 나머지 기능은 그대로 작동한다.

4아키텍처 심화 분석

README의 How-it-works + content-graph 스키마 기반 — 링크 한 줄이 MP4가 되는 전 과정.

html-video의 파이프라인은 여섯 단계로 이뤄진다. 소스 페칭 → 에이전트 루프 → 콘텐츠 그래프 → 프레임별 HTML → 엔진 렌더 → ffmpeg. 이 중 ②~④가 '메타레이어'의 심장이다 — 에이전트는 '무슨 장면을(스토리보드)'을 정하고, 엔진은 '어떻게 그릴지(렌더)'만 정해서, 둘이 서로의 영역을 침범하지 않는다.

단일 프레임 영상은 콘텐츠 그래프를 건너뛰는 빠른 경로(fast path)를 탄다 — 템플릿 하나, HTML 하나, 곧장 렌더. 네트워크 호출은 ①의 소스 페칭과 ⑥의 사운드트랙 둘뿐이고, 나머지는 전부 로컬이다.

① 어댑터 패턴 — 엔진을 '한 칸의 부품'으로

이 프로젝트의 설계 정수는 하나의 render(input, ctx) 계약이다. 어떤 렌더 백엔드든 이 인터페이스만 만족하면 어댑터가 된다. 그래서 새 엔진을 추가하면 모든 템플릿·모든 에이전트·스튜디오 전체가 그 엔진을 공짜로 얻는다. 위 파이프라인에서 ⑤번 박스만 갈아끼우면 ②~④(스토리보드·에이전트 루프)는 손대지 않아도 된다.

② 콘텐츠 그래프 — 영상의 '대본'을 그래프로 표현

다중 장면 영상의 핵심 자료구조다. 에이전트의 1라운드가 이 그래프를 만들고, 2라운드가 그걸 읽어 프레임 HTML을 그린다. 스키마는 단순하다.

interface ContentGraph {
  schemaVersion: 1;
  intent: 'single-frame' | 'explainer' | 'data-viz'
        | 'promo' | 'comparison' | 'other';
  synopsis?: string;
  nodes: Array<EntityNode | DataNode | TextNode>;
  edges: Array<{ from: string; to: string;
    kind: 'sequence' | 'contrast' | 'dependency';
    reason?: string }>;
}

여기서 영리한 부분은 엣지의 종류마다 의미가 다르다는 점이다.

③ 위상정렬 — 그래프를 '재생 순서'로 펴기

콘텐츠 그래프는 방향이 있는 비순환 그래프(DAG)다. topoSort(graph)는 이 그래프를 한 줄의 프레임 재생 순서로 변환한다. dependency 엣지는 반드시 지키고, sequence 엣지는 가능하면 따르고, contrast는 무시한다. 그 결과로 "1,500자 기사 → 장면마다 한 논점을 담은 다중 장면 해설 영상"이 만들어지고, 모든 줄이 원문의 무언가로 추적된다.

④ 에이전트 2라운드 프로토콜 — JSON과 HTML 두 블록

스튜디오는 에이전트에게 단일 프레임 빠른 경로와 다중 프레임을 모두 가르친다. 다중 프레임일 때 에이전트는 두 종류의 코드 블록을 내보낸다: json#content-graph(스토리보드 1개)와 노드마다 html#<nodeId>(프레임 HTML). 서버는 이를 파싱해 자동으로 writeContentGraph + writeFrameHtml을 호출한다. 그래프가 없으면 단일 프레임 경로로 우아하게 되돌아간다(graceful fallback).

5디렉토리 구조 해부

packages/ 8개가 각각 파이프라인의 어느 부품인지.

레포 루트에는 모노레포 설정(package.json·pnpm-workspace.yaml·tsconfig.base.json·biome.json), 두 언어의 README, 그리고 흥미롭게도 CLAUDE.md(코딩 에이전트용 작업 메모)가 있다. 알맹이는 packages/ 8개와 templates/ 21개이며, 패키지 이름만 봐도 4절의 파이프라인과 맞아떨어진다.

템플릿은 '에이전트가 읽는 부품'이다

21개 템플릿은 잡동사니가 아니라, 각자 template.html-video.yaml manifest로 자기를 설명하는 자기완결 단위다. 스튜디오가 시작할 때 이 manifest들을 스캔한다. manifest에는 ① 용도(category·tags·best_for), ② 출력 사양(해상도·종횡비·fps·길이), ③ 입력 슬롯(inputs JSON 스키마), ④ 라이선스 출처(SPDX id + attribution 플래그)가 담긴다. 그래서 에이전트는 HTML을 열지 않고도 manifest만 보고 템플릿을 고르고 채울 수 있다.

6학습 포인트 (기술별)

이 레포를 교재 삼아 무엇을, 어떻게 배울 수 있나.

🧩 ① 어댑터/플러그인 패턴으로 확장 가능한 시스템 설계

"하나의 인터페이스, N개의 백엔드"는 실무에서 가장 자주 쓰는 확장 설계다. 이 레포는 render(input, ctx) 한 계약으로 엔진을 갈아끼우는 깔끔한 예제를 제공한다.

실습 아이디어: adapter-hyperframes가 어떤 입력을 받아 어떤 출력을 내는지 타입을 추적하고, "내가 새 엔진을 붙이려면 최소 무엇을 구현해야 하나"를 한 페이지로 정리해 보기.

🗺️ ② IR(중간 표현) + 위상정렬로 '의미'를 다루기

콘텐츠 그래프는 "비정형 텍스트 → 구조화된 그래프 → 순서가 있는 산출물"이라는, 컴파일러·데이터 파이프라인에 두루 통하는 패턴이다. content-graph 패키지는 의존성이 0이라 순수 알고리즘 학습용으로 최적이다.

실습 아이디어: topoSort를 직접 다시 구현해 보고, dependency/sequence/contrast 세 엣지의 처리 차이를 단위 테스트로 검증. DAG에 사이클을 일부러 넣어 validate가 어떻게 막는지 확인.

🎥 ③ 헤드리스 브라우저 녹화 + ffmpeg 인코딩 파이프라인

Playwright로 크로미움을 띄워 화면을 프레임 단위로 잡고, ffmpeg로 webm→mp4(libx264) 인코딩·concat·오디오 mux를 하는 흐름은 '화면을 영상으로 만드는' 모든 작업의 토대다. 스크린샷 자동화, E2E 테스트 녹화에도 그대로 응용된다.

실습 아이디어: 간단한 GSAP 애니메이션 HTML 한 장을 만들고, Playwright로 N프레임 캡처 → ffmpeg로 mp4 만들기를 처음부터 손으로 해보기(이 레포의 어댑터를 안 쓰고).

🤖 ④ 에이전트 오케스트레이션 — CLI를 프로그램으로 부리기

runtime 패키지는 외부 CLI(claude --print, codex exec 등)를 자식 프로세스로 띄우고 stdin/stdout으로 대화하는 실전 코드다. "LLM을 API가 아니라 로컬 CLI로 부린다"는 요즘 패턴의 좋은 표본.

실습 아이디어: Node의 child_process.spawn으로 아무 CLI나 띄워 stdin에 프롬프트를 흘리고 stdout을 스트리밍 받아 보기. 그다음 ACP가 이걸 어떻게 표준화하는지 비교.

📦 ⑤ pnpm 워크스페이스 모노레포 운영

workspace:* 상호 참조, pnpm -r build 일괄 빌드, tsconfig.base.json 상속, Biome 단일 설정 — 여러 패키지를 한 저장소로 굴리는 실전 셋업이 한눈에 보인다.

실습 아이디어: 패키지 2개짜리 미니 모노레포를 만들어 한쪽이 다른 쪽을 workspace:*로 참조하게 하고, 루트에서 한 번에 빌드·타입체크가 도는지 확인.

📜 ⑥ 라이선스 출처를 '데이터'로 관리하기

각 템플릿 manifest에 SPDX id와 attribution 플래그를 박아 "라이선스 클린을 구조적으로 보장"하는 접근은 오픈소스 운영의 좋은 모범이다. 단순 주석이 아니라 기계가 읽는 메타데이터로 출처를 추적한다.

7하드웨어 / 시스템 요구사항

GPU는 필요 없다 — 대신 'CLI 환경'이 핵심.

이미지 생성 모델과 달리 html-video는 GPU가 필요 없다. 신경망을 직접 돌리지 않고, 브라우저 렌더와 ffmpeg 인코딩이 작업의 무게중심이라 평범한 노트북에서도 충분하다. 대신 '환경 세팅' 항목이 몇 가지 있다.

3줄로 시작

pnpm install
pnpm -r build
node packages/cli/dist/bin.js studio   # http://127.0.0.1:3071 에서 스튜디오 열림

CLI 점검 명령도 있다. doctor는 깔린 에이전트·엔진을 감지하고, search-templates는 의도로 템플릿을 찾는다.

node packages/cli/dist/bin.js doctor
node packages/cli/dist/bin.js search-templates --intent "github stars race" --top 3

8직접 해볼 수 있는 실습 과제

난이도별 5개 — 클론만으로 끝내지 말고 손을 움직여 보자.

9관련 기술 심화 학습 로드맵

이 레포를 제대로 씹어먹기 위한 4주 코스.

10핵심 키워드 사전

이 문서·레포에 등장한 용어를 한자리에.

11참고 링크

원문으로 더 깊이 파고들 때.