84 lines
4.1 KiB
Markdown
84 lines
4.1 KiB
Markdown
# Audio Library
|
|
|
|
Workstream 13 — a flexible classroom-timer sound library. A row is one of three
|
|
**kinds**: an uploaded `file`, an external `url`, or a synthesized `recipe`.
|
|
|
|
## Purpose
|
|
|
|
`director` / `office_manager` / `teacher` add library entries; any campus staff
|
|
(`director`, `office_manager`, `teacher`, `support_staff`) can pick one to play in
|
|
the classroom timer. The existing **built-in timer sounds stay hardcoded global
|
|
defaults** for every organization — their metadata lives in frontend static
|
|
constants and they are synthesized client-side, so they are not duplicated here.
|
|
New library entries are **campus-scoped**.
|
|
|
|
The **"Generate"** button in the timer creates a `recipe` row: a JSON set of
|
|
synthesis parameters played purely via the Web Audio API (no file, no network).
|
|
Until an AI key is wired, the recipe is produced by a local stub
|
|
(`business/audio-files/generate.ts`); only that function's body changes when the
|
|
key lands — the persistence, playback and library wiring are the same.
|
|
|
|
## Entity
|
|
|
|
`audio_files`: `title`, `kind` (`file` | `url` | `recipe`), `url` (nullable —
|
|
set for `file`/`url`), `recipe` (nullable JSONB — set for `recipe`), `is_default`
|
|
(false for campus rows; reserved for future platform-global rows), nullable
|
|
`organizationId` + `campusId`. A null `organizationId` denotes a global row
|
|
visible to everyone. Exactly one of `url` / `recipe` is populated, matching
|
|
`kind` (validated in the service).
|
|
|
|
For a `file` row, the binary is uploaded first through the JWT-authenticated file
|
|
subsystem (`POST /api/file/upload/...`) and `url` references it. Downloads are
|
|
JWT-only after the customer decision to remove per-file ownership checks. A `url`
|
|
row holds an external link. A `recipe` row never touches the file subsystem.
|
|
|
|
## Routes (`/api/audio_files`)
|
|
|
|
- `GET /` — list the caller's campus rows **plus** global defaults
|
|
(`organizationId` null). Requires `READ_AUDIO_FILES`.
|
|
- `POST /` — add a `file` / `url` / `recipe` row (campus-scoped). Requires
|
|
`MANAGE_AUDIO_FILES`. Body `{ data: { kind, title, url? , recipe? } }`.
|
|
- `PUT /:id`, `DELETE /:id` — edit/remove an own-organization row (never a
|
|
global default). Requires `MANAGE_AUDIO_FILES`.
|
|
|
|
## Authorization
|
|
|
|
- `READ_AUDIO_FILES` — seeded for the campus audio-library audience.
|
|
- `MANAGE_AUDIO_FILES` — `director`, `office_manager`, `teacher` (not
|
|
`support_staff`, who is read/play-only).
|
|
|
|
Non-global users can only manage rows in their own organization; global defaults
|
|
(`organizationId` null) are read-only to them. List/scope is enforced in the
|
|
service via the shared access helpers.
|
|
|
|
## Frontend wiring
|
|
|
|
The classroom-timer sound picker (`business/classroom-timer`) merges the
|
|
hardcoded built-ins with the `audio_files` library and groups them by origin —
|
|
**Built-in** / **Generated** / **Uploaded** — for clear structure. Playback
|
|
branches by kind: `builtin` → `playBuiltInSound(id)`, `recipe` →
|
|
`playRecipe(recipe)` (`business/classroom-timer/audio-recipe.ts`), `file`/`url` →
|
|
`new Audio(url)`. Users with `MANAGE_AUDIO_FILES` see a **Generate** button and
|
|
a delete affordance on their own rows; global defaults are read-only.
|
|
|
|
## Tests
|
|
|
|
- **Unit** (`npm test`): `audio-access.test.ts` (visibility/management rules) and
|
|
`shared/constants/audio-files.test.ts` (the `file`/`url`/`recipe` kinds +
|
|
`isAudioFileKind`).
|
|
- **Frontend unit** (`vitest`): `business/audio-files/generate.test.ts` (the
|
|
local recipe stub shape).
|
|
- **Seeded e2e** (`frontend/tests/e2e/audio-files.seeded.e2e.ts`,
|
|
`npm run test:e2e:content`): create/persist + same-campus read, `support_staff`
|
|
read-only, and external-role lockout.
|
|
|
|
## Open / deferred
|
|
|
|
- **Binary `file` upload UI** — the typed upload client now exists, so the audio
|
|
upload affordance can be wired when desired. `recipe` and external `url` rows
|
|
are unaffected (no `/file/download`).
|
|
- **AI generation** — swap the local `generateSoundRecipe` stub for a real model
|
|
call once an AI key is available; the rest of the pipeline is unchanged.
|
|
- If platform-global audio rows are later added, keep deletion/editing restricted
|
|
to platform-owned rows; download itself is already JWT-only.
|