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

Phase 5: Frontend — Audio Processing Templates

Status: ✅ Done Parent plan: 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

• 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
• 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()
• 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
• 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
• Task 6: Register module in app.ts / global exports for inline onclick handlers
• 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

• All tasks completed (except Task 4 deferred)
• Code follows project conventions
• 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)