1. 목적
사용자가 작품을 읽으며 자신의 목소리로 녹음할 수 있는 기능을 제공합니다. 녹음된 오디오는 서버에 저장되어 언제든지 재생할 수 있으며, 작품 읽기 경험을 개인화하는 핵심 기능입니다.
2. 녹음 기본 규칙
2-1. 제한 사항
| 항목 | 정책 |
|---|
| 최대 녹음 길이 | 30분 (1,800초) |
| 녹음 단위 | 작품 x 에피소드 x 언어별 1개 |
| 고유 제약 | user + book + episode + language_code 조합 |
- 동일 작품의 동일 에피소드에서 동일 언어로는 1개의 녹음만 유지됩니다.
- 기존 녹음이 있는 상태에서 새 녹음을 저장하면, 기존 녹음을 삭제 후 새 녹음으로 교체됩니다.
2-2. 데이터 구조 (Recording)
| 필드 | 타입 | 설명 |
|---|
user | FK | 녹음 사용자 |
book | FK | 작품 |
episode | FK | 에피소드 |
language_code | CharField(10) | 녹음 언어 코드 (예: ko, en, jp) |
file_url | URLField(500) | S3 저장 파일 URL |
duration | IntegerField | 녹음 길이 (초 단위) |
created_at | DateTimeField | 녹음 생성 시각 |
3. 서버 업로드 구조
3-1. 업로드 흐름
녹음 파일은 S3 Presigned URL 방식으로 서버에 업로드됩니다.
- 녹음 완료: 클라이언트에서 M4A(AAC) 포맷으로 로컬 녹음
- 세그먼트 병합: FFmpeg를 사용하여 다수의 녹음 세그먼트를 하나의 M4A 파일로 병합
- Presigned URL 요청: 서버에 업로드용 Presigned URL 요청
- S3 직접 업로드: 클라이언트가 Presigned URL로 S3에 직접 업로드
- 업로드 확인: 서버에 업로드 완료를 알리고, Recording 레코드 생성
3-2. 오디오 처리
- 코덱: AAC (M4A 컨테이너)
- 비트레이트: 128kbps
- 샘플레이트: 44,100 Hz
- 오디오 소스: 음성 인식 모드 (
voice_recognition)
- FFmpeg를 사용하여 AAC 프라이밍 샘플(오프셋) 처리 및 세그먼트 병합 수행
3-3. 백그라운드 업로드
- 녹음 저장 시 업로드 태스크가 백그라운드 큐에 등록됩니다.
- 네트워크 불안정 시 최대 2회 재시도 후 일시 중지됩니다.
- 24시간이 경과한 미완료 태스크는 자동으로 정리됩니다.
4. 뷰어 내 녹음 기능
4-1. 읽기/녹음 모드 토글
뷰어에서는 읽기 모드와 녹음 모드를 전환할 수 있습니다.
- 읽기 모드: 일반 책 읽기 화면
- 녹음 모드: 녹음 다이얼로그가 활성화되어 녹음 제어 가능
4-2. 녹음 상태 흐름
녹음 다이얼로그는 다음 상태를 가집니다.
| 상태 | 설명 |
|---|
idle | 대기 상태 (녹음 시작 전) |
counting | 카운트다운 (3, 2, 1) |
recording | 녹음 중 |
paused | 녹음 일시정지 |
4-3. 녹음 버튼 상태
| 버튼 | 조건 | 동작 |
|---|
start | 세그먼트 없음 | 새 녹음 시작 |
pause | 녹음 중 | 녹음 일시정지 |
resume | 커서가 끝 위치 | 이어서 녹음 |
overwrite | 커서가 중간 위치 | 해당 위치부터 덮어쓰기 |
4-4. 파형 및 노이즈 미터
- 실시간 오디오 레벨을 감지하여 파형(waveform)으로 시각화합니다.
- 60ms 간격으로 레벨을 샘플링합니다.
- 42dB 이하는 무음으로 처리하며, 42
70dB 범위를 0.150.9 사이로 매핑합니다.
4-5. 녹음 중 제한 사항
- 녹음 중에는 언어 전환이 비활성화됩니다.
- 녹음 중에는 타임라인 시크가 비활성화됩니다.
- 재생 중에는 녹음 시작이 비활성화됩니다.
- 30분 최대 녹음 시간에 도달하면 자동으로 녹음이 중지됩니다.
4-6. 완료 후 플레이어 모드
- 녹음 완료 후 저장하면 녹음 다이얼로그가 닫히고 재생 목록(플레이리스트) 다이얼로그로 전환됩니다.
- 재생 목록에서 해당 녹음을 선택하여 재생할 수 있습니다.
- 15초 앞/뒤로 건너뛰기가 지원됩니다.
4-7. 수정 모드
- 기존 녹음을 서버에서 다운로드하여 수정할 수 있습니다.
- 비파괴적 편집 세션: 원본 파일을 백업한 후 편집하며, 취소 시 원본으로 롤백됩니다.
- 저장 시 기존 녹음을 삭제하고 새 녹음으로 교체합니다.
5. 관리 API
5-1. 사용자 녹음 목록
- Endpoint:
GET /api/users/recordings/
- 현재 로그인한 사용자의 전체 녹음 목록을 반환합니다.
5-2. 에피소드별 녹음 목록
- Endpoint:
GET /api/books/<book_id>/episodes/<episode_id>/recordings/
- 특정 에피소드의 녹음 목록을 반환합니다.
5-3. 녹음 삭제
- Endpoint:
DELETE /api/users/recordings/<pk>/
- 사용자 본인의 녹음을 삭제합니다.
6. 뱃지 표시 규칙
| 조건 | 뱃지 위치 |
|---|
| 단일 에피소드 작품에 녹음 존재 | 작품 상세 메인에 녹음 뱃지 표시 |
| 에피소드별 1개 이상 녹음 존재 | 해당 에피소드 표지에 녹음 뱃지 표시 |