Parksy Mini-DAW — PC 작업 매뉴얼

이 문서는 Termux에서 코드를 작성한 뒤,

집 PC에서 검증/실행/마무리하는 전체 동선을 다룬다.

대상: 본인 (dtslib1979)

0. 전제 조건

PC 환경

Windows 10/11

Python 3.10+ 설치됨

ffmpeg 설치됨 (PATH에 등록)

Git 설치됨

Pianoteq 8 설치됨 (선택 — 렌더 테스트용)

설치 확인 (CMD에서)

python --version
ffmpeg -version
git --version
"C:\Program Files\Pianoteq 8\Pianoteq 8.exe" --help

ffmpeg 없으면: https://ffmpeg.org/download.html → PATH 등록

Pianoteq 없어도 Phase 1의 CUT + MIDI까지는 테스트 가능

1. 레포 클론 및 세팅 (최초 1회)

CMD 또는 PowerShell

cd D:\  (또는 WD Passport 경로)
git clone https://github.com/dtslib1979/parksy-audio.git
cd parksy-audio\local-agent

python -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txt

이미 클론돼 있으면

cd D:\parksy-audio
git pull origin main
cd local-agent
.venv\Scripts\activate
pip install -r requirements.txt

2. Phase 1 검증 (이것만 하면 끝)

2-1. 서버 기동

cd D:\parksy-audio\local-agent
.venv\Scripts\activate
uvicorn server:app --host 0.0.0.0 --port 8787 --reload

브라우저에서 http://localhost:8787/health 열어서

`{"ok": true}` 뜨면 성공

2-2. 상태 확인

브라우저에서: http://localhost:8787/status

확인할 것:

{
  "ffmpeg": true,       ← 필수
  "basic_pitch": true,  ← pip install 됐으면 true
  "pianoteq": true,     ← 설치 경로 맞으면 true
  "fluidsynth": false   ← 없어도 됨
}

ffmpeg가 false면: ffmpeg 설치 후 PATH 등록

basic_pitch가 false면: `pip install basic-pitch` 재실행

pianoteq가 false면: `local-agent/render.py` 상단의 PIANOTEQ_EXE 경로 수정

2-3. 테스트용 오디오 준비

mkdir D:\parksy-audio\local-agent\sources

아무 WAV/MP3 파일 하나를 sources/ 폴더에 넣기.

(YouTube → ClipDown으로 다운받은 클래식 음원 추천)

2-4. CUT 테스트

새 CMD 창 열고 (서버는 계속 돌리고):

curl -X POST http://localhost:8787/cut ^
  -H "Content-Type: application/json" ^
  -d "{\"input_path\": \"D:/parksy-audio/local-agent/sources/test.wav\", \"ss\": \"0\", \"to\": \"120\"}"

`test.wav` 대신 실제 파일명 넣기

성공하면 응답에 `clip_id`와 `clip_path` 나옴

`outputs/clips/` 폴더에 WAV 파일 생성 확인

2-5. MIDI 추출 테스트

curl -X POST http://localhost:8787/extract-midi ^
  -H "Content-Type: application/json" ^
  -d "{\"clip_path\": \"D:/parksy-audio/local-agent/outputs/clips/여기에_clip_id.wav\"}"

2-4에서 받은 clip_path를 그대로 넣기

성공하면 `outputs/midi/`에 .mid 파일 생성

notes 수도 응답에 포함됨

2-6. RENDER 테스트 (Pianoteq 있을 때만)

curl -X POST http://localhost:8787/render ^
  -H "Content-Type: application/json" ^
  -d "{\"midi_path\": \"D:/parksy-audio/local-agent/outputs/midi/여기에_midi_id.mid\"}"

성공하면 `outputs/renders/`에 WAV 파일 생성

이 WAV를 재생해서 소리 나오면 Phase 1 완료

2-7. 검증 체크리스트

[ ] 서버 기동 (uvicorn)
[ ] /status → ffmpeg=true
[ ] /cut → clip.wav 생성
[ ] /extract-midi → .mid 생성
[ ] /render → .wav 생성 (Pianoteq 있을 때)
[ ] 최종 WAV 재생 → 소리 나옴

전부 체크되면 Phase 1 종료. 커밋하고 push.

3. 도구별 역할 분담

Claude Code (Termux, 핸드폰)

코드 작성 / 수정 / push

구조 설계 / 문서 작성

원격에서 가벼운 작업

Claude Chat (PC 브라우저)

긴 대화 / 전략 논의 / 백서 작성

코드 리뷰 요청

"이거 맞냐?" 확인용

Claude MCP Desktop (PC)

PC 로컬 파일 접근 가능

에러 로그 분석

Pianoteq 경로 찾기 / 설정 도움

빌드 실패 디버깅

사용 동선 (권장)

[핸드폰 Termux]          [집 PC]
     │                      │
     │  코드 작성/push       │
     │──────────────────────>│
     │                      │  git pull
     │                      │  uvicorn 서버 기동
     │                      │  curl로 테스트
     │                      │
     │                      │  에러 나면?
     │                      │  → Claude MCP Desktop에 로그 던지기
     │                      │  → 수정 → 테스트 반복
     │                      │
     │                      │  성공하면?
     │                      │  → git commit & push
     │  git pull            │
     │<─────────────────────│
     │  다음 Phase 진행      │

4. 에러 대응 가이드

"ffmpeg not found"

:: ffmpeg 설치 확인
ffmpeg -version

:: PATH에 없으면 환경변수로 지정
set FFMPEG_BIN=C:\ffmpeg\bin\ffmpeg.exe

"basic-pitch not installed"

.venv\Scripts\activate
pip install basic-pitch

TensorFlow 관련 에러 나오면:

`pip install tensorflow` 먼저 실행

"Pianoteq exe not found"

:: 실제 설치 경로 확인
dir "C:\Program Files\Pianoteq*"

:: 환경변수로 지정
set PIANOTEQ_EXE=C:\실제경로\Pianoteq 8.exe

또는 local-agent/render.py 상단 직접 수정:

PIANOTEQ_EXE = r"C:\실제경로\Pianoteq 8.exe"

"MIDI conversion failed" / notes=0

입력 WAV가 너무 짧거나 무음일 수 있음

다른 오디오 파일로 재시도

클래식 피아노 독주가 추출률 가장 높음

"Render finished but WAV missing or too small"

Pianoteq CLI 옵션이 버전에 따라 다를 수 있음

먼저 최소 커맨드로 테스트:

"C:\Program Files\Pianoteq 8\Pianoteq 8.exe" --midi test.mid --wav test.wav

이것도 안 되면 Pianoteq 버전 확인 (`--help`)

서버가 안 뜸 (import error)

cd D:\parksy-audio\local-agent
.venv\Scripts\activate
python -c "import config; print('OK')"
python -c "import audio_cut; print('OK')"
python -c "import extract_midi; print('OK')"
python -c "import render; print('OK')"

어디서 에러 나는지 확인 후 해당 모듈만 수정

5. Phase 1 완료 후 커밋

검증 성공 시

cd D:\parksy-audio
git add -A
git commit -m "test: Phase 1 PC 검증 완료 — CUT/MIDI/RENDER 풀사이클 통과"
git push origin main

Pianoteq 경로 수정했으면

git add local-agent/render.py
git commit -m "fix: Pianoteq 경로 수정 (로컬 PC 환경)"
git push origin main

6. Phase 2 작업 목록 (Phase 1 끝나면)

1	clean_midi.py (노이즈 제거, 휴머나이징)	Termux or PC
순서	작업	도구
2	FFmpeg 그라데이션 MP4 자동 생성 스크립트	PC (ffmpeg 필요)
3	CUT PWA UI (파형 뷰어)	Termux
4	MIDI 최소 편집 PWA UI	Termux
5	YouTube 업로드 자동화	PC

Phase 2는 Phase 1 검증 끝난 후에만 시작.

순서는 1 → 2 우선 (코드 레벨), 3~5는 나중.

7. 폴더 구조 요약 (PC 기준)

D:\parksy-audio\
  local-agent\
    .venv\               ← Python 가상환경 (git 제외)
    sources\             ← 원본 오디오 넣는 곳 (git 제외)
    outputs\
      clips\             ← /cut 결과
      midi\              ← /extract-midi 결과
      renders\           ← /render 결과
    server.py            ← uvicorn으로 실행
    audio_cut.py
    extract_midi.py
    render.py
    config.py
    requirements.txt

8. 환경변수 정리

`PARKSY_SOURCE_DIR`	`./sources`	원본 오디오 폴더
변수	기본값	설명
`PARKSY_OUTPUTS_DIR`	`./outputs`	출력 폴더
`FFMPEG_BIN`	`ffmpeg`	ffmpeg 경로
`FFPROBE_BIN`	`ffprobe`	ffprobe 경로
`PIANOTEQ_EXE`	`C:\Program Files\Pianoteq 8\Pianoteq 8.exe`	Pianoteq 경로
`FLUIDSYNTH_BIN`	`fluidsynth`	FluidSynth 경로
`SOUNDFONT_PATH`	(비어있음)	SoundFont 파일 경로

환경변수 없어도 기본값으로 동작.

Pianoteq 경로만 맞으면 된다.

9. Claude MCP Desktop 활용법

PC에서 Claude MCP Desktop을 쓸 때 이렇게 말하면 된다:

서버 기동 도움

parksy-audio/local-agent 폴더에서 uvicorn 서버 띄워줘.
포트 8787, reload 모드로.

에러 디버깅

이 에러 로그 봐줘: [에러 메시지 붙여넣기]
local-agent/server.py에서 뭐가 잘못된 건지 알려줘.

Pianoteq 경로 찾기

내 PC에 Pianoteq가 설치돼 있는데 경로를 모르겠어.
Program Files 폴더에서 찾아줘.

풀사이클 테스트 자동화

local-agent 서버 띄우고, 테스트 오디오로 CUT → MIDI → RENDER 순서대로 돌려봐.
결과 파일 확인까지 해줘.

10. 요약 — 집 가서 할 일 (10분)

1. git pull
2. cd local-agent
3. .venv 만들고 activate
4. pip install -r requirements.txt
5. uvicorn server:app --port 8787 --reload
6. 브라우저에서 /status 확인
7. curl로 /cut → /extract-midi → /render 순서대로
8. WAV 재생해서 소리 나오면 끝
9. git commit & push

이것만 하면 된다. 나머지는 다 Termux에서 끝냈다.