Repository navigation
Shared Audio
wcorn edited this page Apr 5, 2026
·
1 revision
여러 모듈(Tools, Planner 등)이 공유하는 오디오 재생 인프라.
앱 전역에서 사용하는 알림음·효과음을 중앙에서 관리한다. 모듈별로 별도의 오디오 로직을 구현하지 않는다.
- Tools: 메이플 재획 타이머 알림음
- Planner (예정): 일정·루틴 알림, 복습 알림
- 추후 추가되는 모든 모듈의 사운드 피드백
mp3로 통일한다. 브라우저 호환성과 용량 효율이 가장 좋다.
운영 초기 단계에서 채택한 방식. 소리 파일은 정적 에셋으로 배포하고, 코드 레지스트리로 관리한다.
fe/public/sounds/ # 정적 에셋 (mp3 파일)
└── *.mp3
fe/src/shared/audio/
├── sounds.ts # SoundAsset 레지스트리
├── useSound.ts # 재생 훅
└── types.ts
fe/src/shared/audio/sounds.ts
export interface SoundAsset {
id: string; // 'alert-default', 'alert-bell'
name: string; // 사용자에게 표시될 이름
path: string; // '/sounds/alert-default.mp3'
}
export const SOUNDS: SoundAsset[] = [
{ id: 'alert-default', name: '기본 알림', path: '/sounds/alert-default.mp3' },
// 초기에는 여러 개 등록해서 비교 가능
];
export const DEFAULT_ALERT_SOUND_ID = 'alert-default';
export function getSoundById(id: string): SoundAsset | undefined {
return SOUNDS.find(s => s.id === id);
}fe/src/shared/audio/useSound.ts
interface UseSoundOptions {
soundId: string;
volume?: number; // 0.0 ~ 1.0
}
interface UseSoundReturn {
play: () => void;
stop: () => void;
preload: () => void;
isReady: boolean;
}
export function useSound(options: UseSoundOptions): UseSoundReturn;-
HTMLAudioElement기반 - 첫 사용자 인터랙션(시작 버튼 클릭 등) 이후 재생 가능 (브라우저 자동재생 정책)
- 동시 재생 시 새 인스턴스 생성 또는
currentTime = 0으로 리셋 후 재생
// Tools Timer에서
const { play } = useSound({
soundId: config.soundId ?? DEFAULT_ALERT_SOUND_ID,
volume: config.soundVolume,
});
// 알림 시점에
play();각 모듈은 선택만 한다. 등록은 개발자가 한다.
<Select value={soundId} onValueChange={setSoundId}>
{SOUNDS.map(s => (
<SelectItem key={s.id} value={s.id}>{s.name}</SelectItem>
))}
</Select>
<Button onClick={() => play()}>미리듣기</Button>- 파일을
fe/public/sounds/{name}.mp3에 배포 -
fe/src/shared/audio/sounds.tsSOUNDS 배열에 한 줄 추가 - (선택) 기본값을 바꾸려면
DEFAULT_ALERT_SOUND_ID수정 - 배포
각 모듈은 사용자가 선택한 soundId를 자체 설정 키에 저장한다.
// 예: Tools Timer
interface TimerLastConfig {
// ... 기타 설정
soundId: string; // SOUNDS 레지스트리의 id
soundVolume: number; // 0.0 ~ 1.0
}- 저장된
soundId가 현재 레지스트리에 없을 경우DEFAULT_ALERT_SOUND_ID로 폴백
소리 파일 수가 늘거나, 코드 배포 없이 자유롭게 관리하고 싶어지면 방식 B로 마이그레이션한다.
다음 중 하나라도 해당되면 도입 검토:
- 등록된 소리 파일이 5개 이상 쌓임
- 소리 교체·테스트 빈도가 높아져 배포 번거로움이 느껴짐
- BE가 도입되어 기기 간 동기화가 가능해짐
/settings/sounds (공통 사운드 관리 화면, 신규)
↓ 공유 리소스
/tools/timer ← 드롭다운에서 선택
/planner/... ← 드롭다운에서 선택
핵심 원칙: 공통 관리 화면 1개 + 모듈별 선택 UI N개. 모듈은 등록에 관여하지 않는다.
- 사용자가
/settings/sounds로 진입한다. - "소리 추가" 버튼으로 mp3 파일을 업로드한다.
- 이름을 지정하고 미리듣기로 확인한다.
- 저장된 소리는 자동으로 모든 모듈의 선택 드롭다운에 나타난다.
- 필요 없는 소리는 삭제·이름변경할 수 있다.
┌─────────────────────────────────────┐
│ ← 설정 | 사운드 관리 │
├─────────────────────────────────────┤
│ [+ 소리 추가] │
│ │
│ ┌─ 기본 알림 (내장) ────────────┐ │
│ │ ▶ 미리듣기 │ │
│ └────────────────────────────────┘ │
│ │
│ ┌─ 벨소리 ──────────────────────┐ │
│ │ ▶ 미리듣기 ✎ 이름변경 🗑 삭제 │ │
│ └────────────────────────────────┘ │
└─────────────────────────────────────┘
LocalStorage는 Blob 저장 부적합 → IndexedDB 사용.
// IndexedDB 스키마 (구상)
// DB: orino
// Store: sounds
interface StoredSound {
id: string; // uuid
name: string; // 사용자 지정 이름
blob: Blob; // mp3 파일 내용
mimeType: string; // 'audio/mpeg'
createdAt: string; // ISO
source: 'user'; // 내장 vs 사용자 업로드 구분
}재생 시 Blob → URL.createObjectURL(blob) → HTMLAudioElement.src 로 사용.
- 기기 간 동기화 불가: IndexedDB는 브라우저·기기별 독립 (BE 도입 전까지)
- 크기 제한: 보통 브라우저당 수백 MB까지 가능하지만, mp3 파일 크기 가이드 제시 필요 (예: 1MB 이하)
- 파일 검증: 업로드 시 mime type + 실제 디코딩 가능 여부 확인
- 방식 A의 내장 사운드(
SOUNDS배열)는 유지. 방식 B에서 읽기 전용 기본 소리로 노출 - 사용자 업로드 소리는 IndexedDB에서 읽어 병합
- 모듈의 선택 UI는 내장 + 사용자 업로드를 하나의 목록으로 표시
- LocalStorage에 저장된
soundId는 그대로 유효 (레지스트리 조회만 변경)
방식 B 도입 시 별도 기획 + Issue 생성 필요:
-
/settings공통 설정 영역 신설 (라우트, 레이아웃) -
/settings/sounds관리 화면 - IndexedDB 스토리지 래퍼 (
shared/audio/storage.ts) - 업로드 유효성 검사·에러 핸들링
- 기존
useSound훅 확장 (IndexedDB blob 지원)
-
단위 테스트:
getSoundById,useSound훅의 play/stop 동작 - 통합 테스트: 모듈(Timer 등)에서 소리 선택 → 재생 확인
- 수동 테스트: 다양한 mp3 파일로 재생 품질, 볼륨, 동시 재생 확인