Skip to content

Roadmap

Jump to bottom
Alexander Refsum Jensenius edited this page Jul 28, 2026 · 12 revisions

Moved from the README so it can evolve without commits. Roughly ordered.

Near term

  • State-resolved descriptors (v0.8.0) — ambiscape resolve / resolve.machine_states / diel_states slice a multi-state session by machine band or wall clock and run the full summary on each state (states.json), so a drone night and a quiet morning stop averaging into one number.
  • Standard ratings & global indices (v0.5.0) — NR/NC/RC room criteria, intermittency ratio + emergence, the ecoacoustic battery (ACI, ADI/AEI, NDSI, BI, entropy H), EDT/C50/C80/D50, and spatial descriptors (directional entropy, horizon fractions, fg/bg direction overlap) appended to every analyze summary.
  • Catalog aggregation (v0.7.0) — ambiscape catalog collects all summary.json files in a corpus into one CSV + transposed Markdown table, with rank/outliers helpers for cross-session statistics.
  • Tests + CI — 26 pytest tests over a synthetic AmbiX fixture (BWF writer, plane waves, diffuse noise, phase-locked synthetic swinging bells); GitHub Actions on Python 3.10/3.12 (v0.2.0).

Analysis modules

  • Prototype loop (v0.21) — ambiscape loop: seamlessly loopable prototype segment, typicality-scored (median spectrum/level/event density of the take) with a seam term and an equal-power tail-into-head crossfade. load_features now carries per-row take identity so overlapping takes (Zoom + phone on one clock) are never mixed. Field validation: the 2026-07-28 Belgian train corpus (seam residuals 0.2--1.1 dB across five loops, incl. a 4-ch AmbiX station loop).

  • Resynthesis page (v0.21) — ambiscape resynth: a session's analysis distilled into a recipe driving four basic synthesis layers (octave-filtered noise bed, detuned oscillator pairs with measured AM, Poisson event bursts, cross-fed delay diffusion) rendered as one self-contained Web Audio HTML page — teaching material for analysis-by-synthesis.

  • Cyclic-machine detector — landed in v0.3.0 as the states module (band_level, state_segments, switch_points, duty_cycle) plus background.source_fingerprint for the on-state spectrum. Field validation: the Haarlem-loft case study (air-pump night states, fridge ~24 min duty cycle).

  • Tonal-event finder — landed as the rhythm module (strike detection from partial envelopes, point-process periodicity, phase clusters, repetition-vs-variation stats). Civic-schedule matching landed in v0.3.0 as schedule.grid_scan (targeted per-tick scans) alongside schedule.match_periods.

  • Wind/handling detector (v0.15.0) — landed as the geophony module's wind index (low-frequency energy weighted by ambisonic diffuseness: wind on the capsules is incoherent between channels), alongside a rain/water index (flat high-band hiss).

  • Source-domain detectors (v0.15.0) — first-class mechanical (low-freq fraction, rumble, envelope periodicity), anthropophony (voice-band, 3–8 Hz syllabic modulation, activity) and geophony modules, each merged into the analyze summary like biophony — the Krause/Schafer source taxonomy (geophony/biophony/anthropophony/ technophony) made measurable.

  • Schaeffer typo-morphology from features (v0.15.0) — draft now proposes mass (from spectral flatness) and facture (from continuity) with the evidence surfaced under _schaeffer, instead of leaving them "TODO".

  • Environmental-rhythm metric — a defensible single figure (or small vector) built from envelope power spectra at minute-to-hour scales, duty cycles, and state-alternation periods. The ingredients are now in place (the modulation profile, mechanical envelope-periodicity, the source decomposition); combining them into one honest figure is still open. Research question as much as feature.

  • Multi-band auto-state scan — from the Ghent house study (2026-07): analyze's automatic resolve pass caught the dishwasher (188–428 Hz pump comb, inside the default 250–1000 Hz band) but missed the fridge entirely, whose energy sits at 2–8 kHz (9.2 kHz line). Scan a small bank of bands (e.g. 63–250, 250–1000, 1000–4000, 2000–8000 Hz) for two-state structure and emit one named state per band that passes the gate, instead of trusting one band.

  • Duty-cycle descriptors in the summary — the Ghent fridge (8.2 min on / 35.9 min period / 23 % duty, ±4 min period wander across the night) was quantified by hand from the feature caches; states. duty_cycle already computes this, but nothing surfaces period / on-time / duty / period-jitter in summary.json or the README when a cyclic state is detected. Cheap and highly interpretable.

  • Guard ecoacoustic indices against machine hiss — the Ghent kitchen scored 17 % "biophony band activity" (30 % during machine-on, 97 % of machine-on minutes bird-active) that was fridge/dishwasher hiss in the 2–8 kHz band; narrowband bird peaks were 0.0/min. When the mechanical index is high or a machine state is active, flag or mask NDSI/ADI/bird-band figures in the README (the numbers are honest, the reading isn't).

  • Longitudinal / seasonal analysis (v0.10.0) — longitudinal module: trend + seasonal decomposition of dated session summaries across weeks/months/a year (the year-in-one-room path is many daily sessions → 365 tiny rows → inherently out-of-core).

  • Per-file scene mode (v0.10.0) — io.open_recording and ambiscape scenes <folder> for contributed corpora organized as independent recordings rather than folder-sessions (validated on the 41-scene Transcontinental set: all descriptors physically sensible).

Inputs & multimodal

  • Mono / stereo / binaural inputs (v0.13–v0.14) — non-ambisonic recordings analysed too: a lateral left/right cue recovered from stereo, first-class binaural ear-signal handling (opt-in via calibration.json), and a FuMa/AmbiX channel-order fix in the ISO binaural path (FuMa takes were decoded as AmbiX — wrong ears, wrong loudness/sharpness/roughness).
  • Visual / multimodal features (v0.12, wired v0.14) — the vision module (per-frame brightness / colour / light-direction / motion) and an ambiscape vision command that timestamps the visual stream onto the audio clock and folds vis_ keys into an existing summary.json.

Interop

  • AEM export adapter — write ambiviz-compatible AEM .npz for a selected excerpt so the hand-off needs no glue code.
  • BirdNET hook (v0.6.0) — species-level biophony on hi-fi windows (ml.birdnet_session, gated by diffuseness), optional [ml] companion to PANNs, plus a cache-based biophony module (narrowband activity, temporal entropy, band activity, spatial dispersion) for corpus-wide structural biophony without ML.
  • CLAP zero-shot search — free-text queries ("compressor hum", "door slam") across a corpus's cached features/excerpts.

Publishing

  • PyPI (trusted publishing) — currently v0.15.0
  • Documentation site (MkDocs → GitHub Pages)
  • Zenodo DOI per release (GitHub–Zenodo integration)
  • JOSS or similar software paper once tests + state-resolution land

Clone this wiki locally