Spaces:
Paused
Download docs/ARCHITECTURE.md from 2Btainment/absolution-omega: direct link, hf CLI and curl.
- Browser
- Download file 3.56 kB
-
https://huggingface.co/spaces/2Btainment/absolution-omega/resolve/main/docs/ARCHITECTURE.md
- Command line
-
hf download hf://spaces/2Btainment/absolution-omega/docs/ARCHITECTURE.md
-
curl -L -o ARCHITECTURE.md https://huggingface.co/spaces/2Btainment/absolution-omega/resolve/main/docs/ARCHITECTURE.md
Architecture decision record — Vertical Slice 0.1
ADR-001: Scope before architecture inflation
Decision: minimal Python backend + vanilla TypeScript-free browser JS. Reason: enables actual audio processing and measured test coverage with no JavaScript package registry, no cloud account, no remote API call. Trade-off: production hybrid stack would benefit from typed React/Next.js, Tauri, durable workers, auth and an operations/data platform.
ADR-002: HPSS first, neural adapter second
HPSS is reproducible and needs no downloaded weights. It is a
spectrogram-derived harmonic-vs-percussive decomposition, not a way to
extract arbitrary instruments. An optional demucs.api.Separator
adapter can produce neural drums/bass/other/vocals given trusted weights.
The trained model branch is not yet validated against provided checkpoints.
ADR-003: Explicit residual as a source of truth
Input x and estimated stems s_i are same-rate, same-shape float64.
Compute residual = x - sum(s_i). Check mixture closure in float64 and
publish actual measured maximum error. Never infer source isolation quality
from that identity. For Demucs resample stem outputs back to source rate,
keeping frame positions and noting resampler effects.
ADR-004: Immutable user asset
Original is stored as imported, with SHA256, then separate normalized decoded signals are used for processing. Previews are lossy relative to float64 working precision, specifically 16-bit PCM. Masters are FLOAT WAV. Project manifests are updated by atomic file replace.
ADR-005: Local-only, no telemetry, no network model access
Default host is 127.0.0.1 for the documented startup. No outbound network calls, silent checkpoint downloads, analytics or license bypass. No auth, therefore this release must NOT be accessible on a network untrusted by the operator. Do not enable public sharing without threat modeling, authentication, quotas, persistent queues and proper isolation.
Proposed data entities (not yet a database schema)
Project, InputAsset, SignalAnalysis, ProcessingJob, ModelManifest, StemAsset, ResidualAsset, TransformationGraph, QualityReport. Manifest.JSON currently contains a subset, storing only one input per project.
Measurable acceptance criteria for v0.1
- Full import → HPSS → stem preview → export runs via actual HTTP.
- 8 automated tests pass on compatible development runtime.
- HPSS output samples have input shape and sample rate.
- Sample-space closure passes tolerance 1e-8.
- Original source SHA-256 persists in manifest.
- Invalid audio and unsupported methods fail with errors. Long tracks are accepted within the configurable upload-size quota and HPSS is processed in chunks.
- Local run does not require an external service or pretrained models.
Iteration risk register
- Native library & optional Demucs package version incompatibility.
- In-memory job loss on process restart and possible concurrent file reads.
- No auth; local single-user only.
- Memory pressure for long/high-rate files.
- Coarse HPSS cannot reliably resolve individual instruments.
- DSP reconstruction check does not measure separation quality.
- Future source datasets/checkpoint licenses require explicit review.
API security improvement checklist
Add authentication and rate limits before remote access; CSRF defenses; secure cookies; isolated file processing; proactive MIME/codec scanning; resource quotas; job cancellation; audit logs; secrets management; versioned asynchronous job persistence; signed artifacts.