Chapter 11

💻실전 예제 3가지

직접 만들어보기

메트로놈, MediaPipe 손 추적, OSC 메시지 전송기를 직접 만들어봅니다.

약 45분

Chapter 11: 실전 예제 3가지 — 직접 만들어보기

이론은 충분합니다. 이제 직접 만들어봅시다! 이 장에서는 3가지 실전 프로젝트를 바이브 코딩으로 처음부터 끝까지 완성합니다. 각 예제는 실제로 AI에게 입력할 프롬프트를 그대로 보여드리며, 단계별로 Git 커밋을 하면서 진행합니다.

🎼 음악으로 비유하면

이 장은 에뛰드(연습곡) 3곡을 연주하는 시간입니다. 첫 번째 곡은 단순한 스케일 연습(메트로놈), 두 번째는 양손 협응(MediaPipe 손 추적), 세 번째는 앙상블 합주(OSC로 Ableton 연결)입니다. 각 곡이 점점 어려워지지만, 하나씩 익히면 최종 프로젝트를 위한 기초가 완성됩니다.

예제 1: 웹 메트로놈 만들기

목표

HTML, CSS, JavaScript만으로 브라우저에서 동작하는 메트로놈을 만듭니다. 프레임워크 없이 순수 웹 기술만 사용하므로 토큰을 최소한으로 사용합니다.

왜 메트로놈인가?

🎼 음악으로 비유하면

메트로놈은 가장 기본적인 음악 도구이면서, 프로그래밍의 핵심 개념을 담고 있습니다. 타이머(setInterval) = 일정한 박자, 오디오 API(Web Audio) = 소리 생성, UI 업데이트 = 시각적 피드백. 음악에서 박자가 모든 것의 기초이듯, 이 예제는 웹 개발의 기초를 다집니다.

Step-by-Step 실습

프로젝트 폴더 및 Git 초기화

프로젝트 생성

$ mkdir -p metronome-app && cd metronome-app && git init

Initialized empty Git repository in /home/user/metronome-app/.git/

AGENTS.md 생성bash

첫 커밋

$ git add -A && git commit -m "프로젝트 초기화 및 AGENTS.md 작성"

[main (root-commit) a1b2c3d] 프로젝트 초기화 및 AGENTS.md 작성

AI에게 기본 구조 생성 요청

이제 AI에게 메트로놈을 만들어달라고 요청합니다:

메트로놈 생성 프롬프트bash

💡 프롬프트 분석

이 프롬프트가 효과적인 이유를 분석해봅시다:

구체적인 기술 지정: "Web Audio API", "오실레이터 사용"
숫자로 명시: "40-240", "기본값 120", "880Hz", "440Hz"
시각적 요구사항: "원이 깜빡이는", "다크 테마", "모바일 반응형"
제약 조건: "파일 하나", "파일 불필요" 모호한 부분이 없으므로 AI가 한 번에 정확한 결과를 만들 확률이 높습니다.

결과 확인 및 커밋

로컬 서버 실행

$ python3 -m http.server 8080

Serving HTTP on 0.0.0.0 port 8080 ...

브라우저에서 http://localhost:8080을 열어 메트로놈이 동작하는지 확인합니다. 소리가 나고, 원이 깜빡이고, BPM 슬라이더가 작동하면 성공입니다.

두 번째 커밋

$ git add index.html && git commit -m "기본 메트로놈 구현: Web Audio + 시각 피드백"

[main b2c3d4e] 기본 메트로놈 구현: Web Audio + 시각 피드백

기능 추가 — 박자 선택

박자 선택 추가 프롬프트bash

세 번째 커밋

$ git add index.html && git commit -m "박자 선택 기능 추가 (4/4, 3/4, 6/8)"

[main c3d4e5f] 박자 선택 기능 추가 (4/4, 3/4, 6/8)

ℹ️ 토큰 절약 팁

파일 하나에 모든 코드를 넣는 방식은 토큰을 크게 절약합니다. 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 작성

프로젝트 초기화bash

AI에게 기본 손 추적 페이지 생성 요청

MediaPipe 데모 프롬프트bash

🔥 이 프롬프트의 핵심 포인트

구체적인 landmark 번호를 지정한 것에 주목하세요. "검지 끝"이라고만 하면 AI가 잘못된 번호를 쓸 수 있지만, "landmark 8"이라고 명시하면 정확합니다. MediaPipe Hands의 랜드마크 번호를 미리 조사해둔 덕분입니다. 자료 조사의 힘입니다.

결과 확인 — 카메라 테스트

서버 실행

$ python3 -m http.server 8080

Serving HTTP on 0.0.0.0 port 8080 ...

브라우저에서 http://localhost:8080을 열고 카메라 접근을 허용합니다. 손을 카메라 앞에 놓으면:

21개의 빨간 점이 손 관절 위에 표시됩니다
초록색 선이 관절을 연결합니다
우측 패널에 좌표가 실시간으로 업데이트됩니다

커밋

$ git add index.html && git commit -m "MediaPipe 손 추적 기본 구현"

[main d4e5f6g] MediaPipe 손 추적 기본 구현

기능 추가 — 제스처 인식

손 추적이 되면, 간단한 제스처를 인식해봅시다:

제스처 인식 추가 프롬프트bash

커밋

$ git add index.html && git commit -m "제스처 인식 추가 (주먹, 펼침, 피스)"

[main e5f6g7h] 제스처 인식 추가 (주먹, 펼침, 피스)

디버깅 — 문제가 생겼을 때

카메라가 안 켜지거나 랜드마크가 안 보이면:

디버깅 프롬프트bash

⚠️ 카메라 접근 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 메시지 예시javascript

Step-by-Step 실습

프로젝트 생성

프로젝트 초기화bash

OSC 브릿지 서버 생성

서버 생성 프롬프트bash

웹 UI 생성

UI 생성 프롬프트bash

테스트 및 Ableton 연결

서버 실행

$ npm install && node server.js

OSC 브릿지 서버 시작: http://localhost:3000 WebSocket 서버 대기 중... OSC 전송 대상: localhost:11000

ℹ️ Ableton Live에서 OSC 받기

Ableton Live 자체는 OSC를 직접 지원하지 않습니다. Max4Live 디바이스를 사용하거나, TouchOSC Bridge, OSCpilot 같은 도구가 필요합니다. TouchDesigner는 OSC In CHOP으로 바로 받을 수 있습니다.

포트 설정 프롬프트bash

커밋

$ git add -A && git commit -m "OSC 전송기 완성: 서버 + UI + 프리셋"

[main f6g7h8i] OSC 전송기 완성: 서버 + UI + 프리셋

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개 커밋!
프롬프트를 자신만의 방식으로 수정해서 다른 결과를 얻어보세요.