Pixerate/pixerate-animation-editor

Pixerate 애니메이션 편집기

씬(scene)은 아트워크(각각 고유 ID를 가진 벡터 패스와 그룹으로 파싱된 SVG)와 정렬된 샷(shot) 목록으로 구성됩니다. 샷은 선택적으로 카메라를 이동시키고, run 명령들을 실행한 후, 일시 정지(기본 600ms)합니다. 명령들은 "with": "previous"가 아닌 이상 하나씩 순차적으로 실행되며, 각 명령의 기본 길이는 콘텐츠에서 결정됩니다(enter는 600ms, exit는 450ms, move는 700ms, draw는 패스 길이를 따릅니다). 따라서 속도를 변경하려는 경우가 아니라면 duration은 생략하세요. 모든 프레임은 시간의 순수 함수입니다.

Id: 요소 ID는 get_animation(elements) 또는 find_animation_elements에서 가져옵니다. 샷 ID는 사용자가 직접 선택합니다("intro"). 명령은 샷 ID와 해당 샷의 run 내에서의 인덱스로 식별됩니다. 시간은 밀리초(ms) 단위이며, 위치는 아트워크의 문서 단위입니다. 나중에 등장하는 요소는 enter 명령 전까지 숨겨져 있습니다. 한 번도 등장하지 않는 요소는 처음부터 표시됩니다.

오류, 네임스페이스가 있는 도구 이름 및 일반 명령 도구에 대해서는 pixerate-agent-tools를 참조하세요. 전체 명령 어휘(모든 유형, 옵션 및 기본값)는 references/commands.md에 있습니다.

워크플로우 스킬

이러한 작업의 경우 워크플로우 스킬도 함께 로드하세요. 해당 스킬에는 방법, 단계 간 점검, 문제점 및 아래 나열된 도구 사용법이 포함되어 있습니다.

• pixerate-animation-motion-graphics: 샷, 스태거 진입, 이징, 유지, 길이 맞추기.
• pixerate-animation-logo-reveal: 로고의 부분들을 비트에 맞춰 짧게 리빌하고, 마지막에 유지합니다.

작업 방법

1. 읽기. get_animation으로 요소, 타이밍이 포함된 샷, 클립, 드라이버 및 문제점을 확인합니다. 아트워크가 없다면 먼저 set_animation_artwork_svg를 호출하고(애니메이션할 모든 요소에 ID를 부여), import_flair_effect / import_pptx_animation으로 시작하세요. 윤곽선 텍스트의 경우 get_text_layout이 글자, 단어 및 줄 단위를 보여줍니다.
2. 샷 계획, 각각 하나의 아이디어. 각 샷에서 시청자가 무엇을, 어떤 순서로 주목해야 하는지 기록한 다음, 각 비트를 명령에 매핑하세요. 숨겨진 종료 상태(morph/match 대상, follow 패스)는 참조하기 전에 아트워크에 존재해야 합니다.
3. 배치로 작성. insert_shots로 전체 샷을 추가하고, edit_animation으로 여러 관련 편집을 하나의 실행 취소 단계로 묶어 수행합니다(확실하지 않은 경우 먼저 dry_run: true 사용; "$0.indexes[0]"와 "$last.shot"는 이전 작업을 참조). add_commands, update_command, move_command, delete_commands로 세부 조정합니다. write_animation은 모든 샷을 교체할 때만 사용하세요. 이전에 작성해 본 적 없는 명령 유형의 경우, describe_animation_command로 먼저 정확한 필드를 반환받으세요. 키프레임 방식이 아닌 수행된 듯한 모션(손으로 그린 듯한 휘두르기, 불규칙한 드래그, 이동 중 색상 선택)이 필요한 경우, record_animation_take로 시간 샘플을 기록하여 하나의 샷으로, 마치 사람이 무대에서 실시간으로 녹화하는 것처럼 처리하세요.
4. 맞춤 및 큐 지정. fit_animation으로 특정 길이에 맞춥니다(속도가 중요한 샷은 유지). 음악이나 음성 해설의 경우, set_animation_settings에서 beat 또는 narration을 설정하고, get_timing_grid로 큐를 읽은 후, 샷에 "at": { "beat": n } 또는 { "word": i }를 지정하세요.
5. 점검. check_animation을 실행하고 모든 오류와 경고(too-fast, overlap, out-of-frame, enter-visible, cue-missed와 같은 코드)를 수정하세요. 간격과 호를 숫자로 확인하려면 get_motion_path를 사용하세요.
6. 확인. render_animation_frame을 shot + at: "end"와 함께 사용하거나, times를 사용하여 연락처 시트를 만드세요. onion_skin / motion_paths를 추가하여 한 그림에서 모션을 볼 수 있습니다. 매 편집 후가 아니라 배치 작업 후에 렌더링하세요. seek_animation은 사용자에게 특정 순간을 보여줍니다.
7. 내보내기 요청 시: export_flair_motion, export_flair_effect(set_animation_controls 이후) 또는 export_lottie를 사용하고, 반환된 노트에서 샘플링되거나 누락된 사항을 확인하세요.

모범 사례

• 샷 하나당 하나의 아이디어, 한 번에 하나의 초점 모션. 액션을 배치하여 시선이 어디를 봐야 할지 알 수 있게 하세요. 보조 요소는 덜, 나중에, 또는 전혀 움직이지 않아야 합니다. 카메라(노드 frame)를 사용하여 모든 요소를 움직이지 않고 주의를 집중시키세요.
• 모든 변화에 이징 적용. 도착은 ease-out(감속하여 제자리에, enter의 기본값), 퇴장은 ease-in (exit에 ease: "ease-in"), 이동은 ease-in-out(기본값)을 사용합니다. linear는 기계적인 움직임(일정한 회전, 진행률 표시줄)이나 루프에만 사용하세요.
• 크기와 거리에 따른 타이밍. 작은 UI 변경 150-300ms, 요소 진입 300-600ms, 큰 이동 및 카메라 이동 600-1200ms. 120ms 미만은 금지(too-fast). 큰 것은 작은 것보다 느리게 움직입니다.
• 예비 동작과 후속 동작. 빠른 퇴장 전 준비 동작으로 ease-in-back; 도착 시 오버슈트 및 안정화를 위해 pop, rise, ease-out-back 또는 스프링 프리셋(spring-gentle, spring-quick)을 사용하세요. spring-bouncy는 장난스러운 느낌을 주므로 드물게 사용하세요.
• 겹치는 액션. 관련 항목들을 40-120ms 간격으로 스태거(stagger 또는 텍스트의 경우 split과 함께 cascade 사용) 처리하여 동시에 움직이지 않도록 하세요. 보조 모션은 "with": "previous"와 약간의 delay를 사용하여 선행 동작을 따라가게 하세요.
• 호. 자연스러운 움직임 곡선: 각 지점에서 멈추는 체인 이동 대신 via 웨이포인트가 있는 move (하나의 부드러운 패스)를 사용하거나, 패스 노드를 follow하세요.
• 녹화 테이크. 초당 30-60회 성능을 샘플링하세요. 녹화기는 중요한 포인트만 유지합니다 (tolerance를 높이면 더 적고 깔끔한 명령). 각 움직이는 요소는 현재 포즈에서 샘플링하여 시작하세요 (get_motion_path의 마지막 지점 또는 정지 시 경계 중심). 그렇지 않으면 첫 번째 샘플에서 해당 위치로 점프합니다. 테이크는 다른 샷 뒤(또는 at 위치)에 새로운 샷으로 추가되며, 기존 샷 위에 레이어될 수 없습니다. 다른 샷과 마찬가지로 일반 move(via 및 times 포함), scale, rotate, fade 및 style 명령을 사용하여 세부 조정하세요.
• 읽을 수 있을 만큼 충분히 유지. 각 결과를 화면에 충분히 표시하세요(샷 hold, 기본값 600ms). 읽어야 하는 텍스트는 단어당 약 250ms, 마지막 프레임이나 로고는 더 길게 유지하세요.
• 절제된 과장. 강조(pulse, shake, teeter, color-pulse)는 주의가 필요한 한 가지에, 한 번만 사용하세요. 자체적으로 원래 상태로 돌아옵니다.
• 모션 블러는 진정으로 빠른 모션에만 사용하세요(motionBlur: { shutter: 180 }). 스테이지와 렌더링된 프레임에 영향을 미치며, Flair 또는 Lottie 내보내기에는 적용되지 않습니다.
• 접근성. 깜박임 방지: 초당 3회를 초과하지 않도록 하세요(WCAG 2.3.1). 따라서 color-pulse와 큰 영역의 페이드는 느리고 적게 사용하세요. 필수 UI 모션의 경우 대규모 시차, 확대/축소 및 회전을 피하세요. 축소된 모션 대안을 제공하세요(호스트가 prefers-reduced-motion에서 페이드 또는 종료 상태로 전환해야 함. 이 편집기는 자동 생성하지 않음). 5초 이상 실행되는 루프는 일시 중지 방법이 필요합니다(WCAG 2.2.2).
• 인터랙티브 요소. 버튼 또는 토글의 경우 trigger(click, hover, press, scroll)를 설정하세요. 클릭 토글의 경우 마지막 샷이 시작 상태를 복원하도록 만드세요.

도구 참조

읽기

도구	용도
get_animation	여기서 시작하세요. 이름, 아트워크 크기, 길이(ms), 루프, 요소(id, 유형, 이름, 부모, 경계, 솔리드 페인트, 숫자 매개변수가 있는 라이브 효과), 각 명령의 인덱스, 시작, 종료 및 flairPrimitive가 포함된 모든 샷, 클립, 드라이버, 컨트롤 및 문제 요약, 편집이 거부될 때의 readOnly를 반환합니다. includeElements: false(기본 true)는 대형 아트워크에서 요소 목록을 건너<0xE1><0x85><0xB3>니다.
get_shot	저장된 하나의 샷(shot id)을 시작/종료와 각 명령의 시작/종료(ms)와 함께 읽습니다. 하나의 샷을 세부 조정하는 동안 get_animation보다 가볍습니다.
describe_animation_command	아직 사용해보지 않은 명령 유형을 작성하기 전, 또는 쓰기 작업이 필드를 거부할 때: types(예: ["enter", "move"]) 각각에 대한 전체 JSON Schema를 반환하며, 각 필드의 유형, 범위, 기본값, 의미 및 필수 여부를 보여줍니다. 쓰기 도구들은 각 명령 필드를 짧게, 해당 필드를 사용하는 유형 접두사와 함께 한 번 나열합니다.
find_animation_elements	아트워크가 큰 경우, ID 또는 이름에 query가 포함된 요소를 찾습니다(대소문자 구분 없음, limit 기본 20, 최대 200). ID, 유형, 이름, 부모, 경계, 페인트, 효과를 반환합니다.
get_text_layout	split으로 윤곽선 텍스트를 애니메이션하기 전에: 읽기 순서대로 group의 줄, 단어 및 글자 ID를 반환합니다. 요소가 패스 그룹이 아니면 오류가 발생합니다(텍스트를 윤곽선으로 변환하고, 글자당 하나의 패스로 만든 후 그룹화).
get_motion_path	간격, 호 및 착지 지점을 숫자로 확인: from에서 to ms까지 step ms(기본 33, 최대 400개 샘플)마다 node 중심(문서 단위)을 샘플링하고, 각 이동 변경이 시작되고 끝나는 위치를 표시합니다.
get_timing_grid	from과 to 사이의 비트(번호, ms, 마디, 마디 내 비트)와 나레이션 단어(인덱스, 텍스트, 시작, 종료)를 나열하고(limit 기본 200), 각각에서 재생되는 샷을 표시하여 at 큐를 선택하는 데 도움을 줍니다. 비트 그리드나 나레이션이 설정되지 않은 경우 힌트와 함께 비어 있습니다.
check_animation	모든 쓰기 배치 후에 실행하세요. 코드, 심각도, 샷, 명령 인덱스, 노드 ID, 측정된 값과 필요한 값, 수정 방법이 포함된 문제 목록을 표시합니다. 오류와 경고를 수정하고, 참고 사항은 권고 사항입니다.
render_animation_frame	결과 확인: time(ms) 또는 shot + at(start, middle, end, 기본 end). times(2-16개 순간)는 레이블이 지정된 연락처 시트를 만듭니다(columns 1-8). onion_skin은 고스트 프레임을 추가합니다(before 기본 2, after 0, spacing ms 또는 "commands"). motion_paths(true 또는 ID)는 이동 경로를 그립니다. 기본 형식은 SVG입니다. format: "png"는 호스트가 래스터화할 수 있는 경우에만 사용하세요.
export_flair_motion	씬을 Flair SvgMotion { svg, animate }로 홀드, 샘플링 단계 수 및 노트와 함께 가져옵니다. fps(기본 씬 fps, 없으면 30), curves 및 behaviors(기본 true), flair 대상 버전(기본 0.39, 이전 버전은 스프링, 단계, 동작 및 곡선을 샘플링).
export_flair_effect	Flair 카탈로그 벡터 효과(id는 케밥 케이스, name, description, category 기본 icon, tags, 추가로 위와 동일한 curves / behaviors / flair)를 가져옵니다. 먼저 set_animation_controls를 호출하여 색상이 {{name: color}} 컨트롤이 되도록 하세요.
export_lottie	lottie-web 및 모바일 플레이어용 Lottie(Bodymovin v5) JSON을 샷당 마커와 함께 가져옵니다. fps(기본 씬 fps, 없으면 30), 샘플링된 키프레임 수 및 전달되지 않은 항목(그레이디언트, 대시, 리빌 클립, 포인트 수가 변경된 morph)에 대한 노트를 포함합니다.

쓰기

도구	용도
seek_animation	사용자에게 특정 순간을 보여줍니다: time(ms) 또는 shot의 시작, play true/false. 씬을 변경하지 않습니다.
set_animation_artwork_svg	아트워크를 독립형 svg(viewBox 포함)로 한 번의 실행 취소 단계로 교체합니다. 애니메이션할 모든 요소에 ID를 부여하세요. 기존 샷이 새 아트워크에 없는 ID를 참조하면 거부됩니다. 요소를 반환합니다.
import_pptx_animation	전체 씬을 PowerPoint 슬라이드의 도형 및 애니메이션 창으로 교체합니다(data는 base64 .pptx, slide 기본 1). 클릭당 하나의 샷, 지연, 반복 및 가속도 유지. 텍스트, 그림 및 차트는 노트와 함께 생략됩니다. 먼저 dry_run: true로 실행하세요.
set_animation_drivers	모든 드라이버를 교체합니다(빈 목록은 지움). 대상의 x, y, rotation, scaleX, scaleY 또는 opacity가 소스 노드의 속성을 change · factor + offset으로 따르며, 선택적으로 clamp됩니다. 시차, 굴러갈 때 회전하는 바퀴, 무언가가 떠오를 때 사라지는 그림자 등에 사용하세요.
set_animation_clip	이름이 지정된 재사용 가능한 클립을 정의, 교체 또는 (clip: null로) 삭제합니다. run은 "$"를 대상으로 합니다. play 명령으로 모든 노드에서 재생합니다. 반복되는 동일한 명령보다 클립을 선호하세요.
copy_animation	to의 노드에 from을 애니메이션하는 모든 명령(모든 샷 또는 shots)을 제공합니다. 각 복사본은 원본으로 시작하며, 선택적으로 stagger(ms)됩니다. 일회성 복제에 빠릅니다. 재사용할 모션에는 클립을 사용하세요.
record_animation_take	수행된 모션을 새 샷으로 녹화합니다(한 번의 실행 취소 단계). samples(각각 { node, t (테이크 시작부터 ms), x, y (중심), scaleX, scaleY, rotation, opacity, fill, stroke, strokeWidth })는 녹화된 times의 웨이포인트를 통한 move와 시작 시점의 몇 가지 이징된 scale / rotate / fade / style 명령이 됩니다. 선택적 length, id, label, at, tolerance. dry_run: true는 먼저 run을 반환합니다. 샷 ID, 시작 시간, 각 명령의 인덱스, 유형, 시작 및 종료를 반환합니다. 이후에 check_animation 및 render_animation_frame을 실행하세요.
fit_animation	샷 speed를 설정하여 씬을 seconds 동안 지속되도록 하고 비율은 유지합니다. keep의 샷은 작성된 대로 재생됩니다. dry_run: true는 먼저 새 길이와 속도를 보고합니다.
import_flair_effect	전체 씬을 Flair 벡터 effect 또는 SvgMotion motion으로 교체합니다(정확히 하나만 제공, 선택적 name). 플레이스홀더는 색상 컨트롤이 됩니다. 각 Flair 단계는 샷이 됩니다. 먼저 dry_run: true를 사용하세요.
insert_shots	위치 at(기본 끝)에 하나 이상의 완전한 샷(id, run, 선택적 label, camera, hold, speed, at)을 추가합니다. 모든 샷의 타이밍과 문제를 반환합니다.
update_shot	set을 통해 하나의 샷의 label, camera, run, hold, speed, at 또는 id를 변경하고, remove를 통해 label, camera, hold, speed 또는 at을 지웁니다.
delete_shots	ID로 샷을 제거합니다(한 번의 실행 취소 단계).
move_shot	샷을 인덱스 to로 재정렬합니다(0 = 첫 번째).
add_commands	샷의 run 내 인덱스 at(기본 끝)에 명령을 추가합니다. 명령이 할당된 인덱스와 타이밍을 반환합니다. 이후 업데이트에 해당 인덱스를 사용하세요.
update_command	하나의 명령(shot 및 command 인덱스로 지정)을 변경합니다. set의 필드는 교체되고, remove의 이름은 지워집니다(예: "delay"). 명령과 타이밍을 반환합니다.
delete_commands	샷에서 인덱스로 명령을 제거합니다. 이후 명령은 위로 이동하므로 이후에 인덱스를 다시 읽으세요.
move_command	하나의 명령을 run 내의 인덱스 to로 이동합니다. "with": "previous" 명령은 새 이웃과 함께 시작됩니다.
set_animation_settings	name, description, loop(none, loop, ping-pong), trigger(click, hover, press, scroll 또는 null), 내보내기 fps(기본 30), 씬 steps(12 = on twos, null은 부드러움)를 설정합니다.