feat: 안드로이드 판의 개선을 PC 판으로 옮긴다 (v2.0)

.github/workflows/build.yml

@@ -0,0 +1,21 @@
+name: build
+
+on:
+  push:
+    branches: [ main, "feature/**" ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  build:
+    name: 빌드 · 단위 테스트
+    runs-on: windows-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-dotnet@v4
+        with:
+          dotnet-version: 10.0.x
+      - name: 빌드
+        run: dotnet build SoundVisualizer.slnx -c Release
+      - name: 단위 테스트
+        run: dotnet test SoundVisualizer.Tests/SoundVisualizer.Tests.csproj -c Release --no-build

.gitignore

@@ -5,3 +5,4 @@ obj/
 *.suo
 *.sln.docstates
 .agents/mcp_config.json
+*.lscache

README.ko.md

@@ -4,7 +4,7 @@
 
 <br/>
 
-# Sound Visualizer
+# SoundVisualizer
 
 <img width="1024" height="818" alt="SoundVisualizer" src="https://github.com/user-attachments/assets/b11aa5b3-c995-4e36-8ff6-3e2f2c2b2388" />
 
@@ -20,9 +20,11 @@
 
 <br/>
 
-> **Sound Visualizer**는 컴퓨터의 시스템 오디오를 실시간으로 캡처하여 방향·크기·의미를 그래픽 오버레이로 변환하는 데스크톱 애플리케이션입니다. 
+> **SoundVisualizer**는 컴퓨터의 시스템 오디오를 실시간으로 캡처하여 방향·크기·의미를 그래픽 오버레이로 변환하는 데스크톱 애플리케이션입니다. 
 단순한 파형 시각화를 넘어, **YAMNet**과 **ONNX Runtime** 기반의 AI 사운드 분류기를 내장하여 현재 재생 중인 소리의 종류(배경음, 대화음, 위협음 등)를 실시간으로 인지하고 피드백을 제공합니다.
 
+> 📱 안드로이드 버전도 있습니다: [SoundVisualizer for Android](https://github.com/bibibic76/SoundVisualizer)
+
 ---
 
 ## 📖 목차
@@ -31,7 +33,6 @@
 - [시스템 및 AI 아키텍처](#-시스템-및-ai-아키텍처)
 - [설치 및 실행 방법](#-설치-및-실행-방법)
 - [빌드 가이드 (개발자용)](#-빌드-가이드-개발자용)
-- [팀원 및 역할](#-팀원-및-역할)
 - [라이선스](#-라이선스)
 
 ---
@@ -55,21 +56,40 @@
 - **원형 모드 (Circle)**: 화면 중앙을 기점으로 바깥쪽으로 퍼져나가는 원형 파동을 렌더링합니다.
 - **패드 모드 (Pad)**: 지정된 공간 그리드(방향)에 고정된 패드 형태로 소리를 표현합니다.
 - **외곽선 모드 (Outline)**: 파도 모드를 기반으로, 파도의 상한 외곽선 테두리만 표현하여 화면 가림을 최소화합니다.
+- 30 FPS부터 모니터 주사율까지, 최대 프레임을 얼마로 두어도 그래픽이 같은 빠르기로 움직입니다.
 
 ### 2. 온스크린 실시간 제어 및 에디터
 전체 화면 게임을 내리지 않고도 오버레이 상태에서 즉각적인 수정이 가능합니다.
 - **F2 / F3 단축키**: 사운드 모드 및 시각화 모드 실시간 변경. 핫키는 변경 가능합니다.
-- **에디터 모드 (기본 F4키)**: 화면에 나타나는 가이드라인 경계를 직접 드래그하여 시각화 영역의 크기와 한계를 자유롭게 리사이징합니다. 색상, 투명도, AI 감지 민감도 등 모든 설정 또한 패널에서 조정 가능합니다.
+- **에디터 모드 (기본 F4키)**: 화면에 나타나는 가이드라인 경계를 직접 드래그하여 시각화 영역의 크기와 한계를 자유롭게 리사이징합니다. 색상, 투명도 등 모든 설정 또한 패널에서 조정 가능합니다.
 
 ### 3. 하드웨어 인식 7.1 다중 채널 지원
 - 시스템의 오디오 채널 구성(Stereo, 5.1, 7.1 Surround)을 자동 인식하고, 소리의 발생 방향(각 채널)을 정확하게 매핑하여 입체적인 시각 효과를 렌더링합니다.
+- 사운드 모드는 실행할 때와 출력 장치가 바뀔 때 그 장치에 맞춰지며, 직접 바꿀 수도 있습니다.
+- 스테레오 출력에서는 좌우에 함께 있는 소리를 화면 위쪽에, 좌우 차이만 옆쪽에 그립니다. 그래서 가운데에서 나는 소리가 양쪽에서 나는 소리처럼 보이지 않습니다.
 
 ### 4. AI 실시간 사운드 분류 (ONNX & YAMNet)
 - **3-Class 분류 체계**: 모든 소리를 `Ambient(환경음)`, `Speech(대화음)`, `Danger(위협음)` 3가지로 분석하여 카테고리별로 지정된 UI 색상과 투명도로 동적 시각 피드백을 제공합니다. 색상과 투명도는 커스터마이징이 가능합니다.
-- **Gunshot Booster**: 게임 및 영상 내의 총소리를 놓치지 않도록 특수 학습된 부스터 모델이 가동되어 위협음 탐지 민감도를 향상합니다.
-
-### 5. 글로벌 다국어 지원
-- 한국어, 영어, 일본어, 중국어, 스페인어, 프랑스어, 독일어, 러시아어 등 8개 국어를 지원합니다.
+- **위협 단서**: 사이렌, 경보, 폭발음, 폭죽 같은 경고음은 모델의 상위 후보 다섯 개 안에(5% 이상) 들기만 해도 `위협음`으로 봅니다. 음악이나 게임 소리에 묻혀도 놓치지 않기 위해서입니다. 총소리 이름은 오경보를 막기 위해 이렇게 끌어올리지 않습니다.
+- **흔들리지 않는 색**: `위협음`은 조건을 넘는 첫 결과에 바로 바뀌고, `대화음`과 `환경음`은 두 번 연달아 같아야 바뀌어 색이 깜빡이지 않습니다. 조용한 동안에는 AI 가 쉬고, 소리가 나면 바로 다시 듣습니다.
+- **모든 채널을 듣습니다**: 5.1/7.1 환경에서는 앞쪽뿐 아니라 뒤쪽·옆쪽 채널의 소리도 AI 가 듣습니다.
+- **늦게 온 위협음**: `위협음` 판정이 소리보다 조금 늦게 와도, 그 소리를 나던 때의 크기로 그립니다. 앞서 숨겨 둔 종류였던 소리도 그렇습니다.
+
+### 5. 소리마다 종류 정하기 (분류 탭)
+- AI 가 알아듣는 소리 521개를 안드로이드 버전과 같은 묶음으로 보여 주고, 묶음마다(고급 모드에서는 소리마다) `환경음`, `대화음`, `위협음` 가운데 무엇으로 볼지 선택합니다.
+- 이름으로 찾고, 종류나 바꾼 소리로 거르고, 한 번에 모두 되돌릴 수 있습니다. 바꾼 것은 오버레이의 AI 에 바로 반영됩니다.
+
+### 6. 도움말, 안내, 트레이 아이콘
+- **도움말 탭**: 시작하기, 표현 모드, 소리 종류, 단축키, 자주 묻는 질문, 정보가 미리 채워진 GitHub 이슈나 메일로 보내는 제보 버튼, 오픈소스 라이선스를 담았습니다.
+- **안내**: 캡처할 출력 장치가 없을 때, 소리 종류 구분을 쓸 수 없을 때, 시각화가 멈춘 까닭을 홈 탭에 알려 줍니다.
+- **트레이 아이콘**: 알림 영역에서 시각화를 켜고 끄거나, 런처로 돌아오거나, 종료할 수 있습니다.
+- **튜토리얼**: 처음 열면 실제 그리기 엔진으로 소리, 방향, 소리 종류가 어떻게 그려지는지 짧게 보여 줍니다. 홈 탭에서 다시 볼 수 있습니다.
+- **개발자 모드**: AI 가 들은 소리(상위 다섯 개, 확신도, 걸린 시간)를 오버레이 왼쪽 위에 띄우고, 모든 결과를 앱 옆 `ai-log` 폴더의 CSV 파일로 기록할 수 있습니다.
+- **키보드와 화면 읽어주기**: 런처의 모든 칸에 Tab 키로 닿습니다. 탭 줄에서는 화살표로 탭을 옮기고, 어디서나 `Ctrl + Tab` 으로 다음 탭으로 갑니다. 대화 창과 오버레이 편집 패널은 `Esc` 로 닫습니다. 언어 목록은 화살표로 열어 둘러보고 `Enter` 로 선택할 때만 언어가 바뀝니다. 아이콘 버튼, 단축키 버튼, 색 버튼, 소리 목록은 내레이터·NVDA 같은 화면 읽어주기가 이름으로 읽고, 실행 상태와 안내, 바꾼 소리 수는 바뀔 때 바로 읽힙니다. 편집 화면에서 마우스로 끄는 값은 모두 패널의 슬라이더로도 바꿀 수 있습니다.
+
+### 7. 글로벌 다국어 지원
+- 한국어, 영어, 일본어, 중국어(간체·번체), 베트남어, 태국어, 인도네시아어, 스페인어, 포르투갈어(브라질), 프랑스어, 이탈리아어, 독일어, 러시아어, 폴란드어, 터키어, 힌디어, 아랍어(오른쪽에서 왼쪽) 등 18개 언어를 지원합니다. 기본값은 Windows 표시 언어를 따릅니다.
+- 화면 글꼴은 Pretendard 이고, Pretendard 에 없는 문자는 Windows 글꼴로 보입니다.
 
 ---
 
@@ -78,34 +98,43 @@
 본 프로젝트는 고성능 실시간 처리를 위해 철저한 메모리 관리 및 백그라운드 최적화로 설계되었습니다.
 
 * **Core Audio API (WASAPI)**: Windows 시스템 전체 오디오를 딜레이 없이 루프백 캡처.
-* **DSP & FFT 연산**: 백그라운드 오디오 스레드에서 초당 수십 번의 고속 주파수 변환 연산 수행.
+* **채널별 크기 측정**: 캡처 스레드가 버퍼마다 채널별 최고 크기를 재고, 렌더 루프는 지난 프레임 뒤로 가장 큰 값을 가져갑니다.
 * **Zero-Allocation 렌더링**: C# / WPF 환경에서 GC(가비지 컬렉터)의 개입을 최소화하여 프레임 드랍 방지.
-* **ONNX 추론 파이프라인**: 16kHz 모노 변환 및 Log-mel 스펙트로그램 전처리를 거친 후, `Microsoft.ML.OnnxRuntime` 엔진으로 전이 학습된 YAMNet 가중치 기반 실시간 분류 수행.
+* **프레임과 무관한 움직임, 쉬는 오버레이**: 스무딩은 60 FPS 기준으로 맞춥니다. 1초 동안 보이는 것이 없으면 프레임마다 그리지 않고 쉬다가, 소리가 나면 바로 깨어납니다.
+* **ONNX 추론 파이프라인**: 250ms 마다 최근 0.975초의 소리를 모노로 섞고, 앨리어싱 방지 필터를 거쳐 16kHz 로 바꾼 뒤, 모델이 만들어질 때와 같은 방식의 Log-mel 스펙트로그램으로 바꿔 `Microsoft.ML.OnnxRuntime` 의 YAMNet 으로 분류합니다. 모델 파일은 불러올 때 고정된 SHA-256 으로 확인하고, 각 단계는 기준 출력과 비교하는 단위 테스트로 검증합니다.
 
 ---
 
 ## 🚀 설치 및 실행 방법
 
-Sound Visualizer는 설치가 필요 없는 가벼운 **포터블(Portable)** 패키지로 제공됩니다.
+SoundVisualizer는 설치가 필요 없는 가벼운 **포터블(Portable)** 패키지로 제공됩니다. Windows 10/11 (64비트)에서 돌아가며, .NET 을 따로 설치하지 않아도 됩니다.
 
 1. **[GitHub Releases](https://github.com/amophi/SoundVisualizer/releases)** 페이지에 접속합니다.
-2. 최신 버전의 `SoundVisualizer.zip` 파일을 다운로드 및 압축 해제합니다.
+2. 최신 버전의 `SoundVisualizer_vX.Y.zip` 파일을 다운로드해 원하는 곳에 압축 해제합니다.
 3. 폴더 내의 **`SoundVisualizer.exe`**를 실행합니다.
-4. 런처에서 언어 및 초기 설정을 마친 후, **Start**를 클릭하여 오버레이를 활성화합니다.
+4. 런처에서 언어 및 초기 설정을 마친 후, **실행**을 눌러 오버레이를 켭니다.
+
+설정은 `SoundVisualizer.exe` 옆의 `settings.json` 에 저장되므로, 폴더를 그대로 옮기거나 복사해도 됩니다.
 
 ---
 
 ## 🛠 빌드 가이드 (개발자용)
 
 코드 수정 및 기여를 위해 소스에서 직접 빌드하는 방법입니다.
 
-1. **요구 사항**: Windows 10/11, Visual Studio 2022 (.NET 데스크톱 개발 워크로드), .NET 10.0 SDK
+1. **요구 사항**: Windows 10/11, .NET 10 SDK. Visual Studio 2026 (.NET 데스크톱 개발 워크로드)은 있어도 되고 없어도 됩니다.
 2. **리포지토리 클론**:
    ```bash
    git clone https://github.com/amophi/SoundVisualizer.git
    ```
-3. Visual Studio에서 `SoundVisualizer.slnx` 솔루션을 엽니다.
-4. `Release` 또는 `Debug` 구성 선택 후 솔루션을 빌드(`Ctrl + Shift + B`)하고 실행(`F5`)합니다.
+3. 리포지토리 폴더에서 빌드하고 테스트합니다.
+   ```bash
+   dotnet build SoundVisualizer.slnx -c Release
+   dotnet test SoundVisualizer.Tests/SoundVisualizer.Tests.csproj
+   ```
+   또는 Visual Studio 에서 `SoundVisualizer.slnx` 를 열어 빌드(`Ctrl + Shift + B`)하고 실행(`F5`)합니다.
+
+솔루션은 세 프로젝트로 나뉩니다. `SoundVisualizer`(WPF 앱), `SoundVisualizer.Core`(오디오, AI, 렌더링 계산, 설정, 18개 언어 문자열 표. 화면에 의존하지 않음), `SoundVisualizer.Tests`(xUnit 테스트. AI 각 단계의 기준 출력 비교 포함).
 
 ---