카메라 영상에서 실시간으로 바닥 마커를 인식하여 가상의 게임 보드를 평면 투영(Homography) 매핑하고, MediaPipe를 이용한 손 제스처(손/주먹) 인터랙션으로 즐기는 증강현실(AR) 리듬게임입니다.
키보드나 마우스 없이 오직 웹캠과 사용자의 손동작만으로 게임 플레이 및 메뉴 조작이 가능합니다.
librosa를 활용하여 기본 비트 감지 및 채보 생성 기능을 수행했습니다.
본 프로젝트는 MIT License를 따릅니다.
- [프로젝트 소개]
- [주요 기능]
- [시작하기 및 실행 방법]
- [플레이 데모 타임라인]
- [기술 스택]
- [개발 비하인드 (인식 로직 변경)]
- [향후 추가하고 싶은 기능]
- [참고 자료 및 출처]
본 프로젝트는 대학 컴퓨터 비전 및 인터랙티브 미디어 프로젝트의 일환으로 제작된 컴퓨터 비전 기반 AR 리듬게임입니다.
전통적인 하드웨어 입력 장치(키보드/마우스)에서 벗어나, 사용자의 실제 주변 환경(바닥 평면)을 게임 공간으로 융합하고 신체 제스처(Hand Gesture)를 입력 장치로 활용하여 더 높은 가상현실 몰입감을 제공하는 것을 목표로 합니다.
또한 어떠한 오디오 음원이든 자동으로 비트를 분석하여 동적으로 채보를 생성하는 알고리즘을 내장하고 있습니다.
-
바닥 스캔 및 트랙 고정: 특징점 알고리즘(
ORB)과 brute-force 매칭(BFMatcher)을 사용해 카메라 뷰 내에서 미리 지정된 바닥 마커 영역을 실시간으로 추적합니다. -
원근 변환 (Perspective Transform): 가상의 긴 게임 보드(
$480 \times 720$ )에서 떨어지는 노트를 카메라가 바라보는 바닥 좌표($480 \times 480$ )에 맞게 왜곡 제어(cv.warpPerspective)하여 완벽한 AR 일체감을 구현합니다.
- 비트 감지 (Onset Detection): 입력된 MP3 파일의 오디오 신호를 분석하여 드럼이나 베이스 같은 타악기 성분(
librosa.effects.hpss)을 분리하고, 에너지가 피크를 이루는 지점(librosa.util.peak_pick)을 추출합니다. - 실시간 랜덤 라인 배치: 감지된 비트 타임스탬프에 맞춰 4개의 라인(Lane) 중 하나에 실시간으로 노트를 생성하여 매번 새로운 플레이 경험을 제공합니다.
- 고성능 핸드 트래킹:
MediaPipe Hands를 활용해 화면 안의 손 관절 랜드마크를 추적합니다. - 제스처 기반 노트 타격: 단순한 손의 위치 인식을 넘어, 손가락 마디 관절의 굽힘 여부를 계산하여 ✊(주먹)에서 ✋(손)으로, 혹은 ✋(손)에서 ✊(주먹)으로 제스처가 전환되는 순간(State Change)을 트리거로 노트를 타격합니다.
- 비접촉 메뉴 조작: 음악 선택 화면, 결과 창 등 모든 UI UI 버튼 역시 손을 올려두고 제스처를 바꾸는 방식으로 선택할 수 있습니다.
-
실시간 스코어링 & 이펙트: 판정선 타이밍 내에 제스처를 바꾸면
HIT이펙트와 함께 100점을 획득하며, 놓칠 경우MISS이펙트가 발생합니다.- 노트 판정 기준
- 타이밍: 오디오 싱크 타임스탬프 기준
$\pm 0.15$ 초 이내 입력 시 HIT 처리 - 좌표: 4개의 트랙 라인 중심 좌표(
$X$ 축) 기준 오차 범위$\pm 50$ 픽셀 이내에 손이 위치해야 유효 타격으로 인정
- 타이밍: 오디오 싱크 타임스탬프 기준
- 노트 판정 기준
-
판정선 흡착(Snap) 보정: 사용자의 손이 판정선 주위 임계치 내로 진입하면, 손의 Y축 좌표를 가상 보드의 판정선에 일치하도록 동적으로 흡착(Snap)시킵니다.
- 임계치: 기준 원의 y 좌표 기준
$\pm 150$ 픽셀 이내
- 임계치: 기준 원의 y 좌표 기준
-
다이내믹 HP 바: 게임 시작 시 가득 찬 상태로 시작하며,
MISS시 체력이 감소하고HIT시 소량 회복됩니다. 체력이 30% 이하로 떨어지면 게이지 바가 적색으로 점등하며 경고하고, 0%가 되면 게임이 즉시 종료됩니다. -
환경 세팅 재사용 기능: 매 게임마다 바닥을 다시 스캔할 필요 없이, 기존 스캔 데이터를 유지(
유지선택)하여 빠르게 재경기를 시작할 수 있습니다.
사용자의 플레이 분석 및 피드백을 위해 비디오 레코더를 시스템 도메인별로 이원화하여 파일로 저장합니다. (XVID 코덱, .avi 포맷)
- out_recorder: 인게임 외적인 전반적인 흐름을 기록합니다. [바닥 스캔 단계], [카메라 정렬 지시 화면], [재경기 유지/재스캔 선택 메뉴] 등 시스템 제어 레이아웃과 텍스트 정보가 포함된 전체 시퀀스를 저장합니다.
- play_recorder: 순수 게임 플레이 순간만을 집중 기록합니다. 음악이 재생되고 실시간 노트가 낙하하는 순간부터 게임 오버 혹은 게임 클리어 연출이 출력되는 결과창 직전까지의 핵심 인게임 화면만을 별도로 정밀 기록합니다.
프로그램을 실행하기 위해 PC에 웹캠(Webcam)이 연결되어 있어야 하며, 아래 파이썬 패키지들이 설치되어 있어야 합니다.
- opencv-python, numpy, librosa, pygame, mediapipe, Pillow
실행 전, 스크립트와 동일한 위치에 음원 파일(mp3)이 준비되어 있어야 합니다.
├── AR_rhythm_game.py
├── classic.mp3
└── pop.mp3
터미널을 열고 아래 명령어를 입력하여 프로그램을 실행합니다.
- python AR_rhythm_game.py
- 종료: 게임 도중 창을 닫거나 키보드 q를 누르면 안전하게 종료
Ar_rhythm_game_2026-06-07_16-56-26.avi
[전체 플레이 시나리오 Flow]
- 바닥 스캔(~ 6s): 카메라를 통한 마커 초기 스캔 및 가이드 사각형 정렬
- 카메라 위치 조정(~ 12s): 평면 투영 매핑 매트릭스 계산 및 가이드 화살표 연출
- 음악 선택(~ 16s): UI 버튼 위에 손을 올린 뒤 제스처를 전환하여
pop.mp3선택 - 1차 플레이 (Game Over)(~ 33s): 채보 생성 안내 연출 후 카운트다운과 함께 시작 -> 노트 입력 실패로 HP가 방전되어
GAME OVER연출 확인 - 메인 메뉴 복귀(~ 36s): 결과창 조작을 통해 초기 세팅 화면으로 이동
- 기존 설정 유지(~ 39s): 바닥 재스캔 단계를 건너뛰고 기존 스캔 정보 사용(
유지선택) - 음악 재선택(~ 41s): 동일한 제스처 인터랙션으로
classic.mp3선택 후 게임 진입 - 2차 플레이 (Game Over)(~ 1m 8s): Miss로 깎인 체력을 타이밍에 맞춘 Hit 타격으로 극복하며 플레이하는 모습 연출 -> 노트 입력 실패로 HP가 방전되어
GAME OVER연출 - 게임 재시작(~ 1m 12s): 결과창 조작을 통해 같은 음악(
classic.mp3)을 같은 설정으로 재시작 - 3차 플레이 (Game Clear)(~ 2m 50s): 완주 후
GAME CLEAR및 최종 점수 확인 - 프로그램 종료(~ 2m 52s): 메뉴 조작을 통해 프로그램 안전 종료
- Language: Python
- Computer Vision / AR: OpenCV (v4.x)
- Hand Tracking: MediaPipe
- Audio Analysis: librosa
- Game Engine / Audio Play: Pygame (mixer)
- UI / Font Rendering: Pillow (PIL)
-
인식 백엔드 변경 (
analyze_hand_gesture➡️analyze_hand_gesture_mp) 초기 프로토타입 설계 당시에는 OpenCV 기반의 컨투어(Contour) 및 Convexity Defects 방식을 사용하는 레퍼런스(hand-gesture-recognition-opencv)를 참고하여 손동작 인식 로직을 개발했습니다.
그러나 해당 방식은 주변 배경 잡음, 복잡한 조명 환경, 혹은 카메라 앵글의 미세한 변화에 따라 손가락 개수 오인식이 빈번하게 발생하는 아쉬움이 있었습니다.이를 극복하기 위해 복잡한 환경에서도 21개의 3D 손 관절 랜드마크를 강력하게 추적하는 MediaPipe Hands로 백엔드를 완전히 교체했습니다. 결과적으로 9번 랜드마크(중지 기저관절) 중심 좌표 추적과 손가락 끝/마디 관절의 Y축 상대 비교 로직을 통해 환경 영향을 받지 않는 고정밀
analyze_hand_gesture_mp()알고리즘을 구축할 수 있었습니다.
- 인게임 영상 및 음원 녹화 합성: 현재 비디오 레코더(
play_recorder,out_recorder)는 마이크나 시스템 사운드 없이 순수 프레임(화면)만 녹화하는 한계가 있습니다. 향후FFmpeg파이프라인이나moviepy라이브러리를 연동하여, 플레이가 끝난 후 녹화된.avi영상 파일에 플레이했던 배경음악(.mp3) 소리를 싱크에 맞춰 오디오 포함 비디오 파일로 출력하는 기능을 추가할 예정입니다. - UI/UX 최적화: OpenCV 프레임 기반 렌더링을 고도화하여 가독성 높고 세련된 인게임 GUI 디자인 적용
- 모션 설명 및 안내 추가: 게임 진입 전, 초보 사용자가 제스처 조작법(✊✋ 전환)을 쉽게 익힐 수 있도록 안내 컴포넌트 추가
- 화려한 게임 이펙트: 노트 Hit/Miss 시 콤보 연출, 스파크 파티클 등 시각적 몰입감을 극대화하는 애니메이션 이펙트 적용
- 게임 난이도 세분화: 사용자 취향에 맞춰 노트 낙하 속도(NOTE_SPEED) 및 판정선 타이밍 스케일 조절 기능 추가
- 다양한 노트 규격 확장: 단타 노트 외에 길게 누르는 롱노트(Long Note), 양손을 동시에 사용하는 동시치기 패턴 구현
- 기본 비트 감지 및 채보 알고리즘 프로토타이핑: [librosa 공식 GitHub] "https://github.com/librosa/librosa"
- 초기 프로토타입 스킨/손 윤곽선 인식 아이디어 레퍼런스: [mahaveerverma/hand-gesture-recognition-opencv] "https://github.com/mahaveerverma/hand-gesture-recognition-opencv"
- 음악
- classic.mp3: 클래식 피아노_Piano Amor
- pop.mp3: Escape Your Love (Upbeat Fashion Pop Dance)_FASSounds(Music by FASSounds from Pixabay)