# Phase 3: Processed Audio Source Model

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

## Objective
Add the `ProcessedAudioSource` type, rename `MultichannelAudioSource` to `CaptureAudioSource`, remove `MonoAudioSource` and `BandExtractAudioSource`, and update the store's resolution logic.

## Tasks

- [x] Task 1: Rename `MultichannelAudioSource` → `CaptureAudioSource` in `storage/audio_source.py`
  - Change class name, update `source_type` default to `"capture"`
  - Same fields: `device_index`, `is_loopback`, `audio_template_id`
- [x] Task 2: Add `ProcessedAudioSource` dataclass in `storage/audio_source.py`
  - Fields: `audio_source_id: str` (input source), `audio_processing_template_id: str`
  - `source_type` = `"processed"`
  - Inherits standard base fields (id, name, description, tags, created_at, updated_at)
- [x] Task 3: Remove `MonoAudioSource` class entirely
- [x] Task 4: Remove `BandExtractAudioSource` class entirely
- [x] Task 5: Update `create_audio_source()` factory function to handle new types
- [x] Task 6: Update `AudioSourceStore` resolution logic:
  - `resolve_audio_source()` now returns: device info (from CaptureAudioSource at chain end) + ordered list of filter chains (from AudioProcessingTemplates along the chain)
  - Walk chain: ProcessedAudioSource → ... → CaptureAudioSource
  - Collect all audio_processing_template_ids in order
  - Cycle detection for ProcessedAudioSource chains
- [x] Task 7: Update `ResolvedAudioSource` dataclass:
  - Remove `channel` and `freq_low`/`freq_high` fields (handled by filters now)
  - Add `audio_processing_template_ids: List[str]` — ordered list of template IDs along the chain
- [x] Task 8: Update reference validation in store:
  - `ProcessedAudioSource.audio_source_id` must reference an existing audio source
  - `ProcessedAudioSource.audio_processing_template_id` must reference an existing template
  - Delete checks: can't delete a source referenced by another ProcessedAudioSource
  - Added `get_sources_referencing_template()` helper for template delete checks
- [x] Task 9: Update API schemas in `api/schemas/audio_sources.py`
  - Remove `MonoAudioSourceCreate/Update/Response` schemas
  - Remove `BandExtractAudioSourceCreate/Update/Response` schemas
  - Add `CaptureAudioSourceCreate/Update/Response` (rename from Multichannel)
  - Add `ProcessedAudioSourceCreate/Update/Response`
  - Update discriminated union to use new type literals
- [x] Task 10: Update API routes in `api/routes/audio_sources.py`
  - Handle new source types in create/update endpoints
  - Remove handling of old types
  - Update WebSocket test endpoint to work with new resolution (no channel/band)
- [x] Task 11: Update any imports/references across the codebase that reference the old types

## Files to Modify/Create
- `storage/audio_source.py` — **modify** — rename, add, remove dataclasses
- `storage/audio_source_store.py` — **modify** — new resolution logic, validation
- `storage/audio_template_store.py` — **modify** — CaptureAudioSource import
- `api/schemas/audio_sources.py` — **modify** — new schemas
- `api/routes/audio_sources.py` — **modify** — handle new types
- `core/processing/audio_stream.py` — **modify** — remove channel/band logic
- `core/processing/value_stream.py` — **modify** — remove channel logic
- `core/demo_seed.py` — **modify** — update demo data to new types
- `storage/color_strip_source.py` — **modify** — update comment
- `storage/value_source.py` — **modify** — update comment
- `static/js/types.ts` — **modify** — new TS interfaces
- `static/js/core/icons.ts` — **modify** — new icon mapping
- `static/js/core/graph-nodes.ts` — **modify** — new icon mapping
- `static/js/features/audio-sources.ts` — **modify** — new source types
- `static/js/features/streams.ts` — **modify** — new card sections
- `static/js/features/value-sources.ts` — **modify** — badge text
- `static/js/features/color-strips.ts` — **modify** — badge text, navigation
- `static/js/core/command-palette.ts` — **modify** — navigation mapping

## Acceptance Criteria
- [x] `CaptureAudioSource` replaces `MultichannelAudioSource` (same behavior, new name/type)
- [x] `ProcessedAudioSource` can be created referencing a source + template
- [x] `MonoAudioSource` and `BandExtractAudioSource` are fully removed
- [x] Chain resolution walks ProcessedAudioSource → ... → CaptureAudioSource correctly
- [x] Cycle detection prevents circular source references
- [x] Reference validation prevents dangling references
- [x] API accepts/returns new type discriminators

## Notes
- Clean-slate: no migration of existing data. Old source type records will be lost.
- The `source_type` string changes from `"multichannel"` to `"capture"` — this is a breaking change but acceptable for clean-slate.
- `ResolvedAudioSource` is consumed by `AudioColorStripStream` and `AudioValueStream` — they will need updates in Phase 4.
- Template reference checks in the store need coordination with `AudioProcessingTemplateStore` — may need to pass it as a dependency.

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

## Handoff to Next Phase

### What was built
- `CaptureAudioSource` replaces `MultichannelAudioSource` (class + source_type "capture")
- `ProcessedAudioSource` added with `audio_source_id` + `audio_processing_template_id` fields
- `MonoAudioSource` and `BandExtractAudioSource` fully removed from model, store, schemas, routes, and all frontend references
- `ResolvedAudioSource` now returns `audio_processing_template_ids: List[str]` instead of `channel`/`freq_low`/`freq_high`
- Chain resolution walks ProcessedAudioSource → ... → CaptureAudioSource, collecting template IDs in order (outermost first)
- Cycle detection for both create and update operations
- `get_sources_referencing_template()` helper added for template delete checks
- All frontend TS files updated: types, icons, card sections, navigation, command palette

### What Phase 4 needs to know
- `ResolvedAudioSource` now has `audio_processing_template_ids` field — Phase 4 must resolve these to `FilterInstance` lists and instantiate/apply them in the stream runtime
- `AudioColorStripStream._pick_channel()` currently returns raw `analysis.spectrum, analysis.rms` — Phase 4 must wire filter processing here
- `AudioValueStream._pick_rms()` and `_pick_peak()` currently return raw analysis values — Phase 4 must apply filter chain
- Both streams store `self._audio_processing_template_ids` for use by Phase 4
- The WebSocket test endpoint also needs filter application wired in Phase 4

### Temporary breakages (resolved in Phase 4)
- Channel selection removed from `AudioColorStripStream._pick_channel()` — always uses mono mix
- Channel selection removed from `AudioValueStream._pick_rms()` and `_pick_peak()` — always uses mono
- These were previously handled by MonoAudioSource/BandExtractAudioSource; now handled by channel_extract/band_extract filters in ProcessedAudioSource chains

### Known deviations from plan
- Task 7: Used `audio_processing_template_ids: List[str]` (template IDs) rather than `filter_instances: List[FilterInstance]` — runtime resolution deferred to Phase 4
- Task 8: Template reference validation at create time not implemented (would require injecting AudioProcessingTemplateStore as dependency) — deferred to Phase 4 or Phase 7
- Frontend was also updated comprehensively (not just backend) to avoid broken UI