docs/TASKS.md

Task ledger

Last updated: 2026-05-12

Completed in current pass: API validation and visible errors

• Fix /api/jobs rejecting UI-submitted subdivision values such as "16".
• Add defensive backend coercion for integer, float, and boolean pipeline parameters.
• Convert frontend control values according to /api/config.defaults before submitting jobs.
• Add a global visible error banner for failed API/network requests.
• Surface extraction-start failures in the summary and Pipeline log panels.
• Add regression coverage in scripts/test_param_validation_and_api_errors.py.

User-requested tasks

Task	Status	Evidence
Review the project	Done	docs/PROJECT_REVIEW.md.
Determine length of significant subprocesses	Done	pipeline_runner.py, scripts/benchmark_subprocesses.py, docs/benchmark-subprocesses.json, docs/PIPELINE_TIMING_AND_REALTIME.md.
Identify near-realtime subprocesses	Done	docs/PIPELINE_TIMING_AND_REALTIME.md.
Add documentation to project	Done	docs/*.md, updated README.md.
Replace Gradio UI	Done	Active app is FastAPI + custom web UI; Gradio moved to legacy/.
Document features, tasks, and progress	Done	docs/FEATURES.md, this file, docs/PROGRESS.md.
Continue development while keeping docs up-to-date	In progress	Latest pass adds SSE progress, per-hit review artifacts, hit/sample audition, hardened artifact serving, and docs updates.

Completed implementation tasks

• Preserve old Gradio apps in legacy/.
• Expose extraction as a FastAPI job API.
• Serve a custom browser UI from web/.
• Add per-stage timing to the pipeline.
• Write per-run manifest.json.
• Add synthetic benchmark script.
• Add API documentation.
• Add UI replacement documentation.
• Add project review and realtime analysis documentation.
• Add run-history listing endpoint: GET /api/jobs.
• Add run-history UI panel.
• Add disk cache for stem/full-mix loads.
• Extend cache clearing to disk cache.
• Add prototype-based online_preview clustering mode.
• Add UI controls for clustering mode and disk cache.
• Fix duplicate sample writes in build_archive.
• Add feature, task, and progress docs.
• Add GET /api/jobs/{id}/events SSE progress stream.
• Add per-hit review WAV export under review/hits/.
• Add manifest hits rows with onset, duration, cluster, representative flag, and artifact path.
• Add click-to-audition for waveform onset markers and detected hit rows.
• Add sample-row audition controls.
• Harden artifact path containment with Path.relative_to().
• Add hit review/streaming documentation.

Validation tasks

• Python compile check for active Python files.
• FastAPI smoke test for health/config/job flow.
• Pipeline smoke test on synthetic audio.
• API history/cache smoke test.
• SSE and review-hit artifact smoke test via scripts/test_sse_and_review_hits.py.
• Git status reviewed before packaging.
• Project archive excludes .runs/, .cache/, and dependency folders.

Remaining high-value tasks

• Add onset adjustment and rerun-from-onsets flow.
• Add cluster merge/split/relabel workflow.
• Add side-by-side run comparison.
• Convert frontend to TypeScript with a small Vite build once UX stabilizes.
• Add automated browser-level UI tests.

Interactive UX continuation tasks

Task	Status	Evidence
Add supplied interactive UX docs under docs/interactive-ux/	Done	docs/interactive-ux/*.md.
Read and align UX docs with current implementation	Done	Status sections updated in every interactive UX document.
Add persistent semantic job state	Done	supervised_state.py, supervision_state.json.
Add event log and constraint store	Done	supervised_state.py; tested by scripts/test_interactive_supervision.py.
Add hit/cluster confidence and review queue	Done/Partial	Heuristic confidence and review queue implemented; feature-margin confidence remains open.
Add move hit to cluster	Done	POST /api/jobs/{job_id}/hits/{hit_id}/move.
Add pull hit into new cluster	Done	POST /api/jobs/{job_id}/hits/{hit_id}/pull-out.
Add cluster lock/unlock	Done	POST /api/jobs/{job_id}/clusters/{cluster_id}/lock.
Add suppress hit as bleed/noise	Done	POST /api/jobs/{job_id}/hits/{hit_id}/suppress.
Add accept/favorite hit action	Done	POST /api/jobs/{job_id}/hits/{hit_id}/review; supervised re-export honors pinned/favorite representatives.
Add suggestion inbox	Done/Partial	UI/API supports accept/reject; exact diff preview still open.
Add cluster explanation drawer	Done	GET /api/jobs/{job_id}/explain/cluster/{cluster_id} plus UI drawer.
Add semantic undo	Done	POST /api/jobs/{job_id}/undo.
Add supervised export from edited state	Done	supervised_export.py; POST /api/jobs/{job_id}/export; UI edited download links.
Add click-to-add missed onset	Done	Add-onset waveform mode creates forced hits from stem.wav.
Add suppressed-hit restore	Done	POST /api/jobs/{job_id}/hits/{hit_id}/restore; UI restore button.
Add exact suggestion diff previews	Done	Suggestions expose diff; UI has Diff preview.
Add true local feature-neighborhood reclustering	Todo	Requires cached feature vectors and constraint-aware assignment.

Visual simplification tasks

Task	Status	Notes
Restyle web UI to supplied minimal waveform-first reference	Done	Light theme, top-bar primary action, large waveform, compact right controls, sample-card grid, collapsible advanced/power panels.
Close remaining reference-alignment gaps	Done	Removed waveform header, added one custom transport row, moved fast modes into Advanced, collapsed power tools into Review & edit, hid visible audition players.

Latest validation tasks

• python3 -m py_compile app.py pipeline_runner.py sample_extractor.py supervised_state.py supervised_export.py scripts/*.py
• node --check web/app.js
• python3 scripts/test_api_job.py

Fixed workstation UI tasks

Task	Status	Notes
Remove document-level page scrolling	Done	html, body and .shell are viewport-locked; long content uses panel-local overflow.
Add left sidebar for secondary tools	Done	Source guidance, selection context, pipeline logs, and run history live in the left sidebar.
Add right sidebar for controls	Done	Core extraction, exports, and advanced model/DSP settings live in the right sidebar.
Add bottom bar for expandable editor panels	Done	Review/edit and raw tables live in bottom-dock.
Add explicit upload button	Done	Top bar now has a visible Upload audio control.
Make whole-app file dropping work	Done	Window-level drag/drop handlers select dropped files and prevent browser navigation.
Add drag overlay	Done	globalDropOverlay appears while dragging files over the app.

Pass 9 tasks: reproduced audio and parameter hierarchy

Task	Status	Notes
Export normalized source mix	Done	source.wav written per run.
Export non-target context bed	Done	context_bed.wav is source minus target stem; silent for stem=all.
Keep isolated target reconstruction	Done	target_reconstruction.wav written per run and per supervised export.
Make reproduced audio incorporate context	Done	reconstruction.wav is context bed plus target reconstruction.
Add full-context reproduction to ZIP	Done	rendered_reproduction_full_mix.wav plus compatibility alias.
Add target-stem reconstruction to ZIP	Done	rendered_reconstruction_target_stem.wav.
Update supervised export audio model	Done	Edited export writes full-context and target-only previews.
Add Source/Stem/Reproduced transport modes	Done	Transport buttons added in web/index.html and wired in web/app.js.
Separate common controls from advanced parameters	Done	Common controls: stem, sensitivity, sample groups, presets.
Group advanced parameters by pipeline stage	Done	Stem separation, hit detection, grouping, export/cache.

Remaining follow-up tasks:

• Add source-vs-reproduced waveform/error comparison.
• Add LUFS loudness matching for long previews.
• Optionally cache explicit Demucs non-target stem sums instead of residual subtraction.

Pass 10 tasks: clean default UI

Task	Status	Notes
Collapse secondary panels by default	Done	Source, selection, pipeline, history, exports, and review/edit no longer open on first load.
Make bottom dock compact by default	Done	Bottom dock is a small tab bar until Review & edit or Tables is opened.
Reduce top-bar visual weight	Done	Smaller brand mark, shorter upload control, compact backend status, smaller primary button.
Give center workspace more room	Done	Reduced sidebars/gaps/padding and collapsed bottom dock.
Hide long helper copy from common controls	Done	Common-control hint text is hidden; advanced descriptions remain in expandable sections.
Preserve no-scroll workstation behavior	Done	Body remains viewport-locked; panel-local scrolling remains.
Preserve all current features	Done	Existing DOM ids and API paths are preserved; changes are layout/CSS/default-open-state only.

Pass 11 tasks: immediate waveform and real progress flow

Task	Status	Notes
Show uploaded waveform immediately	Done	Browser decodes selected/dropped files with Web Audio and renders a peak envelope before extraction.
Preserve source preview playback before extraction	Done	Uploaded file object URL remains wired to the Source transport.
Add explicit sequential start flow	Done	Left sidebar Start here panel shows Load → Controls → Extract → Review/export.
Add top-level backend progress contract	Done	Job payloads include progress with fraction, stage, and work-unit fields.
Add stage progress fields	Done	StageTiming includes progress, work_done, and work_total.
Report Demucs chunk progress	Done	extract_stem() reports exact completed split chunks through progress_cb.
Render extraction progress on waveform	Done	Running jobs draw the uploaded/extracted waveform in completed and remaining colors.
Avoid guessed progress values	Done	UI consumes backend progress only; no ETA or timer interpolation is used.
Add docs for progress semantics	Done	See docs/IMMEDIATE_WAVEFORM_AND_REAL_PROGRESS.md.

Follow-up tasks:

• Add finer-grained callback progress inside onset detection.
• Add finer-grained callback progress inside clustering pair computation.
• Add browser-level tests for upload waveform rendering and progress tinting.

Automatic card-flow task batch

Completed:

• Start extraction automatically after file drop/upload.
• Keep immediate browser waveform rendering before backend work completes.
• Add automatic tuning stage after source/stem loading.
• Stream sample-card availability through partial_samples.
• Group cards by detected type.
• Add dismiss-card action.
• Add draw-another-candidate action for missing samples.
• Add simple trim/extend controls and save adjusted timing as forced hit.
• Add waveform zoom/pan interaction.
• Make MIDI export robust when pretty_midi is unavailable.

Next:

• Promote drawn candidate cards into backend representative choices.
• Add immediate local reclustering after dismiss/draw constraints.
• Add browser tests for the automatic card-flow path.

Reference image UI alignment

• Match top bar structure: brand, beta badge, current file, export buttons.
• Match main layout: waveform left, settings right, sample columns below.
• Keep automatic upload/process flow.
• Keep advanced controls hidden behind a collapsed expert section.
• Preserve existing review/edit tools in a secondary drawer.
• Implement true per-card selection and selected-only export artifacts.
• Run browser screenshot comparison in an environment that allows localhost rendering.

Selected cards and separation backends

Completed:

• Add Spleeter backend option.
• Default new jobs to Spleeter spleeter:4stems + drums.
• Keep Demucs as explicit quality/fallback backend.
• Add none backend for full-mix preview.
• Add optional requirements-spleeter.txt.
• Add per-card checkbox selection.
• Add selected-only backend export.
• Persist draw-next representative overrides.
• Rewrite preview audio immediately for trim/extend edits.
• Add regression smoke test for selected export/card actions.

Next:

• Add card-column relabel/merge/split actions.
• Add browser-level tests for card selection/export/edit flows.
• Add localized high-quality separation refinement on short candidate windows.

Upload/runtime fallback update (2026-05-12)

• Added a visible top-bar Choose audio affordance in addition to whole-app drag/drop.
• Fixed the default hidden state of the error banner so placeholder errors are not shown on page load.
• API errors now surface request path/status/detail in the visible banner and pipeline logs.
• /api/config now includes runtime diagnostics for optional separation backends.
• If Spleeter is unavailable, the simple UI keeps the app usable by switching to full-mix mode; backend fallback also uses full-mix rather than silently launching Demucs.