Skip to content

Shared Audio

wcorn edited this page Apr 5, 2026 · 1 revision

공통 사운드 시스템

여러 모듈(Tools, Planner 등)이 공유하는 오디오 재생 인프라.

1. 개요

목적

앱 전역에서 사용하는 알림음·효과음을 중앙에서 관리한다. 모듈별로 별도의 오디오 로직을 구현하지 않는다.

사용처

  • Tools: 메이플 재획 타이머 알림음
  • Planner (예정): 일정·루틴 알림, 복습 알림
  • 추후 추가되는 모든 모듈의 사운드 피드백

파일 형식

mp3로 통일한다. 브라우저 호환성과 용량 효율이 가장 좋다.

2. 현재 구현 (방식 A: 개발자 등록)

운영 초기 단계에서 채택한 방식. 소리 파일은 정적 에셋으로 배포하고, 코드 레지스트리로 관리한다.

2.1 폴더 구조

fe/public/sounds/                # 정적 에셋 (mp3 파일)
  └── *.mp3

fe/src/shared/audio/
  ├── sounds.ts                  # SoundAsset 레지스트리
  ├── useSound.ts                # 재생 훅
  └── types.ts

2.2 레지스트리

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);
}

2.3 재생 훅

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으로 리셋 후 재생

2.4 사용 예시

// Tools Timer에서
const { play } = useSound({
  soundId: config.soundId ?? DEFAULT_ALERT_SOUND_ID,
  volume: config.soundVolume,
});

// 알림 시점에
play();

2.5 모듈에서의 선택 UI

각 모듈은 선택만 한다. 등록은 개발자가 한다.

<Select value={soundId} onValueChange={setSoundId}>
  {SOUNDS.map(s => (
    <SelectItem key={s.id} value={s.id}>{s.name}</SelectItem>
  ))}
</Select>
<Button onClick={() => play()}>미리듣기</Button>

2.6 새 소리 추가 절차

  1. 파일을 fe/public/sounds/{name}.mp3 에 배포
  2. fe/src/shared/audio/sounds.ts SOUNDS 배열에 한 줄 추가
  3. (선택) 기본값을 바꾸려면 DEFAULT_ALERT_SOUND_ID 수정
  4. 배포

2.7 LocalStorage 저장 규칙

각 모듈은 사용자가 선택한 soundId를 자체 설정 키에 저장한다.

// 예: Tools Timer
interface TimerLastConfig {
  // ... 기타 설정
  soundId: string;        // SOUNDS 레지스트리의 id
  soundVolume: number;    // 0.0 ~ 1.0
}
  • 저장된 soundId가 현재 레지스트리에 없을 경우 DEFAULT_ALERT_SOUND_ID로 폴백

3. 향후 확장 (방식 B: 사용자 관리 화면)

소리 파일 수가 늘거나, 코드 배포 없이 자유롭게 관리하고 싶어지면 방식 B로 마이그레이션한다.

3.1 트리거 조건 (도입 시점 판단 기준)

다음 중 하나라도 해당되면 도입 검토:

  • 등록된 소리 파일이 5개 이상 쌓임
  • 소리 교체·테스트 빈도가 높아져 배포 번거로움이 느껴짐
  • BE가 도입되어 기기 간 동기화가 가능해짐

3.2 개념

/settings/sounds (공통 사운드 관리 화면, 신규)
  ↓ 공유 리소스
/tools/timer         ← 드롭다운에서 선택
/planner/...         ← 드롭다운에서 선택

핵심 원칙: 공통 관리 화면 1개 + 모듈별 선택 UI N개. 모듈은 등록에 관여하지 않는다.

3.3 유스케이스

  1. 사용자가 /settings/sounds 로 진입한다.
  2. "소리 추가" 버튼으로 mp3 파일을 업로드한다.
  3. 이름을 지정하고 미리듣기로 확인한다.
  4. 저장된 소리는 자동으로 모든 모듈의 선택 드롭다운에 나타난다.
  5. 필요 없는 소리는 삭제·이름변경할 수 있다.

3.4 화면 설계 (초안)

┌─────────────────────────────────────┐
│  ← 설정  |  사운드 관리              │
├─────────────────────────────────────┤
│  [+ 소리 추가]                      │
│                                     │
│  ┌─ 기본 알림 (내장) ────────────┐   │
│  │  ▶ 미리듣기                    │   │
│  └────────────────────────────────┘  │
│                                     │
│  ┌─ 벨소리 ──────────────────────┐   │
│  │  ▶ 미리듣기  ✎ 이름변경  🗑 삭제 │  │
│  └────────────────────────────────┘  │
└─────────────────────────────────────┘

3.5 저장소: IndexedDB

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 로 사용.

3.6 제약

  • 기기 간 동기화 불가: IndexedDB는 브라우저·기기별 독립 (BE 도입 전까지)
  • 크기 제한: 보통 브라우저당 수백 MB까지 가능하지만, mp3 파일 크기 가이드 제시 필요 (예: 1MB 이하)
  • 파일 검증: 업로드 시 mime type + 실제 디코딩 가능 여부 확인

3.7 방식 A와의 호환성 (마이그레이션)

  • 방식 A의 내장 사운드(SOUNDS 배열)는 유지. 방식 B에서 읽기 전용 기본 소리로 노출
  • 사용자 업로드 소리는 IndexedDB에서 읽어 병합
  • 모듈의 선택 UI는 내장 + 사용자 업로드를 하나의 목록으로 표시
  • LocalStorage에 저장된 soundId는 그대로 유효 (레지스트리 조회만 변경)

3.8 구현 시 필요 작업

방식 B 도입 시 별도 기획 + Issue 생성 필요:

  • /settings 공통 설정 영역 신설 (라우트, 레이아웃)
  • /settings/sounds 관리 화면
  • IndexedDB 스토리지 래퍼 (shared/audio/storage.ts)
  • 업로드 유효성 검사·에러 핸들링
  • 기존 useSound 훅 확장 (IndexedDB blob 지원)

4. 테스트 전략

  • 단위 테스트: getSoundById, useSound 훅의 play/stop 동작
  • 통합 테스트: 모듈(Timer 등)에서 소리 선택 → 재생 확인
  • 수동 테스트: 다양한 mp3 파일로 재생 품질, 볼륨, 동시 재생 확인

Clone this wiki locally