cosmicstack-labs/lazy-frames

Lazy Frames

Lazy Frames는 타입이 지정된 JSON 명세로부터 비디오를 렌더링합니다. 컴포지션은 spec.json 파일이며, 각 장면(scene)은 타이밍, 콘텐츠, 스타일을 선언합니다. CLI는 이 명세를 결정론적이고 픽셀 완벽한 MP4로 변환합니다. 코어 렌더러는 클라우드나 키가 필요 없습니다. 검토된 플러그인은 명시적으로 선언된 외부 서비스를 사용할 수 있으며, 생성된 미디어는 결정론적 렌더링 전에 로컬로 캐시됩니다.

현재 CLI 릴리스: [email protected].

• browser-frame, ui-callout, 그리고 플랫/뎁스 parallax 장면에서 캡처된 웹사이트 미디어는 기본적으로 중앙 크롭됩니다. 피사체가 다른 앵커를 필요로 하는 경우에만 params.position을 재정의하세요.
• capture, check, gen, preview, render 명령어는 stderr에 실시간 단계를 보고합니다. Render는 프레임 백분율을 보고합니다. --json 옵션을 사용하면 stdout은 깨끗한 기계 판독 가능 JSON을 유지합니다.

1. 프로젝트 상태로 시작

상태	작업
spec.json이 있는 기존 프로젝트	명세를 읽고, 편집을 수행하거나 요청된 작업을 실행합니다. 라우팅을 건너뜁니다.
웹사이트 URL이 포함된 새 요청	website-promo 워크플로(§ 3)로 라우팅합니다.
텍스트 브리핑이 포함된 새 요청	cinematic 워크플로(§ 3)로 라우팅합니다.
기존 푸티지가 포함된 새 요청	edit 워크플로(§ 3)로 라우팅합니다.
불명확한 경우	한 가지 질문을 합니다: "특정 웹사이트, 주제/브리핑, 또는 기존 비디오 푸티지에 관한 것인가요?"

2. 사전 요구 사항

node --version   # >= 20
ffmpeg -version  # 필수
python3 --version   # Python 3; Windows에서는 `python`도 괜찮습니다.
ls "/Applications/Google Chrome.app"  # macOS; Windows는 Program Files에 있는 Chrome을 사용하거나 CHROME_PATH를 설정하세요.

npm으로 설치:

npm install lazy-frames
npx lazy doctor

또는 소스에서 빌드:

npm install && npm run build

환경 확인:

node packages/cli/dist/index.js doctor

Doctor는 Node 플랫폼/메모리, Python 버전 + 계층, 제공자(절차적 이미지, 뎁스, 음악, TTS) 가용성을 보고합니다. 로컬 내레이션은 tts.say(macOS say 또는 Windows SAPI)를 사용합니다. 외부 제공자는 범위가 지정된 플러그인으로 설치됩니다. image.mlx-photoreal을 사용할 수 없는 경우(16GB 미만 시스템에서 예상됨), 대신 절차적 이미지 생성기가 사용됩니다. 여전히 시네마틱 스틸을 생성하지만 포토리얼은 아닙니다.

플러그인 및 외부 제공자

ElevenLabs는 기본적으로 포함되지만, 네트워크 사용 전에 여전히 프로젝트 범위의 승인이 필요합니다. 사용자가 제공자 또는 스토리텔링 기능을 요청하면, 레지스트리를 검색하고 상태와 권한을 검사한 후 승인 또는 설치에 대해 물어보세요:

node packages/cli/dist/index.js plugin search tts
node packages/cli/dist/index.js plugin info elevenlabs
node packages/cli/dist/index.js plugin install elevenlabs -p projects/cine

마켓플레이스 스캐폴드는 설치될 수 있지만, 검토된 어댑터가 배송될 때까지 실행할 수 없습니다. 임의의 패키지 URL을 설치하거나 프로젝트 파일에 API 키를 저장하지 마세요. ElevenLabs는 환경 변수 ELEVENLABS_API_KEY를 읽습니다. 레지스트리: https://lazy-frames.cosmicstack.ai/plugins/index.json

3. 워크플로

website-promo

입력: URL. 출력: 사이트 자체 캡처된 비주얼로 구축된 프로모/쇼케이스 MP4.

# 1. 사이트 캡처 (@2x 스크린샷, 팔레트, 텍스트, 글꼴, 로고)
node packages/cli/dist/index.js capture https://example.com projects/acme

# 2. 생성된 시작자 명세 + 캡처된 자산 검토
cat projects/acme/spec.json
ls projects/acme/assets/sites/example.com/

# 3. 필요한 경우 명세 편집 (장면, 텍스트, 타이밍, 전환 조정)

# 4. 유효성 검사 + 게이트 실행
node packages/cli/dist/index.js snapshot projects/acme --update
node packages/cli/dist/index.js check projects/acme

# 5. 렌더링
node packages/cli/dist/index.js render projects/acme

캡처 명령어는 다음을 기록합니다:

• assets/sites/<domain>/hero.png + full.png (2x DPR 스크린샷)
• assets/sites/<domain>/ledger.json (팔레트, 글꼴, 텍스트 블록, 메타데이터)
• 캡처된 콘텐츠로 구축된 5개 장면이 포함된 시작자 spec.json
• 스크린샷 장면은 명세가 크롭 앵커를 재정의하지 않는 한 명시적으로 { "x": "center", "y": "center" }를 사용합니다.

cinematic

입력: 텍스트 브리핑 또는 주제. 출력: 생성된 스틸, 뎁스-패럴랙스, 내레이션, 음악, SFX가 포함된 30–60초 시네마틱 클립.

# 1. 절차적 스틸 + 일치하는 뎁스 맵 생성
node packages/cli/dist/index.js gen image -p projects/cine --seed 21 --style ridge --palette "#070B14,#F59E4C,#F4F7FB" --name ridge-01
node packages/cli/dist/index.js gen image -p projects/cine --seed 42 --style dune --palette "#070B14,#7FB7D9,#F4F7FB" --name dune-01

# 2. 생성된 자산을 참조하는 spec.json 작성 (references/spec-format.md 참조)

# 3. 장면 연결 내레이션 초안 작성, 그런 다음 선택적 오디오 자산 생성
node packages/cli/dist/index.js script projects/cine --apply
node packages/cli/dist/index.js gen music -p projects/cine --mood calm --bpm 90 --bars 12 --seed 21
node packages/cli/dist/index.js gen tts -p projects/cine --text "모든 프레임이 로컬에서 계산됩니다." --name n1

# 4. 유효성 검사 + 렌더링
node packages/cli/dist/index.js snapshot projects/cine --update
node packages/cli/dist/index.js check projects/cine
node packages/cli/dist/index.js render projects/cine

edit

입력: 기존 푸티지 (MP4) + 브리핑. 출력: 오버레이, 그레이딩, 전환이 포함된 비디오로 합성된 푸티지.

푸티지 파일을 참조하는 video-layer 장면과 제목 및 전환을 위한 타이포그래피/분위기 장면이 포함된 명세를 작성합니다. 엔진은 비디오 시킹(머신별 결정론적 프레임 추출)을 소유합니다. video-layer 매개변수는 references/scene-types.md를 참조하세요.

4. 에이전트 계약

모든 워크플로에서 에이전트의 작업:

1. 입력 리서치 (사이트 읽기, 브리핑 이해, 푸티지 검사).
2. spec.json 생성 또는 개선 — 유효한 타입 지정 명세 (references/spec-format.md 참조).
3. 요청 시 내레이션 스크립트 생성 (lazy script <project> --apply), 그런 다음 장면 연결 비트 검토.
4. 필요한 경우 자산 생성 (lazy gen image, lazy gen music, lazy gen tts).
5. lazy check 실행 및 모든 오류 수정. 경고는 조언용입니다.
6. lazy snapshot --update 실행하여 회귀 기준선 설정.
7. lazy check 다시 실행 — 스냅샷 + 시크 결정론 게이트가 통과해야 합니다.
8. lazy preview 실행하고 URL을 사용자에게 전달. 수정할지 렌더링할지 질문.
9. 승인 후에만 렌더링. lazy render — 사용자가 확인하기 전에는 절대 실행하지 않음.
10. 출력 확인: 파일이 존재하고, 비어 있지 않으며, 예상 길이인지 확인.
11. 출력 경로 + sha256 보고.

절대 규칙

• 사용자 승인 전에는 절대 렌더링하지 마세요. 항상 미리보기에서 멈춥니다.
• lazy check를 절대 건너뛰지 마세요. 스키마 오류, 누락된 자산, 비결정론을 잡아냅니다.
• 새 프로젝트에서 첫 lazy check 전에 항상 lazy snapshot --update를 실행하세요.
• .lazy/를 절대 편집하지 마세요. 생성된 파일입니다. spec.json을 편집하고 다시 렌더링하세요.
• 검토되지 않은 플러그인을 설치하거나 제공자 자격 증명을 프로젝트 파일에 저장하지 마세요. 레지스트리와 환경 변수를 사용하세요.
• 명세에서 자산을 프로젝트 상대 경로로 참조 (예: assets/gen/ridge-01.png).
• 장면은 순차적이며 선택적 중복이 있습니다. 중복 + 페이드/디졸브 = 크로스페이드입니다.
• 모든 타이밍은 밀리초 단위입니다. 시작 시간은 컴포지션 시작부터 절대적입니다.
• 팔레트 규칙: palette[0] = 배경, palette[1] = 강조, palette[2] = 전경.
• 너비/높이는 짝수여야 합니다 (h264 yuv420p 요구 사항).
• 글꼴은 번들로 제공됩니다: Inter (본문) 및 Space Grotesk (제목). 외부 글꼴 없음.
• 진행 상황은 stderr에 속합니다. --json을 사용하는 명령어는 stdout을 최종 JSON 결과용으로 예약합니다.

5. 주요 개념

결정론

동일한 명세 + 동일한 머신 = 바이트 동일 MP4 (sha256으로 확인). 세 가지 Chrome 플래그가 이를 강제합니다: --jitless (V8 인터프리터 전용), --use-angle=swiftshader (소프트웨어 렌더링), 그리고 런타임에서의 정수 픽셀 변환 반올림. CSS 서브픽셀 텍스트 렌더링은 세션 간 비결정적입니다 — 런타임은 모든 변환을 정수 픽셀로 스냅합니다.

게이트

lazy check는 두 개의 차단 게이트를 실행합니다:

• 스냅샷 회귀: 키프레임(장면 중간점 + 전환 중간점)을 렌더링하고, 픽셀을 해시하고, snapshots/baseline.json과 비교합니다. 차이 = 장면 + 타임스탬프가 있는 오류입니다.
• 시크 결정론: 하나의 브라우저 세션에서 5개의 샘플링된 타임스탬프를 두 번 렌더링하고, 해시를 비교합니다.

오디오

오디오는 명세에서 선언적입니다 (narration, music, sfx). 렌더러는 캐노니컬 WAV 오디오를 생성 및 캐시한 후, ffmpeg를 통해 믹싱합니다:

• 내레이션: 로컬 say 또는 설치된 TTS 플러그인, startMs에 배치되거나 sceneId + offsetMs에 고정
• 음악: seed로 시드된 절차적 신디사이저 (코드 패드 + 퍼커션), 비디오 길이만큼 반복
• SFX: 합성된 whoosh/hit/rise/boom, atMs에 배치됨, 게인 적용

LUT / 그레이딩

두 가지 계층:

• 스테이지 그레이드 (style.grade): 컴포지션 루트에 대한 CSS 필터 프리셋 (빠르고 미묘함)
• 출력 LUT (outputs[0].lut): 인코딩 중 ffmpeg lut3d로 적용되는 3D LUT .cube 파일 (시네마틱 컬러 그레이드). 번들 LUT: teal-orange, noir-film, faded-vintage.

6. 참조

파일	URL	읽을 목적
spec-format.md	https://lazy-frames.cosmicstack.ai/references/spec-format.md	유효한 spec.json 작성 — 전체 스키마, 모든 필드, 기본값
scene-types.md	https://lazy-frames.cosmicstack.ai/references/scene-types.md	장면 유형 선택 및 매개변수 구성
workflows.md	https://lazy-frames.cosmicstack.ai/references/workflows.md	website-promo, cinematic, edit 워크플로에 대한 단계별 가이드
cli.md	https://lazy-frames.cosmicstack.ai/references/cli.md	플래그와 예제가 포함된 모든 CLI 명령어
gates.md	https://lazy-frames.cosmicstack.ai/references/gates.md	스냅샷 회귀 + 시크 결정론 게이트 사용법

이 참조 자료는 설치된 패키지의 skill/references/와 저장소의 skill/references/에서도 사용할 수 있습니다.