web 작업 완

docs/03-server-direction.md

@@ -184,6 +184,7 @@ Wi-Fi UDP 오디오에서는 패킷 도착 간격이 흔들릴 수 있습니다.
 
 ```text
 listen_port = 4860
+web_port = 4861
 sample_rate = 48000
 channels = 1
 frame_ms = 10
@@ -194,6 +195,32 @@ audio_output = default
 
 설정 파일 형식은 단순 key-value 텍스트 형식을 후보로 둡니다. 자동 검색을 추가하더라도 고정 포트와 고정 설정 방식은 유지합니다.
 
+## Web UI 방향
+
+서버 제어와 상태 확인은 GUI 앱보다 Web UI를 우선합니다.
+
+현재 기준은 다음과 같습니다.
+
+```text
+web_host = 127.0.0.1
+web_port = 4861
+```
+
+Web UI는 같은 장비의 브라우저에서만 접근하는 localhost 전용으로 둡니다. 같은 Wi-Fi의 다른 장비에서 접속하는 기능은 현재 범위에 포함하지 않습니다. 별도 비밀번호나 인증은 두지 않고, `127.0.0.1` 바인딩으로 외부 노출을 막습니다.
+
+초기 Web UI는 다음 기능을 제공합니다.
+
+- UDP 수신 상태와 오류 표시
+- 오디오 출력 상태와 오류 표시
+- sender별 packet, dropped, out_of_order, last seen 표시
+- 전체 output mute
+- sender별 mute
+- sender별 gain
+- sender별 display name
+- 통계 reset
+
+UDP 바인딩 실패나 수신 오류가 발생하면 Web UI의 `udp_state`, `udp_error`에 표시하는 방향을 우선합니다.
+
 ## 검증 순서
 
 초기 검증은 다음 순서를 따릅니다.
@@ -214,8 +241,10 @@ audio_output = default
 현재 서버 구현 범위는 다음과 같습니다.
 
 - UDP `4860` 바인딩
+- localhost Web UI `127.0.0.1:4861`
 - 서버 지정 56바이트 패킷 헤더 v1 파싱
 - 단일 활성 `sender_id`의 `PCM_S16LE / mono / 48 kHz / 10 ms` payload 재생
 - sequence 기반 손실/순서 역전 로그 출력
+- Web UI를 통한 output mute, sender mute, sender gain, sender display name, 통계 reset
 
 다음 작업은 클라이언트 송신 패킷을 서버 지정 헤더 v1에 맞추고, 실제 송신기에서 들어온 오디오가 실행 OS의 기본 출력 장치로 재생되는지 확인하는 것입니다. 그 다음 서버 작업은 단일 활성 송신기 제한을 풀고, 2대에서 16대까지 송신기별 버퍼와 믹싱을 검증하는 방향으로 진행합니다.

plans/7aaa0cce-3da2-4ae4-8eda-c956e96c5af3.md

@@ -265,3 +265,14 @@ UDP 서버와 오디오 수신 경로 문제는 다음 상태로 표시합니다
 ```
 
 server가 UDP 바인딩에 실패하면 현재처럼 프로세스를 바로 종료할지, Web UI만 살려서 오류를 보여줄지는 구현 전에 결정해야 합니다. 사용자가 Web UI에서 UDP 서버 문제를 보길 원하므로, Web UI를 먼저 띄우고 UDP 수신을 별도 상태로 관리하는 구조를 우선 검토합니다.
+
+### 구현 진행 기록
+
+- `mic_server` 안에 localhost 전용 HTTP 서버를 추가했습니다.
+- Web UI는 `http://127.0.0.1:4861`에서 정적 HTML/CSS/JS로 제공합니다.
+- `GET /api/status`와 기본 제어 API를 추가했습니다.
+- Web UI에서 UDP 상태, 오디오 상태, sender별 packet/drop/out_of_order/last seen을 표시합니다.
+- Web UI에서 전체 output mute, sender mute, sender gain, sender display name, 통계 reset을 제어할 수 있게 했습니다.
+- UDP 수신 상태와 오디오 초기화 상태를 `udp_state`, `udp_error`, `audio_state`, `audio_error`로 공유 상태에 기록합니다.
+- `server/server.conf.example`에 `web_port = 4861`을 추가했습니다.
+- `server/CMakeLists.txt`의 `miniaudio.h` 탐색 경로를 Homebrew miniaudio 구조에 맞게 보강했습니다.

server/CMakeLists.txt

@@ -7,7 +7,11 @@ set(CMAKE_CXX_STANDARD_REQUIRED ON)
 set(CMAKE_CXX_EXTENSIONS OFF)
 
 find_package(Threads REQUIRED)
-find_path(MINIAUDIO_INCLUDE_DIR miniaudio.h REQUIRED)
+find_path(MINIAUDIO_INCLUDE_DIR
+    NAMES miniaudio.h
+    PATH_SUFFIXES include/miniaudio miniaudio
+    REQUIRED
+)
 
 add_executable(mic_server
     src/main.cpp

server/README.md

@@ -81,7 +81,44 @@ cmake --build build
 
 서버는 UDP `4860`을 열고 첫 번째 유효한 `sender_id`를 활성 송신기로 선택합니다. `sender_id`를 고정하고 싶으면 `server.conf.example`의 `sender_id` 값을 1 이상의 값으로 지정합니다.
 
-현재 구현은 단일 송신기의 `PCM_S16LE / mono / 48 kHz / 10 ms` payload를 기본 오디오 출력 장치로 재생합니다. 목표 규모는 2대에서 16대이지만, 여러 송신기 동시 믹싱과 송신기별 음량 조절은 아직 구현하지 않습니다.
+현재 구현은 단일 송신기의 `PCM_S16LE / mono / 48 kHz / 10 ms` payload를 기본 오디오 출력 장치로 재생합니다. 목표 규모는 2대에서 16대이지만, 여러 송신기 동시 믹싱은 아직 구현하지 않습니다.
+
+## Web UI
+
+서버는 실행 시 localhost 전용 Web UI를 함께 엽니다.
+
+```text
+http://127.0.0.1:4861
+```
+
+Web UI는 외부 장비에서 접속하지 못하도록 `127.0.0.1`에만 바인딩합니다. 별도 비밀번호나 인증은 현재 범위에서 사용하지 않습니다.
+
+현재 Web UI에서 확인할 수 있는 항목은 다음과 같습니다.
+
+- UDP 수신 상태와 마지막 오류
+- 오디오 출력 상태와 마지막 오류
+- 활성 sender 수와 `sender_id`
+- sender별 packet, dropped, out_of_order, last seen
+- 지터 버퍼 overflow와 underflow
+
+현재 Web UI에서 사용할 수 있는 기본 제어는 다음과 같습니다.
+
+- 전체 output mute
+- sender별 mute
+- sender별 gain
+- sender별 display name
+- 통계 reset
+
+내장 API는 초기 검증용으로 다음 경로를 제공합니다.
+
+```text
+GET  /api/status
+POST /api/output/mute
+POST /api/senders/{sender_id}/mute
+POST /api/senders/{sender_id}/gain
+POST /api/senders/{sender_id}/name
+POST /api/stats/reset
+```
 
 Windows에서는 네이티브 Windows 실행이 아니라 WSL2에서 실행합니다. WSL2에서 실제 소리를 들으려면 WSLg 또는 Linux 오디오 출력 경로가 동작해야 합니다.