Metadata-Version: 2.4
Name: ambiscape
Version: 0.15.1
Summary: Long-duration first-order ambisonic soundscape analysis (streaming companion to ambiviz)
Author-email: Alexander Refsum Jensenius <a.r.jensenius@imv.uio.no>
License: MIT
Project-URL: Repository, https://github.com/fourMs/ambiscape
Project-URL: Issues, https://github.com/fourMs/ambiscape/issues
Project-URL: Author ORCID, https://orcid.org/0000-0001-6171-8743
Project-URL: Companion toolbox (ambiviz), https://github.com/fisheggg/ambiviz
Keywords: ambisonics,soundscape,field-recording,acoustics,spatial-audio,long-duration,ISO-12913
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Multimedia :: Sound/Audio :: Analysis
Classifier: Intended Audience :: Science/Research
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.24
Requires-Dist: scipy>=1.10
Requires-Dist: soundfile>=0.12
Requires-Dist: matplotlib>=3.7
Provides-Extra: viz
Requires-Dist: ambiviz>=0.0.1; extra == "viz"
Provides-Extra: iso
Requires-Dist: mosqito>=1.2; extra == "iso"
Provides-Extra: music
Requires-Dist: librosa>=0.10; extra == "music"
Provides-Extra: capture
Requires-Dist: sounddevice>=0.4; extra == "capture"
Provides-Extra: ml
Requires-Dist: panns-inference>=0.1; extra == "ml"
Requires-Dist: silero-vad>=5.0; extra == "ml"
Requires-Dist: torch>=2.0; extra == "ml"
Requires-Dist: birdnetlib>=0.17; extra == "ml"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Dynamic: license-file

# ambiscape

[![PyPI version](https://img.shields.io/pypi/v/ambiscape)](https://pypi.org/project/ambiscape/)
[![Documentation](https://img.shields.io/badge/docs-fourms.github.io%2Fambiscape-blue)](https://fourms.github.io/ambiscape/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

Analysis toolkit for long-duration (hours) first-order ambisonic soundscape recordings (Zoom H3-VR and other AmbiX/SN3D B-format sources), processed in a stream with constant memory. Stereo, binaural, and mono recordings — including a phone's `.m4a` — are analysed too: a lateral left/right cue is recovered from stereo, and 2-channel binaural ear signals are handled directly (see [Mono, stereo & binaural inputs](https://fourms.github.io/ambiscape/guide/stereo-mono/)).

## Install

```bash
pip install ambiscape            # core
pip install "ambiscape[iso]"     # + ISO 532-1 loudness/sharpness/roughness
pip install "ambiscape[ml]"      # + AudioSet tagging, speech privacy gate
pip install "ambiscape[viz]"     # + ambiviz (HRIR binaural, AEM visuals)
```

## Quickstart

```bash
ambiscape probe      <session-folder>   # metadata
ambiscape analyze    <session-folder>   # features, descriptors, figures, README
ambiscape draft      <session-folder>   # pre-fill taxonomy annotations
ambiscape taxonomy   <session-folder>   # Schaeffer map + Schafer timeline
ambiscape rhythm     <session-folder>   # strike-level rhythm of periodic sources
ambiscape modspec    <session-folder>   # micro/meso/macro modulation profile
ambiscape tonality   <session-folder>   # tonal tracks, harmonicity, pitch classes
ambiscape spatial    <session-folder>   # direct/diffuse split, pass-bys, azimuth R(t)
ambiscape schedule   <session-folder>   # match events against civic time grids
ambiscape timbre     <session-folder>   # event timbre templates (no-ML clustering)
ambiscape music      <session-folder>   # librosa tempogram + chromagram [music]
ambiscape carillon   <session-folder>   # which bells a carillon played: strike-note inventory [music]
ambiscape vision     <video-or-folder>  # per-frame visual features (multimodal companion)
ambiscape iso        <session-folder>   # ISO 12913-3 indicators
ambiscape speechgate <wav-or-folder>    # privacy check before publishing
ambiscape deposit    <session-folder>   # non-identifying 1 Hz TSV export
ambiscape resolve    <session-folder>   # per-state descriptors (on/off, day/night)
ambiscape catalog    <corpus-folder>    # aggregate all summary.json -> CSV
ambiscape longitudinal <corpus-folder>  # trend + seasonal over dated sessions
ambiscape scenes     <folder>           # analyze each WAV as an independent scene
ambiscape capture    <root>             # always-on feature-extraction daemon [capture]
```

A *session* is a folder of WAVs on one absolute clock (BWF timestamps,
parsed natively); a single one-off recording opens as its own scene with
`open_recording(path)`. `analyze` produces a per-session `README.md` with a
descriptor table (Leq, LAeq, L10/L50/L90, events, diffuseness ψ, azimuthal
concentration R, …) and overview figures (level + spectrogram + anglegram +
ψ timeline, percentile spectra, directogram).

## In notebooks

Everything the CLI does is a library call, and version 0.3 adds a
notebook-oriented case-study toolbox — machine on/off states, source
fingerprints, civic-grid scans, bit-exact segment export:

```python
import ambiscape as asc
from ambiscape import background, features, schedule, states

sess = asc.open_session("2026-07-15-Haarlem-loft")
F = features.load_features(
    features.extract_session(sess, "analysis/features"))

segs = states.state_segments(states.band_level(F, (250, 1000)))  # vent on/off
fp = background.source_fingerprint(F, night_minutes, morning_minutes)
bells = schedule.grid_scan(F, 900.0, band=(350, 800))            # church clock
asc.export_segment(sess, t0, 600.0, "seg6_vent_switchoff.wav")

from ambiscape import enf                       # v0.4: grid-frequency traces
enf.enf_summary(enf.enf_track(sess))            # mains ENF wander, mHz-level

from ambiscape import ecology, iso              # v0.5: ratings & indices
ecology.indices(F)                              # ACI, ADI/AEI, NDSI, BI, H
iso.room_criteria(iso.background_octaves_db(F)) # NR / NC / RC (HVAC idiom)
asc.decay_metrics(x[:, 0], fs)                  # T60 + EDT, C50/C80, D50

from ambiscape import biophony, ml              # v0.6: nature & animals
biophony.summarize_biophony(F)                  # narrowband/temporal/spatial
ml.birdnet_session(sess, F=F, hifi_max_diffuse=0.75, lat=52.4, lon=4.6)
```

See the [machine-states guide](https://fourms.github.io/ambiscape/guide/states/)
and the executable session report it was built for.

## Documentation

- **[User guide & API reference](https://fourms.github.io/ambiscape/)** —
  the session model and conventions, feature/descriptor definitions, room
  acoustics and ISO indicators, the taxonomy workflow, machine listening,
  deposit export.
- **[Wiki](https://github.com/fourMs/ambiscape/wiki)** — research context,
  field-recording protocol, design decisions, recipes, roadmap.

## Dependencies

- [ambiviz](https://github.com/fisheggg/ambiviz) renders rich spatial visuals from ambisonic files
- librosa

## License

MIT — see [LICENSE](LICENSE). Developed in the
[AMBIENT project](https://www.uio.no/ritmo/english/projects/ambient/index.html)
at [fourMs / RITMO](https://www.uio.no/ritmo/english/), University of Oslo.
