129 lines
3.3 KiB
Markdown
129 lines
3.3 KiB
Markdown
# Phase 6-3: Mixer — Design Spec
|
|
|
|
## Overview
|
|
|
|
`voltex_audio`에 그룹 기반 믹서를 추가한다. BGM/SFX/Voice 그룹별 독립 볼륨 제어와 페이드 인/아웃을 지원한다.
|
|
|
|
## Scope
|
|
|
|
- MixGroup enum (Master, Bgm, Sfx, Voice)
|
|
- GroupState (볼륨 + 페이드)
|
|
- MixerState (전체 그룹 관리, effective_volume = group * master)
|
|
- PlayingSound에 group 필드 추가
|
|
- mix_sounds에 mixer 파라미터 추가
|
|
- AudioSystem API: set_group_volume, fade_group
|
|
|
|
## Out of Scope
|
|
|
|
- 동적 그룹 생성 (고정 4개만)
|
|
- 그룹 간 라우팅/버스
|
|
- 이펙트 체인 (reverb, EQ 등)
|
|
- 페이드 커브 (선형만)
|
|
|
|
## Module Structure
|
|
|
|
- `crates/voltex_audio/src/mix_group.rs` — MixGroup, GroupState, MixerState (Create)
|
|
- `crates/voltex_audio/src/mixing.rs` — PlayingSound에 group, mix_sounds에 mixer (Modify)
|
|
- `crates/voltex_audio/src/audio_system.rs` — SetGroupVolume, FadeGroup 명령 (Modify)
|
|
- `crates/voltex_audio/src/lib.rs` — mix_group 모듈 등록 (Modify)
|
|
|
|
## Types
|
|
|
|
### MixGroup
|
|
|
|
```rust
|
|
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
|
|
pub enum MixGroup {
|
|
Master,
|
|
Bgm,
|
|
Sfx,
|
|
Voice,
|
|
}
|
|
```
|
|
|
|
### GroupState
|
|
|
|
```rust
|
|
pub struct GroupState {
|
|
pub volume: f32,
|
|
pub fade_target: f32,
|
|
pub fade_speed: f32,
|
|
}
|
|
```
|
|
|
|
- `new()` → volume=1.0, fade_target=1.0, fade_speed=0.0
|
|
- `tick(dt: f32)` — volume을 fade_target으로 fade_speed * dt만큼 이동. 도달하면 fade_speed=0.
|
|
|
|
### MixerState
|
|
|
|
```rust
|
|
pub struct MixerState {
|
|
groups: [GroupState; 4], // Master, Bgm, Sfx, Voice 순서
|
|
}
|
|
```
|
|
|
|
배열 인덱스로 접근 (HashMap 대신 간결하게).
|
|
|
|
- `new()` — 전부 volume=1.0
|
|
- `set_volume(group, volume)` — 즉시 설정, fade 중지
|
|
- `fade(group, target, duration)` — fade_speed = |target - current| / duration
|
|
- `tick(dt)` — 모든 그룹 업데이트
|
|
- `volume(group) -> f32` — 해당 그룹 현재 볼륨
|
|
- `effective_volume(group) -> f32` — group.volume * master.volume (Master 그룹은 자기 자신만)
|
|
|
|
## Mixing Integration
|
|
|
|
### PlayingSound 변경
|
|
|
|
```rust
|
|
pub group: MixGroup, // 기본 Sfx
|
|
```
|
|
|
|
- `new()` → group = MixGroup::Sfx
|
|
- `new_3d()` → group = MixGroup::Sfx
|
|
- 기존 생성자에 group 파라미터 추가하지 않음 (기본값 사용). 필요 시 직접 설정.
|
|
|
|
### mix_sounds 변경
|
|
|
|
`mixer: &MixerState` 파라미터 추가.
|
|
|
|
각 사운드의 최종 볼륨 계산:
|
|
```
|
|
base_volume = sound.volume * mixer.effective_volume(sound.group)
|
|
```
|
|
이후 spatial gains 적용은 기존과 동일.
|
|
|
|
### AudioCommand 추가
|
|
|
|
```rust
|
|
SetGroupVolume { group: MixGroup, volume: f32 },
|
|
FadeGroup { group: MixGroup, target: f32, duration: f32 },
|
|
```
|
|
|
|
### AudioSystem 메서드 추가
|
|
|
|
```rust
|
|
pub fn set_group_volume(&self, group: MixGroup, volume: f32)
|
|
pub fn fade_group(&self, group: MixGroup, target: f32, duration: f32)
|
|
```
|
|
|
|
### 오디오 스레드
|
|
|
|
- `MixerState` 인스턴스 보유
|
|
- 매 루프: `mixer.tick(dt)` 호출 (dt ≈ 5ms)
|
|
- mix_sounds에 `&mixer` 전달
|
|
|
|
## Test Plan
|
|
|
|
### mix_group.rs
|
|
- GroupState::tick: 페이드 진행, 목표 도달 시 정지
|
|
- MixerState::set_volume: 즉시 반영
|
|
- MixerState::fade: 여러 tick 후 목표 도달
|
|
- MixerState::effective_volume: group * master
|
|
- Master=0이면 모든 그룹 effective=0
|
|
|
|
### mixing.rs (통합)
|
|
- group 볼륨 적용: Sfx volume=0.5 → 출력 절반
|
|
- master=0 → 전체 무음
|
|
- 기존 2D/3D 테스트는 mixer volume=1.0으로 변화 없음
|