Recipes

Task-oriented walkthroughs. Commands assume pip install "ambiscape[iso,ml]".

Analyze an overnight home session end-to-end

ambiscape probe   NIGHT/                 # sanity: takes, clock, convention
ambiscape analyze NIGHT/ --notes "living room, window closed, HVAC on"
# read NIGHT/README.md, look at analysis/overview.png:
#   - steady lanes = machines; find the on/off transitions
#   - anglegram ridge = where the dominant source sits
ambiscape draft   NIGHT/                 # regimes + events + tag hints
# listen to the hinted moments, edit -> annotations.json
ambiscape taxonomy NIGHT/                # Schaeffer map + Schafer timeline
ambiscape iso     NIGHT/                 # loudness/sharpness/roughness

Verify a B-format file's channel convention

ambiscape probe FOLDER/        # prints ambix|fuma per take (from zTRK tags)

No tags? Compute an azimuth histogram: a distribution hugging 0°/180° across varied content means the horizontal decode is getting a vertical channel — wrong map.

T60 from a clap

import ambiscape as asc
sess = asc.open_session("FOLDER")
x, fs = asc.read_span(sess, t0=CLAP_TIME - 2, dur=6)
print(asc.decay_time(x[:, 0], fs))   # {band: (T60, dynamic_range_dB)}

Trust bands with ≥ 30 dB dynamic range where T20/T30-style fits agree. Remember the field rule: 5 s of stillness around the clap.

Compare many sessions

Every analyze writes analysis/summary.json. Aggregate:

import json, pathlib, pandas as pd
rows = {p.parent.parent.name: json.load(open(p))
        for p in pathlib.Path(".").glob("*/analysis/summary.json")}
print(pd.DataFrame(rows).T[["leq_dbfs", "dynamics_L10_L90",
                            "diffuseness_median", "azimuth_R"]])

Prepare excerpts for publication (e.g., Freesound)

1. asc.pick_segments(F) or choose by ear; cut with ffmpeg (-c copy keeps the 4-channel stream bit-exact).
2. ambiscape speechgate SEGMENTS/ — every file must PASS.
3. Convert to FLAC (ffmpeg -i seg.wav -c:a flac seg.flac) — lossless, half the size, keeps all channels.
4. Tag ambisonic b-format ambix (Freesound detects 4-channel B-format and provides the binaural spatial player); one pack per location; coarse geotags for home locations; CC license chosen once for the series.

Hand off to ambiviz

pip install "ambiscape[viz]"

Extract a short excerpt (above), then use ambiviz's aem, anglegram, or directogram on it directly — the excerpt is exactly the "loadable file" ambiviz is built for.