Imgcli은(는) 무엇을 하나요?
Remotion 비디오를 위한 복사-붙여넣기 컴포넌트입니다. 컴포넌트는 shadcn을 통해 설치되며 components/imgcli/ 디렉토리에 저장됩니다 — 코드를 완전히 소유하게 됩니다.
설치
필수 조건: Remotion 프로젝트 (npx create-video@latest).
# Imgcli 레지스트리에서 설치
npx shadcn@latest add https://imgcli.com/r/text-reveal.json
# 컴포넌트는 components/imgcli/text-reveal.tsx에 저장됨
짧은 형식 @imgcli/<name>을 사용하려면 components.json에서 @imgcli를 https://imgcli.com/r/{name}.json에 매핑하세요. 프로젝트 설정에 대한 자세한 내용은 설치 가이드를 참조하세요.
의존성 자동 설치
많은 컴포넌트가 registryDependencies를 통해 다른 컴포넌트를 가져옵니다 — shadcn이 이를 전이적으로 설치합니다. 예를 들어, search-typing을 설치하면 snap-cn-ui, input 및 caret도 함께 설치됩니다.
@imgcli/snap-cn-ui는 공유 코어 라이브러리입니다 (타임라인 폴드 훅, 테마 컨텍스트, 색상 수학). 대부분의 UI 프리미티브가 이에 의존합니다. 직접 설치하는 경우는 드뭅니다.
두 가지 계층
Imgcli는 두 종류의 컴포넌트를 제공합니다 — API가 다릅니다:
- Animation 계층 (장면 및 애니메이션) — 텍스트 애니메이션, 전환, 배경, UI 블록 시뮬레이션, 브랜드/소셜 카드, 전체 구성. 프레임 기반. 공유 props:
speed(시간 배율), 텍스트의 경우:fontSize,color,fontWeight. - UI 프리미티브 (
snap-cn-ui) — 타임라인 기반의 shadcn 스타일 프리미티브. 현재 두 가지가 제공됩니다:input및caret. 상태 기반 props (state,style,size,theme) — 열림/입력 상태는 타임라인의 순수 함수입니다.speedprop 없음.@imgcli/snap-cn-ui기반.
컴포넌트 카테고리
만들고자 하는 것에 따라 선택하세요. 카탈로그는 references/components/ 아래에 파일별로 나뉘어 있습니다. references/components/index.md 에서 시작하세요 — 이 파일은 아래 카테고리별로 그룹화된 라우터 테이블이며, 각 컴포넌트에 Use for / Avoid for 신호를 제공합니다. 훑어보고 후보를 고른 후, 필요한 references/components/<name>.md 파일만 열어 확인하세요 (전체 props, 예제, 모든 사용/사용 금지 노트). 모든 파일을 읽지 마세요.
| 카테고리 | 계층 | 컴포넌트 |
|---|---|---|
| 텍스트 및 제목 | Animation | text-reveal, type-morph, text-swell, text-highlight, text-swap, text-build, text-rewrite, text-select, word-flip, punch-lines, word-gather, word-wheel |
| 자막 | Animation | word-captions, karaoke-captions |
| AI 채팅 입력 | Animation | prompt-send, search-typing, prompt-zoom, answer-stream, answer-highlight, agent-steps |
| 화면 및 기기 | Animation | phone-frame, laptop-frame, terminal-simulator, screen-recording, cursor-track |
| 로고 | Animation | logo-assemble, logo-flicker, logo-collapse, logo-drift, block-wordmark, wordmark-cut |
| 장면 | Animation | announce-title, hero-launch, orbit-gallery, moodboard-reveal, status-cycle, count-grid, roster-grant, orb-swarm, reel-collage, card-rail, cut-lockup, bloom-lockup, gather-lockup, sky-lockup |
| 소셜 증명 | Animation | follower-rush, channel-thread |
| 효과 | Animation | pulsing-border |
| UI 프리미티브 | snap-cn-ui | input, caret (+ snap-cn-ui, 공유 코어 라이브러리) |
설치 가능한 이름을 확인하려면 라이브 컴포넌트 인덱스를 사용하세요. 아래 참조에는 이전 이름과 대체 이름이 포함되어 있습니다.
컴포넌트 패턴
계층에 따라 규칙이 다릅니다 — 프리미티브에 animation 계층 props를 가정하지 마세요.
Animation 계층 (장면 및 애니메이션)
- 컴포넌트별로 명명된
Props인터페이스 (예:TextRevealProps). speed?: number— 전역 시간 배율 (기본값1),frame * speed로 적용.- 텍스트 컴포넌트:
fontSize,color,fontWeight. - 장면 간 전환은 이 레지스트리에 없습니다 — Remotion의 자체
@remotion/transitions(slide,wipe,fade,flip)를<TransitionSeries>내에서 사용하세요. - 루트에
className?: string.
UI 프리미티브 (snap-cn-ui)
- 상태 기반,
speed기반이 아님:state(예:"open"/"closed"),style,variant,size,theme?: Partial<SnapCnTheme>. - 열림/닫힘/활성 상태는 타임라인의 순수 함수입니다 (키프레임 프리셋).
- 모달 계층 프리미티브 (dialog, alert-dialog, drawer)를 트리거 요소와 함께 구성하세요 — 각 컴포넌트의 예제를 참조하세요.
애니메이션 API
import { interpolate, spring, useCurrentFrame, useVideoConfig } from "remotion";
const opacity = interpolate(frame, [0, 30], [0, 1], { extrapolateRight: "clamp" });
const scale = spring({ fps, frame, config: { damping: 12, mass: 1, stiffness: 100 } });
// 결정론적 무작위성 (절대 Math.random() 사용 금지)
import { random } from "@remotion/random";
const jitter = random(`seed-${frame}`);
구성 구조
import { Sequence, Series } from "remotion";
<Sequence from={30} durationInFrames={60}>
<TextReveal text="Ship it in React" />
</Sequence>
<Series>
<Series.Sequence durationInFrames={60}><SceneA /></Series.Sequence>
<Series.Sequence durationInFrames={60}><SceneB /></Series.Sequence>
</Series>
캔버스 및 타이밍
- 캔버스 표준:
1280×720 @ 30fps. 컴포넌트는 이에 맞춰 설계되었습니다. - 각 Sequence의 예산을 컴포넌트의 자연 길이에 맞게 설정 —
components/index.md의Length열 (각 파일의Natural length)을 참조하세요. 예산이 부족하면 애니메이션이 잘리고, 초과하면 여백이 생깁니다. - 분위기 매칭: 각 카탈로그 항목에는
vibe태그가 있습니다 (tech/premium/data/clean/playful/social) — 브랜드에 맞는 분위기의 컴포넌트를 선택하세요. - 팔레트 및 글꼴: 라이브러리의 토큰 범위 내에서 유지하세요 (
references/design.md→ 토큰). 그래야 사용자가 추가한 요소가 충돌하지 않습니다.
디자인 기본값 — AI 슬롭 방지
자체 텍스트, 장면 크롬 또는 카드를 작성할 때(사전 제작 컴포넌트가 아닌 경우) 절제를 유지하세요:
- 추가하는 본문/제목 텍스트에 장식용
letter-spacing을 사용하지 마세요. text-transform: uppercase/ 전체 대문자 기본값을 사용하지 마세요 — 문장 형식을 선호하세요 (LAUNCH가 아닌Launch).- 그라디언트 텍스트 채우기 또는 장식용 그라데이션 워시를 사용하지 마세요 — 그라데이션은 의도적인 배경으로만 사용하세요.
- 글로우 / 컬러 드롭 섀도우 또는 큰 블러 반경 (
blur > ~24px, 확산, 다중 레이어)을 사용하지 마세요 — 미묘한 1px 높이감만 허용합니다.
예외: 효과 자체가 본질인 컴포넌트에서는 이러한 규칙을 제거하지 마세요 — word-flip의 그라데이션 단어, block-wordmark의 색상 덱, announce-title의 글로우, pulsing-border 자체, 그리고 자막 프리셋의 두꺼운 윤곽선은 모두 정당합니다. 이 규칙은 사용자의 추가 요소에 적용되며 라이브러리 자체에는 적용되지 않습니다.
전체 do/avoid 예제: references/design.md. 모션 품질(타이밍, 예측, 스테이징, 이징)에 대해서는 references/motion-principles.md를 참조하세요.
주의사항 (Imgcli 특화)
- 전환 컴포넌트는 제공되지 않습니다 — 장면 변경은 Imgcli 컴포넌트가 아닌
@remotion/transitions의<TransitionSeries.Transition>을 사용하세요.text-swap은 한 줄을 바꾸는 것이지 장면을 바꾸는 것이 아닙니다. - 터미널 스크롤은 즉시 — step 함수
translateY를 사용하고, 스크롤에 spring/ease를 절대 사용하지 마세요. - 분할 레이아웃에
overflow: hidden— 너비 애니메이션 중 콘텐츠 깨짐 방지. - 커서 깜빡임은 결정론적 —
Math.floor(frame / 15) % 2 === 0, 인터벌 사용 금지. - 정적 파일은
public/디렉토리에 —import대신staticFile('cursor.svg')로 로드. - 소셜 카드는 오프라인 렌더링 —
avatarUrl=""/coverUrl=""는 그라데이션으로 폴백; fetch 사용 금지.
일반 Remotion 규칙 (Math.random() 사용 금지, setInterval 사용 금지, transform 애니메이션에 top/left 대신 사용, 렌더링 전 글꼴 로드)은 Remotion 자체 스킬에 있으며, 이 스킬에는 없습니다: npx skills add remotion-dev/skills.
비디오 구성하기
컴포넌트를 덤프하지 말고 — 하나의 스토리를 구성하세요. 전체 비디오를 만들라는 요청을 받으면 ("제품 데모 만들어줘", "체인지로그 비디오", "내 랜딩 페이지 인트로"):
- 전략 결정 — 준비된 템플릿 vs 컴포넌트 조합 vs 새 컴포넌트 제작.
references/anatomy.md§1 참조. - 비트 따라가기 — 제품 데모는 Hook → Positioning → Product reveal → Features → Proof → CTA입니다 (마지막 두 개는 선택 사항).
references/anatomy.md§2 참조. - 레시피 사용 —
references/archetypes/index.md는 아키타입별 제작으로 연결합니다: 콘텐츠 계약 (추론 → 질문 → 플레이스홀더), 지속 시간 변형, 비트→컴포넌트 슬롯 및 작업된<TransitionSeries>골격. - 각 비트의 컴포넌트를
references/components/index.md에서 선택하고,vibe태그를 브랜드에 맞추고 각<Sequence durationInFrames>를 자연 길이에 맞게 예산 설정. - 품질 기준 확인 — 하나의 악센트, 문장형 키네틱 타이포그래피, 실제 콘텐츠, 글로우 후광 없음, 기능 목록 열거 없음, 타이포그래피 뒤 장식용 그라데이션 워시 없음.
references/anatomy.md§3 참조.
워크플로우
전체 비디오의 경우, 사용 가능한 경우 해당 워크플로우 스킬을 사용하세요. 각 스킬은 Imgcli 컴포넌트를 비트별로 구성하고 Remotion에서 결과를 확인합니다. 에이전트 가이드는 설치 및 공개 컴포넌트 검색을 다룹니다.
remotion-launch-video— 런칭 필름, 발표, Product Hunt / X 프로모션용.remotion-product-demo— 실제 화면 녹화, CLI 및 AI 앱 데모의 워크스루용.remotion-motion-graphics— 키네틱 타이포그래피, 로고 스팅, 통계 및 짧은 오프너용.remotion-kinetic-typography— 애니메이션 텍스트 및 타이틀 카드용.remotion-logo-animation— 로고 리빌, 인트로 및 아웃트로 스팅용.remotion-explainer-video— 내레이션된 설명 비디오(자막 포함)용.
참조
references/anatomy.md— 전체 비디오 구성: 전략 (템플릿/구성/새 제작), 제품 데모 비트, 좋은 결과물과 슬롭의 품질 기준.references/archetypes/index.md— 아키타입별 제작 레시피 라우터 (product-demo 플래그십 + changelog, feature-announcement, oss-showcase, cli-tool-demo, testimonial-reel, year-in-review, pricing-reveal, logo-bumper): 콘텐츠 계약, 지속 시간 변형, 비트→슬롯 맵.references/components/index.md— 라우터 테이블 (모든 컴포넌트, 카테고리별 그룹,Use for/Avoid for포함). 단일 컴포넌트의 전체 props, 예제 및 사용/사용 금지 노트를 보려면references/components/<name>.md를 열어 확인하세요.references/design.md— 안티 슬롭 디자인 기본값 (do/avoid) + 디자인 토큰 (팔레트, 글꼴, 캔버스).references/motion-principles.md— Imgcli + Remotion에 적용된 모션 디자인 원칙.references/anti-patterns.md— 일반적인 생성 실수와 수정 방법.