🎙 음성 기반 감정 분류 모델 (Wav2Vec2 + MLP)

✅ 프로젝트 개요

이 프로젝트는 사람의 **음성 데이터를 기반으로 감정(행복, 슬픔, 놀람, 분노, 우울)**을 분류하는 모델입니다.
Meta(Facebook AI)에서 개발한 wav2vec2.0 모델을 사용하여 음성에서 고차원 벡터(특징)를 추출하고,
추출된 벡터를 입력으로 받아 감정을 예측하는 MLP 분류기를 구성합니다.

🚀 NEW! 실시간 발화 단위 처리 & Late Fusion

🎯 발화 단위 기반 처리

• STT 결과를 트리거로 사용하여 발화 완료 시점 감지
• 해당 시간 구간의 음성만 추출하여 정확한 감정 분석
• 자연스러운 감정 표현 단위로 분석하여 높은 정확도

🔥 Late Fusion 멀티모달 시스템

# 3개 모달리티 각각 5차원 확률 벡터 생성
text_emotion = [0.1, 0.2, 0.4, 0.2, 0.1]     # 강래 - 텍스트 감정
audio_emotion = [0.0, 0.1, 0.3, 0.5, 0.1]    # 준용 - 음성 감정
vision_emotion = [0.05, 0.05, 0.3, 0.5, 0.1] # 균호 - 비전 감정

# Late Fusion 방법들
# 방법 1: 가중 평균 (현재 사용 - 학습 불필요)
final_emotion = weighted_average(text_emotion, audio_emotion, vision_emotion)

# 방법 2: MLP 학습 (향후 계획)
# fusion_input = text_emotion + audio_emotion + vision_emotion  # 15차원
# final_emotion = trained_mlp(fusion_input)  # → 5차원 최종 감정

🚨 Late Fusion 학습 필요성

• 현재: 가중 평균 방식 (임시) - 텍스트 30% + 음성 40% + 비전 30%
• 향후: MLP 학습 - 실제 라벨링 데이터로 최적 조합 학습

---

⚙️ 현재 진행 방식: Feature Extraction

현재는 **wav2vec2 모델의 사전학습 가중치를 고정(freeze)**하고,
해당 모델로부터 음성의 고정된 768차원 벡터를 추출한 후,
이를 입력으로 하는 MLP(다층 퍼셉트론) 감정 분류기만 학습하는 구조입니다.

• ✅ 빠르게 실험 가능
• ✅ 적은 데이터로도 안정적인 학습
• ❌ wav2vec2가 감정에 특화되지는 않음

---

🔜 향후 계획: Fine-Tuning

향후에는 감정 분석에 맞춰 **wav2vec2 모델 전체 또는 일부를 미세조정(Fine-tuning)**할 예정입니다.

• wav2vec2의 하위 Transformer 레이어까지 학습에 포함시켜,
  감정 정보에 더욱 민감한 특성 벡터를 추출하도록 개선합니다.

Fine-tuning은 다음과 같은 상황에서 진행할 예정입니다:

• ✅ 충분한 양의 라벨링된 감정 음성 데이터 확보 시
• ✅ 현재 MLP 분류기 기반 성능 한계 도달 시
• ✅ 고성능 GPU 환경이 준비되었을 때

🚨 모델 학습 필요성

# 현재 상태
✅ STT: 바로 사용 가능 (Google API)
✅ wav2vec2: 한국어 사전학습 모델 사용
❌ MLP 분류기: 한국어 감정 데이터로 학습 필요!

🎯 두 가지 학습 방법

방법 1: Feature Extraction (빠른 시작) ⚡

wav2vec2 (freeze) → [1024차원] → MLP (학습) → 감정 예측

• ✅ 빠른 학습 (MLP만)
• ✅ 적은 GPU 메모리
• ✅ 적은 데이터로도 가능
• ❌ 중간 성능 (~70-80%)

방법 2: Fine-tuning (최고 성능) 🏆

wav2vec2 (학습) → [1024차원] → MLP (학습) → 감정 예측

• 🔥 전체 모델을 감정 분석에 특화
• ✅ 최고 성능 (~85-95%)
• ❌ 긴 학습 시간
• ❌ 많은 GPU 메모리 필요

---

🗂 주요 파일 구조

seeksick-voice/
├── models/
│   └── classifier.py            # MLP 감정 분류기 정의
├── features/
│   └── extractor.py             # wav2vec2 기반 임베딩 추출
├── predict.py                   # 단일 오디오 파일 감정 예측
├── train.py                     # 모델 학습 스크립트
├── real_time_processor.py       # 🆕 실시간 발화 단위 처리기
├── speech_to_text.py           # 🆕 STT 모듈 (발화 감지)
├── audio_segmenter.py          # 🆕 음성 세그먼트 추출기
├── late_fusion_system.py       # 🆕 멀티모달 Late Fusion 시스템
├── test_realtime.py            # 🆕 실시간 시스템 테스트
├── train_late_fusion.py        # 🆕 Late Fusion MLP 학습
├── wav/                        # 음성 파일들
├── outputs/                    # 학습된 모델 저장
├── annotation/                 # 라벨링 데이터
├── README.md                   # 설명 문서
└── requirements.txt            # 필요한 라이브러리 목록

---

📦 사용 기술

• Python 3.8+
• PyTorch - 딥러닝 프레임워크
• HuggingFace Transformers - wav2vec2 모델
• Librosa - 음성 로딩 및 전처리
• SpeechRecognition - 🆕 실시간 STT
• PyAudio - 🆕 실시간 음성 녹음
• NumPy - 수치 연산

---

🎧 감정 분류 클래스

• 행복 (Happy)
• 슬픔 (Sad)
• 놀람 (Surprise)
• 분노 (Anger)
• 우울 (Depression)

---

💻 실행 방법

1️⃣ 환경 설정

# 가상환경 생성
python -m venv .venv
source .venv/bin/activate  # (Windows: .venv\Scripts\activate)

# 의존성 설치
pip install -r requirements.txt

2️⃣ 기본 사용법

# 단일 파일 감정 예측
python predict.py

# 실시간 감정 분석 테스트
python test_realtime.py

# Late Fusion 멀티모달 시스템
python late_fusion_system.py

# Late Fusion MLP 학습 (라벨링 데이터 준비 후)
python train_late_fusion.py

# 한국어 음성 감정 모델 학습
python train_korean_emotion.py          # Feature Extraction 방식
python train_korean_emotion_finetune.py  # Fine-tuning 방식 (고성능)

3️⃣ 실시간 처리 옵션

키보드 입력 테스트 (추천)

python test_realtime.py
# → 1번 선택 → 텍스트 입력으로 테스트

실제 마이크 음성 테스트

python test_realtime.py  
# → 2번 선택 → 마이크 음성으로 테스트

---

🔧 시스템 아키텍처

발화 단위 처리 파이프라인

🎤 실시간 녹음 → 📝 STT → ⏱️ 발화 완료 감지 → 🎵 음성 세그먼트 추출 → 🧠 감정 분석

Late Fusion 아키텍처

📝 텍스트 모달리티 (강래) ─┐
🎵 음성 모달리티 (준용)   ├─→ 🔥 Late Fusion MLP → 🎯 최종 감정
👁️ 비전 모달리티 (균호) ─┘

---

🚨 주요 특징

동기화 전략

• 발화 완료를 트리거로 모든 모달리티 동시 분석
• 시간 구간 기반 정확한 세그먼트 추출
• 자연스러운 감정 표현 단위 처리

확장성

• 각 모달리티 독립적 개발 가능
• 플러그인 방식으로 모달리티 추가/제거
• API 인터페이스 표준화

실시간 성능

• 백그라운드 녹음으로 지연시간 최소화
• 순환 버퍼로 메모리 효율성
• 비동기 처리로 응답성 향상

---

💡 참고

• Wav2Vec2.0 논문 (Facebook AI)
• HuggingFace Wav2Vec2 Documentation
• Late Fusion for Multimodal Learning

---

👥 팀 역할

• 준용 🎵: 음성 모달리티 (현재 프로젝트)
• 강래 📝: 텍스트 모달리티
• 균호 👁️: 비전 모달리티

각자의 모달리티에서 5차원 감정 확률 벡터를 출력하여
Late Fusion MLP에서 최종 통합 분석을 수행합니다! 🚀

🇰🇷 한국어 지원 현황

✅ 완전 한국어 지원

• STT: Google Speech API ko-KR
• wav2vec2: kresnik/wav2vec2-large-xlsr-korean 사용
• 감정 라벨: 한국어 (행복, 슬픔, 놀람, 분노, 우울)

📚 학습 데이터 준비

// data/korean_emotion_train.json
[
  {
    "audio_path": "wav/happy_001.wav",
    "text": "오늘 정말 기분이 좋아요", 
    "emotion": 0  // 0:행복, 1:슬픔, 2:놀람, 3:분노, 4:우울
  }
]