Panaudia

This SDK is for adding Panaudia to web applications.

As well as this guide we have some other resources to help you use this SDK:

Installation

Depending on how your project is structured you can either install the SDK as a package from npm or use our single panaudia-sdk.js file directly.

Install as package from npm

Install the SDK as a JavaScript/TypeScript package from npm with your favourite package manager.

npm install panaudia-sdk

yarn add panaudia-sdk

You can then import its functions in your code like this:

import {connect,
    disconnect,
    move,
    setAttributesCallback,
    setStateCallback,
    setConnectionStatusCallback} from 'panaudia-sdk'

Install panaudia-sdk.js file

panaudia-sdk.js a single, dependency free, file of ~15KB that is easy to install with importmap, either directly from a CDN by adding this script tag to your html:

<script type="importmap">
    {
      "imports": {
        "panaudia-sdk": "https://cdn.jsdelivr.net/npm/panaudia-sdk@1.0.4/dist/panaudia-sdk.js"
      }
    }
</script>

Or download the file from here and host it yourself:

<script type="importmap">
    {
      "imports": {
        "panaudia-sdk": "path/to/file/panaudia-sdk.js"
      }
    }
</script>

The imports are then identical to above.

Usage

The detailed function reference for this SDK is here

Connecting

First add a function to your own code to handle connection status messages from the SDK and pass it to setConnectionStatusCallback:

function connectionStatusCallback(status, message){
    /*
    handle connection status callbacks here to update application
    state and display status messages to users.
    */
     ...
}

setConnectionStatusCallback(connectionStatusCallback);

function connectionStatusCallback(status: ConnectionStatus, message: string){
    /*
    handle connection status callbacks here to update application
    state and display status messages to users.
    */
     ...
}

setConnectionStatusCallback(connectionStatusCallback)



Then use a Ticket (see here for details) to connect to your Space giving a starting position and rotation. The parentId must be the id of an existing dom element for the SDK to add the audio player to.

// This will place the user in the front right quadrant of the Space
const position = {x:0.5, y:0, z:-0.5}
const rotation = {x:0, y:0, z:0}

connect(ticket, parentId, position, rotation)

// This will place the user in the front right quadrant of the Space
const position = {x:0.5, y:0, z:-0.5}
const rotation = {x:0, y:0, z:0}
const data = true

connect(ticket, data, parentId, position, rotation)



This will establish a connection to the Space and start streaming audio in both directions.

Moving

As your user moves around in your application update the server:

move(position, rotation);

move(position, rotation)



You will get back a constantly updated binaural mix of the Space.

Disconnecting

if you want to disconnect from the server call disconnect:

disconnect();

disconnect()



State and Attribute callbacks

You can also, optionally, get callbacks giving you information about other users in the Space. If you are using Panaudia in conjunction with something like a game or VR server this is probably unnecessary, but for using Panaudia on its own it gives you simple game server like behaviour.

State callbacks happen at high frequency giving location, rotation, volume and gone information for all other users in the Space.

Attribute callbacks occur less frequently and pass around customisable data about each user.

You can set the callbacks in a similar way to the status one:

function stateCallback(state){...}
function attributesCallback(attributes){...}

setStateCallback(stateCallback);
setAttributesCallback(attributesCallback);

function stateCallback(state: NodeState){...}
function attributesCallback(attrs: NodeAttributes){...}

setStateCallback(stateCallback)
setAttributesCallback(attributesCallback)



The custom attributes can come from two places:

Ticket attributes which were written into the ticket when it was created. These can be considered secure as it's hard for the user to tamper with them.
Connection attributes which were given in the optional attrs parameter to the connection call above. These are not secure from user tampering but can be used to pass through things like user choices. We use this for avatar colours in our demo apps.

Coordinates

Ambisonics and 3D graphics tend to use different coordinates systems.

For convenience this SDK has two versions of some functions, one that uses native ambisonic coordinates and one that automatically converts between the two.

These functions will automatically do the conversions for you:

connect(...)
move(...)
setStateCallback(...)

They all either take as parameters or return values called position and rotation.

Positions are objects with numeric values for x, y and z in the range - 1 to + 1, in the WebGL coordinate system.

Rotations are objects with numeric values for rotations x, y and z in the range -pi to +pi radians. These are intrinsic rotations ordered XYZ.

If you prefer to work directly with the underlying ambisonic coordinate system you can use these functions instead, which do no conversion:

connectAmbisonic(...)
moveAmbisonic(...)
setAmbisonicStateCallback(...)

Instead of position and rotation these functions have a coordinates value which is an object with numeric values for x, y, z, yaw, pitch and roll:

Full details about Panaudia's coordinates systems are here here.

JavaScript SDK Guide