Revideo Scene Flow 이해하기

Revideo 씬은 TypeScript 제너레이터 함수다. yield 단위로 시간이 흐르고, yield*로 시퀀스·병렬 작업을 묶는다. 이 페이지에서 makeScene2D, yield, yield*, waitFor, chain, all의 정확한 의미를 다룬다.

🎬 씬의 기본 골격

import {Circle, makeScene2D} from '@revideo/2d';
import {createRef, waitFor} from '@revideo/core';

export default makeScene2D(function* (view) {
  const circleRef = createRef<Circle>();

  // (1) 노드 추가 — 단일 작업
  yield view.add(
    <Circle fill={'red'} size={100} ref={circleRef} />,
  );

  // (2) 시간 진행 — 2초 동안 x 200px 이동
  yield* circleRef().position.x(200, 2);

  // (3) 노드 제거
  circleRef().remove();

  // (4) 대기
  yield* waitFor(1);
});

function* 키워드가 핵심. 제너레이터 함수는 yield마다 실행이 멈췄다 재개되는 함수. Revideo는 이 메커니즘을 그대로 비디오 타임라인으로 사용한다.

📐 `yield` vs `yield*` vs `yield;`

패턴	의미	프레임
`yield view.add(...)`	노드 추가, 프레임 안 찍음 (yielded value가 promise라 대기만 함)	0 frames
`yield* waitFor(2)`	2초간 시간 진행	60 frames (30fps 기준)
`yield;`	빈 yield = 1 frame 진행	1 frame
`yield* tween(x, y, dur)`	트윈 애니메이션, `dur`초 동안 진행	dur × 30 frames

Revideo 내부 의사코드 (공식 문서):

let result = scene.next();
while (result.value) {       // yielded가 truthy(= promise)면
  if (isPromise(result.value)) {
    result = await result.value;  // 대기만, 프레임 안 찍음
  }
  result = scene.next();
}
drawFrame();                 // 빈 yield일 때만 프레임 그림

즉 yield마다 프레임이 생기는 게 아니라, yield* 또는 yield;(빈 yield)일 때만 프레임이 찍힌다. 이게 Revideo의 핵심 동작 원리.

🔗 `chain` / `all` — 시퀀스와 병렬

import {all, chain} from '@revideo/core';

// 순차: scale → 1초 대기 → rotation
yield* chain(
  circleRef().scale(40, 2),
  waitFor(1),
  circleRef().rotation(360, 2),
);

// 병렬: scale과 rotation 동시
yield* all(
  circleRef().scale(40, 2),
  circleRef().rotation(360, 2),
);

// 혼합: 병렬 2초 → 그 다음 다른 것
yield* chain(
  all(
    circleRef().scale(40, 2),
    circleRef().rotation(360, 2),
  ),
  circleRef().scale(60, 1),
);

함수	용도
`chain(g1, g2, ...)`	g1 끝나면 g2 시작 (순차)
`all(t1, t2, ...)`	모든 트윈 동시 시작 (병렬)

🌳 노드 추가 규칙

view.add(...)로 직접 추가 가능한 건 View2D만 (또는 그 안에 있는 노드)
<Circle>, <Rect>, <Img>는 View2D의 자식으로만 추가 가능
view.add(<>...</>)처럼 Fragment로 묶으면 여러 노드 한 번에 추가

// OK: Fragment로 묶어서 view에 직접 추가
yield view.add(
  <>
    <Rect width={100} height={100} fill={'red'} />
    <Txt text={'Hello'} />
  </>,
);

// OK: View2D 안에 노드들
yield view.add(
  <Layout>
    <Rect />
    <Img />
  </Layout>,
);

🛡️ `yield`의 약속 — promise는 await

view.add(...) 자체가 promise를 반환할 수 있다 (이미지 로딩, 폰트 로딩 등). yield를 붙이면 Revideo가 자동으로 await한다. 안 붙이면 경고가 뜬다:

Tried to access an asynchronous property before the node was ready

해결법: view.add 호출에는 항상 yield 붙이기. 안전하고 무해하다.

📋 실전 패턴 모음

패턴	코드
3초 대기	`yield* waitFor(3);`
페이드 인	`yield* node().opacity(1, 1);` (0→1, 1초)
위치 이동	`yield* node().position.x(200, 2);`
회전	`yield* node().rotation(360, 2);`
확대	`yield* node().scale(2, 1);`
노드 숨기기	`node().opacity(0, 0.5);` (0으로 페이드)
노드 제거	`node().remove();`
노드 교체	`node().remove(); yield view.add(<NewNode />);`

🎯 다음 단계

데이터로 영상个性化: Revideo Parameterized Videos → 다음 손자 페이지
첫 영상 만들기: Revideo Quickstart → 이전 손자 페이지
프로젝트 폴더: Revideo 프로젝트 구조 → 이전 손자 페이지

🔗 공식 리소스

공식 Scene Flow: https://midrender.com/revideo/docs/guide/understanding-scene-flow
Animations API: https://midrender.com/revideo/docs/animations (flow, signals, tweening 등 20+ 항목)

상위 문서: ← Revideo 시작하기 출처: Revideo 공식 문서 — Scene Flow 한글화 (2026-07-29) 공급사: Revideo (현 Midrender)

변경 이력

날짜	변경
2026-07-29	초안 작성 — yield/yield*/chain/all + 프레임 규칙 한글화
2026-07-29	메타데이터 블록을 본문 하단으로 이동