💻실전 예제 3가지
직접 만들어보기
메트로놈, MediaPipe 손 추적, OSC 메시지 전송기를 직접 만들어봅니다.
Chapter 11: 실전 예제 3가지 — 직접 만들어보기
이론은 충분합니다. 이제 직접 만들어봅시다! 이 장에서는 3가지 실전 프로젝트를 바이브 코딩으로 처음부터 끝까지 완성합니다. 각 예제는 실제로 AI에게 입력할 프롬프트를 그대로 보여드리며, 단계별로 Git 커밋을 하면서 진행합니다.
이 장은 에뛰드(연습곡) 3곡을 연주하는 시간입니다. 첫 번째 곡은 단순한 스케일 연습(메트로놈), 두 번째는 양손 협응(MediaPipe 손 추적), 세 번째는 앙상블 합주(OSC로 Ableton 연결)입니다. 각 곡이 점점 어려워지지만, 하나씩 익히면 최종 프로젝트를 위한 기초가 완성됩니다.
예제 1: 웹 메트로놈 만들기
목표
HTML, CSS, JavaScript만으로 브라우저에서 동작하는 메트로놈을 만듭니다. 프레임워크 없이 순수 웹 기술만 사용하므로 토큰을 최소한으로 사용합니다.
왜 메트로놈인가?
메트로놈은 가장 기본적인 음악 도구이면서, 프로그래밍의 핵심 개념을 담고 있습니다. 타이머(setInterval) = 일정한 박자, 오디오 API(Web Audio) = 소리 생성, UI 업데이트 = 시각적 피드백. 음악에서 박자가 모든 것의 기초이듯, 이 예제는 웹 개발의 기초를 다집니다.
Step-by-Step 실습
프로젝트 폴더 및 Git 초기화
# AGENTS.md 생성
cat > AGENTS.md << 'EOF'
# 웹 메트로놈
## 기술 스택
- HTML5 + CSS3 + Vanilla JavaScript
- Web Audio API (소리 생성)
- 프레임워크 미사용
## 코딩 규칙
- 한국어 주석 필수
- 모든 코드는 단일 index.html 파일에 작성
- ES6+ 문법 사용
## 기능 요구사항
- BPM 조절 (40-240)
- 시작/정지 버튼
- 시각적 비트 표시 (깜빡임)
- 첫 박 강세 (다른 소리)
- 박자 선택 (4/4, 3/4, 6/8)
EOFAI에게 기본 구조 생성 요청
이제 AI에게 메트로놈을 만들어달라고 요청합니다:
codex "index.html 파일 하나에 웹 메트로놈을 만들어줘.
요구사항:
1. Web Audio API로 클릭 소리를 생성 (오실레이터 사용, 파일 불필요)
2. BPM 슬라이더 (40-240, 기본값 120)
3. 시작/정지 토글 버튼
4. 현재 BPM 숫자 표시
5. 비트마다 화면에 원이 깜빡이는 시각적 피드백
6. 첫 박은 높은 음(880Hz), 나머지 박은 낮은 음(440Hz)
7. 4/4 박자 기본
CSS는 다크 테마로, 가운데 정렬, 모바일 반응형으로.
한국어 주석을 꼭 넣어줘."이 프롬프트가 효과적인 이유를 분석해봅시다:
- 구체적인 기술 지정: "Web Audio API", "오실레이터 사용"
- 숫자로 명시: "40-240", "기본값 120", "880Hz", "440Hz"
- 시각적 요구사항: "원이 깜빡이는", "다크 테마", "모바일 반응형"
- 제약 조건: "파일 하나", "파일 불필요" 모호한 부분이 없으므로 AI가 한 번에 정확한 결과를 만들 확률이 높습니다.
결과 확인 및 커밋
브라우저에서 http://localhost:8080을 열어 메트로놈이 동작하는지 확인합니다. 소리가 나고, 원이 깜빡이고, BPM 슬라이더가 작동하면 성공입니다.
기능 추가 — 박자 선택
codex "index.html의 메트로놈에 박자 선택 기능을 추가해줘.
- 드롭다운으로 4/4, 3/4, 6/8 선택
- 선택한 박자에 따라 비트 원의 개수가 바뀜
(4/4는 원 4개, 3/4는 원 3개, 6/8는 원 6개)
- 강세 패턴도 박자에 맞게 변경
(6/8은 1번째와 4번째 박에 강세)
- 기존 코드를 유지하면서 수정해줘"파일 하나에 모든 코드를 넣는 방식은 토큰을 크게 절약합니다. AI가 "index.html을 읽어와야지" 한 번만 하면 되니까요. 여러 파일로 분리하면 각 파일을 읽고 쓰는 데 토큰이 소모됩니다. 간단한 프로젝트에서는 단일 파일 전략이 효율적입니다.
예제 2: MediaPipe 손 추적 데모
목표
웹캠으로 손을 추적하고, 화면에 21개 손가락 랜드마크 좌표를 실시간으로 표시하는 데모를 만듭니다. 이것이 최종 프로젝트(Ableton 제어)의 기초가 됩니다.
이 예제는 테레민의 디지털 버전을 만드는 첫 단계입니다. 테레민은 손의 위치로 음높이와 볼륨을 제어하죠. 우리도 카메라로 손의 위치를 파악하는 것부터 시작합니다. 지금은 소리를 내지 않고, 손의 좌표를 "보는" 것만 합니다. 악기를 연주하기 전에 먼저 악기를 이해하는 단계입니다.
MediaPipe Hands 핵심 개념
시작하기 전에, MediaPipe의 손 추적이 어떻게 작동하는지 이해합시다:
| 개념 | 설명 | 음악 비유 | |------|------|-----------| | Landmark | 손의 관절 포인트 (21개) | 피아노 건반 하나하나 | | x, y, z 좌표 | 각 포인트의 3D 위치 | 음의 높이, 세기, 깊이 | | Confidence | 추적 신뢰도 (0~1) | 연주 정확도 | | Handedness | 왼손/오른손 구분 | 양손 피아노 연주 |
Step-by-Step 실습
프로젝트 생성 및 AGENTS.md 작성
mkdir -p hand-tracker-demo && cd hand-tracker-demo && git init
cat > AGENTS.md << 'EOF'
# MediaPipe Hand Tracker Demo
## 기술 스택
- HTML5 + CSS3 + JavaScript
- MediaPipe Hands (CDN)
- Canvas API (랜드마크 시각화)
## 주요 파일
- index.html: 메인 페이지 (단일 파일)
## 기능
1. 웹캠 연결 및 비디오 표시
2. MediaPipe Hands로 손 랜드마크 감지
3. Canvas 오버레이에 랜드마크 점과 선 그리기
4. 좌표값 실시간 텍스트 표시
5. FPS 카운터
## MediaPipe CDN
https://cdn.jsdelivr.net/npm/@mediapipe/hands
https://cdn.jsdelivr.net/npm/@mediapipe/camera_utils
https://cdn.jsdelivr.net/npm/@mediapipe/drawing_utils
EOF
git add -A && git commit -m "hand-tracker 프로젝트 초기화"AI에게 기본 손 추적 페이지 생성 요청
codex "MediaPipe Hands를 사용한 손 추적 데모 페이지를
index.html 하나로 만들어줘.
## 필수 기능:
1. 웹캠 비디오를 화면 중앙에 표시 (640x480)
2. 비디오 위에 Canvas를 겹쳐서 랜드마크를 그림
3. MediaPipe Hands CDN으로 로드 (npm 설치 불필요)
4. 감지된 손의 21개 랜드마크를 빨간 점으로 표시
5. 랜드마크 사이를 초록색 선으로 연결
6. 화면 우측에 실시간 좌표 패널:
- 검지 끝(landmark 8)의 x, y 좌표
- 엄지 끝(landmark 4)의 x, y 좌표
- 검지-엄지 사이 거리
7. 좌측 상단에 FPS 카운터
8. 카메라 접근 실패 시 에러 메시지 표시
## 스타일:
- 다크 테마 (배경 #1a1a2e)
- 좌표 텍스트는 모노스페이스 폰트
- 모바일에서도 사용 가능하게 반응형
## MediaPipe 설정:
- maxNumHands: 2 (양손)
- minDetectionConfidence: 0.7
- minTrackingConfidence: 0.5
한국어 주석을 반드시 넣어줘."구체적인 landmark 번호를 지정한 것에 주목하세요. "검지 끝"이라고만 하면 AI가 잘못된 번호를 쓸 수 있지만, "landmark 8"이라고 명시하면 정확합니다. MediaPipe Hands의 랜드마크 번호를 미리 조사해둔 덕분입니다. 자료 조사의 힘입니다.
결과 확인 — 카메라 테스트
브라우저에서 http://localhost:8080을 열고 카메라 접근을 허용합니다. 손을 카메라 앞에 놓으면:
- 21개의 빨간 점이 손 관절 위에 표시됩니다
- 초록색 선이 관절을 연결합니다
- 우측 패널에 좌표가 실시간으로 업데이트됩니다
기능 추가 — 제스처 인식
손 추적이 되면, 간단한 제스처를 인식해봅시다:
codex "index.html에 제스처 인식 기능을 추가해줘.
다음 3가지 제스처를 인식:
1. '주먹' - 모든 손가락이 접혀있을 때
(각 손가락 끝 landmark가 해당 MCP landmark보다 아래)
2. '펼침' - 모든 손가락이 펴져있을 때
3. '피스' - 검지와 중지만 펴져있을 때
인식 결과:
- 화면에 큰 텍스트로 현재 제스처 이름 표시
- 제스처별로 다른 색 배경 효과 (주먹=빨강, 펼침=초록, 피스=파랑)
- 제스처가 바뀔 때 부드러운 전환 효과
기존 랜드마크 표시는 유지하면서 추가해줘."디버깅 — 문제가 생겼을 때
카메라가 안 켜지거나 랜드마크가 안 보이면:
# 에러 로그 확인 요청
codex "index.html의 콘솔에 에러가 나와.
'Failed to load MediaPipe Hands model'이라는 에러야.
원인을 분석하고 수정해줘.
CDN URL이 최신인지도 확인해줘."
# HTTPS 문제인 경우
codex "카메라가 'NotAllowedError'로 안 켜져.
localhost가 아닌 환경에서 테스트할 때
HTTPS가 필요한 것 같은데,
간단한 해결 방법을 알려줘."대부분의 브라우저는 localhost에서만 HTTP로 카메라 접근을 허용합니다. 다른 기기에서 테스트하려면 HTTPS가 필요합니다. 개발 단계에서는 항상 localhost를 사용하세요.
예제 3: OSC 메시지 전송기
목표
웹 브라우저에서 OSC(Open Sound Control) 메시지를 보내는 도구를 만듭니다. 이것으로 Ableton Live나 TouchDesigner를 제어할 수 있습니다.
OSC는 디지털 시대의 MIDI입니다. MIDI가 건반을 DAW에 연결하듯, OSC는 웹 앱을 Ableton이나 TouchDesigner에 연결합니다. MIDI보다 더 유연하고, 네트워크를 통해 전송되므로 다른 컴퓨터의 소프트웨어도 제어할 수 있습니다.
| 비교 | MIDI | OSC | |------|------|-----| | 데이터 타입 | 노트, CC (정해진 형식) | 자유로운 형식 (문자열, 숫자, 배열) | | 전송 방식 | USB/DIN 케이블 | 네트워크 (WiFi/유선) | | 주소 체계 | 채널 + CC 번호 | URL 형식 (/track/1/volume) | | 음악 비유 | 우편 주소 | 이메일 주소 |
OSC 기본 개념
OSC 메시지는 주소 패턴과 값으로 구성됩니다:
// OSC 메시지 구조
주소: /track/1/volume 값: 0.75
주소: /track/2/pan 값: -0.5
주소: /effect/reverb/mix 값: 0.3
// Ableton에서 받을 수 있는 OSC 메시지 예시
/live/track/1/volume 0.8 // 트랙 1 볼륨을 80%로
/live/track/1/mute 1 // 트랙 1 뮤트 켜기
/live/tempo 120.0 // 템포를 120 BPM으로Step-by-Step 실습
프로젝트 생성
mkdir -p osc-sender && cd osc-sender && git init && npm init -y
cat > AGENTS.md << 'EOF'
# OSC 메시지 전송기
## 기술 스택
- 프론트엔드: HTML + JavaScript
- 서버: Node.js + Express + osc.js
- 통신: WebSocket (브라우저 ↔ 서버), UDP (서버 ↔ Ableton/TD)
## 구조
- public/index.html: 웹 UI
- server.js: WebSocket-to-OSC 브릿지 서버
## OSC 대상 포트
- Ableton Live (via Max4Live): UDP 11000
- TouchDesigner: UDP 7000
## 필요 npm 패키지
- express: 웹 서버
- osc: OSC 프로토콜 라이브러리
- ws: WebSocket 서버
EOF
git add -A && git commit -m "OSC 전송기 프로젝트 초기화"OSC 브릿지 서버 생성
codex "Node.js로 OSC 브릿지 서버를 만들어줘.
## server.js 요구사항:
1. Express로 public/ 폴더의 정적 파일 서빙 (포트 3000)
2. WebSocket 서버를 같은 포트에 연결
3. 웹소켓으로 받은 메시지를 OSC UDP로 변환하여 전송
4. OSC 전송 대상:
- 기본: localhost:11000 (Ableton)
- 설정 가능하게 (환경변수 또는 URL 파라미터)
5. 에러 핸들링 (포트 사용 중, UDP 전송 실패 등)
6. 콘솔에 송수신 로그 표시
## package.json 의존성:
- osc, express, ws
한국어 주석 필수."웹 UI 생성
codex "public/index.html에 OSC 전송 UI를 만들어줘.
## UI 구성:
1. 연결 상태 표시 (WebSocket 연결/끊김)
2. OSC 주소 입력 필드 (기본값: /live/track/1/volume)
3. 값 슬라이더 (0.0 ~ 1.0, 기본값: 0.5)
4. 전송 버튼 + 슬라이더 실시간 전송 토글
5. 최근 전송 메시지 로그 (최대 20개)
6. 프리셋 버튼 3개:
- 'Volume' → /live/track/1/volume
- 'Pan' → /live/track/1/pan
- 'Tempo' → /live/tempo
## 스타일:
- 다크 테마 (Ableton 느낌의 UI)
- 슬라이더는 크게 (터치 친화적)
- 연결 상태: 초록/빨강 LED 아이콘
## 동작:
- 페이지 로드 시 자동으로 WebSocket 연결
- 슬라이더 변경 시 실시간 전송 모드이면 즉시 전송
- 전송된 메시지를 로그에 타임스탬프와 함께 표시
한국어 주석 필수."테스트 및 Ableton 연결
Ableton Live 자체는 OSC를 직접 지원하지 않습니다. Max4Live 디바이스를 사용하거나, TouchOSC Bridge, OSCpilot 같은 도구가 필요합니다. TouchDesigner는 OSC In CHOP으로 바로 받을 수 있습니다.
# TouchDesigner에서 테스트하기 더 쉬움
# TouchDesigner > Add Operator > CHOP > OSC In
# Port: 7000 으로 설정
# 서버의 OSC 전송 포트도 7000으로 변경
codex "server.js에서 OSC 전송 포트를 환경변수로
설정할 수 있게 해줘.
기본값은 7000 (TouchDesigner)으로 변경.
OSC_PORT=11000 node server.js 형태로 사용."3가지 예제 통합 — 최종 프로젝트 미리보기
이 3가지 예제를 결합하면 우리의 최종 목표에 가까워집니다:
| 예제 | 제공하는 기술 | 최종 프로젝트에서의 역할 | |------|-------------|------------------------| | 메트로놈 | Web Audio, 타이밍, UI | 오디오 피드백, 시각적 인터페이스 | | 손 추적 | MediaPipe, 제스처 인식 | 입력 장치 (손 → 데이터) | | OSC 전송기 | WebSocket, OSC, 서버 | 출력 채널 (데이터 → Ableton/TD) |
예제 1(메트로놈)은 리듬 섹션, 예제 2(손 추적)는 연주자의 손, 예제 3(OSC 전송기)는 **PA 시스템(스피커와 앰프)**입니다. 이 세 가지가 합쳐지면 "손으로 연주하면 소리가 나는" 완전한 악기가 됩니다.
효율적인 프롬프팅 팁 정리
이 장에서 사용한 프롬프트들의 공통 패턴을 정리합니다:
구체적인 숫자 제시
"적당한 크기" 대신 "640x480", "40-240", "880Hz" 처럼 정확한 숫자를 씁니다. AI가 추측하지 않아도 됩니다.
계층적 구조화
프롬프트를 ##(제목)과 -(항목)으로 구조화합니다. AI가 요구사항을 놓치지 않습니다.
기존 코드 유지 명시
"기존 코드를 유지하면서 추가해줘"라고 반드시 명시합니다. 안 그러면 AI가 처음부터 다시 쓸 수 있습니다.
한 번에 하나씩
"메트로놈 + 손 추적 + OSC 전부 한 번에 만들어줘"보다 각각 따로 만드는 게 결과가 좋습니다. 복잡한 곡을 한 번에 녹음하지 않고 트랙별로 녹음하는 것과 같습니다.
에러 메시지 그대로 복사
디버깅할 때는 에러 메시지를 정확히 복사해서 AI에게 보여줍니다. "에러가 나요"보다 "TypeError: Cannot read property 'x' of undefined at line 45"가 훨씬 좋습니다.
바이브 코딩은 "무엇을 만들지"를 명확하게 설명하는 능력이 핵심입니다. 코드를 몰라도, 원하는 결과를 구체적으로 기술할 수 있으면 됩니다. 작곡가가 연주를 못해도 악보를 쓸 수 있듯이, 프로그래밍을 못해도 소프트웨어를 설계할 수 있습니다.
실습 과제
- 메트로놈을 직접 만들어보세요. 위의 프롬프트를 그대로 사용해도 좋습니다.
- MediaPipe 손 추적 데모를 만들고, 웹캠으로 테스트해보세요.
- (선택) OSC 전송기를 만들고, TouchDesigner가 있다면 연결해보세요.
- 각 단계를 Git 커밋하면서 진행하세요. 최소 3개 커밋!
- 프롬프트를 자신만의 방식으로 수정해서 다른 결과를 얻어보세요.