README
¶
LASA — Live Atomic Spatial Audio
A protocol for live, object-based, spatial audio streaming.
Features:
- Multiple clients, can contribute audio and listen simultaneously
- Each clients can contribute multiple object-based sources
- Binaural and ambisonic sinks
- Audio and pose data in the same packet
- Real-time DB for state
- Built on Media over QUIC
- MIT licenced
Design
Architectually, LASA is split between two types of data:
- Atomic: Fast, regular, stateless (audio and pose)
- Stateful: Uneven in regularity and size, extensible, cachable (everything else)
They are handled in quite different ways due to these characteristics.
Media over QUIC
LASA should really be called LASAoMoQ as we have taken the decision to commit to Media over QUIC as the transport. Doing so allows LASA to take advantage of several features inherent in the protocol:
-
MoQ provides a single resilient connection with TLS that can carry both low-latency, multi-track audio via datagrams, and multiple reliable streams of state data.
-
Agnosticism over codec allows us to use binary packets holding both compressed audio and pose data together.
-
MoQ's own identifier structure overlaps to some degree with LASA's allowing us to push some of LASA's own structure up into the transport layer, removing redundency and increasing efficiency.
Atomic Audio
LASA is opinionated about audio format. Object-based audio at 48kHz is sent in Opus encoded 5ms frames.
These are atomic in that each 5ms frame can also carry full x, y, z, yaw, pitch, roll pose data.
Each audio frame can thus carry with it the time-varying data required by a renderer to spatialise it correctly.
This removes issues of synchronisation and extra positional latency due to interpolation offsets.
Audio is sent in MoQ datagram tracks whose characteristics are lossy and low latency (a bit UDP like).
To add greater resilience, LASA allows for error correction with the addition of full bandwith redundant audio data. The offset, and from that the size of loss this can mask, is adjustable at the cost of additional latency. ie we can mask a 20ms outage if you will accept 20ms of additional latency.
Presence
Like a game engine, LASA, optionally, provides a presence feed containing the pose of all other clients connected to a Space.
Distributed State
All other state in LASA, apart from the audio and pose data, is managed through a distributed key-value store. This is a real-time, pub-sub database with sequential consistancy.
State change operations are carried in a MoQ reliable stream track allowing the state store to provide good consistency guarantees. Keys are utf-8 strings, values are binary data.
LASA has a base profile which uses the lasa. key prefix namspace to distribute necessay parameters and attributes through the system,
but the state store can be extended carry any desired data.
LASA's base profile synchronises things like rendering chacteristics, such as gain or directivity, per user muting and permissions information,
and display data about users.
Spec
LASA is defined in two spec documents in this repo:
lasa-core.mdIdentifiers, tracks and namespaces, connection and auth, audio packet formats, presence, and the state machinery with its wire encoding.lasa-base-profile.md— The base lasa state namespace covering roles, permissions, channels, moderation, and key lifetimes.
There are also JSON Schema documents in ./schemata defining the data objects LASA uses:
Go reference implementation
This repo also contains a Go reference implementation of the LASA protocol.
The sibling repo https://github.com/panaudia/panaudia-lasa contains a full, LASA media server, Panaudia LASA, also MIT licensed.
Tickets
lasa-ticket (cmd/lasa-ticket, go install github.com/panaudia/lasa/cmd/lasa-ticket@latest) creates keys, mints and checks the JWT based tickets that LASA uses, on the same verifier the server runs. tickets/ has the guide and sample issuer code in Go, Python and TypeScript.
TypeScript Client
There is a TypeScript, WebTransport client in typescript
Directories
¶
| Path | Synopsis |
|---|---|
|
Package client is the reference LASA client: it dials a space, presents the Connection Config in CLIENT_SETUP, publishes entity sources when the space subscribes to them, and subscribes sinks, state and presence.
|
Package client is the reference LASA client: it dials a space, presents the Connection Config in CLIENT_SETUP, publishes entity sources when the space subscribes to them, and subscribes sinks, state and presence. |
|
cmd
|
|
|
lasa-ticket
command
Command lasa-ticket creates keys, mints and checks LASA tickets (lasa-core.md §4.3).
|
Command lasa-ticket creates keys, mints and checks LASA tickets (lasa-core.md §4.3). |
|
Package conformance holds the LASA conformance matrix and the test that keeps it aligned with the assertion ids carried in the spec text (lasa-planning/plan/conformance-suite.md §2).
|
Package conformance holds the LASA conformance matrix and the test that keeps it aligned with the assertion ids carried in the spec text (lasa-planning/plan/conformance-suite.md §2). |
|
Package connect implements LASA connection establishment (lasa-core.md §4): parsing and validating the Connection Config against the normative schemas, verifying Tickets (Ed25519 JWTs), resolving the config's entities and setups into the connection's admitted entity set, and the §4.6 rejection codes.
|
Package connect implements LASA connection establishment (lasa-core.md §4): parsing and validating the Connection Config against the normative schemas, verifying Tickets (Ed25519 JWTs), resolving the config's entities and setups into the connection's admitted entity set, and the §4.6 rejection codes. |
|
Package ident implements the LASA identifier and state-key grammars, namespace tuple types, track-name constants, and the subscribe/announce authorization matrix (lasa-core.md §2, §3).
|
Package ident implements the LASA identifier and state-key grammars, namespace tuple types, track-name constants, and the subscribe/announce authorization matrix (lasa-core.md §2, §3). |
|
Package presence implements the LASA presence-track machinery (lasa-core.md §7): generations, implicit index assignment, keyframe chunking, and delta emission.
|
Package presence implements the LASA presence-track machinery (lasa-core.md §7): generations, implicit index assignment, keyframe chunking, and delta emission. |
|
profile
|
|
|
base
Package base implements the LASA base profile (lasa-base-profile.md): the lasa.
|
Package base implements the LASA base profile (lasa-base-profile.md): the lasa. |
|
Package schemata embeds the normative LASA JSON schemas so Go consumers can validate against exactly the files published in this repository.
|
Package schemata embeds the normative LASA JSON schemas so Go consumers can validate against exactly the files published in this repository. |
|
Package server is the LASA transport shell: a self-contained MoQ server (over the forked moqtransport) that authenticates Connection Configs, routes tracks, runs the state engine and presence machinery, and drives an embedder through the Backend SPI (plan/server-spi.md).
|
Package server is the LASA transport shell: a self-contained MoQ server (over the forked moqtransport) that authenticates Connection Configs, routes tracks, runs the state engine and presence machinery, and drives an embedder through the Backend SPI (plan/server-spi.md). |
|
Package state implements the LASA state engine (lasa-core.md §6): the server-side store with actor-owned writes, a bounded broadcast log for live fan-out, two-lane delivery (catch-up + live) per subscription, the six-step reconnect gate, tombstone GC, and the disconnect sweep.
|
Package state implements the LASA state engine (lasa-core.md §6): the server-side store with actor-owned writes, a bounded broadcast log for live fan-out, two-lane delivery (catch-up + live) per subscription, the six-step reconnect gate, tombstone GC, and the disconnect sweep. |
|
clientstore
Package clientstore implements the client half of the LASA state machinery (lasa-core.md §6.5–6.6): the local store, the catch-up window with the reference apply-live-with-transient-tombstones strategy, and cursor persistence honouring "never ahead of the persisted store" (invariant F7 of plan/state-engine-design.md: no cursor until the subscription's first catch-up frontier is applied).
|
Package clientstore implements the client half of the LASA state machinery (lasa-core.md §6.5–6.6): the local store, the catch-up window with the reference apply-live-with-transient-tombstones strategy, and cursor persistence honouring "never ahead of the persisted store" (invariant F7 of plan/state-engine-design.md: no cursor until the subscription's first catch-up frontier is applied). |
|
typescript
|
|
|
tests/vectors/generator
command
Golden-vector generator: emits tests/vectors/lasa-wire.json from the authoritative Go codecs.
|
Golden-vector generator: emits tests/vectors/lasa-wire.json from the authoritative Go codecs. |
|
Package wire implements every LASA byte layout: the audio packet formats (lasa-core.md §5), the state messages and subscribe parameter (§6.7), the presence packets (§7), and the wire constants (§9).
|
Package wire implements every LASA byte layout: the audio packet formats (lasa-core.md §5), the state messages and subscribe parameter (§6.7), the presence packets (§7), and the wire constants (§9). |