pireel/pireel 딥다이브
— 서버 없이 브라우저 안에서 도는 AI 비디오 에디터, 그걸 MCP로 에이전트가 운전한다

1프로젝트 한 줄 요약

Pireel의 정체를 정확히 잡으려면 세 단어를 기억하면 된다. backend-free(백엔드리스) · talking-head(토킹헤드 영상) · agent-drivable(에이전트가 운전 가능). README 원문은 이렇게 시작한다 — "An open-source, backend-free AI video editor for talking-head video."

이 저장소는 사실 사설 모노레포에서 단방향으로 동기화된 공개 미러다(README 명시, 단일 스쿼시 커밋). 그래서 "브라우저에서 즉시 되는 것"과 "호스티드 서비스 전용인 것"의 경계가 뚜렷하다 — 이 구분은 4장에서 정확히 짚는다. 먼저, 왜 3일 만에 400개 넘는 별을 받았는지부터 보자.

2왜 주목받는가

Pireel이 트렌딩에 오른 건 "또 하나의 AI 영상툴"이라서가 아니다. 시장에 널린 AI 비디오 에디터들과 설계 철학 자체가 다른 지점이 세 곳 있다. 하나씩 뜯어보자.

3기술 스택 전체 지도

Pireel은 pnpm 워크스페이스 모노레포(루트 name pireel-studio v0.1.0, "type":"module")다. 서버가 없으므로 스택의 무게중심이 전부 프론트엔드 + 브라우저 API에 쏠려 있다는 게 특징이다. 계층별로 훑어보자.

빌드 · 언어 툴링

프론트엔드 (UI 계층)

AI / 에이전트

Vercel AI SDK(ai ^6.0.168 + @ai-sdk/react ^3.0.176)가 내부 챗의 useChat + streamText 툴콜링을 담당한다. 그리고 이 챗의 툴 실행면이 외부 MCP 에이전트와 정확히 같은 실행면을 공유한다는 게 핵심 설계다(4장 참고).

미디어 · 비디오 (★핵심 계층)

상태 · 데이터

fast-json-patch ^3.1.1 + jsondiffpatch ^0.7.6로 undo/버전 diff를, nanoid ^5.1.11로 ID를 만든다. 컴포지션(편집 상태)은 JSON 패치로 관리돼 실행 취소가 가볍다.

백엔드? → 사실상 없음

OSS 셸의 유일한 "서버"는 Vite 개발 플러그인 apps/studio-oss/local-assets-plugin.ts다. node:fs/node:crypto로 디스크 기반 업로드 라우트(content-addressed sha256)를 흉내 낸다 — 호스티드의 R2+CDN을 로컬로 대체하는 개발 편의 장치일 뿐이다. 실제 프로덕션 백엔드(Cloudflare Workers + Durable Objects + R2)는 이 repo에 없다. 검증 결과 "백엔드리스"는 사실이다 — 편집/프리뷰/타임라인/자막/익스포트가 전부 클라이언트다.

4아키텍처 심화 분석

Pireel의 아키텍처는 세 개의 렌즈로 보면 전부 이해된다. ① 패키지가 어떻게 층을 이루는가, ② 편집 상태(컴포지션)를 어떻게 표현해 프리뷰와 익스포트가 픽셀 단위로 같아지는가, ③ 외부 AI 에이전트가 어떻게 열린 브라우저 탭을 원격 조종하는가. 순서대로 파고든다.

① 패키지 레이어 — 순수 엔진을 UI가 감싼다

핵심은 studio-engine이 React도 DB도 provider도 모르는 순수 로직이라는 점이다. 컴포지션 모델·자막 렌더·MCP 프로토콜·비디오 렌더가 전부 여기 있고, UI(studio-ui)는 이 엔진을 React로 감쌀 뿐이다. 이 분리 덕분에 같은 엔진 코드가 브라우저에서도, (호스티드의) 서버 오프라인 툴에서도 재사용된다.

② 컴포지션 데이터 모델 — "블록은 데이터, 렌더는 템플릿+테마"

composition-core.ts의 구조는 연속 비디오(track 0) + 멀티트랙 오버레이 블록이다. 여기서 영리한 결정 하나: 블록은 HTML을 저장하지 않고 데이터만 저장한다.

// 블록은 "무엇을" 담을지만 선언한다 (어떻게 그릴지는 나중에)
{
  templateId: "metric-card",       // 어떤 템플릿?
  slots: { title: "MRR", value: "$42k" }, // 슬롯 채우기
  startSec: 3.2, durationSec: 2.5,   // 언제부터 얼마나
  trackIndex: 1, box: {...}          // 어느 트랙, 어디에
}

실제 HTML/애니메이션은 조립(assemble) 시점에 템플릿 레지스트리 + 테마(CSS 변수)로 동적 렌더된다. 그래서 테마를 바꿔도 블록 데이터는 그대로고, CSS 변수만 교체하면 룩이 바뀐다. 또 에이전트는 자유형 HTML을 통째로 생성할 필요 없이, templateId와 slots만 선언적으로 채우면 된다(자유형이 필요하면 custom 템플릿 사용).

비디오 트랙은 VideoShot[](각 {srcStart, srcEnd, treatment, src?})로, 편집 타임라인 = 각 클립의 소스 구간을 이어붙인 것이다. treatment는 full / punch-in / corner-br / split-l 같은 프레이밍이고, src가 설정되면 외부에서 삽입한 B-roll 클립이 된다.

③ 프리뷰 = 익스포트 = "같은 소스" (WYSIWYG의 진짜 비밀)

대부분의 에디터에서 "미리보기"와 "실제 출력"이 미묘하게 다른 건, 둘을 다른 코드로 그리기 때문이다. Pireel은 이걸 원천 봉쇄한다 — 프리뷰와 익스포트가 글자 그대로 같은 iframe을 구동한다.

익스포트의 마법은 "브라우저 자신을 래스터라이저로 쓰는" 트릭이다. HTML 오버레이(#root)를 SVG foreignObject로 감싸 <img>로 만들면, 브라우저(Blink)가 그걸 이미지로 그려 준다. 그 이미지를 캔버스에 얹고, 그 캔버스를 WebCodecs로 인코딩한다. viewBox는 레이아웃 좌표, width/height는 출력 해상도로 잡아 4K에서도 벡터가 재래스터화되어 선명하다.

④ MCP "에이전트가 운전" — 3계층 브리지

가장 독창적인 부분이다. 툴 실행이 브라우저에 깊게 묶여 있어(React state 클로저, MediaPipe, 프리뷰 iframe) 서버에서 실행할 수 없다. 그래서 Pireel은 서버가 실행하지 않고 "열린 탭으로 포워딩"한다. 아래 그림에서 ✅는 이 repo에 있는 것, ❌는 호스티드 전용이라 빠진 것이다.

왜 Durable Object(DO)인가? 툴 실행이 특정 브라우저 탭에 묶이므로, 유저 하나당 DO 하나(idFromName(userId))를 두고 소켓을 단일 활성으로 유지한다(새 탭이 열리면 옛 탭을 code 4000으로 kick). 외부 에이전트의 툴콜은 이 DO를 거쳐 열린 탭의 runStudioTool로 전달되고, 그 결과가 다시 소켓으로 돌아온다.

// use-agent-bridge.ts — 툴콜을 열린 탭에서 "직렬로" 실행
queue = queue.then(async () => {
  let out;
  try {
    out = tool === 'get_state'
      ? { ok: true, state: getState() }
      : await runTool(tool, input ?? {});  // 내부 챗과 동일
  } catch (e) {
    out = { ok: false, error: String(e) };
  }
  sock.send(JSON.stringify({ id, ...out }));       // 결과를 소켓으로 반환
});

편집 파이프라인 — 원본 영상이 완성작이 되기까지

여기서 로컬로 도는 것(analyze_visual = MediaPipe, 익스포트 = WebCodecs)과 유료 LLM이 필요한 것(analyze_narration, add_graphics)이 명확히 나뉜다. 후자를 "brief 계약"으로 외부 에이전트에 넘기는 게 BYO-brain의 핵심이다.

5디렉토리 구조 해부

구조가 말해 주는 것: 관심사가 칼같이 분리돼 있다. studio-engine은 순수 로직(React 无관)이라 테스트·재사용이 쉽고, studio-ui는 그걸 React로 감싼 표현 계층이다. 눈여겨볼 파일 크기의 불균형 — hyperframes-workbench.tsx가 무려 7,116줄이다. 워크벤치 하나가 state·프리뷰·타임라인·runStudioTool을 전부 쥐고 있는 "God component"에 가까운데, 이건 편집 상태가 서로 촘촘히 얽혀 있어 쪼개기 어려운 에디터의 숙명이기도 하다.

6학습 포인트

실습 아이디어 (짧게)

가장 먼저 packages/studio-engine/src/caption-fx.ts를 열어 drawCaptionFx(ctx, o, t, ...)가 어떻게 시각 t 하나로 자막 프레임을 그리는지 따라가 보라. 그다음 client-export.ts의 헤더 주석(오버레이를 SVG foreignObject로 굽는 과정)을 읽으면, "프리뷰와 익스포트가 왜 같은가"가 손에 잡힌다. 이 두 파일만으로도 Pireel의 렌더링 철학이 완성된다.

7시스템 / 실행 요구사항

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

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

10핵심 키워드 사전

11참고 링크