App Store 헤더 비디오

두 가지 App Store 크리에이티브 에셋 비디오를 제작합니다: 앱 아이콘 위에 루핑되는 제품 페이지 헤더와 검색 결과에서 앱 카드에 표시되는 검색 결과 헤더입니다. 두 비디오 모두 음소거 상태로 자동 재생되며 끊임없이 반복되므로, 모든 프레임이 소리 없이도 동작해야 하고 마지막 프레임이 첫 번째 프레임으로 자연스럽게 이어져야 합니다.

이 스킬은 파일을 준비합니다. 업로드나 제출은 절대 수행하지 않습니다. 사용자가 App Store Connect에 게시합니다.

수집할 입력 정보

대화에서 이미 제공된 정보가 무엇인지 확인하고, 누락된 정보만 요청하세요.

배치 위치 — 헤더(21:9), 검색 결과(3:2), 또는 둘 다. 각각 다른 해상도를 가지므로 헤더 렌더링을 검색 결과에 그대로 재사용할 수 없습니다.
하나의 아이디어 — 비디오가 전달해야 할 한 문장의 아이디어. Apple의 가이드라인: "하나의 명확한 아이디어에 집중하세요." 두 가지 아이디어는 모두 전달되지 않습니다.
앱 식별 정보 — 앱 이름, 한 줄 가치 제안, 브랜드 색상, 로고 파일, 앱 아이콘 PNG.
실제 제품 자료 — 컨셉이 앱을 보여주는 경우 실제 앱의 스크린샷 또는 영상. 크리에이티브 에셋은 앱 사용 대신 브랜드나 콘텐츠를 강조할 수 있으므로 선택 사항이지만, 앱이 표시될 때는 실제 캡처여야 합니다.
길이 — 기본값 8초. Apple은 5~30초를 허용합니다.
시기 — 상시, 시즌성 출시, 기능 출시, 리브랜딩. 이후 에셋의 재사용 가능 여부에 영향을 줍니다.

절차

이 스킬의 스크립트는 이 파일과 같은 디렉토리의 scripts/에 있습니다. 스크립트를 실행할 때는 SKILL.md 파일의 자체 디렉토리를 기준으로 경로를 해석하세요. 사용자의 작업 디렉토리는 스킬 디렉토리가 아닙니다.

1. 배치 위치 확정 및 사양 읽기

빌드하기 전에 references/specs.md를 읽으세요. Apple의 정확한 표, 앱 프리뷰와 크리에이티브 에셋의 차이점, 안전 영역 규칙이 포함되어 있습니다.

PATH에 asc CLI가 있다면 asc asset-library specs 명령어로 Apple의 실시간 참조 데이터를 확인할 수 있습니다. 이 데이터를 사용하여 이 스킬이 작성된 이후 숫자가 변경되지 않았는지 확인하세요. references/publishing.md에 해당 쿼리가 있습니다.

두 배치 위치는 서로 교체할 수 없습니다:

배치 위치	종횡비	크기	일반적인 용도
제품 페이지 헤더	21:9	정확히 3840x1646	아이콘 위의 전체 너비 배너
검색 결과	3:2	1920x1280 ~ 3840x2560	검색 결과의 카드

2. 하나의 아이디어 선택 및 포스터 프레임 지정

단일 아이디어와 포스터 프레임을 기록하세요. 포스터 프레임은 재생이 시작되기 전 사용자가 보는 정지 이미지이며, Apple이 자동 재생이 꺼져 있을 때 표시하는 프레임입니다. 포스터 프레임은 정적 이미지로 단독으로도 의미가 전달되어야 합니다. "가치 제안이나 가장 설득력 있는 기능으로 시작하세요" (Apple). 포스터 프레임을 이해하기 위해 캡션이 필요하다면 아이디어가 아직 완성되지 않은 것입니다.

3. 클립이 아닌 이음매(seam) 설계

비디오는 지속적으로 반복되며 사람들이 여러 번 시청하므로 t=0과

t=D에서의 상태가 일치해야 합니다. 애니메이션 전에 이를 계획하세요:

연속 동작 — 완전 360° 회전 또는 끝없이 이동하는 필드는 추가 작업 없이 완벽하게 감싸집니다.
기본 상태로 복귀 — 스케일 또는 위치가 시작 값으로 다시 애니메이션되고 마지막 비트가 정확히 시작 프레임에 도달합니다.
페이드 스루(Fade through) — 시작 비트에서 페이드 인, 유지, 종료 비트 동안 기본 상태로 페이드 아웃되어 감싸기가 부드러운 디졸브가 됩니다.

클립은 [start, start + duration) 구간에 걸쳐 표시되며, 끝 상태가 정확히 끝에 도달하는 것은 렌더링되지 않습니다. 종료 트윈을 한 프레임 일찍 (start + duration - 1/fps) 끝내면 최종 가시 프레임이 실제로 기본 상태가 됩니다. 그렇지 않으면 루프가 닫히기 한 프레임 모자랍니다.

시작 프레임과 다른 프레임에서 끝나는 클립은 루프가 아닌 버그로 읽힙니다.

4. HyperFrames로 빌드

npx hyperframes init <project-dir>

루트 index.html은 캔버스를 선언합니다. 배치 위치의 정확한 픽셀 크기로 설정하세요. HyperFrames는 구성의 작성된 해상도로 렌더링하며, 사용자가 가정하는 크기는 무시합니다:

<div id="root"
     data-composition-id="main"
     data-width="3840" data-height="1646"
     data-duration="8" data-fps="30">

이 단계를 성공시키거나 망치는 규칙:

#root에 1920px/1080px를 하드코딩하지 말고 width:100%; height:100%로 스타일링하세요.
21:9 또는 3:2에 대한 --resolution 프리셋이 없습니다. --resolution landscape-4k는 3840x2160으로, 모양이 잘못되어 거부됩니다.
호스트 div, 씬 루트, 타임라인 키에 동일한 id를 부여하세요. 불일치 시 각 씬이 45초간 대기한 후 정적 프레임을 표시합니다.
씬 내부에서 from 대신 fromTo를 사용하세요. 호스트가 씬을 다시 탐색하고 from은 뒤로 탐색 시 표류하여 루프가 깨집니다.
폰트는 @font-face와 함께 assets/fonts/에 파일로 번들링되어야 합니다. 번들된 패밀리만 이름으로 확인됩니다.
텍스트와 카피는 이미지에 굽지 말고 변수(data-var-text)로 구성에 배치하세요.
각 씬을 compositions/ 내의 자체 하위 구성으로 유지하여 단일 비트를 다시 렌더링할 수 있도록 하세요.

references/hyperframes-build.md에는 루프 기법 스니펫, 확인 및 스냅샷 명령어, 렌더 플래그, 그리고 3840x1646 브라우저 렌더링이 반복 작업하기에 너무 느릴 때 대체할 수 있는 캔버스-to-ffmpeg 파이프라인이 있습니다. 사양과 검증은 동일합니다.

5. 컨셉이 필요할 때만 지원 이미지 생성

사진, 일러스트레이션, 분위기 배경은 이미지 생성 도구를 사용합니다. 이미지 모델로 앱 UI를 절대 생성하지 마세요. 인터페이스를 환각(hallucinate)하며, 스토어 목록의 가짜 UI는 UI가 없는 것보다 나쁩니다. 앱에는 실제 스크린샷을 사용하고, 그 외 모든 것에는 생성 도구를 사용하세요.

mcode-tools connector tools --keyword image
mcode-tools connector tool <tool_name>          # 먼저 input_schema 읽기
mcode-tools connector call <tool_name> --args '{"prompt":"...","aspect_ratio":"21:9"}'

references/asset-generation.md에는 전체 검색 및 호출 흐름과 특정 종횡비를 위한 프롬프트 작성 방법이 있습니다.

6. 확인, 스냅샷, 미리보기 — 그 다음 렌더링

npx hyperframes check --json                                  # 반드시 깨끗해야 함
npx hyperframes snapshot --at 0,4,8                            # PNG 읽기
npx hyperframes preview --background                           # 사용자에게 URL 제공

미리보기를 보여주기 전에 스냅샷을 확인하세요. 검사(check) 통과만으로 프레임이 올바르게 보이는 것은 아닙니다.

사용자가 미리보기를 보고 승인한 후에만, 또는 중단 없이 파일을 요청했을 때만 렌더링하세요:

npx hyperframes render --quality delivery --fps 30 --format mp4 --output out/<name>.mp4

소스가 앱의 화면 녹화인 경우 --video-frame-format png를 추가하여 UI 텍스트와 단색이 프레임 추출에서 손상되지 않도록 하세요.

스냅샷으로 반복 작업하고, 한 번만 렌더링하세요. 단일 프레임 스냅샷은 거의 즉각적이므로 npx hyperframes snapshot --at 0,4,7.9로 구성을 평가하고 PNG를 읽으세요. 8초 분량의 3840x1646 딜리버리 렌더링은 M-시리즈 Mac에서 약 9초가 소요됩니다. 렌더링 자체가 느린 부분이 아니라 반복 작업이 느린 부분입니다. 프레임이 올바르게 보일 때 한 번만 렌더링하세요.

딜리버리 품질로 테스트를 렌더링하거나, 이음매(seam) 판정을 신뢰하기 전에 다시 인코딩하세요. 드래프트 품질 렌더링은 양자화 노이즈를 수반하며, 인코더의 최종 프레임 노이즈는 첫 번째 프레임의 노이즈와 다릅니다. 이는 지오메트리가 아닌 랩(wrap) 차이로 나타나며, 존재하지 않는 버그를 쫓게 됩니다. 작은 테스트가 --quality draft에서 나온 경우, 컨폼 스크립트가 사용하는 방식(libx264 -crf 18 -pix_fmt yuv420p)으로 다시 인코딩하고 확인하세요.

7. 파일을 사양에 맞게 컨폼(conform)

HyperFrames 렌더링 후에도 이 작업을 실행하세요. 잘못된 프레임 속도와 잘못된 픽셀 크기는 사람들이 가장 먼저 겪는 두 가지 거부 사유입니다.

node <skill-dir>/scripts/conform-video.mjs --in out/header.mp4 --out out/<app>-header.mp4 --placement header
node <skill-dir>/scripts/conform-video.mjs --in out/search.mp4 --out out/<app>-search.mp4 --placement search

각 배치 위치는 자체 구성과 자체 렌더링이 필요합니다. 헤더 캔버스는 21:9이고 검색 캔버스는 3:2입니다. 하나를 다른 쪽으로 자르면 구성이 무시되고 피사체가 프레임 밖에 위치하게 됩니다. 컨폼은 해상도, 프레임 속도 및 코덱을 수정합니다. 잘못된 모양을 위해 빌드된 구성은 고칠 수 없습니다. 검색 구성의 루트는 data-width="3840" data-height="2560"로 설정하세요.

배치 위치당 하나의 프로젝트 루트. 루트 구성은 캔버스를 선언하므로 두 배치 위치가 하나의 루트를 공유할 수 없습니다. 각각 자체 index.html과 에셋 사본이 있는 별도의 프로젝트 폴더를 생성하세요. check와 snapshot은 루트만 보며, render --composition <file>은 독립 구성 파일을 렌더링합니다.

스크립트는 정확한 캔버스로 스케일 및 자르기, 상수 30 또는 60 fps 강제, H.264 yuv420p(알파 없음) 인코딩, 오디오 제거, faststart 설정을 수행합니다. 소스가 너무 작으면 자동으로 업스케일하지 않으며 그 사실을 알립니다.

8. 전달 전 검증

node <skill-dir>/scripts/verify-video.mjs out/<app>-header.mp4 --placement header
node <skill-dir>/scripts/verify-video.mjs out/<app>-search.mp4 --placement search

스크립트는 해상도, 종횡비, 프레임 속도(상수, 정확히 30 또는 60), 지속 시간, 코덱, 픽셀 형식 및 오디오를 확인합니다. 또한 루프 이음매를 판단합니다. 클립 자체의 일반적인 프레임 간 모션을 기준으로 첫 번째 프레임과 마지막 프레임을 비교하여, 일반 프레임 단계보다 더 파괴적인 랩을 눈에 띄는 점프로 보고합니다. 두 프레임을 모두 보여주는 *-seam.png 스트립을 생성합니다. 종료 코드가 0이어야 합니다. 그렇지 않으면 구성을 수정하고 다시 렌더링하세요.

그런 다음 포스터 프레임을 추출하여 단독으로 확인하세요. 이것이 스토어가 재생 시작 전에 표시하는 정지 이미지입니다. 캡션이 필요하다면 비디오에 수정이 필요합니다. 첫 번째 프레임이 아닐 수 있는 가장 강력한 프레임을 선택하세요:

ffmpeg -v error -y -ss 00:00:04.000 -i out/<app>-header.mp4 -frames:v 1 out/<app>-poster.png

선택한 타임코드를 보고하세요. 포스터 프레임은 Asset Library에서 에셋에 설정되며 에셋이 승인된 후에는 편집할 수 없습니다. 따라서 제출 전에 선택해야 합니다.

9. 전달

사용자에게 다음을 제공하세요:

최종 파일 경로(들), 배치 위치당 하나
검증 보고서
포스터 프레임 및 해당 프레임 위치
게시 단계

크리에이티브 에셋은 세 개의 별도 게이트(업로드, 승인, 배치)를 통과해야 하며, 승인만으로 게시되지 않습니다. references/publishing.md에는 정확한 asc 명령어와 함께 두 가지 경로가 있습니다:

asc asset-library view --app APP_ID                     # 라이브러리 ID 찾기
asc asset-library videos upload --library-id ID --file ./header.mp4
asc asset-library videos set-poster-frame --id VIDEO_ID --time-code 00:00:04:00
asc localizations list --app APP_ID                     # 지역화 ID 찾기
asc localizations placements create --localization-id LOC --video-id VID \
  --placement-type PRODUCT_PAGE_HEADER_ASSET           # 또는 APP_STORE_SEARCH_RESULTS_ASSET

이미 라이브 상태인 앱의 경우 App Store Connect의 간단한 방법은 다음과 같습니다: Apps → 앱 → 사이드바 → Asset Library → + → Upload Creative Assets → 두 파일 모두 업로드 → 포스터 프레임 설정 → Add for Review → Submit for Review → APPROVED 대기 → 라이브 버전 → **Product Page Information (제품 페이지 정보) → "Header and Search Results" → Browse Assets → 에셋 선택 → Next (다음) → Publish (게시). 이렇게 하면 새 버전이나 새 검토 없이 라이브로 전환됩니다. 앱에 라이브 버전이 아직 없는 경우 대신 에셋을 다음 버전에 첨부하고 제출하세요.

사용자에게 Header and Search Results 탭의 Preview로 결과를 확인하라고 알리세요. iPhone 및 iPad, 여러 방향, 언어 및 다크 모드에서 에셋을 보여주며, 배치 위치별로 자르기가 다릅니다. 포스터 프레임은 에셋이 승인된 후에 편집할 수 없으므로 제출 전에 선택하세요.

여기서 멈추세요. 업로드, 검토 제출 또는 게시를 직접 실행하지 마세요. 업로드 및 게시는 사용자의 단계입니다.

출력 계약

out/<app>-header.mp4 — 3840x1646, H.264 yuv420p, 상수 30 또는 60 fps, 5~30초, 알파 없음, 오디오 없음, 500MB 미만
out/<app>-search.mp4 — 3:2, 1920x1280~3840x2560 범위 내, 동일 인코딩 규칙
모든 검사가 PASS인 검증 보고서
포스터 프레임 및 해당 타임코드
references/publishing.md의 게시 단계가 포함된 짧은 전달 메모

두 배치 위치 모두 자체 파일을 받습니다. 하나의 파일을 두 위치에 모두 제공하지 마세요.

장애 처리

증상	조치
`ffprobe` / `ffmpeg`를 찾을 수 없음	`brew install ffmpeg`(macOS) 또는 `choco install ffmpeg`(Windows); 스크립트가 확인 및 컨폼을 위해 필요합니다
HyperFrames가 Chrome을 시작할 수 없음	`npx hyperframes browser ensure`, 그 다음 `npx hyperframes doctor --json` 실행 후 `.ok` 확인
렌더링이 느리게 느껴짐	보통 그렇지 않습니다. 3840x1646, 8초 딜리버리 렌더링은 M-시리즈 Mac에서 약 9초가 소요됩니다. 정말 느리다면 렌더러에 GPU 워커가 있는지 확인하고, 다시 렌더링하는 대신 `hyperframes snapshot` 프레임으로 반복 작업하세요. `--quality looks`는 `--quality delivery`보다 빠릅니다 (외형만 확인할 경우)
인코더가 레벨 4.1로 파일 태그 지정	두 캔버스 모두 레벨 4.1 매크로블록 상한을 초과합니다. 3840x1646은 24720 매크로블록이고 1920x1280은 9600이며, 제한은 8192입니다. `-level 5.1`로 다시 인코딩하세요
이음매 검사 실패	마지막 비트를 수정하여 상태가 기본 상태로 돌아가도록 하세요. 크로스페이드(`--seam-crossfade`)는 폴백(fallback)이지 수정이 아닙니다. 콘텐츠의 `C` 초를 소비하기 때문입니다
썸네일 크기에서 텍스트를 읽을 수 없음	텍스트를 확대하세요. Apple은 에셋이 스토어에서 다르게 나타난다고 언급하므로 가장 작은 렌더링이 실제 테스트입니다
App Store Connect에서 업로드 거부됨	로컬 원본이 아닌 실제 업로드된 파일에 대해 `verify-video.mjs`를 다시 실행하세요. `asc asset-library videos upload`도 업로드 전에 Apple의 라이브 사양에 대해 파일을 검증하므로, 오류 메시지에 놓친 규칙이 명시됩니다
Apple이 배치 위치 거부	슬롯이 이미 사용 중일 수 있습니다. 배치 위치 생성은 기존 위치를 교체하지 않습니다. `asc localizations placements delete`를 사용하여 먼저 이전 위치를 제거한 후 새 위치를 생성하세요

앱스토어 헤더 비디오