Web Audio API

# WASM/Web Audio 기반 공간 음향 브라우저 확장프로그램 구현 계획서

---

## 1. 개요 및 목적

* **개요**: 웹 브라우저(Chrome/Edge 등)에서 재생되는 모든 오디오 스트림을 실시간으로 캡처하여, 사용자가 원하는 음향 효과를 적용하는 브라우저 확장프로그램을 구축합니다.
* **주요 기능**:
* **PEQ (Parametric Equalizer)**: 다중 밴드 이퀄라이저를 통한 음역대 정밀 제어
* **공간 모사 (Hall / Studio Reverb)**: IR(Impulse Response) 임펄스 응답 데이터를 활용한 컨볼루션 리버브 적용
* **3D 공간 음향 (Spatial Audio)**: HRTF 모델 기반의 3D 패닝 및 머리 방향(Orientation) 추적 공간감 형성


* **핵심 기술 스택**: Chrome Extension (Manifest V3), Web Audio API, Rust + WASM, Offscreen Document, Three.js (`spatial.ts` 3D UI 이식)

---

## 2. 시스템 아키텍처

```
[ 웹 탭 (YouTube / Spotify 등) ]
              │ (chrome.tabCapture)
              ▼
[ Extension Offscreen Document (오디오 파이프라인) ]
  ├── 1. MediaStreamSource (탭 오디오 캡처)
  ├── 2. PEQ Chain (BiquadFilterNode / Rust WASM)
  ├── 3. ConvolverNode (공간 모사 IR 데이터 적용)
  ├── 4. PannerNode / Binaural DSP (HRTF 기반 3D 공간 음향)
  └── 5. AudioContext.destination (최종 스피커 출력)
              ▲
              │ (chrome.runtime Message)
[ Extension Popup / Option UI (`spatial.ts` 기반 3D 시각화 패널) ]

```

---

## 3. 핵심 모듈별 구현 전략

### ① 오디오 캡처 & 백그라운드 처리 (Manifest V3)

* **Offscreen Document 활용**: Service Worker는 DOM 및 오디오 재생 환경을 제공하지 않으므로, 백그라운드 오디오 처리를 전용 Offscreen Document로 분리합니다.
* **`chrome.tabCapture`**: 활성화된 탭의 MediaStream ID를 추출한 뒤 Offscreen Document로 전달하여 `AudioContext`에 바인딩합니다.

### ② 오디오 처리 파이프라인 (Audio DSP)

* **PEQ (파라메트릭 EQ)**:
* 기본 5~10 밴드의 `BiquadFilterNode`를 직렬로 연결하여 구성
* 주파수(Frequency), Q값, 게인(Gain)을 UI 조작에 따라 실시간 업데이트


* **공간 모사 (Convolution Reverb)**:
* `ConvolverNode`를 사용하여 실제 음향 공간의 IR 음원(`.wav`) 적용
* 외부 오픈소스 IR 라이브러리(OpenAIR 등)에서 수집한 파일들을 확장프로그램 내 `assets/ir/` 경로에 패키징


* **3D 공간 음향 (Spatial Audio)**:
* `PannerNode`의 `panningModel = 'HRTF'` 옵션을 사용하여 입체음향 구현
* 청취자 좌표(`listener.positionX`), 바라보는 방향(`listener.forwardX`), 음원 위치(`panner.positionX`)를 동적으로 제어


* **Rust WASM 확장성 (선택 사항)**:
* 고성능 바이노럴 DSP, 특수 이펙터 알고리즘, 위상 보정이 필요한 경우 Rust 코드를 WASM으로 빌드하여 `AudioWorkletNode` 내부에서 렌더링



### ③ 사용자 인터페이스 (Popup UI / Option Page)

* 기존 `spatial.ts` 코드를 확장프로그램 Popup UI에 포팅하여 3D Canvas 및 HUD 컨트롤 환경 구축
* UI에서 조작한 파라미터(음원/청취자 좌표, EQ 값, Preset 선택 등)를 Message Passing을 통해 Offscreen 오디오 파이프라인으로 전송

---

## 4. 단계별 개발 로드맵

### Phase 1: 기반 환경 구축 & 오디오 파이프라인 검증

* Manifest V3 규격 설정 (`manifest.json` 내 `offscreen`, `tabCapture`, `userScripts` 권한 및 CSP `'wasm-unsafe-eval'` 설정)
* `chrome.tabCapture`로 탭 오디오를 바이패스하여 정상 출력되는지 검증하는 마일스톤 완료

### Phase 2: 핵심 오디오 이펙터 노드 구현

* PEQ 노드 체인 구성 및 게인/주파수 변경 메시징 루틴 작성
* `ConvolverNode` 구현 및 기본 스튜디오/콘서트 홀 IR 바이너리 파일 로드 로직 완성
* `PannerNode` (HRTF) 연동하여 좌우/상하/거리 음향 위치 변화 테스트

### Phase 3: UI 이식 및 메시징 연결

* 기존 `spatial.ts` 3D 씬 컨트롤러를 Popup 페이지 구조로 변환
* UI의 Drag & Drop 좌표 변경, 머리 방향 Slider 조작 이벤트를 오디오 파이프라인 노드의 파라미터 값으로 매핑

### Phase 4: Rust WASM 최적화 및 패키징

* 고부하 연산 파트(커스텀 DSP)를 Rust로 전환 후 WASM 바이너리 번들링
* 메모리 누수 체크, 오디오 레이턴시 최적화 및 최종 확장프로그램 패키징

---

## 5. 보안 및 기술 고려사항 (Checklist)

* [ ] **CSP (Content Security Policy)**: Manifest V3 기준에 맞춰 로컬 번들 파일만 로드하도록 제한 (`manifest.json`에 WASM 실행 권한 명시)
* [ ] **자원 관리**: 탭이 닫히거나 캡처가 중단될 때 `AudioContext.close()` 및 MediaStream 트랙 해제를 통한 메모리 누수 방지
* [ ] **오디오 버퍼 끊김 방지**: UI 메인 스레드와 오디오 스레드를 완전 분리하여 3D 렌더링 작업이 오디오 재생에 영향을 주지 않도록 유효성 검증