Find-Word/.agent/TASK-v0.2.5.md

Find-Word v0.2.5 배경음 loudness 균일화 작업

기준

• canonical repository: https://source.ibit.kr/OZ-Group/Find-Word
• 기준 커밋: 812540c7438639f25b886cfd620201d92de15362
• 작업 브랜치: fix/v0.2.5-ambience-loudness
• 제품 버전: 0.2.5
• 배포 대상: https://findword.heart-m.com/
• 정확한 credit: Designed by OZ at Heat-T Medical Inc.

사용자 증상

대화 음성은 일정하지만 배경 소음은 선택한 현장음 파일에 따라 체감 크기가 다르다. 모든 배경음을 같은 체감 loudness로 맞춘다.

측정된 근본 원인

v0.2.3의 8개 WAV는 원본 추출 뒤 단순 RMS/peak 기준으로 처리되어 통합 loudness가 약 −38.69~−22.20 LUFS, 16.49 LU 차이였다. 브라우저는 각 배경을 RMS 0.03으로 다시 정규화하지만 주파수 가중 loudness 차이는 남는다. 또한 mixingGains가 파일별 peak를 사용해 공통 gain을 계산하여 crest factor가 큰 market만 같은 SNR에서도 background RMS가 추가 감쇠됐다. 예를 들어 +6 dB에서 market은 약 0.021779 RMS, 다른 환경은 0.03이었다.

구현 계약

1. 8개 현장음의 source, license, selected segment는 v0.2.3과 동일하게 보존한다.
2. 생성 단계에서 FFmpeg EBU R128/loudnorm 기반의 재현 가능한 loudness normalization을 적용한다. 목표 integrated loudness, true-peak ceiling, 측정 알고리즘·도구 버전·pass 통계·최종 측정값을 계획/manifest/provenance에 기록한다.
3. 최종 8개 WAV의 integrated loudness 편차는 엄격한 허용오차 안에 들어야 하며 true peak, PCM, duration, fade, non-silence 계약을 함께 만족한다. 테스트는 manifest 자기보고가 아니라 실제 파일을 독립 측정한다.
4. runtime은 loudness-normalized 배경을 다시 파일별 RMS로 정규화하지 않는다. 목표 음성·intro 정규화는 유지한다.
5. 파일별 peak 차이가 background gain을 바꾸지 않게 한다. 검증된 background/voice/intro peak 상한과 허용 SNR 최대값에서 구한 보수적이고 환경 독립적인 고정 headroom gain을 사용한다. 같은 master volume과 SNR에서 모든 environment의 background gain 값은 동일해야 한다.
6. SNR slider는 목표 음성 gain만 상대적으로 바꾸며 background gain은 environment와 SNR 모두에서 일정하게 유지한다. 음량 master는 모든 경로에 동일하게 적용한다.
7. 변조·과도 peak·잘못된 자산은 fail closed한다. 8개 실제 현장음, 101개 voice, same-origin runtime, cache busting, atomic ambience publication, attribution/license를 보존한다.
8. 제품 버전과 audio/ambience asset query version을 0.2.5로 일관되게 갱신한다.
9. CHANGELOG.md의 v0.2.5 절에 원인, 알고리즘, 수치 계약, runtime 변경, 테스트, 배포 변경을 모두 기록한다.
10. 직접 변경하는 모듈·함수·클래스·핵심 변수/매개변수·비자명한 수학/오디오 로직에 상세 한국어 설계 주석을 쓴다.

개발 방식

• strict vertical-slice TDD: 실제 실패하는 loudness/runtime 계약을 먼저 기록한다.
• 기존 .agent/evidence*와 RESULT*.md는 수정하지 않는다.
• v0.2.5 결과는 .agent/evidence-v0.2.5/와 .agent/RESULT-v0.2.5.md에 별도로 저장한다.
• /tmp/findword-ambience-sources의 해시 고정 원본 8개를 사용한다.
• Codex는 commit/push/merge/tag/deploy를 하지 않는다. Neo가 독립 검증 뒤 수행한다.