노래 녹음을 연주 가능한 5파트 밴드 악보로 변환하기

오디오를 밴드 악보로 변환한다는 것은 무엇인가요?

Audio to Band Score는 완성된 곡 녹음을 5인조 학교 밴드가 실제로 연주할 수 있는 편곡으로 바꾸는 에이전트 스킬입니다. 원본 스템을 그대로 제시하거나 자동 MIDI 인식을 완성된 채보로 간주하는 대신, 에이전트가 소스 분리, 음악 분석, 악기 배정, 악보 기보, 품질 검사, MuseScore 내보내기를 단계적으로 수행하도록 안내합니다.

표준 워크플로에서는 리허설에 바로 사용할 수 있는 세 가지 파일이 생성됩니다. 재생 또는 DAW 검사용 MIDI 파일, 인쇄 가능한 PDF 악보, 편집 가능한 기본 MuseScore MSCZ 파일입니다.

중요: 이 프로젝트는 독립 실행형 데스크톱 애플리케이션이 아니라 에이전트 스킬입니다. 호환되는 에이전트 런타임에서 저장소에 접근할 수 있도록 하고, 필요한 로컬 오디오 및 악보 도구를 제공해야 합니다.

편곡 워크플로의 작동 방식

이 스킬은 다음과 같은 단계별 프로세스를 따릅니다.

믹스된 녹음
    → 시간 정렬된 소스 분리
    → 박자, 섹션, 화성 및 음표 후보 분석
    → 악기 배정 및 연주 가능성에 따른 수정
    → MuseScore 기보
    → 구조 감사 및 시각적/파일 검사
    → MIDI + PDF + 편집 가능한 MSCZ

핵심 원칙은 연주 가능한 충실도입니다. 목표는 녹음의 구조, 화성 진행, 그루브, 알아볼 수 있는 리프, 중요한 전환을 유지하면서 요청된 연주자에게 비현실적인 세부 사항은 단순화하거나 재분배하는 것입니다.

주요 기능

• Demucs를 사용해 믹스된 녹음을 시간 정렬된 분석 스템으로 분리합니다.
• 4소스 및 6소스 분리 결과를 비교할 수 있습니다.
• 섹션, 템포 후보, 박자표, 화성, 베이스 진행, 리프, 필, 음악적 진입 지점을 분석합니다.
• 리드 기타, 리듬 기타, 베이스, 키보드, 드럼에 연주 재료를 배정합니다.
• 초급, 학교 아마추어 중급, 고급 난이도 목표를 지원합니다.
• 편집되지 않은 인식 결과를 제공하는 대신 구조화되고 편집 가능한 MuseScore 악보를 생성합니다.
• 악보 구조, 선택한 TAB의 음정과 줄 관계, 내보내기 안정성, 파일 일관성을 검사합니다.
• 유료 외부 API에 오디오를 업로드하는 대신 기본적으로 로컬 및 무료 도구를 사용합니다.

기본 5파트 편성

기본 악보는 보컬을 반주하기 위한 편곡이지만, 요청에 따라 동작이 변경되지 않는 한 기악 악보에 보컬 라인은 포함되지 않습니다. 대신 보컬 트랙은 곡의 구조, 호흡 공간, 악기 진입 지점을 파악하는 데 사용됩니다.

• 리드 기타: 시그니처 리프, 훅, 필, 기악 테마를 위한 리듬형 6현 TAB입니다.
• 리듬 기타: 코드, 스트러밍, 아르페지오, 그루브 지원을 위한 리듬형 6현 TAB입니다.
• 베이스: 근음 진행, 전환, 저음역 움직임을 위한 리듬형 4현 TAB입니다.
• 키보드: 화성, 패드, 대선율, 키보드 특유의 모티프를 위한 큰보표 기보입니다.
• 드럼: 그루브, 액센트, 전환, 필을 위한 표준 5선 드럼 기보입니다.

요청된 편성, 튜닝, 조성, 난이도, 길이, 편곡 제약 조건이 이러한 기본값보다 우선합니다.

설치 및 로컬 설정

1. 저장소 복제

git clone https://github.com/kiri603/To-Sheet-Music-Skill.git
cd To-Sheet-Music-Skill

2. Python 환경 생성

Python 3.11을 호환성 기준으로 권장합니다. Demucs와 지원 패키지가 다른 Python 프로젝트와 충돌하지 않도록 전용 가상 환경을 생성하세요.

python3.11 -m venv work/audio-env
source work/audio-env/bin/activate
python -m pip install demucs numpy soundfile imageio-ffmpeg

Windows에서는 work/audio-env/Scripts/ 아래의 Python 및 활성화 실행 파일을 사용하세요. 설치하기 전에 패키지가 컴퓨터에 설치된 Python 인터프리터와 호환되는지 확인하세요.

3. 외부 요구 사항 설치

• FFmpeg: 오디오 디코딩에 필요합니다. 운영 체제에서 설치하거나, 명시적으로 제공한 --ffmpeg 경로 또는 imageio-ffmpeg를 사용할 수 있습니다.
• MuseScore Studio: 악보를 열고 MIDI 및 PDF 파일을 내보내는 데 필요합니다.
• 선택적 분석 도구: 작업에 따라 librosa, basic-pitch, pretty_midi, mido, music21, pypdf 또는 Poppler를 사용할 수 있습니다.
• CUDA: 선택 사항입니다. 호환되는 GPU를 사용할 수 없는 경우에도 분리 워크플로를 CPU에서 실행할 수 있습니다.

저장소는 소프트웨어를 자동으로 설치하거나 모델 가중치를 포함하지 않습니다. 필요한 모델 가중치는 필요할 때 로컬 환경에서 다운로드합니다.

4. 에이전트에서 스킬 사용 가능하게 만들기

이 스킬은 SKILL.md와 agents/openai.yaml을 중심으로 구성되어 있습니다. 사용 중인 런타임의 스킬 로딩 절차에 따라 저장소를 에이전트 런타임에 추가하거나 노출하세요. 런타임마다 방식이 다르므로 이 저장소는 이 단계에 대한 범용 설치 명령을 정의하지 않습니다.

기본 사용법: 편곡 요청

스킬을 사용할 수 있게 되면 소스 녹음과 명확한 편곡 요청을 에이전트에 제공하세요. 예를 들면 다음과 같습니다.

Use $audio-to-band-score to arrange "song.wav" for lead guitar, rhythm guitar,
bass, keyboard, and drums at the default school-amateur intermediate level.
Preserve the original song structure and recognizable riffs, then deliver MIDI,
PDF, and editable MSCZ files.

유용한 요청에는 입력 파일, 악기 구성, 연주자 수준, 그리고 가장 중요한 음악적 특성이 명시되어야 합니다. 해당하는 경우 원하는 조성, 기타 또는 베이스 튜닝, 편곡 길이, 컷, 반복 구간 및 기타 연주 제약 조건도 지정하세요.

소스 분리 직접 실행

편곡을 완성하기 전에 분석용 스템을 확인하거나 준비하려는 경우 소스 분리 도우미를 독립적으로 실행할 수 있습니다.

python scripts/separate_audio.py \
  --input "path/to/song.wav" \
  --out-dir "work/separation-v1" \
  --profile high \
  --device auto

high 프로필은 4소스 및 6소스 Demucs 분석을 모두 실행하여 두 분석의 근거를 비교할 수 있게 합니다. balanced 프로필은 6소스 분석만 실행하며, 내부 시험이나 리소스가 제한된 시스템을 위한 것입니다.

출력 디렉터리는 새 디렉터리여야 합니다. 이 도우미는 기존 디렉터리를 덮어쓰지 않도록 의도적으로 거부하며, 이를 통해 이전 스템과 분석 근거를 보호합니다. 매 실행마다 work/separation-v1 또는 work/separation-v2와 같은 버전이 지정된 경로를 선택하세요.

완성된 MuseScore 파일 감사

에이전트가 work/final.mscz를 만든 후, 결과물을 내보내기 전에 감사 도우미를 실행하세요.

python scripts/score_tools.py audit \
  --score "work/final.mscz" \
  --report "work/audit.json"

감사에서는 피치, 현, 프렛 간 관계를 포함한 구조 검사와 일부 TAB 검사를 수행합니다. 기술적 불일치를 식별할 수 있지만, 모든 음표, 박자, 아티큘레이션 또는 결합된 악기 파트가 음악적으로 정확하다는 것을 증명하지는 않습니다.

MIDI, PDF 및 MSCZ 내보내기

인쇄용, 재생용, 편집용 버전의 일관성을 유지하려면 동일한 네이티브 MuseScore 파일에서 모든 형식을 내보내세요.

python scripts/score_tools.py export \
  --score "work/final.mscz" \
  --out-dir "work/export-v1" \
  --name "song_band" \
  --musescore "/path/to/MuseScore"

내보내기 도우미는 기존 출력 디렉터리를 덮어쓰지 않습니다. 요청된 세 가지 형식이 모두 성공적으로 생성된 후에만 새 디렉터리를 게시합니다.

• song_band.mid는 재생 및 DAW 또는 MIDI 검사를 제공합니다.
• song_band.pdf는 인쇄 가능한 리허설 악보를 제공합니다.
• song_band.mscz는 편집 가능한 네이티브 MuseScore 프로젝트를 제공합니다.

작업 디렉터리에는 manifest.json, 분리된 WAV 스템, 분석 메모, MIDI 후보, MusicXML, 감사 보고서 및 렌더링된 PDF 페이지가 포함될 수도 있습니다. 사용자가 결과물로 요청하지 않는 한 이러한 파일은 근거 자료 및 품질 보증 자료로 사용됩니다.

더 나은 결과를 위한 고급 팁

정확한 편곡 개요 작성

곡을 채보해 달라는 일반적인 요청에만 의존하지 마세요. 결과물을 누가 연주하며 무엇을 연주할 수 있는지 명시하세요. 예를 들어 초급용 악보와 고급용 악보를 구분하고, 비표준 튜닝을 지정하며, 반드시 알아볼 수 있게 유지해야 하는 리프나 전환 구간을 밝혀야 합니다.

분리된 스템을 근거 자료로 취급

guitar 또는 piano로 표시된 6소스 출력은 후보일 뿐, 악기가 완전히 분리되었다는 보장은 없습니다. 기타 스템을 하나의 완전한 기타 파트로 자동 해석해서는 안 되며, 두 개의 독립적인 기타 파트가 존재한다는 근거도 되지 않습니다. 후보를 원본 믹스, 반복 구간, 화성적 맥락, 리듬 및 악기별 제약 조건과 대조 확인하세요.

타임라인 일관성 유지

이 워크플로는 스템을 공통 타임라인에 유지하고 샘플 레이트, 채널 레이아웃 및 프레임 수를 확인합니다. 원본 녹음과의 정렬도 함께 유지하지 않는 한 개별 스템을 수동으로 자르거나 이동하지 마세요.

버전이 지정된 작업 디렉터리 사용

분리 및 내보내기 도우미는 기존 디렉터리를 덮어쓰지 않으므로 separation-v1, separation-v2, export-v1 및 export-v2와 같은 이름을 사용하세요. 이렇게 하면 프로필 설정을 비교하고 이전 시도의 근거를 보존하기도 쉽습니다.

자동 검사 후 음악적으로 악보 검토

감사 성공은 선택된 구조 및 기보 속성이 확인되었다는 뜻이지, 음악적으로 완벽하다는 뜻은 아닙니다. MIDI를 듣고, PDF를 확인하고, MuseScore에서 MSCZ 파일을 열어 앙상블에 맞는 도입, 전환, 반복, 기타 운지, 키보드 텍스처, 베이스 진행 및 드럼 필인지 확인하세요.

하나의 권위 있는 악보 원본 유지

최종 수정은 네이티브 MSCZ 악보에서 수행한 다음, 동일한 파일에서 MIDI와 PDF를 다시 생성하세요. 내보낸 형식을 각각 독립적으로 편집하면 세 결과물이 서로 일치하지 않을 수 있습니다.

테스트 모음 실행

저장소 루트에서 포함된 테스트를 실행하세요.

python -m unittest discover -s scripts -p "test_*.py" -v

테스트에서는 분리 관련 엣지 케이스, 제한된 모델 다운로드 재시도, 타임라인 검증, TAB 피치 및 현 검사, 구조적 악보 검사 및 내보내기 보호 기능을 다룹니다. 테스트 통과는 도우미 워크플로가 예상대로 작동한다는 것을 확인할 뿐이며, 채보 정확도나 편곡 품질을 측정하지는 않습니다.

제한 사항 및 책임 있는 사용

• 이 프로젝트는 오류 없는 채보나 완전한 오디오 충실도를 보장하지 않습니다.
• 자동화된 검사는 음악적 청취와 악보 검토를 대신할 수 없습니다.
• 이 작업 흐름은 음성 텍스트 변환, 가사 번역 또는 악보 다운로드를 제공하지 않습니다.
• 모델 가중치는 저장소에 포함되어 있지 않으며 필요할 때 다운로드될 수 있습니다.
• 현재 저장소에는 프로젝트 수준의 라이선스 파일이 없으므로 코드나 에셋을 재배포할 수 있다고 가정하지 마세요.
• 타사 도구, 모델, 데이터 세트 및 녹음 파일에는 각각의 라이선스와 사용 조건이 적용됩니다.

사용할 권리가 있는 녹음 파일과 참고 자료만 처리하세요. 비공개 녹음 파일, 자격 증명, 모델 캐시, 생성된 Python 캐시 또는 대용량 임시 파일을 저장소에 커밋하지 마세요.

결론

Audio to Band Score는 혼합 녹음에서 편집 가능하고 리허설에 적합한 5파트 편곡으로 나아가는 체계적인 경로를 제공합니다. 이 도구의 핵심 가치는 완전 자동 채보가 아니라, 소스 분리 근거와 명시적인 음악적 판단, 연주 가능성을 중심으로 한 편곡, 구조 검사, 일관된 MuseScore 내보내기를 결합하는 데 있습니다. 신뢰할 수 있는 결과를 얻으려면 에이전트에 정확한 작업 지침을 제공하고, 분석 근거를 보존하며, 감사 및 테스트를 실행한 뒤 사람의 음악적 검토로 마무리하세요.