Skip to content

README_KO.md

Latest commit

 

History

History
222 lines (166 loc) · 6.83 KB

README_KO.md

File metadata and controls

222 lines (166 loc) · 6.83 KB

AudioQuant

SNAC 기반 AI 초저비트레이트 오디오 코덱 CLI

0.98–2.6 kbps의 초저비트레이트로 오디오를 압축합니다 — WAV 대비 최대 392배 작게, 거의 원본에 가까운 품질로.

WAV:  1분 음성 = 2.88 MB
MP3:  1분 음성 = 960 KB
SNAC: 1분 음성 = 7.35 KB  ← 392:1 압축

주요 기능

  • 초저비트레이트: 음성 0.98 kbps ~ 음악 2.6 kbps
  • 원본에 가까운 품질: 음성 기준 MUSHRA 88.4/100 (0.98 kbps)
  • 사전학습 모델 3종: 음성(24kHz), 음악(32kHz), 고음질(44kHz)
  • 커스텀 .snac 포맷: 44바이트 헤더 + 토큰 데이터
  • 품질 지표: SNR, SI-SNR, 스펙트럼 거리, PESQ (선택)
  • 스트리밍 모드: 1시간+ 팟캐스트도 청크 단위 인코딩
  • GPU 가속: CUDA, MPS (Apple Silicon), CPU 지원
  • Rich 터미널 UI: 프로그레스 바, 컬러 테이블, 스타일 패널

설치

Python 3.10 이상 필요

pip install audioquant

# 품질 지표 포함 (선택)
pip install audioquant[metrics]

소스에서 설치

git clone https://github.com/wjddusrb03/audioquant
cd audioquant
pip install -e ".[dev]"

빠른 시작

# 오디오 압축 (WAV 2.88MB → SNAC 7.35KB)
audioquant compress podcast.wav

# 다시 WAV로 복원
audioquant decompress podcast.snac

# 파일 정보 확인
audioquant info podcast.snac

# 모든 모델 비교
audioquant compare podcast.wav

# 여러 파일 벤치마크
audioquant benchmark file1.wav file2.mp3 file3.flac

명령어

compress — 오디오 압축

audioquant compress input.wav                          # 기본: snac_24khz
audioquant compress input.wav -m snac_44khz            # 고음질 음악
audioquant compress input.wav -o output.snac           # 출력 경로 지정
audioquant compress input.wav -d cuda                  # GPU 강제 사용

decompress — 오디오 복원

audioquant decompress podcast.snac                     # 기본: WAV
audioquant decompress podcast.snac --format flac       # FLAC 출력
audioquant decompress podcast.snac -o restored.wav     # 경로 지정
audioquant decompress podcast.snac -d cuda             # GPU 사용

info — 파일 정보

audioquant info podcast.wav       # 오디오 파일 정보
audioquant info podcast.snac      # SNAC 파일 정보

compare — 모델 비교

audioquant compare input.wav                               # 테이블 출력
audioquant compare input.wav --json                        # JSON 출력
audioquant compare input.wav -m snac_24khz,snac_44khz      # 특정 모델만
audioquant compare input.wav --no-metrics                  # 품질 지표 생략

benchmark — 벤치마크

audioquant benchmark *.wav                             # 모든 WAV 파일
audioquant benchmark file1.wav file2.mp3 --json        # JSON 출력
audioquant benchmark file1.wav -m snac_24khz,snac_44khz  # 특정 모델
audioquant benchmark file1.wav -d cuda                 # GPU 사용

stream — 스트리밍 인코딩

audioquant stream long_podcast.wav -o podcast.snac           # 대용량 파일용
audioquant stream lecture.wav -o lecture.snac --chunk-duration 2.0
audioquant stream lecture.wav -o lecture.snac -m snac_44khz -d cuda

SNAC 모델

모델 샘플레이트 비트레이트 품질 (MUSHRA) 용도 파라미터
snac_24khz 24,000 Hz 0.98 kbps 88.4 음성, 팟캐스트 19.8M
snac_32khz 32,000 Hz 1.9 kbps — 음악, 효과음 54.5M
snac_44khz 44,100 Hz 2.6 kbps — 고음질 음악 54.5M

다른 코덱과 비교

코덱 비트레이트 음성 품질 음악 품질 CLI 도구
SNAC (AudioQuant) 0.98 kbps 88.4 76.8 ✅
EnCodec (Meta) 1.5 kbps 78.3 64.4 ✅
DAC (Descript) 2.5 kbps 85.0 54.0 ✅

작동 원리

SNAC은 **RVQ(Residual Vector Quantization)**를 다중 시간 스케일로 사용합니다 (토큰 레이트는 모델에 따라 다름):

  • 레벨 0 (거친, 10–14 Hz): 전체 멜로디와 톤
  • 레벨 1 (중간, 21–29 Hz): 음색과 감정
  • 레벨 2 (세밀, 42–57 Hz): 발음과 디테일
  • 레벨 3 (최세밀, 83–115 Hz): 고주파 디테일 (32kHz/44kHz만)

지원 포맷

포맷 읽기 쓰기
WAV ✅ ✅
MP3 ✅ ✅
FLAC ✅ ✅
OGG ✅ ✅
OPUS ✅ ✅
SNAC ✅ ✅

프로젝트 구조

audioquant/
├── src/audioquant/
│   ├── models.py         # 데이터 모델 및 모델 레지스트리
│   ├── codec.py          # SNAC 래퍼 (인코딩/디코딩)
│   ├── audio_io.py       # 오디오 파일 I/O
│   ├── format.py         # .snac ���이너리 포맷
│   ├── metrics.py        # 품질 지표 (SNR, PESQ 등)
│   ├── streaming.py      # 청크 인코딩/디코딩
│   ├── benchmark.py      # 모델 간 비교
│   ├── display.py        # Rich 터미널 출력
│   └── cli.py            # Click CLI 명령어
├── tests/                # 270개 테스트
├── pyproject.toml
├── README.md
├── README_KO.md
└── LICENSE

테스트

# 전체 테스트 실행 (SNAC 모델 불필요, ~4초)
pytest tests/ -v

# 특정 테스트 파일
pytest tests/test_format.py -v
pytest tests/test_metrics.py -v

의존성

패키지 용도
snac SNAC 신경 오디오 코덱
torch 텐서 연산
torchaudio 오디오 I/O 및 리샘플링
click CLI 프레임워크
rich 터미널 포맷팅
numpy 수치 연산
pesq (선택) PESQ 품질 지표

Python 3.10 이상 필요

품질 지표

지표 설명 범위
SNR 신호 대 잡음비 높을수록 좋음 (dB)
SI-SNR 스케일 불변 SNR 높을수록 좋음 (dB)
스펙트럼 거리 다중 해상도 STFT 거리 낮을수록 좋음
PESQ 음성 지각 품질 1.0–4.5
압축률 원본 / 압축 크기 높을수록 작음

문제 보고 및 기여

버그를 발견하셨나요? 기능 요청이 있으신가요? 알려주세요!

모든 피드백을 환영합니다. 예상대로 작동하지 않는 부분이 있다면 알려주세요!

라이선스

MIT

감사의 말

  • SNAC — Hubert Siuzdak의 다중 스케일 신경 오디오 코덱
  • TurboQuant — 연구 기술 위에 실용 CLI를 만드는 패턴의 영감