Mabi Music Monitor

마비노기 모바일의 연주 정보를 작은 오버레이로 보여주는 Windows용 오픈소스 프로그램입니다. 게임이 이미 전송한 TCP 패킷을 로컬에서 수동 관찰(passive capture) 하여 곡 제목, 전체 길이, 남은 시간, 합주 파트, 현재 음과 확인 가능한 연주자·악기 정보를 표시합니다.

이 저장소는 사용자가 배포 EXE의 동작을 직접 검토하고 같은 소스에서 다시 빌드할 수 있도록 공개한 전체 소스입니다.

사용 전 주의사항

• 맵을 이동한 뒤에는 프로그램을 껐다가 다시 켜주세요. 맵 이동 과정에서 게임 서버 연결이 바뀌면 연주 정보 인식에 실패할 수 있습니다. 맵 이동을 마친 다음 Mabi Music Monitor를 완전히 종료하고 다시 실행하는 것이 가장 확실합니다.
• 프로그램을 켜기 전에 이미 재생을 시작한 곡은 인식하지 못합니다. 곡의 시작 정보가 프로그램 실행 전에 지나갔기 때문입니다. 연주에 참여하거나 곡을 시작하기 전에 프로그램을 먼저 실행해주세요.

설치 방법

개발 관련 지식은 필요 없습니다. Npcap 설치 → MabiMusicMonitor.exe 다운로드 → 실행 순서로 진행하면 됩니다.

1. Npcap 설치

Mabi Music Monitor는 게임이 전송한 네트워크 정보를 확인하기 위해 Npcap이 필요합니다. Npcap은 프로그램에 포함하지 않으므로 최초 한 번만 별도로 설치해야 합니다.

1. Npcap 공식 홈페이지에 접속합니다.
2. 페이지의 Downloading and Installing Npcap Free Edition 항목에서 첫 번째 Npcap installer 링크를 누릅니다.
3. 받은 설치 파일을 실행하고, 특별히 설정을 바꿀 필요가 없다면 기본 설정 그대로 설치합니다.

Npcap 홈페이지가 연결 시간 초과 등으로 열리지 않을 때는 Wireshark 공식 Windows 다운로드 페이지에서 Windows x64 Installer를 설치하는 방법도 있습니다. Wireshark 공식 Windows 설치 프로그램에는 Npcap이 포함되어 있습니다. 설치 과정에서 Install Npcap 선택을 유지하세요. Npcap 설치가 목적이라면 이후 Wireshark를 실행할 필요는 없습니다.

Npcap은 한 번만 설치하면 되며 Mabi Music Monitor를 실행할 때마다 다시 설치할 필요가 없습니다.

2. Mabi Music Monitor 다운로드

1. 최신 GitHub 릴리스 페이지를 엽니다.
2. 페이지 아래쪽의 Assets에서 MabiMusicMonitor.exe만 다운로드합니다.
3. 원하는 폴더에 파일을 두고 실행합니다. 별도 설치 프로그램은 없습니다.

다른 첨부 파일은 일반적인 실행에는 필요하지 않습니다.

• MabiMusicMonitor.exe: 실제 프로그램입니다. 일반 사용자는 이것만 받으면 됩니다.
• scapy-2.7.0.tar.gz: 사용된 오픈소스 라이브러리의 원본 소스입니다.
• SHA256SUMS.txt: 다운로드 파일의 무결성을 확인하는 SHA-256 정보입니다.
• BUILD_INFO.txt: 프로그램 빌드 환경과 검증 정보입니다.

3. Windows 경고가 뜨는 경우

현재 EXE에는 상용 코드 서명 인증서가 없어 처음 실행할 때 Windows의 PC 보호 또는 인식할 수 없는 앱의 시작을 차단했습니다라는 SmartScreen 경고가 나타날 수 있습니다. 일반적인 SmartScreen 화면이라면 추가 정보 → 실행 순서로 선택할 수 있습니다.

Windows의 Smart App Control이 프로그램 자체를 완전히 차단한 경우 일반 SmartScreen과 달리 개별 프로그램만 예외 처리하지 못할 수 있습니다. 이 경우 Windows 보안 기능을 억지로 끄는 것은 권장하지 않습니다.

반드시 이 저장소의 공식 릴리스에서 받은 파일인지 확인하세요. 실행 파일과 Scapy 원본 소스의 SHA-256은 release/SHA256SUMS.txt에서 확인할 수 있습니다.

4. 관리자 권한 허용

프로그램을 실행하면 **이 앱이 디바이스를 변경할 수 있도록 허용하시겠어요?**라는 관리자 권한 확인 창이 나타납니다. Npcap 패킷 확인에 필요하므로 예를 누릅니다.

5. 실행 완료

별도의 연결 버튼이나 시작 버튼은 없습니다. Mabi Music Monitor를 켜놓은 상태에서 마비노기 모바일을 실행하고 연주하면 게임 연결과 연주 정보를 자동으로 감지합니다.

자주 묻는 질문

Q. GitHub의 파일을 전부 받아야 하나요?

아니요. 일반 사용자는 MabiMusicMonitor.exe만 받으면 됩니다. Npcap은 공식 배포 경로에서 별도로 설치합니다.

Q. Python을 설치해야 하나요?

아니요. 소스에서 직접 빌드할 때만 필요합니다.

Q. 설치 프로그램이 없는데 정상인가요?

정상입니다. MabiMusicMonitor.exe가 바로 실행되는 단일 파일입니다.

Q. 실행했는데 누를 버튼이 없습니다.

정상입니다. 프로그램을 켜둔 뒤 게임에서 연주하면 자동으로 감지합니다.

Q. Windows 경고가 나오면 바이러스인가요?

코드 서명 인증서가 없는 새 프로그램은 SmartScreen 경고가 나타날 수 있습니다. 전체 소스와 SHA-256을 공개하고 있지만, 인터넷에서 받은 실행 파일인 만큼 공식 릴리스에서 받은 파일인지 확인하세요.

주요 기능

• 곡 제목·전체 길이·남은 시간 자동 표시
• MML을 직접 붙여넣지 않아도 패킷에서 곡 정보 인식
• 멜로디와 화음 1~5의 활성 상태, 현재 음과 음높이 표시
• 한 파트에 여러 연주자가 참가하는 합주 표시
• 패킷에서 확인된 악기명과 선택적 닉네임 표시
• 내가 참가한 연주만 타이머로 전환
• 반복 연주 시 다음 회차로 타이머 자동 갱신
• 연주 중단 시 타이머 일시정지, 재참가 시 현재 회차에 재정렬
• 맵 이동 후 게임 서버 연결 자동 갱신
• 타이머만 남기는 축소 모드와 작업 표시줄 최소화

이 프로그램이 하지 않는 일

• 게임에 키보드·마우스 입력을 보내지 않습니다.
• 패킷을 변조·재전송·주입하지 않습니다.
• 게임 프로세스 메모리를 읽거나 수정하지 않습니다.
• DLL을 주입하거나 안티치트를 우회하지 않습니다.
• 캡처 결과나 닉네임을 외부 서버로 업로드하지 않습니다.
• 업데이트 파일을 자동으로 내려받거나 실행하지 않습니다.

구체적인 근거와 확인 위치는 SECURITY.md와 docs/ARCHITECTURE.md에 정리했습니다. 다만 소스 공개가 특정 게임 운영정책의 허용이나 안티치트 호환성을 보증하는 것은 아닙니다. 사용 전 해당 게임의 최신 운영정책을 직접 확인해야 합니다.

개인정보와 로컬 로그

프로그램 폴더의 timer_logs/에 PCAP과 JSONL 로그가 생성됩니다. 여기에는 서버 주소, 패킷 원문, 곡 제목·MML 및 패킷에서 확인된 닉네임이 포함될 수 있습니다. 프로그램이 이를 자동 전송하지는 않지만, 원본 로그를 공개 저장소나 메신저에 올리면 개인정보가 노출될 수 있습니다.

자세한 내용은 PRIVACY.md를 확인하세요. 실제 게임 캡처 로그와 사용자 설정 파일은 이 저장소에 포함하지 않았습니다.

소스에서 검증하고 빌드하기

Python 3.12가 설치된 Windows PowerShell에서 실행합니다.

git clone <repository-url>
cd MabiMusicMonitor
powershell -ExecutionPolicy Bypass -File .\build.ps1

스크립트는 고정된 직접 의존성을 설치하고, 테스트를 실행한 뒤 release/MabiMusicMonitor.exe와 새 SHA-256 파일을 생성합니다. 상세 명령과 재현성 한계는 BUILDING.md에 있습니다.

.\.venv\Scripts\python.exe -m pytest

소스 구성

src/mabi_music_probe/
  countdown_gui.py       오버레이 UI와 상태 관리
  capture/               Npcap/Scapy 수동 캡처 및 연결 탐색
  score_packet.py        곡 제목과 압축 MML 해석
  ensemble_packet.py     합주 파트·악기·연주자 상태 해석
  mml_duration.py        MML 길이와 현재 음 계산
  playback_timing.py     패킷 시각과 실제 청취 시점 보정
tests/                   합성 데이터 기반 자동 테스트

실제 게임 패킷·PCAP·닉네임은 테스트 fixture나 저장소에 포함하지 않습니다.

제한 사항

• 서버가 곡 전체 정보를 내 클라이언트에 보내지 않은 연주는 남은 시간을 계산할 수 없습니다.
• 패킷 형식이 게임 업데이트로 변경되면 인식이 중단될 수 있습니다.
• 표시 시간은 패킷 시각과 관찰된 오디오 지연을 바탕으로 한 추정값입니다.
• Npcap 설치와 관리자 권한이 필요합니다.

라이선스

이 프로젝트는 Scapy와 함께 배포되므로 GNU General Public License v2.0 only로 공개합니다. 자세한 조건은 LICENSE, 직접·빌드 의존성 고지는 THIRD_PARTY_NOTICES.md를 확인하세요.

배포에 사용한 Scapy 2.7.0의 공식 PyPI 원본 소스 배포본은 release/scapy-2.7.0.tar.gz로 함께 제공합니다. 파일 해시는 release/SHA256SUMS.txt에 있으며 PyPI가 게시한 SHA-256과 일치하도록 검증했습니다.