Metadata-Version: 2.4
Name: relata
Version: 0.0.1
Summary: Distributed microphone array processing from ad-hoc consumer device arrays
Project-URL: Homepage, https://github.com/rianczerwinski/relata-publish
Project-URL: Source, https://github.com/rianczerwinski/relata-publish
Author-email: Rían Czerwiński <relata@rian.is>
License-Expression: AGPL-3.0-only
License-File: LICENSE
Keywords: audio,beamforming,gcc-phat,microphone-array,numpy,spatial-audio,tdoa
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Multimedia :: Sound/Audio :: Analysis
Classifier: Topic :: Scientific/Engineering
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: numpy>=1.24
Description-Content-Type: text/markdown

# relata

**Distributed microphone array processing from ad-hoc consumer devices.**

Turn N unpositioned phones, laptops, and tablets — whatever is already lying on
the table — into a calibrated spatial audio capture system, with real-time source
localization, beamforming, and speaker separation.

The name is the Latin plural of *relatum*: the entities that stand in a relation.
The mics are the relata. Their spatial relationships are the relations.
Calibration discovers that relational structure, and everything downstream
exploits it.

---

## Coming Q3 2026

The full engine is in active development. What it does:

**No fixed array. No known geometry.** Most spatial audio libraries assume a
rigid microphone array whose positions you measured in advance. relata starts
from the opposite premise: unknown devices placed anywhere, discovering their own
spatial relationships — from a chirp, or from ambient speech alone. Arrays can be
in continuous motion (handheld, walking, in a vehicle) and the geometry tracks
them.

**Everyone gets their own audio.** Enhancement returns one isolated stream per
detected speaker, not one cleaned-up mixture. Diarization runs two paths at once
— spatial (where the voice came from) and neural (whose voice it is) —
confidence-weighted against each other, neither subordinated to the other.

**Zero-install capture.** One device runs the pipeline; the rest join by scanning
a QR code and streaming from the browser over WebRTC. No app to install.

**Runs on your machine, not someone's cloud.** Every neural model in the core
pipeline — enhancement, separation, speaker embeddings, voice activity,
segmentation — executes as a hand-written numpy forward pass. No PyTorch, no ONNX
runtime, no opaque model binaries, no network calls. The architecture is code;
the weights are data. Transcription plugs in on top, and runs locally too.

**Library first.** Embed it in your app, or drive it from the CLI. Not a service
you send your audio to.

---

## Available now: the TDOA front-end

This release is a **pre-alpha**. It ships one working, self-contained piece of
the engine — the part that measures *how much later a sound reached one mic than
another*. That delay is the raw geometric signal the whole spatial stack is built
on, and it is useful on its own to anyone doing microphone-array work.

It's GCC-PHAT (Generalized Cross-Correlation with Phase Transform) with
sub-sample parabolic interpolation and a peak-to-sidelobe confidence score. Pure
numpy. No model weights, no compiled extensions, no dependencies beyond numpy
itself.

```bash
pip install relata
```

```python
import numpy as np
from relata import compute_gcc_phat, compute_all_tdoas

# One mic pair — recover the time-difference-of-arrival between two signals.
pair = compute_gcc_phat(sig_a, sig_b, sample_rate=16000)
print(pair.tdoa_seconds, pair.confidence)

# Or every pair across a multichannel recording, shaped (n_channels, n_samples).
for pair in compute_all_tdoas(audio, sample_rate=16000):
    print(pair.mic_a, pair.mic_b, pair.tdoa_samples)
```

Positive TDOA means the signal reached `mic_b` later than `mic_a`. Confidence is
a normalized peak-to-sidelobe ratio in `[0, 1]` — low confidence means no source
was found, just noise. At 16 kHz, one sample of delay is about 2.1 cm of path
difference.

Import paths here are a true subset of the full library's, so code written
against this release keeps working as the engine lands.

Requires Python 3.10+.

---

## License

[AGPL-3.0-only](LICENSE).

Commercial licensing — an exception to the AGPL, for embedding relata in a
proprietary product or running a modified hub as a closed hosted service — is
available on request: **relata@rian.is**.
