Classroom Timer Integration

Purpose

A visual countdown timer with sensory backgrounds and a sound library. Sounds come from three places, unified in one picker: hardcoded built-in synthesized sounds, generated sounds (recipe rows), and uploaded audio (file/url rows) from the audio_files library.

Current Behavior

frontend/src/components/frameworks/ClassroomTimer.tsx is a thin wrapper that takes userRole (from the shell) and calls useClassroomTimer(userRole).
Timer state, fullscreen, custom-time parsing, progress/urgency, particles, and Web Audio orchestration live in frontend/src/business/classroom-timer/. shared/constants/classroomTimer.ts keeps timing/particle config plus the sound-group labels and the generated/uploaded fallback icons.
View pieces are under frontend/src/components/classroom-timer/. The sound picker (TimerSettingsPanel) groups sounds by origin — Built-in / Generated / Uploaded — for clear structure.
Backgrounds/presets/tips and the built-in sound metadata are backend-owned content_catalog records loaded via the shared content-catalog API. The built-in sounds themselves are synthesized in-browser (business/classroom-timer/audio.ts, playBuiltInSound).
Missing content-catalog data renders an explicit backend error (no frontend seed fallback).

Audio Library

The picker merges the built-ins with the audio_files library (business/audio-files/):

API/types: shared/api/audioFiles.ts, shared/types/audioFiles.ts (incl. the SoundRecipe shape).
Hooks: useAudioFiles (list; retry: false so a caller without READ_AUDIO_FILES silently falls back to the built-ins), useGenerateAudioFile, useDeleteAudioFile. canManageAudioFiles gates the manage affordances (director/office_manager/teacher).
Playback branches by kind: builtin → playBuiltInSound(id), recipe → playRecipe(recipe) (business/classroom-timer/audio-recipe.ts, pure Web Audio from JSON params), file/url → new Audio(url).
Generate: managers type a name and click Generate; this creates a recipe row whose synthesis parameters come from a local stub (business/audio-files/generate.ts). When an AI key is wired, only that function changes — persistence, playback and the library list are unchanged. An empty name falls back to a generated name.
Delete: managers can remove their own (non-default) library rows.

Tests

business/classroom-timer/selectors.test.ts (timer math)
business/audio-files/selectors.test.ts (canManageAudioFiles), business/audio-files/generate.test.ts (local recipe stub shape)

Verification

npm run typecheck, npm run lint, npm run test pass.

Remaining Work

Swap the local generateSoundRecipe stub for a real model call once an AI key exists.
Binary file upload UI — needs a typed upload client and the file-download ownership fix (see backend/docs/audio-files.md); recipe/url rows are unaffected.

3.0 KiB Raw Blame History