mic/plans/b47aca02-f7bc-4df3-aba9-386f09d2e974.md

작업 플랜

• UUID: b47aca02-f7bc-4df3-aba9-386f09d2e974
• 작업자: Codex
• 생성 시각: 2026-06-02 15:55
• 요청 요약: Mac에서 실행할 서버 수신/믹서 준비

할 일

• 현재 요청 확인
• 필수 문서 확인
• 저장소 상태와 서버 관련 파일 목록 확인
• 클라이언트 방향성 문서 확인
• 서버 준비 범위 정리
• 서버 방향성 문서 작성
• 서버 폴더 README와 설정 예시 추가
• README 문서 목록 갱신
• 결과 검증
• 완료 내용 정리

현재 확인 내용

• 현재 브랜치는 main이며 원격 origin/main과 같은 위치입니다.
• 작업 시작 시점의 server/ 디렉터리는 비어 있었습니다.
• 작업 시작 시점에 사용자 또는 이전 작업으로 보이는 변경사항이 있습니다.
  • README.md 수정
  • client/ 추가
  • docs/02-client-direction.md 추가
  • plans/4b3baabc-2767-4470-bdd9-ea310403f684.md 추가 또는 수정
• 사용자 변경사항은 되돌리지 않고 서버 준비 내용만 추가합니다.
• 프로젝트 규칙상 사용자가 계획을 확정하고 실행을 지시하기 전까지 C++ 소스 코드, 빌드 시스템, 테스트 코드, 프로토콜 세부 구현은 만들지 않습니다.

서버 준비 초안

목표

Mac에서 실행되는 서버가 Orange Pi Zero 2W 클라이언트가 보낸 UDP 오디오 패킷을 수신하고, 단일 송신기의 PCM 오디오를 재생할 수 있는 최소 경로를 준비합니다.

초기 목표는 믹싱 기능 완성이 아니라 Mac에서 실제 소리가 나온다는 것을 확인하는 것입니다.

대상 환경

• 실행 장비: Mac
• 역할: UDP 수신기 및 이후 믹서
• 언어: C++
• 초기 실행 형태: 터미널에서 실행하는 headless/CLI 프로그램 후보

우선 확인할 항목

• Mac 로컬 IP 확인
• Orange Pi와 Mac이 같은 Wi-Fi 네트워크에서 통신 가능한지 확인
• Mac 방화벽 또는 네트워크 권한 확인
• UDP 포트 수신 가능 여부 확인
• 수신한 PCM 프레임을 Mac 오디오 출력 장치로 재생 가능한지 확인

라이브러리 후보

• 네트워크 수신: POSIX UDP socket
• 오디오 출력: PortAudio, RtAudio, Core Audio 후보
• 빌드: CMake 후보, 단 사용자의 구현 승인 전에는 생성하지 않음

초기 수신 방식 후보

• 고정 UDP 포트에서 단일 클라이언트 패킷 수신
• 압축 없는 PCM 16-bit mono payload 처리
• 샘플레이트 후보: 48 kHz
• 프레임 크기 후보: 10 ms
• 서버 지정 패킷 헤더로 sender_id, session_id, sequence, capture_sample_index, timestamp, payload size 확인

검증 방법 후보

• Mac에서 UDP 포트 바인딩 확인
• Orange Pi 또는 로컬 도구에서 테스트 UDP 패킷 수신 확인
• 클라이언트가 보낸 PCM 프레임 수신 확인
• Mac 기본 출력 장치로 오디오 재생 확인
• 패킷 손실, 순서 역전, 수신 지연을 로그로 확인

메모

현재 단계에서는 코드나 빌드 파일을 만들지 않습니다. 다음 단계는 서버 방향성 문서를 정리하고, 사용자가 서버 구현 계획을 승인하면 C++ 서버 구현 계획을 확정하는 것입니다.

진행 기록

• docs/03-server-direction.md를 추가해 Mac 서버의 초기 목표, UDP 수신 방향, 오디오 출력 후보, 패킷 포맷 후보, 지터/버퍼링 방향, 검증 순서를 정리했습니다.
• server/README.md를 추가해 서버 폴더의 현재 목적과 구현 전 기준을 정리했습니다.
• server/server.conf.example을 추가해 초기 설정 후보를 기록했습니다.
• README.md의 문서 목록에 서버 방향성 문서를 추가했습니다.
• 현재 요청에서는 문서화와 설정 예시만 추가했고, C++ 소스 코드, 테스트 코드, 빌드 시스템은 생성하지 않았습니다.

완료 요약

• 서버 준비 문서와 서버 폴더 안내 파일을 추가했습니다.
• 사용자 요청에 따라 서버 초기 포트를 4860, 오디오 포맷 후보를 48 kHz / 16-bit / mono / 10 ms로 기록했습니다.
• 서버 기준으로는 포트 1개를 우선 사용하고, 여러 마이크는 송신기 식별자와 sequence, timestamp로 구분하는 방향을 기록했습니다.
• 서버 지정 패킷 헤더 v1 후보와 miniaudio 우선 후보를 반영했습니다.
• 송신기별 음량 조절은 초기 범위에서 제외했습니다.
• 서버 구현 전에는 패킷 포맷, 오디오 출력 라이브러리, 빌드 방식, 검증 절차를 사용자가 승인해야 합니다.