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

작업 플랜

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

할 일

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

현재 확인 내용

• 현재 브랜치는 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 송신 경로에 집중합니다.
• 자동 검색, 압축, 다중 송신기, 지연 시간 최적화는 이후 확장 후보로 남겼습니다.