JianYing Editor Skill
사용자가剪映 Pro에서 비디오 편집을 자동화하고, 드래프트를 생성하거나 미디어 에셋을 조작하려 할 때 이 Skill을 사용하세요.
Agent 실행 플레이북: docs/agent-playbook.md
최소 명령 SOP: docs/minimal-command-sop.md
자연어 사용 가이드: usage.md
드래프트 검사기 CLI:
python <SKILL_ROOT>/scripts/draft_inspector.py list --limit 20
python <SKILL_ROOT>/scripts/draft_inspector.py summary --name "DraftName"
python <SKILL_ROOT>/scripts/draft_inspector.py show --name "DraftName" --kind content --json
일반 편집 요청의 경우, 항상 해당 플레이북의 "Quick Edit Runtime Template" 및 "Acceptance Checklist"를 따르세요.
🚨 중요 개발 원칙 (CRITICAL DEVELOPER RULES)
- 스크립트 위치: Skill 내부 디렉토리에 편집 스크립트를 생성하지 마십시오. 모든 편집 로직 구현 코드(.py 스크립트)는 사용자 현재 프로젝트의 루트 디렉토리(또는
scripts/와 같은 하위 디렉토리)에 두어 Skill 라이브러리의 순수성과 이식성을 유지해야 합니다. - 버전 및 아키텍처:
- 이중 플랫폼 지원: MacOS (경로 탐지/화면 녹화) 및 Windows를 완벽히 지원합니다.
- 자동 복구(Auto-healing): v5.9+ (
draft_info.json)을 지원합니다. 드래프트가 손상되었거나 버전 충돌이 있는 경우,JyProject를overwrite=True로 초기화하면 자동 복구가 트리거됩니다.
- 배경 음악 선택:
- 간단한 데모는 기본 음악을 사용합니다. 실제 프로젝트에서는
data/cloud_music_library.csv에서 관련 트랙을 우선 검색하여 추천하거나, 비디오 주제(예: "科技", "温暖")에 따라 키워드 필터링을 수행하십시오. - 사용자에게 질문: "주제에 맞는 클라우드 음악을 몇 가지 찾았는데, 들어볼래요? (예:
Illuminate- 기술감)"
- 간단한 데모는 기본 음악을 사용합니다. 실제 프로젝트에서는
규칙 가이드 (Rules)
특정 작업 및 제약 조건에 대한 개별 규칙 파일을 읽으십시오:
- rules/setup.md - 필수 모든 스크립트의 초기화 코드.
- rules/core.md - 핵심 작업: 저장, 내보내기 및 드래프트 관리.
- rules/cli.md - CLI 규약 및 기계 판독 가능 출력 규칙.
- rules/media.md - 에셋 가져오기 및 AI 비디오 분석 최적화 (30m/360p).
- rules/text.md - 자막, 텍스트 및 캡션 추가.
- rules/keyframes.md - 고급: 키프레임 애니메이션 추가.
- rules/effects.md - 필터, 효과 및 전환 검색 및 적용.
- rules/recording.md - 신규: 화면 녹화 및 스마트 줌 자동화.
- rules/web-vfx.md - 고급: Web-to-Video 생성.
- rules/generative.md - 생성형 편집을 위한 사고의 사슬.
- rules/audio-voice.md - 신규: TTS 음성 해설 및 BGM 소싱.
🎯 Agent 빠른 라우팅
- 클라우드 비디오 + 클라우드 음악:
rules/media.md+rules/audio-voice.md->examples/cloud_video_music_tts_demo.py - 지능형 더빙 및 자막 (Script-to-Video):
rules/text.md+rules/audio-voice.md-> 핵심 APIadd_narrated_subtitles - 나레이션 및 자막 정렬:
rules/text.md+rules/audio-voice.md->examples/cloud_video_music_tts_demo.py - 화면 녹화 및 스마트 줌:
rules/recording.md->tools/recording/recorder.py - 일괄 내보내기/헤드리스 내보내기:
rules/core.md+rules/cli.md->examples/robust_auto_export.py - 영화 해설 생성:
rules/generative.md->scripts/movie_commentary_builder.py
📖 클래식 예제 (Examples)
완전한 워크플로우를 보려면 다음을 참조하십시오:
- examples/my_first_vlog.py - 배경 음악과 애니메이션 텍스트가 포함된 완전한 브이로그 생성 데모.
- examples/simple_clip_demo.py - 기본 커팅 및 트랙 관리를 위한 퀵 스타트 튜토리얼.
- examples/compound_clip_demo.py - 신규: 전문가용 중첩 프로젝트 (Compound Clip) 자동화.
- examples/cloud_video_music_tts_demo.py - 클라우드 비디오 + 클라우드 BGM + TTS/자막 정렬.
- examples/web_to_video_intro_demo.py - Web-to-Video 인트로 데모 (HTML 애니메이션 -> 타임라인 클립).
- examples/robust_auto_export.py - 안정적인 내보내기 워크플로우 및 오류 처리.
- examples/auto_exposure_align_demo.py - CV 지원 노출 정렬 워크플로우.
- examples/video_transcribe_and_match.py - 고급: AI 기반 워크플로우 (비디오 전사 -> AI 의미론을 통한 B-Roll 매칭 -> 드래프트 조합).
🧠 프롬프트 및 통합 도구 (Prompts & Integrated Tools)
복잡한 작업에는 다음 템플릿과 스크립트를 사용하십시오:
- 에셋 검색: 중국어/영어 이름으로 필터, 전환 및 애니메이션을 검색합니다:
python <SKILL_ROOT>/scripts/asset_search.py "레트로" -c filters - 영화 해설 빌더: 스토리보드 JSON에서 60초 해설 비디오를 생성합니다:
python <SKILL_ROOT>/scripts/movie_commentary_builder.py --video "video.mp4" --json "storyboard.json" - 네이티브 에셋 동기화: 좋아요 표시/재생한 BGM/스타일을剪映 앱에서 Skill로 가져옵니다:
python <SKILL_ROOT>/scripts/sync_jy_assets.py # 기존 드래프트에서 클라우드 자료 인덱싱 python <SKILL_ROOT>/scripts/build_cloud_music_library.py python <SKILL_ROOT>/scripts/build_cloud_text_styles_library.py - README를 튜토리얼로: 프로젝트 README.md를 전체 설치 튜토리얼 비디오 스크립트로 변환합니다:
- 프롬프트 읽기:
prompts/readme_to_tutorial.md - 내용을
{{README_CONTENT}}변수에 주입합니다.
- 프롬프트 읽기:
- 화면 녹화 및 스마트 줌: 화면을 녹화하고 자동으로 줌 키프레임을 적용합니다:
python <SKILL_ROOT>/tools/recording/recorder.py # 웹 프리뷰 캡처 (고성능) python <SKILL_ROOT>/scripts/web_recorder.py --url "http://localhost:3000" --duration 5 # 또는 기존 비디오에 줌 적용: python <SKILL_ROOT>/scripts/jy_wrapper.py apply-zoom --name "Project" --video "v.mp4" --json "e.json" - 드래프트 검사기: 드래프트 구조 및 메타데이터 검사 (v5.9+ 지원):
python <SKILL_ROOT>/scripts/draft_inspector.py list --limit 20 python <SKILL_ROOT>/scripts/draft_inspector.py summary --name "DraftName" - 자동 내보내기: 드래프트를 MP4/SRT로 헤드리스 내보내기:
참고: MP4 자동 내보내기는 Windows UI Automation을 사용합니다. macOS에서는 드래프트를 생성하고剪映에서 수동으로 내보내십시오.python <SKILL_ROOT>/scripts/auto_exporter.py "DraftName" "output.mp4" --res 1080 --fps 60 # SRT만 내보내기: python <SKILL_ROOT>/scripts/jy_wrapper.py export-srt --name "DraftName" - 템플릿 복제 및 교체기: 템플릿을 안전하게 복제하고 자료를批量 교체합니다 (원본 템플릿 손상 방지):
# 템플릿 복제하여 새 프로젝트 생성 python <SKILL_ROOT>/scripts/jy_wrapper.py clone --template "호텔 템플릿" --name "고객A_복사본" - API 검증기: 환경의 빠른 진단을 실행합니다:
python <SKILL_ROOT>/scripts/api_validator.py
🚀 빠른 시작 예제
import os
import sys
# 1. 환경 초기화 (스크립트 시작 부분에 반드시 동기화, Win/Mac 지원)
current_dir = os.path.dirname(os.path.abspath(__file__))
env_root = os.getenv("JY_SKILL_ROOT", "").strip()
# Skill 경로 탐지 (Antigravity, Trae, Claude 등 지원)
skill_root = next((p for p in [
env_root,
os.path.join(current_dir, ".agents", "skills", "jianying-editor"),
os.path.join(current_dir, ".agent", "skills", "jianying-editor"),
os.path.join(current_dir, ".trae", "skills", "jianying-editor"),
os.path.join(current_dir, ".claude", "skills", "jianying-editor"),
os.path.join(current_dir, "skills", "jianying-editor"),
os.path.abspath(".agents/skills/jianying-editor"),
os.path.abspath(".agent/skills/jianying-editor"),
os.path.abspath(".trae/skills/jianying-editor"),
os.path.abspath(".claude/skills/jianying-editor"),
os.path.abspath("skills/jianying-editor"),
os.path.dirname(current_dir)
] if p and os.path.exists(os.path.join(p, "scripts", "jy_wrapper.py"))), None)
if not skill_root: raise ImportError("Could not find jianying-editor skill root.")
sys.path.insert(0, os.path.join(skill_root, "scripts"))
from jy_wrapper import JyProject
if __name__ == "__main__":
# 2. 프로젝트 초기화 (v5.9+ 및 자동 복구 지원)
project = JyProject("New AI Video", overwrite=True)
assets_dir = os.path.join(skill_root, "assets")
# 3. 지능형 더빙 및 자막 (원클릭 Script-to-Video)
project.add_narrated_subtitles(
text="欢迎使用剪映自动化 Skill。这是一个全面适配 MacOS 的进阶版本。",
speaker="zh_female_xiaopengyou"
)
# 4. 추가素材 가져오기
project.add_media_safe(os.path.join(assets_dir, "video.mp4"), "0s")
project.add_media_safe(os.path.join(assets_dir, "audio.mp3"), "0s", track_name="Audio")
# 5. 애니메이션이 포함된 제목 추가
project.add_text_simple("剪映自动化开启", start_time="1s", duration="3s", anim_in="复古打字机")
project.save()
🛠️ 초기화 및 프로젝트 규칙 (Initialization & Project Rules)
JyProject를 초기화할 때는 주 비디오素材의 비율에 따라 해상도를 설정해야 합니다. **기본값은 가로 (1920x1080)**입니다.
🚨 스크립트 저장 위치 규칙
Skill 설치 디렉토리에 비즈니스 편집 스크립트를 생성하지 마십시오.
- 올바른 방법: 편집 Python 스크립트를 프로젝트의 루트 디렉토리에 두십시오.
- 이유: Skill 디렉토리는 도구 세트 소스 코드만 포함해야 하며, 이후
git pull업그레이드를 쉽게 할 수 있습니다. 비즈니스 코드가 섞이면 버전 관리가 혼란스러워집니다.