feat: add physically explicit narrowband MUSIC

apps/acoustic-camera/README.md

@@ -22,6 +22,9 @@ DAS·DAS-PHAT·GCC-PHAT 위치추정으로 주파수 대역별 acoustic map과 g
 3. 상단 작업 순서에서 입력·설정 상태를 확인한 뒤 Snapshot 카드의 **▶ Snapshot 실행**을 누릅니다.
 4. 완료 후 overlay, 위치 오차와 timing을 확인하고 **Result JSON**을 저장합니다.
 
+MUSIC은 현재 장면 제목 옆 **MUSIC 빠른 예제 → ▶ Snapshot 실행** 두 단계로 확인할 수 있습니다.
+12채널 배열, 1.125 kHz 단일 FFT-grid 가설과 Fixed K=1 Experiment가 함께 열립니다.
+
 이동 장면을 바로 보려면 Moving 카드에서 **이동 예제 열기 → Map 준비 → 재생** 순서로 누릅니다.
 이동 예제는 24×18 grid와 2 Hz map rate를 사용해 CPU fallback에서도 준비량을 줄였습니다.
 
@@ -34,11 +37,12 @@ DAS·DAS-PHAT·GCC-PHAT 위치추정으로 주파수 대역별 acoustic map과 g
 3. **Experiment**: 선택 사항인 `.experiment.json`
 4. **Assets**: Scene이 참조하는 원본 이미지와 오디오
 
-Scene을 불러오면 현재 Experiment의 `sceneId`와 scan plane을 Scene에 맞추고 기존 asset 연결을
-해제합니다. Array를 불러오면 현재 Experiment의 `arrayId`를 맞춥니다. 별도 Experiment는 어느
-시점에 불러와도 문서 자체를 먼저 검증한 뒤 `sceneId`와 `arrayId`를 현재 열린 Scene·Array에
-자동으로 연결합니다. 이후 현재 입력을 기준으로 관계 검증을 다시 수행하므로 원래 참조 ID가 달라도
-연결 대기로 실행이 막히지 않으며, 모든 분석 대역은 보존됩니다. Nyquist 위 tone·band는 ideal ADC
+Scene을 불러오면 scan plane/bounds를 새 Scene에 맞추고 기존 asset 연결을 해제하지만
+Experiment의 `sceneId` provenance label과 분석 대역은 보존합니다. Array를 불러와도
+`arrayId` label을 덮어쓰지 않습니다. 별도 Experiment는 어느 시점에 불러와도 문서 자체를
+먼저 검증하며 원래 `sceneId`/`arrayId`와 모든 분석 대역을 보존합니다. ID가 달라도 실행이
+막히지 않고 현재 열린 Scene·Array가 실제 입력이 되며, Result에 그 실제 ID와 hash가 기록됩니다.
+Nyquist 위 tone·band는 ideal ADC
 alias로 실행되고, 잘못된 scan 범위 같은 실제 관계 오류는 그대로 거부됩니다.
 
 Scene JSON에는 원본 파일 byte가 없습니다. **Assets**에서 Builder에 사용한 파일을 다시 선택하면
@@ -53,7 +57,7 @@ Camera가 SHA-256을 계산해 manifest에 연결합니다. 같은 이름이라
 
 ## 위치 추정 알고리즘과 Backend
 
-**분석 설정 → 위치 추정 알고리즘**에서 다음 세 구현을 선택합니다.
+**분석 설정 → 위치 추정 알고리즘**에서 다음 네 구현을 선택합니다.
 
 - **DAS**: 채널 진폭과 위상을 유지해 coherent sum power를 계산하는 기준선입니다. CPU와 WebGPU를
   지원하고 `rawMap.scale`은 `power`입니다.
@@ -62,13 +66,20 @@ Camera가 SHA-256을 계산해 manifest에 연결합니다. 같은 이름이라
 - **GCC-PHAT**: 기준 마이크와 나머지 마이크의 PHAT 상관에서 기하학적 TDOA를 평가합니다. 현재
   CPU 전용이므로 Auto는 CPU를 선택하고 **WebGPU 강제**는 선택할 수 없습니다. 각 band가 8개
   미만의 FFT bin을 포함하면 협대역 상관이 불안정할 수 있다는 경고가 표시됩니다.
+- **MUSIC**: CPU에서 표준 Schmidt narrowband MUSIC의 근거리 구면파 direct-path manifold를
+  계산합니다. Fixed K 또는 Wax–Kailath AIC/MDL을 선택하며, band마다 아날로그 FFT-grid 가설
+  하나만 허용합니다.
 
-PHAT score는 위치 확률이나 음향 power가 아닙니다. 세 알고리즘 모두 같은 scan grid에 응답 map을
+PHAT score는 위치 확률이나 음향 power가 아닙니다. 네 알고리즘 모두 같은 scan grid에 응답 map을
 만들지만, 진폭 보존 여부와 실패 양상이 다르므로 같은 Scene·Array·band로 비교하세요.
 GCC-PHAT raw score는 pair·band coefficient·IFFT 크기를 정규화한 0–1 양의 상관 응답이라 scan
 범위나 마이크 수에 따른 단순 scale 변화는 피하지만, 확률이나 다른 알고리즘과 공통인 confidence는
 아닙니다.
 
+MUSIC raw `q`는 noise-subspace projection이고 작은 값이 좋은 가설입니다. 화면 heatmap과 peak
+threshold는 reciprocal `P=1/q`의 scan 내 표시값 `P/Pmax`를 사용합니다. 둘 다 확률·confidence
+또는 신뢰구간이 아닙니다. flat `q`는 위치를 임의 선택하지 않고 식별 불가로 표시합니다.
+
 - **Auto (GPU→CPU)**: 권장. WebGPU를 먼저 시도하고 adapter/device 부재나 지원되는 장치 한계가
   있으면 CPU로 계속합니다. 라이브 준비에서는 첫 fallback 뒤 남은 frame이 같은 CPU analysis
   plan을 재사용하므로 GPU 실패를 매 frame 반복하지 않습니다. GCC-PHAT에서는 **Auto (CPU)**로
@@ -129,6 +140,8 @@ cache를 표시하고 알고리즘별 위치추정 비용을 다음처럼 분리
 - DAS/DAS-PHAT: scan point × microphone × STFT frame × 선택 bin의 complex MAC
 - GCC-PHAT: 기준 마이크 pair별 two-pass cross-spectrum, pair × band inverse FFT와
   scan point × pair × band correlation lookup
+- MUSIC: hypothesis별 Float64 covariance, Hermitian Jacobi EVD와
+  scan point × microphone × noise-subspace projection
 
 이는 구현 연산 횟수이지 실행 시간 예측값은 아닙니다. scene 길이, microphone 수, FFT/hop,
 band 수와 폭, grid 및 CPU/GPU에 따라 실제 시간이 달라집니다.
@@ -138,6 +151,12 @@ band 수와 폭, grid 및 CPU/GPU에 따라 실제 시간이 달라집니다.
 DAMAS와 CLEAN-SC 후처리는 아직 구현하지 않았으며, 실행할 수 없는 비활성
 항목은 Camera UI에서 제거했습니다. Result의 `processedMaps` 계약만 향후 확장을 위해 남아 있습니다.
 
+MUSIC에서는 band가 사용자가 지정한 아날로그 FFT-grid center 하나만 포함해야 합니다. 같은 ADC
+bin으로 접히는 서로 다른 Nyquist-zone 가설은 별도 band로 만드세요. spectral inversion이면
+analog carrier 크기의 공간 위상을 유지하면서 positive-bin coefficient와 calibration/manifold
+전체를 켤레 방향으로 계산합니다. signed ADC alias는 orientation만 정합니다. Scene의 tone
+truth로 alias order를 자동 선택하지 않으며 DC/Nyquist edge는 거부합니다.
+
 **Peak 검출 임계값 (%)**은 최강 local peak의 map 값에 대한 상대 임계값이며 Experiment JSON에
 저장됩니다. 기본 25%에서 약한 두 번째 음원이 빠지면 10–20%로 낮추세요. 낮은 값은 더 약한 후보를
 살리는 대신 sidelobe를 음원으로 잘못 고를 가능성도 높입니다. 같은 대역의 두 음원이 알고리즘의
@@ -161,7 +180,8 @@ basin을 사용합니다. 선택한 표준 방식과 threshold는 Experiment와
   남습니다.
 - 입력을 바꾼 뒤 화면에 남은 결과는 이전 실행 snapshot이며 UI가 이전 설정 결과임을 표시합니다.
 - Camera에서 거리·음속·seed를 바꾼 Scene과 scan·STFT·band를 바꾼 Experiment는 우측의 각
-  **JSON 저장** 버튼으로 보존할 수 있습니다.
+  **JSON 저장** 버튼으로 보존할 수 있습니다. Experiment의 `sceneId`/`arrayId`는 provenance
+  label이며, 현재 입력에 다시 연결한 뒤 실제 실행 ID와 hash가 Result에 기록됩니다.
 - **전체 기록 JSON**은 세션에 남은 배열·알고리즘·backend 비교 요약을
   `micarrsim.comparison-history` 문서로 저장합니다.
 
@@ -220,8 +240,9 @@ sensitivity/phase/frequency-response calibration은 적용하지만 결과는
 실제 동기식 microphone `Float32Array`를 Scene 합성 없이 위치추정하려면
 [실시간 위치추정 코어 포팅](../../docs/realtime-porting.md)의
 `createLocalizationPlan`, `localizeMultichannel` 또는
-`createStreamingLocalizer`를 사용하세요. portable config의 `algorithm`으로 같은 세 위치추정을
-선택할 수 있습니다. 실시간성은 장치에서
+`createStreamingLocalizer`를 사용하세요. portable config의 `algorithm`으로 같은 네 위치추정을
+선택할 수 있습니다. MUSIC은 CPU 전용이며 fixed K 또는 엄격한 가정 아래 AIC/MDL을 사용합니다.
+실시간성은 장치에서
 `processingTimeMs <= deadlineMs`와 `deadlineMisses`·`droppedSamples`를
 측정해 판정해야 합니다.