Headless Chrome & Puppeteer

• Puppeteer는 DevTools Protocol을 통해 Chrome 브라우저를 프로그래매틱하게 제어하는 Node.js 라이브러리
• Headless Chrome은 Headless 모드로 실행되는, GUI 없이 백그라운드에서 동작하는 Chrome 브라우저 인스턴스
• 스크린샷 캡처, PDF 생성, DOM 조작, 네트워크 감시 등을 자동화하는 브라우저 자동화 도구

해당 개념이 필요한 이유

• Hyperframes의 렌더링 엔진은 Puppeteer로 Headless Chrome을 구동하여 각 프레임을 캡처한다
• HTML Composition을 Chrome에 로드 → 프레임별 seek → 화면 캡처 → FFmpeg 인코딩이라는 파이프라인의 핵심 축
• 일반 스크린샷과 달리, Chrome의 BeginFrame API를 활용해 결정론적(deterministic) 프레임 캡처가 가능하다

AS-IS — 전통적 비디오 렌더링

sequenceDiagram
    autonumber
    participant 편집기 as 비디오 편집 SW
    participant GPU
    participant 출력 as MP4

    편집기->>GPU: 실시간 렌더링 (wall-clock 의존)
    GPU->>출력: 프레임 인코딩
    Note over 편집기,출력: 실행 환경(GPU, OS)에 따라 결과 달라질 수 있음

TO-BE — Hyperframes의 Puppeteer 기반 렌더링

sequenceDiagram
    autonumber
    participant Engine as @hyperframes/engine
    participant Puppeteer
    participant Chrome as Headless Chrome
    participant Page as Composition HTML

    Engine->>Puppeteer: 브라우저 인스턴스 요청
    Puppeteer->>Chrome: DevTools Protocol로 Headless Chrome 실행
    Engine->>Chrome: Composition HTML 로드
    Chrome->>Page: window.__hf (seek protocol) 대기

    loop 각 프레임 (0 ~ totalFrames)
        Engine->>Page: window.__hf.seek(frame / fps)
        Page->>Page: GSAP timeline.totalTime() → DOM 업데이트
        Engine->>Chrome: BeginFrame API로 프레임 캡처
        Chrome-->>Engine: PNG 버퍼 반환
    end

    Engine->>Engine: FFmpeg로 인코딩 → MP4

Headless Chrome이란

일반 Chrome 브라우저에서 화면 표시(GUI) 부분만 제거한 것. 렌더링 엔진(Blink), JavaScript 엔진(V8), 네트워크 스택 등은 모두 동일하게 동작한다. Chrome 112부터 headless 모드는 headful Chrome과 동일한 코드베이스를 공유한다.

두 가지 바이너리가 존재한다:

바이너리	용도
chrome --headless	일반 Chrome을 headless 모드로 실행
chrome-headless-shell	경량 전용 바이너리 — Hyperframes Docker 모드에서 사용

Puppeteer의 역할

Puppeteer는 Chrome과 사람 사이의 리모컨 역할을 한다:

Node.js 코드 → Puppeteer API → DevTools Protocol (WebSocket) → Chrome

주요 기능:

기능	설명
페이지 탐색	URL 로드, 새 탭 열기
DOM 조작	page.evaluate()로 페이지 내 JS 실행
스크린샷	page.screenshot()으로 현재 화면 PNG 캡처
CDP 세션	Chrome DevTools Protocol에 직접 명령 전송

BeginFrame API — 결정론적 캡처의 핵심

일반 스크린샷(Page.captureScreenshot)은 Chrome이 자체 타이밍으로 화면을 갱신한 “스냅샷”을 찍는 것이다. 반면 BeginFrame API는 엔진이 Chrome의 렌더링 사이클을 직접 제어한다:

방식	타이밍 제어	결정론성
Page.captureScreenshot	Chrome 자체 (wall-clock)	비결정론적
HeadlessExperimental.beginFrame	엔진이 직접 제어	결정론적

Hyperframes 엔진의 캡처 흐름:

1. seek(time) 호출 → DOM/애니메이션 상태 업데이트
2. beginFrame(frameTimeTicks, interval) 호출 → Chrome이 정확히 이 시점의 프레임을 합성(composite)
3. 합성된 프레임 데이터를 PNG 버퍼로 반환

이 방식 덕분에 CPU 속도, OS, 시스템 부하에 관계없이 동일한 입력 → 동일한 픽셀 출력이 보장된다.

window.__hf — Seek Protocol

Hyperframes 엔진과 Composition HTML 사이의 유일한 계약:

interface HfProtocol {
  duration: number;                    // 전체 길이(초)
  seek(time: number): void;            // 해당 시점으로 이동
  media?: HfMediaElement[];            // 미디어 요소 선언
  transitions?: HfTransitionMeta[];    // 트랜지션 메타데이터
}
 
// 페이지에서 이 객체를 노출하면 엔진이 캡처를 시작한다
window.__hf = { duration, seek, media };

엔진은 애니메이션 프레임워크가 무엇인지 전혀 모른다. GSAP이든 CSS든 Three.js든, seek()이 결정론적 출력을 보장하기만 하면 된다.

Hyperframes에서의 브라우저 관리

엔진은 Puppeteer 브라우저 인스턴스를 **풀링(pooling)**하여 재사용한다:

• acquireBrowser() — 풀에서 브라우저 인스턴스를 가져옴 (없으면 새로 실행)
• releaseBrowser() — 사용 후 풀에 반환
• 캡처 모드를 자동 감지: Linux에서 chrome-headless-shell이 있으면 beginframe, 아니면 screenshot 폴백

참고 문서

• Puppeteer Documentation
• Chrome Headless Mode
• Hyperframes Rendering Guide