docs: guide audio localization and live playback

docs/data-contracts.md

@@ -34,6 +34,17 @@ Camera는 사용자가 다시 선택한 파일을 SHA-256으로 계산해 같은
 Builder가 내보낸 Scene JSON과 사용한 원본 이미지·오디오는 함께 보관해야 한다. Preview WAV는
 scene recipe를 mono로 합친 청취 확인용 파일이며 마이크 배열의 192채널 수신 신호가 아니다.
 
+## 이동 음원 trajectory
+
+Scene source의 선택적 `trajectory`는 2–4,096개의 `{ time, position }` keyframe 배열이다. `time`은
+Scene 시작 기준 절대 초이며 0 이상 `scene.duration` 이하에서 엄격히 증가해야 한다. `position`은
+정적 source와 같은 `[x, y, z]` m 좌표다. keyframe 사이 위치는 선형 보간하며, 첫 keyframe은
+호환용 `source.position`과 같은 시작 위치로 Builder가 유지한다.
+
+Camera 라이브 미리보기는 sample 경계에 맞춘 시간창 중앙에서 trajectory 위치를 평가한다. 짧은
+창으로 Scene 시간을 다시 기준화해도 tone 위상, noise sample index와 audio asset 재생 위치는 원래
+절대 시간에 이어진다. 이는 준정적 근사이며 Doppler를 계약하지 않는다.
+
 ## 오디오와 map 정규화
 
 `scene.mix.normalization`은 마이크 신호 합성 전에 적용할 오디오 mix 정책이다. `none`은 원래
@@ -47,10 +58,18 @@ raw DAS map을 덮어쓰지 않는다.
 map은 row-major 배열이다. 첫 행은 `yMax`, 마지막 행은 `yMin`, 각 행은 `xMin`에서 `xMax`
 방향이다. `values.length`는 반드시 `rows × columns`와 같아야 한다.
 
+Experiment의 선택적 `evaluation.detectionThresholdRatio`는 최강 local peak power에 대한 검출
+임계 비율이며 `0 < ratio <= 1`이다. 생략된 이전 문서를 Camera에서 열면 기본값 `0.25`를 적용하며,
+Experiment JSON을 다시 저장하면 이 값이 명시된다. 값을 낮추면 약한 peak 후보를 포함하지만
+sidelobe false positive도 늘 수 있다.
+
 ## Result 평가 정보
 
 각 band의 `peaks`는 위치와 power 값, 선택적 `sourceId`, `localizationErrorM`,
-`localizationErrorPixels`를 저장한다. `metrics`에는 다음 유한값만 기록한다.
+`localizationErrorPixels`, `beamSpread`를 저장한다. `beamSpread`는 선택 peak를 포함하는 연결된
+half-power 성분의 power 가중 centroid·공분산과 major/minor RMS 반경·각도다. `calibrated`는 현재
+항상 `false`이며 확률분포, Gaussian 신뢰구간 또는 통계적 위치 불확실성으로 해석하지 않는다.
+`metrics`에는 다음 유한값만 기록한다.
 
 - `peakToSidelobeDb`
 - `energyInsideTruthRatio`

docs/execution-plan.md

@@ -3,7 +3,8 @@
 > 구현 상태 · 2026-08-28
 >
 > 단계 0–4는 완료되어 설치 없는 브라우저 앱, CPU/WebGPU DAS, Builder→Camera asset 재연결,
-> 배열 비교, 평가·Result 내보내기와 53개 자동 테스트로 검증했다. 단계 5는 향후 고도화 범위다.
+> 임의 오디오·이동 trajectory, 빔 분포·복수 peak 감도, 라이브 시간축 재생, 배열 비교와
+> Result 내보내기를 71개 자동 테스트로 검증했다. 단계 5는 실제 장치·공간 모델 고도화 범위다.
 
 ## 1. 목표와 성공 기준
 
@@ -133,6 +134,7 @@ flattening이 모델 타당성을 훼손하는지 청취 및 spectrum 통계로
 ### 단계 2 — Dataset Builder · 완료
 
 - 이미지와 음원 파일 불러오기, 위치·시간·gain 편집, ambient mix와 미리 듣기
+- 파일 선택 한 번으로 audio asset source 생성, source별 trajectory keyframe 편집·미리보기
 - deterministic seed, clipping 경고, Scene JSON과 mono Preview WAV 내보내기
 - synthetic tone/noise fixture와 로컬 asset manifest 경계 구현
 
@@ -151,6 +153,8 @@ flattening이 모델 타당성을 훼손하는지 청취 및 spectrum 통계로
 - scene/ground truth/acoustic overlay, 배열 geometry, parameter panel 구현
 - 결과 metric, 실행 환경, 입력 hash와 map 내보내기
 - 복수 음원·다중 대역 표시와 실험 preset 비교
+- peak별 half-power 공분산/RMS 빔 분포와 재현 가능한 검출 임계값
+- sample-aligned 준정적 시간창 분석, bounded map 계획과 이동 장면 재생
 
 완료 조건: 사용자가 코드 수정 없이 배열 JSON 두 개를 같은 장면에서 비교할 수 있다.
 
@@ -158,6 +162,7 @@ flattening이 모델 타당성을 훼손하는지 청취 및 spectrum 통계로
 
 - 라이선스 검토를 통과한 DCASE/MIMII adapter와 batch workflow 추가
 - microphone calibration·noise 모델 검토
+- 실제 192채널 장치의 channel/clock/sample 형식이 정해진 뒤 capture·stream adapter 추가
 - 필요 시 DAMAS/CLEAN-SC를 플러그인형 후처리로 추가
 - image-source method 또는 room impulse response 기반 잔향 모듈 추가
 
@@ -167,8 +172,9 @@ flattening이 모델 타당성을 훼손하는지 청취 및 spectrum 통계로
 
 - WebGPU 미지원/장치 한도: 시작 시 capability를 표시하고 CPU fallback 및 grid 상한을 둔다.
 - 좌표·phase 부호 오류: analytic tone test와 배열 대칭성 test를 먼저 만든다.
-- 브라우저 메모리: 현재 전체 192채널 signal buffer에 512 MiB 한도를 적용한다. 장시간 입력은
-  향후 chunk/STFT streaming backend로 확장한다.
+- 브라우저 메모리: snapshot은 전체 192채널 signal buffer에 512 MiB 한도를 적용하고, 이동
+  미리보기는 최대 48개·2,500 points의 짧은 시간창으로 제한한다. 실제 장시간 capture는 향후
+  chunk/STFT streaming backend로 확장한다.
 - 데이터셋 부적합/라이선스: 로컬 asset 계약을 유지하고 synthetic fixture를 기본 test 입력으로
   쓴다. 실제 데이터 adapter는 단계 5의 라이선스 검토 뒤 추가한다.
 - 실제 AC와 simulation gap: 감도, 위상, 위치 오차를 이후 calibration/noise model로 주입 가능하게 한다.
@@ -183,7 +189,13 @@ flattening이 모델 타당성을 훼손하는지 청취 및 spectrum 통계로
 - [x] WGSL kernel, CPU/GPU 비교와 50²/100²/200² benchmark
 - [x] scene canvas, array view, parameter controls와 Result export
 - [x] Builder→Camera SHA-256 asset 재연결 왕복 테스트
+- [x] 임의 오디오 source 원클릭 생성과 codec 안내
+- [x] 이동 trajectory 계약·편집·시간창 합성·Camera 라이브 재생
+- [x] 비확률 beam spread RMS contour와 Result export
+- [x] 복수 음원용 Experiment peak 검출 감도
+- [x] `test.cmd` one-command headless browser 검증
 - [ ] DCASE/MIMII 라이선스 검토와 adapter
+- [ ] 실제 192채널 capture/stream adapter
 - [ ] 잔향·calibration·noise model
 - [ ] DAMAS/CLEAN-SC 후처리
 

docs/index.html

@@ -16,6 +16,7 @@
       <a class="guide-brand" href="/">← micarrsim 홈</a>
       <nav aria-label="문서 목차">
         <a href="#quick-start">빠른 시작</a>
+        <a href="#moving-live">이동 라이브</a>
         <a href="#full-workflow">내 데이터</a>
         <a href="#results">결과 해석</a>
         <a href="#troubleshooting">문제 해결</a>
@@ -52,16 +53,34 @@
         </div>
       </section>
 
-      <section class="guide-section" id="full-workflow">
+      <section class="guide-section" id="moving-live">
         <div class="section-number">02</div>
+        <div>
+          <p class="eyebrow">Moving-source demo</p>
+          <h2>이동 음원을 바로 재생하기</h2>
+          <ol class="guide-steps">
+            <li><a href="/apps/acoustic-camera/">Acoustic Camera</a>에서 <strong>이동 예제</strong>를 누릅니다.</li>
+            <li><strong>라이브 준비</strong>를 눌러 기본 2 Hz map을 계산합니다.</li>
+            <li><strong>재생</strong>을 누르거나 시간 slider를 움직입니다.</li>
+          </ol>
+          <aside class="callout">
+            짧은 시간창마다 계산한 heatmap과 trajectory 위치를 보간하는 합성 장면 미리보기입니다.
+            실제 192채널 마이크 스트림을 녹음하는 기능은 아닙니다.
+          </aside>
+        </div>
+      </section>
+
+      <section class="guide-section" id="full-workflow">
+        <div class="section-number">03</div>
         <div>
           <p class="eyebrow">5분 전체 흐름</p>
           <h2>내 장면을 만들고 Camera에서 실행하기</h2>
           <ol class="guide-steps">
             <li>
-              <a href="/apps/dataset-builder/">Dataset Builder</a>에서 이미지와 오디오를
-              선택하고 음원 위치, gain, 시간, ambient를 설정합니다.
+              <a href="/apps/dataset-builder/">Dataset Builder</a>에서 <strong>+ 오디오 파일 음원</strong>
+              또는 합성 음원을 추가하고 위치, gain, 시간과 ambient를 설정합니다.
             </li>
+            <li>움직이는 source는 <strong>시간에 따라 음원 이동</strong>을 켜고 keyframe을 편집합니다.</li>
             <li><strong>Scene JSON 저장</strong>을 누르고 사용한 원본 파일과 함께 보관합니다.</li>
             <li><strong>Scene 저장 후 Camera 열기</strong>를 누릅니다.</li>
             <li>
@@ -91,7 +110,7 @@
       </section>
 
       <section class="guide-section">
-        <div class="section-number">03</div>
+        <div class="section-number">04</div>
         <div>
           <p class="eyebrow">Compute backend</p>
           <h2>속도와 격자 선택</h2>
@@ -109,23 +128,33 @@
             먼저 50×50을 권장합니다. 100×100은 4배, 200×200은 16배의 scan point를 계산합니다.
             실행 중에는 취소할 수 있으며, 취소하거나 실패해도 이전 완료 결과는 유지됩니다.
           </p>
+          <p class="guide-copy">
+            복수 음원에서 약한 peak가 빠지면 <strong>Peak 검출 임계값</strong>을 기본 25%에서
+            10–20%로 낮춰 보세요. 약한 후보와 함께 sidelobe 오검출도 늘 수 있으며, main lobe보다
+            가까운 같은 대역 음원은 conventional DAS에서 하나로 합쳐질 수 있습니다.
+          </p>
         </div>
       </section>
 
       <section class="guide-section" id="results">
-        <div class="section-number">04</div>
+        <div class="section-number">05</div>
         <div>
           <p class="eyebrow">Result JSON</p>
           <h2>무엇이 저장되나요?</h2>
           <dl class="result-list">
             <div><dt>rawMap / displayMap</dt><dd>선형 power 원본과 화면 표시용 acoustic map</dd></div>
             <div><dt>peaks</dt><dd>검출 위치, source 매칭, m·pixel 위치 오차</dd></div>
+            <div><dt>beamSpread</dt><dd>half-power lobe의 power 가중 공분산과 1× RMS ellipse</dd></div>
             <div><dt>metrics</dt><dd>energy 비율, precision/recall, sidelobe, main-lobe 폭</dd></div>
             <div><dt>evaluation</dt><dd>검출 threshold, 반경, tolerance 등 지표 계산 조건</dd></div>
             <div><dt>timing / environment</dt><dd>backend, grid·scan 범위, 장치 정보와 구간별 시간</dd></div>
             <div><dt>inputHash</dt><dd>Array·Scene·Experiment 입력을 묶은 SHA-256 재현성 식별자</dd></div>
             <div><dt>comparison-history</dt><dd>세션의 배열별 시간·위치 오차·PSR 요약을 한 번에 저장</dd></div>
           </dl>
+          <aside class="callout">
+            화면의 <strong>빔 분포</strong> 1×/2× RMS contour는 acoustic power lobe의 모양입니다.
+            위치 확률, Gaussian 신뢰구간 또는 보정된 측정 불확실성이 아닙니다.
+          </aside>
           <aside class="callout">
             평가는 tone 음원을 해당 주파수 대역이 tone 주파수를 포함할 때만 정답으로 사용합니다.
             noise와 asset 음원은 현재 모든 대역의 정답으로 간주합니다. 녹음 파일의 실제 대역별
@@ -140,7 +169,7 @@
       </section>
 
       <section class="guide-section" id="troubleshooting">
-        <div class="section-number">05</div>
+        <div class="section-number">06</div>
         <div>
           <p class="eyebrow">Troubleshooting</p>
           <h2>막혔을 때 확인할 것</h2>
@@ -164,18 +193,26 @@
             <summary>WebGPU가 없거나 실행이 너무 느립니다.</summary>
             <p>Backend를 Auto 또는 CPU로 두고 50×50 grid부터 실행하세요. 최신 Chrome/Edge와 그래픽 드라이버도 확인하세요.</p>
           </details>
+          <details>
+            <summary>두 번째 음원을 찾지 못합니다.</summary>
+            <p>두 음원이 같은 주파수 대역인지 확인하고 Peak 검출 임계값을 낮추세요. gain 차이, main-lobe 폭보다 짧은 거리, grid 간격과 sidelobe는 threshold만으로 해결되지 않을 수 있습니다.</p>
+          </details>
+          <details>
+            <summary>라이브 준비 버튼이 비활성화됩니다.</summary>
+            <p>Scene에 시간 순서가 올바른 trajectory keyframe이 두 개 이상 있어야 합니다. Builder에서 시간에 따라 음원 이동을 켜거나 Camera의 이동 예제를 사용하세요.</p>
+          </details>
         </div>
       </section>
 
       <section class="guide-section">
-        <div class="section-number">06</div>
+        <div class="section-number">07</div>
         <div>
           <p class="eyebrow">Scope & privacy</p>
           <h2>현재 모델의 범위</h2>
           <p class="guide-copy">
             micarrsim 1.0은 점 음원, 구면 감쇠·분수 지연을 쓰는 자유음장 모델과 conventional
             DAS를 제공합니다. 실내 반사·잔향, 실제 마이크 위치 오차와 비선형성, DAMAS,
-            CLEAN-SC, DCASE/MIMII 자동 adapter는 현재 범위에 포함되지 않습니다. 결과는 실제
+            CLEAN-SC, DCASE/MIMII 자동 adapter와 실제 192채널 capture stream은 현재 범위에 포함되지 않습니다. 결과는 실제
             장비의 절대 성능 보증이 아니라 같은 조건에서 배열을 비교하는 재현 가능한 기준입니다.
           </p>
           <p class="guide-copy">