audio2score-mcp

녹음된 오디오 파일을 편집 가능한 악보로 변환합니다: audio → MIDI → MusicXML.

MusicXML을 목표로 하는 이유는 이것이 "음악 표기법의 SVG"이기 때문입니다 — 악보 앱(MuseScore, Sibelius, Guitar Pro, Finale, Dorico)이 해당 형식을 만든 파이프라인을 소유하지 않아도 열고, 편집하고, 다시 내보낼 수 있는 개방형 텍스트 기반 형식입니다. 이 프로젝트는 .mid와 .musicxml 파일만 생성합니다. 다른 형식(PDF, 오디오, 탭)으로 여는, 편집하고, 내보내는 것은 선택한 악보 앱에서 수동으로 직접 해야 합니다 — 이 프로젝트가 그 부분을 의도적으로 감싸지 않는 이유는 아래 "연결되는 형식" 섹션을 참조하세요.

이 프로젝트를 실행하는 두 가지 방법: 일반 CLI 스크립트로 실행하거나, 동일한 단계를 Claude가 호출할 수 있는 도구로 노출하는 MCP 서버로 실행하는 것입니다.

포함된 내용

• transcribe.py — 오디오 파일 → MIDI, Spotify의 basic-pitch 사용

• to_score.py — MIDI 파일 → MusicXML, music21 사용

• score_to_notes.py — 악보 파일(MIDI, MusicXML, 또는 music21가 읽을 수 있는 모든 것) → daw-mcp의 batch_set_notes 형식의 JSON 노트 배열

• mcp_server.py — MCP 서버로, 세 가지를 각각 도구(transcribe_audio, midi_to_score, score_to_notes)로 감쌉니다

각 단계는 디스크의 실제 개별 아티팩트 — 숨은 중간 단계가 아닙니다. MIDI와 악보 사이의 중단은 의도적입니다. 자동 전사는 손실이 있으므로, 원시 MIDI를 악보로 만들기 전에 꼭 한 번 검토(또는 수동 수정)해 볼 만한 가치가 있습니다.

score_to_notes.py는 의도적인데 특정 포맷에 종속적이지 않았는데, MIDI 전용도 아닙니다. transcribe.py의 .mid이든 외부 OMR 도구의 .mxl이든 music21.converter.parse()는 MIDI와 MusicXML을 동일하게 처리하므로, 동일한 코드 경로로 입력됩니다. 이 프로젝트에는 별도의 MusicXML→MIDI 또는 MusicXML→PDF 도구가 없습니다. .musicxml 파일이 이미 있으면 어떤 악보 앱도 열고 내보낼 수 있으므로, 여기서 그런 도구를 만드는 것은 이미 있는 소프트웨어만 복제하는 것입니다.

Related MCP server: whisper-mcp

파일이 저장되는 곳

권장사항: 입력 파일을 **workspace/**에 넣어 주세요(저장소 내부, gitignore 처리됨 — .gitignore 참조 — 여기에 넣은 것은 무엇이든 커밋되지 않으며, 입력 파일도 포함합니다). 반드시 그럴 필요는 없지만, 어떤 경로든 작동합니다. 모든 출력은 입력 파일 옆에, 같은 기본 이름, 다른 확장자로 생성됩니다.

workspace/song.mp3          <- you put this here (any format basic-pitch/librosa reads: mp3, wav, ogg, flac...)
workspace/song.mid          <- transcribe_audio writes this
workspace/song.musicxml     <- midi_to_score writes this (open in MuseScore/Guitar Pro/Sibelius/Finale/Dorico)
workspace/song.notes.json   <- score_to_notes writes this (feed into daw-mcp's batch_set_notes)

보기: 가지고 있는 아무 악보 앱에서 .mid 또는 .musicxml을 직접 여세요. — 여기서 이 앱을 자동으로 실행하지는 안습니다. MuseScore가 .musicxml을 "손상된"이라 한다면, 아래의 폴리포니 주의사항을 확인하고 파일이 잘못된 것이라고 단정하지 마세요.

설치

특히 Python 3.11이 필요합니다 — basic-pitch는 TensorFlow 2.15를 사용하는데, 그 휠은 cp311에서 끝납니다. 3.12와 3.13은 의존성을 해결하지 못합니다. 그 결과 만들어지는 가상환경은 약 2GB 입니다(전체 TensorFlow, 상대적으로 가벼운 백엔드가 아닌).

uv venv --python 3.11 venv
uv pip install -r requirements.txt --python venv/Scripts/python.exe

의존성은 정확히 고정되어 있습니다 (basic-pitch==0.4.0, music21==10.5.0, setuptools==65.5.0, mcp==2.0.0) — 이 프로젝트에는 자동화된 테스트 스위트가 없으므로, 검증된 것과 정확히 동일한 환경을 새로 만드는 것이 대신입니다. 특히 setuptools를 고정한 이유는 최신(보다) 버전이 basic-pitch에 필요한 전이적 resampy 임포트을 깨뜨리기 때문입니다.

사용법: CLI

venv/Scripts/python.exe transcribe.py "C:\path\to\song.mp3"
# -> C:\path\to\song.mid

venv/Scripts/python.exe to_score.py "C:\path\to\song.mid"
# -> C:\path\to\song.musicxml

venv/Scripts/python.exe score_to_notes.py "C:\path\to\song.mid"
# -> C:\path\to\song.notes.json  (daw-mcp's batch_set_notes format - also
#    takes a .musicxml/.mxl directly, e.g. from OMR, no separate step needed)

출력은 항상 입력 옆, 그리고 동일한 기본 파일명과 다른 확장자로 생기며, 절대 이름은 수 없습니다. 각 스크립트 모두 기존 출력 파일을 덮어쓰지 않느 것입니다. 다시 실행하려면 먼저 기존 파일을 삭제하거나 이동 해야 합니다. 오류(입력 누락, 라이브러리 오류)는 명확한 메시지를 stderr에 쓰고 종료 코드를 0이 아닌 값을 반환합니다. 실패를 조용한 넘어가지는 않습니다.

실제 목표에 필요한 도구만 실행하세요 — 세 가지를 모두 기본으로 연결하지 마세요. 각 도구는 정확히 하나의 파일을 생성하며, 더 필요하지 않아도 실행하게 되면 아무도 원하지 않는 파일만 만들어졌습니다.

첫 두 행의 .mid는 정확히 경 لا"출력"이라기보다는 어쩔 수 없는 체크포인트입니다. basic-pitch는 MIDI만 만들 수 있고, 그 뒤에 오는 것을 그대로 신뢰하기 전에 살펴볼 가치가 있습니다(그 이유는 "알려진 이슈" 참조).

실행 예

실제 실행 예시입니다. 입력: 합성 모노 WAV, C-major 아르페지오(C4-E4-G4-C5, 4분음에 짧은 감쇠 엔벨로프로 시작이 깨끗하게) — "실제 오디오"는 이 프로젝트가 중요하게 여기는 것(실제 파일에 있는 웨이브형, 직접 입력한 MIDI가 아니라)이라기보다는 합성된 파일이므로, 공개 저장소에 저작권 있는 파일을 놓지 않아도 다시 만들 수 재현할 수 있습니다.

$ venv/Scripts/python.exe transcribe.py c_major_arpeggio.wav
WARNING:root:Coremltools is not installed. ...
WARNING:root:tflite-runtime is not installed. ...
WARNING:root:onnxruntime is not installed. ...
Wrote c_major_arpeggio.mid

$ venv/Scripts/python.exe to_score.py c_major_arpeggio.mid
Wrote c_major_arpeggio.musicxml

$ venv/Scripts/python.exe score_to_notes.py c_major_arpeggio.mid
Wrote c_major_arpeggio.notes.json

이 세 개의 WARNING:root 줄은 basic-pitch가 선택적 백엔드(CoreML, TFLite, ONNX)가 없다는 것 — 무해합니다. 사용되는 백엔드는 TensorFlow입니다. 그리고 이것이 transcribe.py v1.1.1이 mcp_server.py의 stdout 스트림을 망트리지 않고 올바르게 숨기는 있는 그 줄입니다(CHANGELOG.md 참조) — 턴면에만 표시되며 MCP 프로토콜 채널에 는 나타나지 안습니다.

c_major_arpeggio.notes.json, dawd-mcp에 바로 넣을 수 있는 출력:

[[0.0, 60, 83, 1.0], [1.25, 64, 80, 1.0], [2.3333, 67, 80, 1.0], [3.5, 72, 78, 0.5], [4.0, 72, 78, 0.5]]

4개 음표(C4, E4, G4, C5) 는 입력되었습니다 — basic-pitch는 네 가지 모두에 대한 음정과 explicit한 둔하게(60/64/67/71, 아르페지와 정확히 일치)을 정답게 감지했지만, 마지막 음(C5) 하나를 하나로 합치지 않고 두 개의 연속된 항목으로 분리했습니다. 감쇠 엔벨로프의 꼬리 부분이 두 번째 시작으로 감지된으로 보입니다. 이는 제질의 자동 트리없 스크립트가 상실적이라는 것을 보여 주는 예시입니다 — 위에서 "무엇이 있는지"에서 경고한 그 문제가 자연스러운 (평평하지 않은) 볼륨 모양을 가진 첫 음에서 발드로 나타났습니다: .musicxml/.notes.json을 무지 믿지 말고 .mid를 먼저 살펴보세요. 특히 서스테인이나 감쇠하는 음 영역에서요.

c_major_arpeggio.musicxml가 있는 실제 악기 앱인 어떤 표기 앱에서 누구나 열릴 수 있는 것은 확인했습니다(잘 만들어진 MusicXML 4.0 DOCTYPE, C4/E4/G4/G4/C5/C5/C5라는 <step>/<octave> - 분리된 C5는 마디 경계를 건너는 묶인음표(tied note)로 나타났습니다. 이것은 한 주에 안 맞는 음에 대한 표준 MusicXML이며, 두 번째 버그가 아닙니다).

사용법: MCP 서버

Claude Code의 설정에 audio2score로 등록됩니다 — 새 설치 후 Claude Code를 다시 시작해야 나타납니다 (MCP 서버는 시작 시 로드됩니다).

세 가지 도구가 세 개의 스크립트를 그대로 미러링합니다:

• transcribe_audio(audio_path) → .mid 경로 반환

• midi_to_score(midi_path) → .musicxml 경로 반환

• score_to_notes(score_path) → .notes.json 경로 반환 (daw-mcp의 batch_set_notes 노트-배열 형식; MIDI 또는 MusicXML을 받음)

CLI와 동일한 동작을 그대로 수행합니다(같은 덮어쓰기 방지, 동일한 오류). MCP 서버는 가벼운 레퍼 — 다른 구현이 아닙니다.

호출이 죽시 시는 경우 알아야 할 한 가지: transcribe_audio 호출이 제한시간 초과 또는 취소되었다고 보여도, 변환 녹는 백그라운에서 계속 실행되며 .mid 파일을 끝까지 작성합니다. 이 경우 첫 호출이 실패한 것으로 보여도, 다시 시도하면 "already exists" 덮어쓰기 방지 보호에 걸릴 수 있습니다. 이 버그가 아닙니다 — 재시도 전에 .mid 파일이 이미 있는지 확인합니다.

다른 곳에서 서버를 직접 등록하려면 MCP 구성(mcpServers)에 다음을 추가하세요. 두 필드 모두 절대 경로를 사용하세요 — 클라이언트가 작업 디렉토리를 지정하지 않은 상태로 stdio 서버를 시작하기 때문에 상대 경로는 해석되지 않습니다:

"audio2score": {
  "type": "stdio",
  "command": "<absolute path to>\\venv\\Scripts\\python.exe",
  "args": ["<absolute path to>\\mcp_server.py"],
  "env": {}
}

제공하지 않는 것

• 악보/MIDI → 오디오, PDF 또는 탭 출력 없음(내보낼 수 없음), MusicXML → MIDI 변환도 없습니다 — 이유와 대해서는 "연결되는 형식"을 참조하십시오.

• 음원 분리(트랙 스플트) 또는 다중 악기 분리 없음

• 자동화된 테스트 스위트은 없습니다(설계상) — 검증은 항상 실제 오디오로 실제 실행합니다.

연결되는 형식

.musicxml이 만들어지면 이 프로젝트는 deliberately로 여기서 끝입니다. 모든 악보 앱은 already MusicXML를 텍스트 편집 없이 열고 자신 메뉴에서 필요한 것으로 (PDF, audio, tab, MIDI)를 내보낼 수 있습니다. 이 내보내기를 자동화라는 과정을 시도했지만 벗어 대부분 되률린 케이스로 남아 있습니다(CHANGELOG.md v1.2.0에서 v2.0.0까지의 전체 대화를 참조) — score_to_notes.py이 별도 변환 단계 없이 MusicXML을 직접 처리해 주는 것이 좋아져서, 그나마 자동화할 만한 흐름은 필요하지 않다는 결과야 것 jok.

OMR 출력은 basic-pitch의 오디오 트랜스크립션보다 적어도 같은 수준으로 의심하세요. 중간에 있는 .musicxml을 신뢰하기 전에 확인하십시오. 그리고 Audiveris가 모든 PDF에서 성공한다고 기대하지 마십시오(위의 탭 북 실패에서 보듯이).

알려진 문제: MuseScore가 트랜스크라이브된 .musicxml 파일을 "손상됨"으로 거부할 수 있습니다.

폴리포니가 많은 트랜스크립션은 MuseScore Studio가 "손상됨"이라고 하며 열기를 거부하는 .musicxml 파일을 생성할 수 있습니다. 근본 원인: music21 자체의 MusicXML 라이터가 여러 보이스(5개 이상)가 동시에 필요한 곡에서 일부 <note> 요소에 <voice> 태그를 생략합니다. 실제 45초 녹음에서 검증되었으며, 이는 깨끗한 단일 멜로디 라인이 아니라 기본 피치가 실제 오디오에서 하모닉스/아티팩트를 감지하여 조밀하고 종종 겹치는 음표로 트랜스크라이브되었습니다. 이것이 이 프로젝트의 코드가 아니라 music21의 라이터 문제임을 확인했습니다: to_score.py는 자체적인 음표/보이스 로직이 없는 두 줄의 parse() + write() 호출이며, 쓰기 전에 score.makeNotation()을 명시적으로 호출해도 해결되지 않습니다. 동일한 파일을 music21 자체로 다시 파싱하면 경고만 표시되고(Cannot put in an element with a missing voice tag) 해당 음표를 보이스 1로 기본 설정하여 복구하지만, MuseScore의 임포터는 단순히 더 엄격하여 허용하지 않고 완전히 거부합니다. 해결 방법: "Open anyway"를 클릭하세요 - 정상적으로 로드되며, 원래 감지된 보이스 대신 해당 특정 음표가 보이스 1로 표시될 뿐입니다. 사소한 레이아웃 문제이지 데이터 손실은 아닙니다. 깨끗하고 폴리포니가 낮은 입력(직접 작성한 멜로디 MIDI를 트랜스크라이브하고 보이스 태그 문제 없이 재검증한 경우)에서는 발생하지 않습니다. 이는 지저분하고 조밀한 실제 오디오 트랜스크립션 출력에만 해당됩니다.