Music Generator
엄격하고 측정 가능한 파이프라인을 통해 독창적인 음악을 생성하는 절차적 음악 생성 시스템입니다. 모든 결정은 에이전트가 내리며, 스크립트가 이를 실행합니다. 파이프라인은 주관적인 추측 대신 객관적인 측정과 품질 게이트를 사용합니다.
사용 시기
다음과 같은 경우 이 스킬을 사용하세요:
- 비디오, 게임, 광고, 팟캐스트 또는 음성 해설을 위한 독창적인 음악 생성
- 분위기 설명(예: "긴장감 넘치는 영화적 빌드업", "차분한 로파이")을 바탕으로 사운드트랙 생성
- 녹음본에서 악기 복제
- 기존 스템 믹싱 또는 마스터링
- 컷/대화가 있는 비디오에 맞춰 점수 작성
- 로봇같이 들리거나, 평평하거나, 불균형한 음악 수정
- 특정 문화적 스타일(카르나틱, 아랍, 아프리카, 동아시아 등) 작업
빠른 시작
스킬 디렉토리에서 해당 가상 환경을 사용하여 실행하세요:
- Windows:
.venv/Scripts/python.exe - Unix:
.venv/bin/python
최초 설정: references/setup.md를 참조하세요.
워크플로우
다음 단계를 순서대로 따르세요. 단계를 건너뛰지 마세요.
| 단계 | 작업 | 출력물 | 확인 사항 |
|---|---|---|---|
| 1 | 프로젝트 생성 | python scripts/setup_project.py --new-project <dir> --title "<Title>" (요청된 경우에만 --ambience 추가) | direction/, presets/, scores/, out/, reports/, STATUS.md가 포함된 프로젝트 구조 |
| 2 | 연구 | python scripts/research_kb.py <dir> --topic "<topic>" --tags <tags>. TinyFish를 통해 웹 소스 추가. 분위기/효과의 경우 --sounds를 사용하고 라이선스/측정값이 포함된 실제 참고 자료를 문서화하세요. | KB 인용 및 출처가 포함된 reports/research_<topic>.md |
| 3 | 방향 시트 | templates/direction_sheet.json을 <dir>/direction/direction_<title>.json으로 복사. references/music-direction.md에 따라 모든 필드를 채우세요. 비디오의 경우 먼저 scripts/video_score.py를 실행하세요. | 작업, 느낌, 섹션, 모티프, 히트, 믹스 의도, 공간 배치가 포함된 완전한 시트 |
| 4 | 프리셋 생성 | python scripts/presets.py scaffold instruments/vocals/environments/sfx <name> --project <dir>. 각 프리셋은 고유한 공간 배치가 필요합니다. | 프로젝트 내 프리셋 (특성, 공간.방위각/거리 포함) |
| 5 | 스코어 작성 | <dir>/scores/<title>_score.json 생성 (선언적, 프리셋 참조). 정확한 제어를 위해 templates/custom_score_template.py를 사용하세요. | 프리셋을 참조하는 트랙이 포함된 유효한 JSON |
| 6 | 렌더링 및 게이트 | python scripts/pipeline.py <dir>/scores/<title>_score.json --project <dir> | out/master.wav (최신 버전의 복사본), out/master_vNN.wav, out/versions.json, <master>.json 태그, stems/, midi/, reports/ci_report.json (0 FAIL) |
| 7 | 수정 | 한 번에 하나의 레버만 변경 (references/music-direction.md §6). 모든 게이트가 통과할 때까지(최대 5회 시도) 6단계를 다시 실행하세요. | 모든 게이트 통과 |
| 8 | 듣고 전달 | python scripts/listen.py out/master.wav --direction direction/<sheet>.json | 결과 확인 및 보고 |
전달 메타데이터 및 버전
인증은 음악 게이트 통과 후 세 가지 사항을 자동으로 기록합니다:
out/master_vNN.wav— 인증된 모든 렌더링은 자체 버전 파일을 얻습니다. 이전 버전은 유지되며, 재렌더링은 절대 덮어쓰지 않습니다.out/master.wav— 단일 마스터를 기대하는 도구를 위한 최신 버전의 복사본입니다.out/versions.json— 각 버전의 타임스탬프, 측정값 및 해당 버전을 획득하게 한 변경 사항(해결한 게이트 실패 또는최초 인증 렌더링)이 포함됩니다.out/master.json— 마스터 옆에 기록되는 표준 태그입니다.
태그 출처: presets/metadata/metadata.json의 기본값(아티스트, 앨범, 저작권, 라이선스, 발행자, ISRC, 언어), 스코어에서 파생된 값(제목, piece_type의 장르, 연도, 사실적 key · BPM · piece_type 설명), 프로젝트 자체 metadata.json의 재정의 순서입니다. 스크립트 대신 <project>/metadata.json에 실제 값을 기록하세요.
에이전트의 규칙:
master_vNN.wav또는versions.json레코드를 절대 삭제하거나 덮어쓰지 마십시오. 전달에 새 테이크가 필요한 경우 새 버전이 됩니다.- 렌더링 후 레코드를 확인하세요:
python scripts/helpers/version_manager.py list --project <dir>. - MP3 압축은 수동이며, 파이프라인의 일부가 아닙니다:
python scripts/helpers/compress_mp3.py out/master_vNN.wav -o <file>.mp3 -b 320k. 사이드카 태그를 MP3에 전달합니다. - 게이트 행
meta.tags및meta.version은 이 레코드만 추적합니다. 경고만 하고 실패하지 않으며, 조각의 첫 번째 렌더링에서INFO입니다.
주요 원칙
- 모듈식: 사운드/공간은
presets/, 노트는scores/, 의도는direction/에 있습니다. 모놀리식 스크립트는 없습니다. - 연구 기반: 모든 사용자 정의 악기/보컬/문화는 KB 연구 인용이 필요합니다.
- 데이터 우선 코드 나중: 새로운 사운드는 Python 생성기가 아닌 씬 데이터(
"scene"/"scene_layers")를 사용합니다. - 한 번에 하나의 변경: 게이트 실패를 수정할 때 정확히 하나의 매개변수를 변경하고 재측정하세요.
- 측정하세요, 추측하지 마세요: 파이프라인 메트릭과 진단을 사용하세요. 취향은 측정되지 않습니다.
- 모든 조각은 믹스 프리셋을 가집니다: 게인 스테이징, 다이내믹스, 사이드체인, 마스터링을 제어합니다.
작업별 경로
| 작업 | 주요 참조 |
|---|---|
| 비디오 스코어링/컷 | references/video-scoring.md, scripts/video_score.py |
| 보컬/합창/허밍 | references/vocals-and-choirs.md, references/vocal-engine.md |
| 문화적 스타일/퓨전 | knowledgebase/README.md, references/cultural-soul.md, references/genre-fusion.md |
| SFX/분위기/폴리 | references/sound-effects.md, references/physical-scene.md, references/environments-as-presets.md |
| SFZ 오케스트라 | references/sfz-libraries.md, scripts/sfz_libs.py |
| 악기 복제/추출 | references/instrument-cloning.md, references/extraction.md |
| 믹싱/마스터링 | references/mixing-and-mastering.md, scripts/mixer.py, scripts/mix_diagnostics.py |
| 게이트 실패 | references/quality-gate.md, scripts/gate_profiles.py |
출력 템플릿
완료: out/master.wav (Xs, -X.X LUFS, -X.X dBTP), midi/<title>_score.mid, stems/ (N개), reports/ci_report.json.
설명: <느낌, 키, BPM, 악기, 프리셋>.
게이트: <N개 통과, K회 시도 후 0개 실패>; 듣기: <판독값>.
확인하지 않음: 취향, 실제 악기 사실감, 최종 비디오 적합성.
다음 단계: <한 가지 제안된 변경>.
참고 사항 및 제한 사항
- 기본적으로 GM SoundFont 사용, SFZ 라이브러리는 선택 사항입니다. 표준 합성에서 가사가 있는 단어는 없습니다(합창/허밍은 텍스처입니다).
listen.py는 earshot 모델이 필요합니다(설치하려면python scripts/setup_project.py --ears실행).spatial.binaural: true프리셋에만 헤드폰 공간화가 적용됩니다.- 믹스 진단은 보고하지만 게이트를 차단하지 않습니다(차단 게이트는 품질 게이트에 있습니다).
- 전체 규칙은
AGENTS.md를, 전체 제한 사항은references/troubleshooting-and-limits.md를 참조하세요.