Panaudia

As well as this guide we have some additional resources to help you create Tickets:

About Tickets

We use JSON Web Tokens wikipedia.org/wiki/JSON_Web_Token as tickets to control access to Panaudia Spaces.

Every user accessing a Space needs their own unique Ticket for it. Two separate users cannot use the same ticket at the same time, the second one trying would fail to get in. Tickets can however be used multiple times to come and go from a Space.

Tickets can be very simple and just grant access, or they be customised to configure Panaudia and modify the user's appearance and behaviour.

Required attributes

A minimal Ticket needs to contain at least these three things:

Space ID - The ID of the Space that the Ticket gives access to.
Name - A human-readable display name for the user, this doesn't have to be their real name, doesn't have to be unique, and can use any utf-8 characters.
Uuid - The Ticket's ID a 128 bit, hex-encoded uuid string. You can provide one to help tie the Panaudia ticker holder to a user in your own system, or Panaudia can automatically generate one for you.

Time constraints

A Ticket can only be used while a Space is active, but you can add additional time constraints to limit when the Ticket can be used. This can be useful to ensure everyone enters before a show starts, or to allocate entry time slots to users.

Not before - The Ticket cannot be used before this time.
Expires - The Ticket cannot be used for entry, or re-entry, after this time.

Configure audio mixing

You can customise how Panaudia will mix the audio from a user, this doesn't affect what they hear but how others will hear them.

Gain - If given this must be a number between 0.0 and 3.0, the default is 1.0. This is a linear gain adjustment that can be used to make the bearer of this Ticket louder or quieter.
Attenuation - If given this must be a number between 0.0 and 3.0. It will modify the way sound from the bearer of this ticket will attenuate with distance. The default is 2.0 which represents the normal (inverse square) way things get quieter as they move further away. The maximum of 3.0 will cause volume to fall off faster with distance (inverse cubed like magnetism), 1.0 will cause volume to decrease linearly, and 0.0 will keep the sound at full volume everywhere.
Priority - Set this to true to ensure that this user's audio is always correctly spatialised for others even when in the distance. This is useful for performers or moderators in Spaces with large numbers of people.

Custom attributes

You can add a set of custom attributes to a user's ticket. These are not used by Panaudia itself, but they will be passed to others connected to the same Space the help customise the appearence or behaviour of this user.

When using the JavaScript SDK these attribute are returned to the callback set with setAttributesCallback

Creating Tickets with Spaces API

The easiest way to create Tickets is with the Spaces API. Post the json configuration for a ticket to:

POST /spaces/{space-id}/tickets



Post the json configuration for a ticket. A simple Ticket request could be just a name:

{ "name": "Paul" }

or something with optional fields:

{
  "name": "Paul",
  "uuid": "7dc3d357-63f4-433b-b8cd-5b7cd6bee3aa",
  "not_before": "2024-12-03T10:00:00Z",
  "expires": "2024-12-03T12:00:00Z",
  "attenuation": 1.5,
  "gain": 1.2,
  "priority": true,
  "attrs": {"colour": "00aaff"}
}

Creating Tickets yourself

You can create Tickets for a Space yourself without calling the Panaudia server. To do this you will need at least a basic understanding of how to create and sign JWTs.

If JWTs are new to you here is some background reading:

Most languages have libraries specifically for working with JWT that will make signing Tickets much easier, whatever language you use the basic steps for making Tickets are the same:

Create Public/Private key pair

We use Public/Private keys created with the Ed25519 elliptic curve algorithm in PEM format to sign and validate Tickets. These keys are small, fast and secure. You may be able to create them with a library, or you can use OpenSSL like this:

openssl genpkey -algorithm ed25519 -out private.pem
openssl pkey -in private.pem -pubout -out public.pem

You must then include the public key in your calls to the Spaces API to create Spaces so that we can use it to check the Tickets you make.

Every Ticket header is the same. As well as identifying the document as a JWT it describes the encryption algorithm and curve used for signing, it looks like this:

{
  "typ": "JWT",
  "alg": "EdDSA",
  "crv": "Ed25519"
}

Create the payload

The payload contains the JWT's claims. This is where the configuration goes. The claim naming doesn't fully match one-to-one with our configuration names as we use some standard JWT claims and some custom claims.

A payload looks something like this:

{
  "iat": 1731194009,
  "iss": "panaudia.com",
  "aud": "space_df8c7a85-0702-45e9-a626-a1c147eafce9",
  "jti": "8c5d04e0-5e84-4d52-94bd-48d64d74510a",
  "preferred_username": "Paul",
  "nbf": 1733391000,
  "exp": 1733394000,
  "panaudia": {
    "attenuation": 2.0,
    "gain": 1.5,
    "priority": true,
    "attrs": {
      "colour": "00aaff"
    }
  }
}

This is how the claims match up with the Ticket configuration:

{
  "iat": ( When the ticket was issued in seconds since the epoc ),
  "iss": ( An identifier for you as the issuer of the ticket ),
  "aud": ( Space ID ),
  "jti": ( Uuid ),
  "preferred_username": ( Name ),
  "nbf": ( Not Before, in seconds since the epoc ),
  "exp": ( Expires, in seconds since the epoc ),
  "panaudia": {
    "attenuation": ( Attenuation ),
    "gain": ( Gain ),
    "priority": ( Priority ),
    "attrs": ( Attrs )
  }
}

These Ticket JWTs are purely access tokens and make no claim about the identity of the bearer, so there is no sub claim, the ticket itself has an ID, the jti claim, and the preferred_username claim is only an informal identifier.

Encode and sign with Private key

The header and the payload are then base64 url encoded and joined with a dot and this string is then signed with the Private Key resulting in a signature. This signature is then itself base64 url encoded and added after the header and the payload, seperated by a second dot.

The resulting Ticket is a long url encoded string broken into three parts by dots:

eyJhbGciOiJFZERTQSIsImNydiI6IkVkMjU1MTkiLCJ0eXAiOiJKV1QifQ.eyJpYXQiOjE3MzExOTYwMzcsImlzcyI6InBhbmF1ZGlhLmNvbSIsImF1ZCI6InNwYWNlX2RmOGM3YTg1LTA3MDItNDVlOS1hNjI2LWExYzE0N2VhZmNlOSIsImp0aSI6IjhjNWQwNGUwLTVlODQtNGQ1Mi05NGJkLTQ4ZDY0ZDc0NTEwYSIsInByZWZlcnJlZF91c2VybmFtZSI6IlBhdWwiLCJuYmYiOjE3MzMzOTEwMDAsImV4cCI6MTczMzM5NDAwMCwicGFuYXVkaWEiOnsiYXR0ZW51YXRpb24iOjIuMCwiZ2FpbiI6MS41LCJhdHRycyI6eyJjb2xvdXIiOiIwMGFhZmYifX19.Tc9OJHjm4hrMXV4z_4TiXC4ni8MEnn4AfonsDtGRucj-k-B_tyyhJhrZAg1Cn-29GsGG6bacuzo6Ckx_tH25Cw

Creating Tickets with Quick Start

You can also create Tickets in the Panaudia web console. Click on the Quick Start tab for any Space and fill in the form to create a Ticket.

This may be useful in development or when evaluating Panaudia.

Creating Tickets