akdavid4real/effectcraft-motion

EffectCraft 모션 키트

EffectCraft에서 60초 기업 모션 그래픽을 제작하기 위한 검증된 워크플로우입니다. 디자인처럼 보이고, 동기화가 잘 맞으며, 씬 사이의 빈 프레임, 중복되는 음성 대사, 장식에 가려진 텍스트, 사라지는 숫자, 박자에서 벗어난 SFX와 같은 고전적인 버그가 없습니다.

디자인은 처음부터 만드는 것이 아니라 모양과 레이아웃에서 비롯됩니다. 다섯 가지 검증된 룩 중 하나를 선택하고, 각 씬을 콘텐츠와 단어 타이밍과 함께 하나의 scene() 호출로 작성하면 레이아웃이 크기, 그리드, 색상 및 모션을 처리합니다. 스타일을 발명하는 에이전트는 어두운 그라데이션, 글로우 블롭 및 작은 중앙 정렬 텍스트로 끝나는 경우가 많습니다. 이것이 생성된 프로모션이 싸구려처럼 보이는 가장 큰 이유입니다.

모든 에이전트가 사용할 수 있습니다. 모든 것은 셸(scripts/ec.py를 통한 effectcraft-cli)에서 실행됩니다. MCP는 선택 사항입니다. 키트 위치: 이 파일이 포함된 폴더($KIT라고 부름).

이 키트가 아닌 경우: 막대기 인물 / 캐릭터 스토리 비디오(분할 화면 '잘못된 방법 vs 올바른 방법')는 stick-figure-story 스킬을 대신 사용하세요.

황금률 (이유는 references/ 참조)

1. 시간은 추측이 아닌 데이터에서 비롯됩니다. 씬 계획은 timeline.json에 있습니다. 씬 스크립트는 SC("s3") 및 W("s3", "word")(단어가 발화되는 절대 시간)을 사용합니다. 23.6과 같은 시간을 직접 입력하지 마세요.
2. 빌드하는 모든 씬을 살펴보세요. 미리보기 프레임을 렌더링하고(ec.py frames) PNG를 여세요. 오류 없이 실행되는 코드도 잘못 렌더링될 수 있습니다.
3. "완료"는 게이트를 통과했음을 의미합니다. timeline.py check에서 FAIL 0개, ec.py qa에서 FAIL 0개, ec.py qa-video에서 FAIL 0개, 그리고 연락처 시트를 살펴보았습니다. 경고를 포함하여 결과를 정직하게 보고하세요.
4. 룩과 레이아웃을 사용하세요(references/looks.md). 선택하기 전에 두 가지 룩을 비교하세요. 씬의 최소 3분의 1은 시각적(전화기 / 아이콘 / 흐름 / 막대 또는 객체가 있는 사용자 지정 씬)이어야 합니다. 사용자 지정 씬 코드는 레이아웃이 다루지 않는 것(지도, 제품 목업)을 위한 것이며, 여전히 룩의 팔레트 P(S.bg)와 유형 크기 LOOK.type을 사용합니다.
5. EffectCraft 스크립트를 작성하기 전에 references/pitfalls.md를 읽으세요. 씬을 디자인하기 전에 references/motion-design.md, references/looks.md 및 references/techniques.md(비트 그리드, 피크 정렬 SFX, 연속 모프, 금지 목록)를 읽으세요.
6. 브랜드는 수정할 수 없습니다(references/brand.md). 실제 로고 파일을 보여주고, 이름을 워드마크로 입력하지 마세요. 태그라인을 글자 그대로 작성하세요. 제품 이름, 버튼 레이블 또는 통계를 임의로 만들지 마세요. timeline.json의 "brand" 블록을 채워 ec.py qa가 이를 확인하도록 하세요.
7. QA 통과와 좋은 디자인은 다릅니다. 씬을 작성하기 전에 색상 스크립트, 비주얼 및 시그니처 순간을 계획하고, 렌더링하기 전에 크리에이티브 디렉터 리뷰에서 영화를 평가하세요(references/design-review.md, references/benchmark_sheet.png와 비교). 7b. 실제 제품 UI(SaaS, 앱 필름): references/ui-footage.md를 따르세요: 샘플 데이터만 캡처하고, 하나의 패널로 자르고, 읽을 수 있게 표시(폭 55% 이상)하거나 애니메이션 UI로 재구축하고, 샷당 하나의 화면, 착색된 썸네일 벽 금지, 임의의 숫자 금지, QA 게이트가 실행되도록 여기에 빌드하세요.
8. 고에너지 / 하이퍼-키네틱 광고(TikTok 스타일, 모든 음성 단어에 강조): 잔잔한 레이아웃 대신 references/high-energy.md 및 templates/hyper.jsx를 따르세요.
9. 계획한 대로가 아니라 렌더링에 표시된 대로 보고하세요. 보고서나 핸드오프를 작성하기 전에 각 씬의 중간과 마지막 0.5초에서 최종 MP4(미리보기 아님)의 프레임을 가져와 모든 주장을 확인하세요: 각 줄이 읽을 수 있을 만큼 충분히 긴지, 그려진 모든 단계가 실제로 보이는지, 스크린샷을 읽을 수 있는지, 길이가 브리핑 및 파일 이름과 일치하는지. 모든 음성 대본을 스크립트와 비교하고 브랜드 이름을 들어보세요. 테스트에서 에이전트의 핸드오프는 네 개의 다이어그램 단계, 세 개의 약속 및 "BridgeAxis Technologies"를 설명했습니다. 영화는 마지막 단계를 컷 0.3초 전에, 약속을 0.5초 동안, 읽을 수 없는 스크린샷, 그리고 "Bridge Access"라고 말하는 음성을 보여주었습니다. timeline.py check 및 ec.py qa는 이제 읽을 수 없는 음성 실수 및 min_read초 미만으로 읽을 수 있는 텍스트에 대해 경고합니다. 이러한 경고를 설명하지 말고 수정하세요. 에이전트의 가장 높은 추론 설정에서 실행하세요: 엉성한 실행은 '낮음' 설정에서였습니다.

프로젝트 레이아웃

<project>/
  timeline.json        씬 계획 + sfx 큐 + 음악 ($KIT/templates/timeline.example.json에서 시작)
  audio_meta.json      음성 파일 + 단어 타임스탬프(오디오 단계에서 생성)
  soundtrack.wav       timeline.py mix에 의해 생성됨
  assets/voice|sfx|bgm|icons|fonts
  scripts/lib.jsx      $KIT/templates/lib.jsx의 복사본 (COMP 설정; 룩이 색상과 글꼴을 제공)
  scripts/look.jsx     `ec.py look NAME --accent HEX`에 의해 작성됨
  scripts/timing.jsx   생성됨 (timeline.py emit) - 절대 편집 금지
  scripts/wipes.jsx    생성됨 (timeline.py emit) - 마지막에 실행
  scripts/reset.jsx, s1.jsx ... s8.jsx
  qa/                  미리보기 및 연락처 시트

모든 명령은 <project>/에서 실행하세요. ec.py는 timeline.json에서 프로젝트 경로와 컴포지션 이름을 읽습니다.

워크플로 A: 새 비디오

0. 브리핑. 빌드하기 전에 물어보세요: 일치시킬 브랜드/웹사이트, 분위기(시끄러운 / 차분한 / 기술적인 / 고급스러운), 길이 및 화면 비율, 음성(성별/톤), 음악/SFX가 필요한지 여부. 크리에이티브 방향을 추측하는 것이 첫 번째 컷이 거부되는 가장 흔한 이유입니다.

1. 설정

mkdir -p <project>/{scripts,assets/{voice,sfx,bgm,icons},qa} && cd <project>
cp $KIT/templates/lib.jsx $KIT/templates/reset.jsx $KIT/templates/s1.jsx scripts/
cp $KIT/templates/timeline.example.json timeline.json   # 프로젝트/컴포지션/출력 이름 편집
python3 $KIT/scripts/ec.py fonts                         # 룩의 글꼴 설치 (머신당 한 번)

scripts/lib.jsx의 COMP를 타임라인의 컴포지션 이름으로 설정하세요. 브랜드의 악센트 색상(로고, 웹사이트 CSS, 제품)을 기록하세요. 브랜드에 웹사이트가 있으면 CSS에서 악센트와 글꼴을 읽으세요. 로고 파일을 assets/logo/에 넣고 timeline.json의 "brand" 블록에 이름, 정확한 태그라인, 로고 파일 및 승인된 모든 제품 이름 또는 URL을 입력하세요(references/brand.md).

2. 대본 및 음성. 8줄 작성(훅, 문제, 브랜드, 23개 혜택, 증거, 엔드 카드); 60초는 약 110130단어를 담습니다. 라인당 하나의 오디오 파일을 생성하고 단어 타임스탬프를 다음 형식으로 audio_meta.json에 가져오세요:

{"voices": [{"id": "s1", "path": "assets/voice/s1.wav", "duration_s": 6.45,
             "words": [{"word": "Every", "start": 0.30, "end": 0.59}, ...]}]}

먼저 python3 $KIT/scripts/ec.py doctor를 실행하세요. 이 머신에 무엇이 있고 누락된 항목을 설치하는 방법을 나열합니다. ready라고 표시되면 대안(edge-tts, Whisper, piper, Playwright)을 조사하거나 설치하지 마세요: 아래 도구가 테스트된 도구입니다. 음성이 전혀 없는 경우 단어 대신 "in+0.5" 오프셋으로 씬 시간을 지정하세요. $KIT/demo/는 완전한 무성 예제입니다(ec.py demo가 렌더링).

• 음성(기본값): 로컬 Kokoro, 여성 음성 af_heart. 무료, 계정 불필요. 모델은 ~/.cache/hyperframes/tts/에 캐시됩니다(첫 실행 시 한 번 다운로드):

  export HYPERFRAMES_PYTHON=~/.venvs/kokoro/bin/python   # 필수: kokoro-onnx가 있는 venv
  npx hyperframes tts "Line one text." -v af_heart -o assets/voice/s1.wav   # 라인당 하나의 파일
  

  HYPERFRAMES_PYTHON이 없으면 "The kokoro-onnx package is not installed" 오류와 함께 실패합니다. pip-install하지 말고 변수를 설정하세요.
• 단어 타임스탬프: npx hyperframes transcribe assets/voice/s1.wav --json. Parakeet 모델을 사용하며, 첫 실행 후 ~/.cache/hyperframes/parakeet에 캐시됩니다(엔진 auto가 선택). Parakeet은 Kokoro와 같은 깨끗한 TTS 음성에 적합합니다. 여기서 -e whisper를 전달하지 마세요: hyperframes의 Whisper 엔진(whisper.cpp)이 설정되지 않았습니다. 악센트가 있는 실제 녹음 음성의 경우 footage-edit 스킬이 대신 faster-whisper large-v3-turbo(~/.venvs/asr)를 사용합니다. 단어와 시작/종료 시간을 audio_meta.json에 복사하세요.
• 음악 및 SFX: media-use 오디오 엔진(node <skills>/media-use/audio/scripts/audio.mjs --request audio_request.json --out audio_meta.json --only bgm,sfx). 설명으로 HeyGen 카탈로그에서 검색합니다. 예: "bgm": {"mode": "retrieve", "query": "warm calm piano"}. <skills>는 Claude Code의 경우 ~/.claude/skills, Codex/OpenCode/DeepSeek의 경우 ~/.agents/skills입니다.
• HeyGen 텍스트 음성 변환(엔진 또는 heygen CLI를 통해)은 대체 음성이지만, 무료 허용량이 소진됩니다. 그럴 때는 Kokoro를 사용하세요. 음악 및 SFX 검색은 HEYGEN_API_BASE가 설정되지 않은 경우 heygen CLI에 로그인(heygen auth login --oauth)해야 합니다. 설정되지 않으면 sfx는 여전히 media-use의 번들 라이브러리에서 응답하며, 사용자는 자신의 음악 파일을 제공할 수 있습니다.

실제로 사용한 제공자와 음성을 기록하세요.

3. 타임라인

python3 $KIT/scripts/timeline.py beats      # 음악 템포, 비트, 마디 시작, 드롭 -> beats.json ("music" 필요)
python3 $KIT/scripts/timeline.py suggest    # 장면 in/out + voice_at 제안; beats.json이 있으면 장면이 비트에서 종료
# timeline.json에 붙여넣고 각 장면의 "bg"(light/dark/accent) 설정, 단어에 고정된 sfx 큐 추가
python3 $KIT/scripts/timeline.py words      # 절대 시간이 있는 모든 단어
python3 $KIT/scripts/timeline.py check      # FAIL 0이어야 함
python3 $KIT/scripts/timeline.py emit       # scripts/timing.jsx + scripts/wipes.jsx 작성
python3 $KIT/scripts/timeline.py mix        # soundtrack.wav 작성 (-14 LUFS)

비트에 맞춰 컷: timeline.py snap은 음성이 여전히 맞는 비트로 기존 컷을 이동합니다. 장면에서 BEAT(n), DOWNBEAT(n), nearBeat(t) 및 T.drop은 시간 슬램과 팝을 음악에 맞춥니다(references/techniques.md). SFX "at"은 숫자, "beat:12", "downbeat:3", "drop", "s2:late"(s2 음성의 "late" 단어; "s2:the#2" = 두 번째 "the"), "wipe:s3"(s3으로의 전환), "in:s3" 또는 "out:s3"일 수 있습니다. "offset", "vol", "max"(트림 길이) 및 "align": "peak"(사운드의 가장 큰 순간이 앵커에 위치: 충격 및 팝에 사용)를 추가하세요.

4. 계획을 세운 다음 장면을 작성하세요. 먼저 계획을 qa/design_review.md(references/design-review.md, 1-6부)에 작성하세요: 장면당 한 줄씩 색상 스크립트, 각 줄이 말하는 내용을 보여주는 비주얼, 각 장면의 히어로, 그리고 하나의 시그니처 순간. timeline.json의 각 장면에 배경("bg": "light" | "dark" | "accent")을 지정하고 timeline.py emit을 다시 실행하세요. 각 컷이 새 장처럼 읽히도록 번갈아 가며 사용하세요. 1-2개의 가장 강력한 순간(보통 감정적 정점)에 "accent"를 사용하세요. 브랜드 공개 및 엔드 카드는 실제 로고가 가장 잘 읽히는 배경(보통 light)에 배치하고, accent에는 배치하지 마세요. 그런 다음 scripts/s1.jsx ... sN.jsx를 작성하세요. 각각은 레이아웃을 사용하는 scene() 호출입니다(사양: templates/layouts.jsx 상단; 가이드: references/looks.md):

// scripts/s2.jsx
scene("s2", "list", { label: "The problem",
  items: [["Late arrivals.", "late"], ["Customs surprises.", "customs"], ["Tracking that tells you *nothing.*", "tracking", "nothing"]],
  punch: ["Too late.", "too"] });

*word*는 줄의 악센트 부분을 표시합니다. 시간은 timeline.py words의 단어("word", "word#2", "word+0.3", "in+0.2")이며, 구두점 없이 작성됩니다. 레이아웃은 프레임을 채우도록 텍스트를 키우거나 줄이므로 원하는 카피를 작성하고 레이아웃이 크기를 조정하도록 두세요. 화면의 줄을 짧게 유지하세요: 헤드라인이지 음성 해설이 아닙니다. 레이아웃이 다루지 않는 것(지도, 제품 목업)에 대해서만 $KIT/templates/scene_template.jsx를 대신 복사하세요.

장면의 최소 3분의 1을 시각적으로 만드세요. 배경에 단어만 있는 필름은 아무리 좋은 타이포그래피라도 슬라이드 데크처럼 읽힙니다. 시각적 레이아웃은 음성이 설명하는 객체를 화면에 배치합니다: phone(전화기 화면의 제품: 결제 랜딩, 주문, 추적 업데이트), icons(레이블이 있는 2-4개의 그려진 픽토그램), flow(각각이 언급될 때 채워지는 선으로 연결된 정류장: 고객 → 전화기 → 은행, 창고 → 항구 → 문), bars(성장하는 2-4개의 막대: 수수료, 대기 시간, 전후). 주장이 아닌 사물이나 과정을 설명하는 장면을 선택하세요.

scene("s4", "flow", { label: "How it works", title: ["Banked the *same day.*", "money", "same"],
  nodes: [{ icon: "shop", label: "You sell", at: "sell" }, { icon: "phone", label: "Tapnest", at: "app" },
          { icon: "bank", label: "Your account", at: "account", note: "Same day" }] });

아이콘은 키트에서 그립니다(파일 없음): phone card bank cash clock check tick shop bolt chart truck box pin lock user people chat globe send star plane doc. 그림/객체 레이어 이름에 "VIS"가 포함된 경우(예: "s5 VIS map") 사용자 지정 시각적 장면도 포함됩니다. ec.py qa는 장면의 3분의 1 미만이 시각적일 때 경고합니다. layouts.jsx를 프로젝트에 복사하지 마세요: ec.py는 키트에서 로드하며, 복사본은 이전 버전을 고정합니다.

5. 룩 선택(먼저 references/looks.md 읽기). 브랜드에 다른 방식으로 맞는 두 가지 룩을 숏리스트에 올리고, 브랜드에서 악센트를 가져온 다음, YOUR 장면에서 비교하세요:

python3 $KIT/scripts/ec.py new
python3 $KIT/scripts/ec.py import soundtrack.wav assets/icons/*.png
python3 $KIT/scripts/ec.py compare editorial swiss --accent FF5B1F   # -> qa/look_compare.png: 열기
python3 $KIT/scripts/ec.py look editorial --accent FF5B1F             # 승자 적용

6. 빌드 및 미리보기

python3 $KIT/scripts/ec.py run s1 s2 s3 s4 s5 s6 s7 s8 wipes   # s1이 컴포지션 + 사운드트랙 생성
python3 $KIT/scripts/ec.py frames 2 4 6.5                      # qa/frames.png 열어서 보기

모든 장면의 두세 순간을 미리보기하세요. 하나의 장면을 수정하려면 편집하고 ec.py rebuild sN을 실행하세요(해당 장면만 지우고 다시 빌드한 다음 와이프를 다시 실행). 모든 것을 다시 빌드하려면(예: 룩 변경 후): ec.py run reset s1 ... sN wipes를 실행하세요. 룩이 전환을 제공합니다. 대체하려면 "GENERATED" 헤더 라인 없이 자체 scripts/wipes.jsx를 작성하세요(emit은 그대로 둠).

7. 오디오 QA ec.py qa-audio - 각 단어가 오디오 메타 파일의 예상 시간에 있고, SFX가 존재하며, 피크에 정렬되어 있음을 확인합니다. ec.py qa-video 전에 실행하세요.

8. 비디오 QA python3 $KIT/scripts/ec.py qa-video는 다음과 같은 항목을 확인합니다: 읽을 수 없는 텍스트, 깜박이는 전환, 새 장면이 아닌 곳의 비트 변화, 존재하지 않는 글꼴, 누락된 로고.

9. 내보내기 ec.py export prores가 .mov를 렌더링합니다.

워크플로 B: 기존 프로젝트 감사/수정

timeline.json을 읽은 다음 python3 $KIT/scripts/ec.py plan을 실행하여 계획을 확인합니다. timeline.py check 및 ec.py qa를 실행합니다. qa/의 프레임을 살펴봅니다. ec.py rebuild sN으로 장면을 수정하거나 $KIT/templates/에서 누락된 파일을 복사합니다.

명령 참조

명령	용도
ec.py doctor	종속성 확인
ec.py new	새 프로젝트 초기화
ec.py fonts	룩 글꼴 설치
ec.py look	룩 적용
ec.py compare	두 룩 비교
ec.py run	장면 렌더링
ec.py rebuild	단일 장면 재렌더링
ec.py frames	미리보기 프레임 생성
ec.py qa	품질 검사 실행
ec.py qa-audio	오디오 품질 검사
ec.py qa-video	비디오 품질 검사
ec.py export	최종 출력 내보내기
timeline.py check	타임라인 검증
timeline.py emit	타이밍 스크립트 생성
timeline.py mix	오디오 믹스