media-use
미디어 요구사항을 로컬에 고정된 파일로 해결합니다. 하나의 동사, 네 가지 유형, 제로 컨텍스트 노이즈.
사용 시기
작곡에 배경 음악, 음향 효과, 이미지 또는 아이콘 등 미디어가 필요할 때마다 resolve를 호출하세요. media-use는 HeyGen 카탈로그를 검색하여 가장 적합한 항목을 다운로드하고, 로컬에 고정하며, 메니페스트에 등록합니다. 에이전트는 한 줄의 결과만 반환받고, 모든 검색 노이즈는 디스크에 남습니다.
Resolve
node <SKILL_DIR>/scripts/resolve.mjs --type <type> --intent "<설명>" --project <dir>
한 줄의 결과를 반환합니다: resolved <id> → <path> (<type>, <metadata>)
유형
| 유형 | 찾는 대상 | 제공자 |
|---|---|---|
bgm | 배경 음악 | HeyGen 오디오 카탈로그 (1만 개 이상 트랙) |
sfx | 음향 효과 | 번들 19개 파일 라이브러리 + HeyGen 카탈로그 |
image | 사진, 배경 | HeyGen 에셋 검색 (7만 5천 개 이상 벡터) |
icon | 아이콘, 로고 | HeyGen 에셋 검색 (type=icon) |
예시
# 배경 음악
node <SKILL_DIR>/scripts/resolve.mjs --type bgm --intent "신나는 기술 런칭" --project .
# → resolved bgm_001 → .media/audio/bgm/bgm_001.mp3 (bgm, 25s)
# 음향 효과
node <SKILL_DIR>/scripts/resolve.mjs --type sfx --intent "휙" --project .
# → resolved sfx_001 → .media/audio/sfx/sfx_001.mp3 (sfx, 0.57s)
# 이미지
node <SKILL_DIR>/scripts/resolve.mjs --type image --intent "그라데이션 기술 배경" --project .
# → resolved image_001 → .media/images/image_001.jpg (image)
# 아이콘
node <SKILL_DIR>/scripts/resolve.mjs --type icon --intent "로켓" --project .
# → resolved icon_001 → .media/images/icon_001.png (icon, 투명)
플래그
| 플래그 | 설명 |
|---|---|
--type, -t | 미디어 유형: bgm, sfx, image, icon |
--intent, -i | 필요한 내용 (자연어) |
--entity, -e | 캐시 매칭용 엔티티 이름 (선택 사항) |
--project, -p | 프로젝트 디렉토리 (기본값: .) |
--adopt | 기존 assets/를 메니페스트에 일괄 가져오기 |
--json | 한 줄 결과 대신 JSON 출력 |
동작 방식
- 프로젝트
.media/manifest.jsonl에서 정확한 프롬프트 일치 확인 - 기존
assets/디렉토리에서 요구 사항과 일치하는 미등록 파일 검색 - 글로벌 캐시
~/.media/에서 재사용 가능한 자산 확인 - 제공자 검색 (HeyGen 오디오 카탈로그, HeyGen 에셋 검색)
- 파일을
.media/<type>/에 고정하고 메니페스트에 등록한 후index.md재생성
에이전트는 한 줄을 반환받습니다. 후보, 점수, 출처는 디스크에 남습니다.
기존 프로젝트 채택
대부분의 HyperFrames 프로젝트에는 이미 assets/에 자산이 있습니다. media-use가 이를 채택합니다:
node <SKILL_DIR>/scripts/resolve.mjs --adopt --project .
# → adopted 9 assets from assets/
# bgm_001 → assets/bgm/mango-fizz.mp3 (bgm, 146.6s)
# image_001 → assets/images/avatar.jpg (image, 400×400)
ffprobe가 실제 재생 시간과 크기를 추출합니다. resolve 중에 의도와 일치하는 assets/의 미등록 파일은 즉시 채택됩니다.
인벤토리 읽기
resolve 또는 adopt 후, .media/index.md에서 전체 인벤토리를 확인하세요:
# .media · 4 assets
id type dur dims path description
bgm_001 bgm 25s — .media/audio/bgm/bgm_001.mp3 신나는 기술 런칭
sfx_001 sfx 0.6s — .media/audio/sfx/sfx_001.mp3 휙
image_001 image — 1920×1080 .media/images/image_001.jpg 그라데이션 기술 배경
icon_001 icon — 200×200 .media/images/icon_001.png 로켓
프로젝트 간 재사용
resolve 시 자산이 자동으로 캐시됩니다. 동일한 프롬프트에 대한 후속 resolve는 ~/.media/의 글로벌 캐시를 사용하므로 재다운로드나 제공자 호출이 없습니다. organize --promote <id>로 자산을 명시적으로 승격시키면 모든 프로젝트에서 재사용할 수 있습니다.
파일
.media/manifest.jsonl— 시스템 단일 진실 공급원(SSOT), 한 줄에 하나의 JSON 레코드.media/index.md— 에이전트가 읽을 수 있는 테이블 (id, type, dur, dims, path, description)~/.media/— 프로젝트 간 재사용을 위한 글로벌 캐시 (콘텐츠 주소 지정, SHA-256)
사용된 CLI 도구
| 도구 | 용도 | 필수 여부 |
|---|---|---|
ffprobe | 채택 시 재생 시간, 크기, 코덱 탐색 | 예 |
heygen | 오디오 카탈로그, 에셋 검색 | 제공자용 |
heygen CLI (단일 정적 바이너리, 런타임 불필요)를 설치하고 인증하세요:
curl -fsSL https://static.heygen.ai/cli/install.sh | bash # 최신 버전을 ~/.local/bin에 설치
heygen update # 이미 설치된 경우: v0.1.6 이상 필요
export HEYGEN_API_KEY=<your-key> # 또는: heygen auth login --key <key>
heygen >= v0.1.6이 필요합니다 — 제공자는 허용 목록에 추가된 --headers 'X-HeyGen-Client-Source: media-use' 플래그( v0.1.6에서 추가됨)와 함께 요청을 전송합니다. asset search는 heygen --help에서 숨겨진 출시 전 명령이지만 실행 가능합니다. PATH에 heygen이 없거나(또는 유효한 키가 없는 경우) 제공자는 stderr에 한 줄 진단을 출력하고 resolve는 "제공자가 해결할 수 없음"으로 폴백됩니다.