Communitygithub.com

HyperFrames CLI

HyperFrames CLI 개발 루프 — `npx hyperframes`로 스캐폴딩(init), 린트, 프리뷰, 렌더링 및 환경 문제 진단(doctor, browser, info, upgrade)을 수행합니다. 이 명령어들을 실행하거나 HyperFrames 빌드/렌더 환경 문제 해결 시 사용하세요. 자산 전처리 명령어(`tts`, `transcribe`, `remove-background`)는 `hyperframes-media` 스킬을 대신 호출하세요.

HyperFrames CLI란 무엇인가요?

HyperFrames CLI는 비디오 컴포지션을 생성, 검증, 미리보기 및 렌더링하기 위한 종합 명령줄 도구입니다. Node.js >= 22 및 FFmpeg가 필요하며, `npx hyperframes`를 통해 액세스됩니다. 이 스킬은 `init`(스캐폴딩), `lint`(HTML 및 컴포지션 검증), `inspect`(시각적 레이아웃 검사), `preview`(핫 리로드 로컬 서버), `render`(MP4/WebM 출력) 및 `doctor`/`info`/`upgrade`와 같은 진단 명령어 등 전체 개발 워크플로우를 다룹니다. 여러 예제 템플릿, Tailwind 통합, Whisper를 통한 오디오 전사, 파라미터화된 렌더 변수(Data Composition Variables)를 지원합니다. 이 스킬은 Claude Code, Cursor, Codex 등 사용 중인 특정 AI 에이전트 IDE에서 HyperFrames 기반 프로젝트로 작업할 때 자동으로 호출되며, 적절한 명령어 실행 순서를 안내하고 모범 사례를 제공합니다. 자산 전처리 작업(narration, transcription, background removal)은 `hyperframes-media` 스킬로 위임됩니다.

지원 대상~Claude Code✓Codex CLI~Cursor
npx skills add https://github.com/alecs5am/ralphy/tree/HEAD/.agents/skills/hyperframes-cli

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

HyperFrames CLI은(는) 무엇을 하나요?

모든 명령은 npx hyperframes로 실행됩니다. Node.js >= 22 및 FFmpeg가 필요합니다.

워크플로우

  1. 스캐폴딩 — npx hyperframes init my-video
  2. 작성 — HTML 컴포지션 작성 (hyperframes 스킬 참조)
  3. 린트 — npx hyperframes lint
  4. 시각적 검사 — npx hyperframes inspect
  5. 프리뷰 — npx hyperframes preview
  6. 렌더링 — npx hyperframes render

프리뷰 전에 반드시 린트와 검사를 수행하세요. lint는 누락된 data-composition-id, 겹치는 트랙, 등록되지 않은 타임라인을 찾아냅니다. inspect는 렌더링된 컴포지션을 헤드리스 Chrome에서 열고, 타임라인을 탐색하며, 말풍선/컨테이너 또는 캔버스 밖으로 흘러나오는 텍스트를 보고합니다.

스캐폴딩

npx hyperframes init my-video                        # 대화형 마법사
npx hyperframes init my-video --example warm-grain   # 예제 선택
npx hyperframes init my-video --video clip.mp4        # 비디오 파일 포함
npx hyperframes init my-video --audio track.mp3       # 오디오 파일 포함
npx hyperframes init my-video --example blank --tailwind # Tailwind v4 브라우저 런타임 포함
npx hyperframes init my-video --non-interactive       # 프롬프트 생략 (CI/에이전트)

템플릿: blank, warm-grain, play-mode, swiss-grid, vignelli, decision-tree, kinetic-type, product-promo, nyt-graph.

init은 올바른 파일 구조를 생성하고, 미디어를 복사하며, Whisper로 오디오를 전사하고, AI 코딩 스킬을 설치합니다. 수동으로 파일을 생성하는 대신 사용하세요.

--tailwind 사용 시, 클래스나 테마 토큰을 편집하기 전에 tailwind 스킬을 호출하세요. 스캐폴드는 Studio의 Tailwind v3 설정이 아닌 브라우저 런타임의 Tailwind v4.2를 사용합니다.

린팅

npx hyperframes lint                  # 현재 디렉토리
npx hyperframes lint ./my-project     # 특정 프로젝트
npx hyperframes lint --verbose        # 정보 수준 결과
npx hyperframes lint --json           # 기계 판독 가능

index.html 및 compositions/ 디렉토리 내 모든 파일을 린트합니다. 오류(반드시 수정), 경고(권장 수정), 정보(--verbose 사용 시)를 보고합니다.

시각적 검사

npx hyperframes inspect                 # 타임라인에 걸쳐 렌더링된 레이아웃 검사
npx hyperframes inspect ./my-project    # 특정 프로젝트
npx hyperframes inspect --json          # 에이전트 판독 가능 결과
npx hyperframes inspect --samples 15    # 더 조밀한 타임라인 스캔
npx hyperframes inspect --at 1.5,4,7.25 # 명시적 히어로 프레임 타임스탬프

lint 및 validate 후에 사용하세요. 특히 말풍선, 카드, 캡션 또는 좁은 타이포그래피가 있는 컴포지션에 유용합니다. 다음을 보고합니다:

  • 가장 가까운 시각적 컨테이너나 말풍선 밖으로 확장되는 텍스트
  • 고정 너비/고정 높이 상자에 의해 잘리는 텍스트
  • 컴포지션 캔버스 밖으로 확장되는 텍스트
  • 클리핑 컨테이너를 이탈하는 자식 요소

렌더링 전에 오류를 수정해야 합니다. 경고는 에이전트 검토를 위해 표시됩니다. --strict를 추가하면 경고에서도 실패 처리합니다. 반복되는 정적 문제는 기본적으로 접혀서 JSON 출력이 LLM 컨텍스트 윈도우에 맞게 간결하게 유지됩니다. 오버플로가 진입/이탈 애니메이션을 위해 의도된 경우, 요소나 조상을 data-layout-allow-overflow로 표시하세요. 장식 요소가 감사 대상에서 제외되어야 하는 경우 data-layout-ignore로 표시하세요.

npx hyperframes layout은 동일한 시각적 검사 패스를 위한 호환성 별칭으로 계속 사용 가능합니다.

프리뷰

npx hyperframes preview                   # 현재 디렉토리 서브
npx hyperframes preview --port 4567       # 사용자 정의 포트 (기본 3002)

파일 변경 시 핫 리로드됩니다. Studio가 브라우저에서 자동으로 열립니다.

프로젝트를 사용자에게 다시 전달할 때는 소스 index.html 경로가 아닌 Studio 프로젝트 URL을 사용하세요:

http://localhost:<port>/#project/<project-name>

프리뷰 출력의 실제 포트와 프로젝트 디렉토리 이름을 사용하세요. 예를 들어, codex-openai-video 디렉토리에서 npx hyperframes preview --port 3017 실행 후 http://localhost:3017/#project/codex-openai-video라고 보고하세요.

index.html은 소스 코드 컨텍스트로만 취급하세요. 구현 파일로 링크하는 것은 괜찮지만, 프로젝트나 프리뷰 표면으로 표시하지 마세요.

렌더링

npx hyperframes render                                # 표준 MP4
npx hyperframes render --output final.mp4             # 이름 지정 출력
npx hyperframes render --quality draft                # 빠른 반복
npx hyperframes render --fps 60 --quality high        # 최종 결과물
npx hyperframes render --format webm                  # 투명 WebM
npx hyperframes render --docker                       # 바이트 단위 동일
플래그옵션기본값참고
--output경로renders/이름_타임스탬프.mp4출력 경로
--fps24, 30, 603060fps는 렌더 시간 두 배
--qualitydraft, standard, highstandarddraft는 반복 작업용
--formatmp4, webmmp4WebM은 투명도 지원
--workers1-8 또는 autoauto각각 Chrome 인스턴스 실행
--docker플래그off재현 가능한 출력
--gpu플래그offGPU 가속 인코딩
--strict플래그off린트 오류 시 실패
--strict-all플래그off오류 및 경고 모두에서 실패
--variablesJSON 객체—data-composition-variables에 선언된 변수 값 재정의
--variables-file경로—변수 값이 포함된 JSON 파일 (--variables 대안)
--strict-variables플래그off--variables에서 선언되지 않은 키 또는 타입 불일치 시 렌더 실패

품질 가이드라인: 반복 작업 중에는 draft, 검토용으로 standard, 최종 결과물에는 high를 사용하세요.

파라미터화된 렌더: 컴포지션은 <html> 루트에 data-composition-variables 를 사용하여 변수를 선언합니다. 이는 선언문의 JSON 배열 ({id, type, label, default} 항목별)로 스키마를 정의합니다. 내부 스크립트는 window.__hyperframes.getVariables()를 통해 확인된 값을 읽습니다. CLI --variables '{"title":"Q4 Report"}' 는 id별로 키가 지정된 JSON 객체로, 한 번의 렌더링을 위해 선언된 기본값을 재정의합니다. 누락된 키는 기본값으로 대체되므로 동일한 컴포지션이 개발 프리뷰와 프로덕션에서 변경 없이 실행됩니다. (서브 컴포지트 호스트는 data-variable-values 로 인스턴스별로 재정의할 수도 있으며, 이는 동일한 객체 형태로 서브 컴포지션의 한 번 마운트에 범위가 지정됩니다. 전체 패턴은 hyperframes 스킬을 참조하세요.)

자산 전처리

npx hyperframes tts, transcribe, remove-background는 컴포지션에 삽입할 자산(내레이션 오디오, 단어 수준 전사, 투명 비디오)을 생성합니다. 각 명령은 첫 실행 시 자체 모델을 다운로드합니다. 음성 선택, Whisper 모델 규칙(.en이 영어가 아닌 언어를 번역하는 함정), 출력 형식 선택(VP9 알파 WebM 대 ProRes), TTS → 전사 → 캡션 체인에 대해서는 hyperframes-media 스킬을 호출하세요.

문제 해결

npx hyperframes doctor       # 환경 확인 (Chrome, FFmpeg, Node, 메모리)
npx hyperframes browser      # 번들 Chrome 관리
npx hyperframes info         # 버전 및 환경 세부 정보
npx hyperframes upgrade      # 업데이트 확인

렌더링이 실패하면 먼저 doctor를 실행하세요. 일반적인 문제: FFmpeg 누락, Chrome 누락, 메모리 부족.

기타

npx hyperframes compositions   # 프로젝트 내 컴포지션 목록
npx hyperframes docs           # 문서 열기
npx hyperframes benchmark .    # 렌더 성능 벤치마크

Individual skills in this repo

This repo contains 11 individual skills — each has its own dedicated page.

alecs5am/ralphy

>- Composition and render craft — assembles scenario.json plus asset-manifest.json into a HyperFrames HTML composition and renders the mp4. Owns timing, transitions, captions, audio mix and ducking, the green zone, the render pipeline, and VO sync. Generates no media of its own. USE WHEN the user asks to "compose the video", "render", "preview", "fix the captions", "mix the audio", "tighten the transitions", "final cut", or edits HyperFrames composition code. TRIGGER (EN): "render it", "compose the video", "captions", "audio mix", "transitions", "final cut", "preview the composition".

alecs5am/ralphy

Asset preprocessing for HyperFrames compositions — text-to-speech narration (Kokoro), audio/video transcription (Whisper), and background removal for transparent overlays (u2net). Use when generating voiceover from text, transcribing speech for captions, removing the background from a video or image to use as a transparent overlay, choosing a TTS voice or whisper model, or chaining these (TTS → transcribe → captions). Each command downloads its own model on first run.

alecs5am/ralphy

Install and wire registry blocks and components into HyperFrames compositions. Use when running hyperframes add, installing a block or component, wiring an installed item into index.html, or working with hyperframes.json. Covers the add command, install locations, block sub-composition wiring, component snippet merging, and registry discovery.

alecs5am/ralphy

Create video compositions, animations, title cards, overlays, captions, voiceovers, audio-reactive visuals, and scene transitions in HyperFrames HTML. Use when asked to build any HTML-based video content, add captions or subtitles synced to audio, generate text-to-speech narration, create audio-reactive animation (beat sync, glow, pulse driven by music), add animated text highlighting (marker sweeps, hand-drawn circles, burst lines, scribble, sketchout), or add transitions between scenes (crossfades, wipes, reveals, shader transitions). Covers composition authoring, timing, media, and the full video production workflow. For dev-loop CLI commands (init, lint, inspect, preview, render) see the hyperframes-cli skill; for asset preprocessing commands (tts, transcribe, remove-background) see the hyperframes-media skill.

alecs5am/ralphy

>- How to make a vivid, character-driven brand POSTER — a single still image, not a video. A generalized overlay on the art-director step: supplies the poster-as-landing architecture (top banner → massive beveled wordmark → chest-up hero photo → scattered vinyl-sticker collage → copy block → thin footer strip), the parameterized slot set (brand, exclamation word, hero, product, palette, original blob glyph, aesthetic register), the model stack (gpt-5.4-image-2 for crisp typography, gemini fallback), and the niche's failure modes. Works for ANY brand and ANY aesthetic the user names — Y2K streetwear, vaporwave, grunge zine, clean DTC — the skill supplies the layout know-how, the user supplies the subject + vibe. USE WHEN the user asks for a poster / flyer / drop poster / "poster-as-landing-page" / brand key-art / album-cover-style still / hype graphic, with no specific existing poster to reproduce. This is a content-niche craft-overlay SKILL (generalized), loaded on top of a poster-format template match — n...

alecs5am/ralphy

>- Compatibility shim for the legacy `/ralphy-remotion` skill name. Use when a saved Claude Code command, old project note, or user request still mentions Ralphy Remotion; redirect the task to HyperFrames and the current Ralphy render playbooks instead of authoring new Remotion code.

alecs5am/ralphy

>- Compatibility shim for the legacy `/remotion-to-hyperframes` skill name. Use when an old project, note, or user request asks to migrate Ralphy Remotion work; translate the intent into the current HyperFrames composition model and follow the editor and HyperFrames playbooks.

alecs5am/ralphy

The full extract → classify → blueprint → de-dup → publish pipeline for a finished `.ralphy/workspaces/<ws>/projects/<id>/`. Reads its `units/*/unit.json` (#069) as the Unit source of truth, then factors the project into ALL FIVE entities — Unit + the four typed blocks Template (structure), Style (look), Recipe (effect/treatment), Asset (reusable media). Applies the recipe-vs-tag split (#082/#083): a candidate is a Recipe only if it carries an extractable artifact (ffmpeg filtergraph / HyperFram

alecs5am/ralphy

>- How to make a realistic AI UGC ad for a product — generalized niche know-how that looks real and doesn't feel AI. A domain overlay on the standard pipeline: supplies the shooting-script shape (timestamp | VO | shot | mannerism), the creator-persona build, the problem-mirror hook, the trust-through-mannerisms rule, and the 9:16 ~15s UGC format defaults. Works for ANY product the user names — their skincare line, a no-name app, a gadget. The skill supplies the know-how; the user supplies the product. USE WHEN the user asks for a UGC ad / creator-style product ad / "make an ad that looks like a real person reviewing my product" / testimonial-style or problem-solution short for TikTok / Reels / Shorts, with no specific existing video to reproduce. This is a niche SKILL (generalized), not a remix TEMPLATE. For "remix this exact ad but swap the product/person", use the remix path (docs/skills-vs-templates.md). For swapping the creator in an existing clip, see /ugc-model-swap.

alecs5am/ralphy

When the user needs marketing ideas, inspiration, or strategies for their SaaS or software product. Also use when the user asks for 'marketing ideas,' 'growth ideas,' 'how to market,' 'marketing strategies,' 'marketing tactics,' 'ways to promote,' 'ideas to grow,' 'what else can I try,' 'I don't know how to market this,' 'brainstorm marketing,' or 'what marketing should I do.' Use this as a starting point whenever someone is stuck or looking for inspiration on how to grow. For specific channel execution, see the relevant skill (paid-ads, social-content, email-sequence, etc.).

alecs5am/ralphy

Full end-to-end workflow for generating a realistic AI UGC ad for a product. 15-second format. Looks real. Doesn't feel AI.

관련 스킬