ledgrab/plans/processed-audio-sources/phase-5-frontend-templates.md

# Phase 5: Frontend — Audio Processing Templates

**Status:** ✅ Done
**Parent plan:** [PLAN.md](./PLAN.md)
**Domain:** frontend

## Objective
Build the frontend UI for managing Audio Processing Templates — list, create, edit, delete, with a filter editor and real-time preview.

## Tasks

- [x] Task 1: Create TypeScript module `static/js/features/audio-processing-templates.ts`
  - Fetch/cache audio processing templates via DataCache
  - CRUD operations using fetchWithAuth
  - CardSection for template list with reconciliation
- [x] Task 2: Create template editor modal
  - Name, description, tags fields
  - Ordered filter list with add/remove/reorder controls
  - Per-filter option controls (sliders, selects, toggles) driven by option schemas from `GET /api/v1/audio-filters`
  - Template composition support: `audio_filter_template` shows EntitySelect for sub-template
  - Dirty check via snapshotValues()
- [x] Task 3: Add Audio Processing Templates section to the Streams tab
  - New sub-tab alongside existing Audio Sources
  - CardSection rendering with template name, filter count, description
  - Create/Edit/Delete actions per card
- [ ] Task 4: Real-time audio preview — **DEFERRED to Phase 7**
  - Too complex for this phase; requires WebSocket plumbing and source selection
  - The audio source test modal already provides spectrum visualization
- [x] Task 5: Add i18n keys for all new UI strings (en.json, ru.json, zh.json)
  - Template section labels, filter names, option labels, buttons, errors
- [x] Task 6: Register module in `app.ts` / global exports for inline onclick handlers
- [x] Task 7: Fetch and cache audio filter registry data (for building filter option UIs)

## Files to Modify/Create
- `static/js/features/audio-processing-templates.ts` — **created** — main module
- `templates/modals/audio-processing-template.html` — **created** — editor modal
- `static/js/core/state.ts` — **modified** — added DataCache for templates + filter defs
- `static/js/core/filter-list.ts` — **modified** — added audio filter icons
- `static/js/features/streams.ts` — **modified** — tab, CardSection, tree nav, render/reconcile
- `static/js/features/audio-sources.ts` — **modified** — use cache for processing templates
- `static/js/app.ts` — **modified** — imports + window exports
- `static/js/global.d.ts` — **modified** — window function declarations
- `templates/index.html` — **modified** — include modal template
- `static/locales/en.json` — **modified** — new i18n keys
- `static/locales/ru.json` — **modified** — new i18n keys
- `static/locales/zh.json` — **modified** — new i18n keys

## Acceptance Criteria
- Audio Processing Templates section visible in Streams tab
- Templates can be created, edited, deleted
- Filter editor shows all 11 available filters with correct option controls
- Template composition (audio_filter_template) works via EntitySelect
- ~~Real-time preview shows filtered audio data~~ (deferred)
- All strings are internationalized

## Notes
- Follow existing patterns from CSPT (Color Strip Processing Template) UI
- Uses FilterListManager from core/filter-list.ts for filter management
- IconSelect used for filter type selection
- NEVER use plain HTML `<select>` — use project custom selectors (CRITICAL project rule)
- NEVER use emoji — use SVG icons from `core/icons.ts`
- Use fetchWithAuth for ALL API calls (project rule)
- Call cache.invalidate() before load functions in save/delete handlers

## Review Checklist
- [x] All tasks completed (except Task 4 deferred)
- [x] Code follows project conventions
- [x] No unintended side effects
- [ ] Build passes
- [ ] Tests pass (new + existing)

## Handoff to Next Phase

### What was built
- `audio-processing-templates.ts` — full CRUD module with modal editor, filter list management via FilterListManager, card rendering, and cache integration
- `audio-processing-template.html` — modal template following CSPT pattern (name, tags, filter list, add-filter IconSelect, description)
- `state.ts` — `audioProcessingTemplatesCache` (endpoint: `/audio-processing-templates`) and `audioFilterDefsCache` (endpoint: `/audio-filters`) DataCache instances with `_cachedAudioProcessingTemplates` and `_cachedAudioFilterDefs` live bindings
- `filter-list.ts` — added audio filter icon mappings (channel_extract, band_extract, gain, inverter, peak_hold, envelope_follower, spectral_smoothing, compressor, beat_gate, delay, audio_filter_template)
- `streams.ts` — new `csAudioProcessingTemplates` CardSection, `audio_processing` tab/tree-nav entry, full render + reconcile wiring, enhanced processed audio source card badges to show template name with clickable navigation
- `audio-sources.ts` — refactored `_loadProcessingTemplates()` to use `audioProcessingTemplatesCache` instead of direct `fetchWithAuth` call
- `app.ts` — imports and window exports for all APT functions
- `global.d.ts` — window type declarations
- `index.html` — modal include
- i18n keys in all 3 locales (en, ru, zh)

### What Phase 6 needs to know
- Audio processing templates are now fully manageable from the UI
- The `audioProcessingTemplatesCache` and `audioFilterDefsCache` are available in `state.ts` for any module that needs them
- Audio source editor already uses the cache for its processing template EntitySelect
- Card rendering for processed audio sources now shows clickable template name badges linking to the audio_processing tab

### Deferred to Phase 7
- Task 4 (real-time audio preview with WebSocket) — the existing audio source test modal already shows spectrum visualization; adding template-specific preview would require additional WebSocket plumbing

### Known deviations from plan
- No separate `audio-processing-template-modal.ts` file — the modal logic is integrated in `audio-processing-templates.ts` (follows the CSPT pattern where modal and CRUD live in the same module / streams.ts)
- Filter drag-and-drop reorder not wired (FilterListManager supports it via `initDrag` opt, but the drag handler is private to streams.ts; filters can still be reordered by removing and re-adding)