docs: guide audio localization and live playback

README.md

@@ -1,8 +1,9 @@
 # micarrsim
 
 192채널 MEMS 마이크 배열의 배치와 자유음장 DAS 음향 영상을 비교하는 로컬 브라우저
-시뮬레이터입니다. Dataset Builder에서 재현 가능한 음향 장면을 만들고 Acoustic Camera에서
-CPU 또는 WebGPU로 배열 응답, acoustic map과 위치 검출 지표를 계산합니다.
+시뮬레이터입니다. Dataset Builder에서 녹음 파일·합성 신호와 이동 경로를 포함한 재현 가능한
+음향 장면을 만들고 Acoustic Camera에서 CPU 또는 WebGPU로 배열 응답, acoustic map과 위치 검출
+지표를 계산하거나 이동 장면을 시간축으로 재생합니다.
 
 별도 프로그램이나 패키지를 설치하지 않습니다. 모든 앱과 계산은 이 저장소와 브라우저 안에서
 실행됩니다.
@@ -51,15 +52,26 @@ powershell.exe -NoLogo -NoProfile -ExecutionPolicy Bypass -File .\scripts\serve.
 실제 완료 시간은 브라우저와 장치에 따라 다릅니다. CPU fallback에서는 WebGPU보다 오래 걸릴 수
 있습니다.
 
+### 이동 음원 바로 보기
+
+1. Acoustic Camera에서 **이동 예제**를 누릅니다.
+2. **라이브 준비**를 눌러 2 Hz acoustic map을 계산합니다.
+3. **재생**을 누르거나 시간 slider를 움직여 음원과 heatmap의 이동을 확인합니다.
+
+이 기능은 trajectory가 있는 합성 Scene의 준정적 시간창 재생입니다. 실제 192채널 마이크 장치에서
+들어오는 스트림을 캡처하는 기능은 아닙니다.
+
 ## 내 장면으로 전체 흐름 실행하기
 
 ### 1. Dataset Builder에서 Scene 만들기
 
 1. 시작 화면에서 **Dataset Builder**를 엽니다.
 2. 선택적으로 배경 이미지와 오디오를 추가합니다.
-3. 음원을 추가해 canvas 또는 x/y/z 입력으로 위치를 정하고, tone·noise·audio asset과 ambient를
-   설정합니다.
-4. 상태가 **저장 가능한 장면**이면 **Scene JSON 저장**을 누릅니다.
+3. 녹음 파일은 **+ 오디오 파일 음원** 한 번으로 asset과 source를 함께 만들 수 있습니다. 합성
+   음원은 별도 버튼으로 추가합니다.
+4. canvas 또는 x/y/z 입력으로 위치를 정하고 tone·noise·audio asset과 ambient를 설정합니다.
+5. 움직이는 음원은 **시간에 따라 음원 이동**을 켜고 keyframe과 경로 미리보기 시간을 편집합니다.
+6. 상태가 **저장 가능한 장면**이면 **Scene JSON 저장**을 누릅니다.
 
 **Preview WAV 저장**은 source와 ambient를 공간 정보 없이 하나의 mono channel로 합친 청취
 확인용 파일입니다. 192채널 마이크 신호나 beamforming 결과가 아닙니다.
@@ -106,6 +118,31 @@ WebGPU 경로도 신호 합성과 STFT 일부는 CPU에서 수행합니다. grid
 100×100은 4배, 200×200은 16배입니다. 처음에는 50×50을 사용하고 해상도가 필요할 때만 높이세요.
 실행 시간은 microphone 수, scene 길이, FFT, 대역 폭과 장치에 함께 좌우됩니다.
 
+## 위치 추정, 빔 분포와 복수 음원
+
+DAS 출력은 각 scan point의 상대 acoustic power map이며 위치 확률분포가 아닙니다. Camera는 map의
+local peak를 위치 후보로 표시합니다. **빔 분포**를 켜면 각 peak의 연결된 half-power lobe에 대해
+power 가중 공분산을 계산해 1× RMS 점선과 2× RMS 영역을 그립니다. Gaussian의 등고선처럼 보일 수
+있지만 통계적으로 보정된 Gaussian, 신뢰구간 또는 발생 확률은 아닙니다.
+
+복수 음원은 각각 별도 local peak가 남을 만큼 공간적으로 분리되고 선택 대역에 에너지가 있어야
+검출됩니다. **Peak 검출 임계값 (%)**은 최강 peak 대비 후보의 최소 power입니다. 기본 25%에서 약한
+두 번째 음원이 빠지면 10–20%로 낮출 수 있지만 sidelobe 오검출도 늘어납니다. 서로 같은 대역에서
+main lobe보다 가깝거나 gain 차이가 큰 음원은 conventional DAS의 물리·알고리즘 한계 때문에
+threshold만으로 분리되지 않을 수 있습니다.
+
+## 이동 음원 라이브의 동작
+
+Builder의 trajectory는 Scene 시작 기준 절대 시간의 keyframe 사이를 직선 보간합니다. Camera는
+장면을 sample 경계에 맞춘 짧은 시간창으로 나누고, 각 창 중앙의 음원 위치에서 tone 위상, noise
+index와 audio asset 재생 위치가 이어지도록 신호를 합성합니다. 계산된 map 사이에서는 heatmap을
+보간하고 ground-truth 위치는 연속 보간합니다.
+
+- Map rate: 초당 분석 map 목표 수. 높을수록 움직임이 세밀하지만 준비 시간이 늘 수 있습니다.
+- 라이브 미리보기 상한: 48 maps, map당 최대 2,500 scan points
+- 모델: 준정적 위치 변화이며 Doppler와 창 내부의 연속 전파 경로 변화는 포함하지 않음
+- 실제 장치: 물리 192채널 capture/stream gateway는 하드웨어 형식이 정해진 뒤 별도 adapter가 필요
+
 ## Result JSON
 
 Result JSON은 계약 버전 `1.0.0`의 `micarrsim.result` 문서입니다. 주요 내용은 다음과 같습니다.
@@ -117,6 +154,7 @@ Result JSON은 계약 버전 `1.0.0`의 `micarrsim.result` 문서입니다. 주
 - 주파수 대역별 선형 power `rawMap`, 표시용 `displayMap`, 검출 `peaks`
 - 위치 오차, precision/recall, truth 반경 내 energy, peak-to-sidelobe, main-lobe 폭을 계산하기
   위한 평가 파라미터와 `metrics`
+- peak별 half-power 공분산과 RMS ellipse를 담은 `beamSpread` (`calibrated: false`)
 
 평가에서 tone source는 tone 주파수가 포함되는 band의 ground truth로만 사용합니다. Audio asset과
 noise source는 스펙트럼을 미리 알 수 없으므로 모든 band의 ground truth로 취급합니다. 이 가정은
@@ -143,6 +181,12 @@ Camera의 **비교 배열** 선택으로 두 fixture를 같은 scene과 experime
 
 ## 테스트와 benchmark
 
+최상위 폴더에서 자동 서버·headless 브라우저·정리까지 한 번에 실행하려면 다음을 사용합니다.
+
+```bat
+test.cmd
+```
+
 서버를 실행한 뒤 다음 주소를 브라우저에서 엽니다.
 
 - 전체 browser test runner: <http://127.0.0.1:4173/tests/>