mic/plans/4b3baabc-2767-4470-bdd9-ea310403f684.md

# 작업 플랜

- UUID: `4b3baabc-2767-4470-bdd9-ea310403f684`
- 작업자: `Codex`
- 생성 시각: `2026-06-02 15:41`
- 요청 요약: `Orange Pi Zero 2W에서 실행할 클라이언트 준비`

## 할 일

- [x] 현재 요청 확인
- [x] 필수 문서 확인
- [x] 저장소 상태와 관련 파일 목록 확인
- [x] 클라이언트 준비 범위 정리
- [x] 사용자 답변을 바탕으로 클라이언트 방향성 문서 작성
- [x] README 문서 목록 갱신
- [x] 사용자의 구현 승인 확인
- [x] 승인 후 클라이언트 구현 계획 확정
- [x] 승인 후 필요한 파일 생성
- [x] 로컬 검토와 빌드 가능 여부 확인
- [x] 완료 내용 정리

## 현재 확인 내용

- 현재 브랜치는 `main`이며 원격 `origin/main`과 같은 위치입니다.
- `client/`와 `server/` 구현 파일은 아직 없습니다.
- 프로젝트 규칙상 사용자가 계획을 확정하고 실행을 지시하기 전까지 C++ 소스 코드, 빌드 시스템, 테스트 코드, 구조 변경은 만들지 않습니다.
- 클라이언트는 Orange Pi Zero 2W의 USB 라발리에 마이크 입력을 캡처하고 Wi-Fi를 통해 Mac 수신기/믹서로 전송하는 역할입니다.

## 클라이언트 준비 초안

### 목표

Orange Pi Zero 2W에서 USB 라발리에 마이크를 인식하고, C++ 송신기 프로그램으로 Mac 수신기까지 오디오를 전송할 수 있는 최소 클라이언트 경로를 준비합니다.

### 대상 환경

- 보드: Orange Pi Zero 2W
- OS: Orange Pi 공식 Debian 12 Bookworm Server, Linux 6.1
- 언어: C++
- 실행 형태: headless SSH 접속 후 실행

### 우선 확인할 항목

- OS 부팅과 SSH 접속
- Wi-Fi 연결 안정성
- USB 라발리에 마이크 인식 여부
- ALSA 장치 목록 확인
- Mac 수신기 IP와 UDP 수신 가능 여부

### 라이브러리 후보

- 오디오 캡처: ALSA `libasound2-dev`
- 네트워크 전송: POSIX UDP socket
- 빌드: CMake 후보, 단 사용자의 승인 전에는 생성하지 않음

### 초기 송신 방식 후보

- 압축 없는 PCM 16-bit mono
- 샘플레이트 후보: 48 kHz 또는 44.1 kHz
- 프레임 크기 후보: 10 ms 또는 20 ms
- 전송: UDP 패킷에 간단한 헤더와 PCM payload 포함

### 검증 방법 후보

- Orange Pi에서 마이크 장치 확인
- 짧은 ALSA 캡처 동작 확인
- Mac에서 UDP 패킷 수신 확인
- 단일 송신기 오디오 재생 확인
- 지연, 끊김, 패킷 손실 로그 확인

## 사용자 답변 반영

### 결정된 초기 범위

- USB 라발리에 마이크 모델은 고정하지 않습니다.
- 첫 테스트 마이크는 MATA STUDIO C300 같은 일반 USB 마이크를 사용합니다.
- 초기 목표는 지연 시간 최적화가 아니라 `소리가 나온다`까지입니다.
- 첫 버전은 송신기 1대만 검증합니다.
- Mac 수신기 포트는 고정 사용을 선호합니다.
- Mac 수신기 IP는 고정 설정과 자동 검색 후보를 함께 검토합니다.

### 반영할 제안

- 첫 구현은 고정 IP 설정 파일 기반으로 시작합니다.
- 자동 검색은 초기 오디오 경로 검증 이후 확장 후보로 둡니다.
- 설정 파일에는 Mac 수신기 주소, 포트, ALSA 장치, 샘플레이트, 채널 수, 프레임 길이를 둘 수 있게 설계합니다.
- USB 마이크 모델이 바뀔 수 있으므로 ALSA 장치명을 하드코딩하지 않고 설정 또는 실행 옵션으로 지정할 수 있게 합니다.
- 마이크가 지원하는 실제 포맷을 먼저 확인한 뒤 캡처 포맷을 정합니다.

### 우려 사항

- USB 마이크가 Linux ALSA에서 USB Audio Class 장치로 정상 인식되는지 확인해야 합니다.
- 마이크가 96 kHz/24-bit 위주로 동작할 경우, 초기 송신 포맷인 48 kHz/16-bit와 맞추기 위해 ALSA `plug` 변환 또는 별도 변환이 필요할 수 있습니다.
- Orange Pi Zero 2W의 USB 연결 방식, 전원, 허브 품질에 따라 마이크 인식이나 안정성이 달라질 수 있습니다.
- 마이크 자체의 MUTE, 게인, 모니터링 설정 때문에 캡처는 되지만 무음처럼 보일 수 있습니다.
- 여러 USB 오디오 장치가 연결되면 ALSA 카드 번호가 바뀔 수 있으므로 카드 번호만 믿는 설정은 피해야 합니다.

## 진행 기록

- `docs/02-client-direction.md`를 추가해 클라이언트 초기 목표, 마이크 기준, ALSA 캡처 방향, UDP 전송 방향, 수신기 주소 설정, 자동 검색 확장 후보, 검증 순서를 정리했습니다.
- `README.md`의 문서 목록에 클라이언트 방향성 문서를 추가했습니다.
- 사용자의 진행 지시에 따라 `client/`에 C++ 클라이언트 초기 구현을 추가했습니다.
- `client/src/main.cpp`는 설정 파일을 읽고 ALSA에서 signed 16-bit little endian PCM을 캡처한 뒤 UDP 패킷으로 송신합니다.
- `client/CMakeLists.txt`, `client/client.conf.example`, `client/README.md`를 추가했습니다.
- `docs/02-client-direction.md`를 현재 구현된 40바이트 UDP 헤더 형식에 맞춰 갱신했습니다.
- 로컬 PowerShell에는 `cmake`와 `g++`가 없고, WSL Ubuntu에도 빌드 도구와 ALSA 개발 패키지가 없어 실제 컴파일은 수행하지 못했습니다.
- 실제 빌드 검증은 Orange Pi 또는 ALSA 개발 패키지가 설치된 Linux 환경에서 수행해야 합니다.
- 사용자 추가 기준에 따라 초기 단일 UDP 포트를 `4860`으로 변경했습니다.
- 여러 포트가 필요할 경우 `4800-5000` 범위 안에서 배정하는 방향을 문서에 반영했습니다.

## 완료 요약

- 클라이언트 방향성 문서를 추가하고 README 문서 목록에 연결했습니다.
- Orange Pi용 최소 C++ 클라이언트 구조를 추가했습니다.
- 첫 버전은 단일 USB 마이크, 단일 Mac 수신기, 고정 설정 파일, UDP PCM 송신 경로에 집중합니다.
- 자동 검색, 압축, 다중 송신기, 지연 시간 최적화는 이후 확장 후보로 남겼습니다.