<img src="https://certify.alexametrics.com/atrk.gif?account=bIEZv1FYxz20cv" style="display:none" height="1" width="1" alt="">

Build a Simple Web App

SECTIONS

Project Complexity: ★☆☆☆☆

Within a few minutes, you can develop a Web application that allows two or more people to talk to each other in a virtual 3D environment using the Spatial Audio API.

  1. Sign up to use the Spatial Audio API
  2. Set up your local development environment
  3. Get a Test JSON Web Token used to authorize your application with High Fidelity
  4. Write the HTML and JavaScript code used to connect to High Fidelity and start communicating!

 

1. Sign Up to Use the Spatial Audio API

If you already have a High Fidelity Developer Account, you can jump straight to the next step.

Before your app can make use of the Spatial Audio API, you'll need a High Fidelity Developer Account.

Sign up for an account or log in here.

2. Set Up Your Local Development Environment

To complete this guide, you will need the following software:

Create a new folder on your local disk that you'll use for development, such as C:\code\hifi-simple-web\. Then, unzip the JavaScript (Web) version of the High Fidelity Spatial Audio Client Library to that folder.

At this point, your development folder should have a file in it called HighFidelityAudio-latest.js. It's okay if your development folder contains other files, too.

Create a new, blank HTML file in your development folder called index.html. We'll write our code in this file later in Step 4.

Install Client Libraries
Install with:

Integrate Spatial Audio into your NodeJS projects by installing the hifi-spatial-audio module. You can use this module with loaders like Webpack

3. Get a Test JSON Web Token

Next, you'll need to get a Test JSON Web Token (JWT). You will use this JWT in Step 4 to authorize your simple Web App with the Spatial Audio API servers.

JWTs are an open industry standard method for securely representing claims between two parties. Click here to learn more about JWTs. (Link will open in a new tab)


To get a Test JWT:

  1. Log in to your High Fidelity Developer Account.
  2. Under "New App Name", enter an app name.
    • Example: "My Test App"
  3. Click the "Create New App" button.
  4. On the page that appears, under "New Space Name", enter a space name.
    • Example: "My Test Space"
  5. On the page that appears, under "Optional User ID", enter a User ID.
      Example: "Test User 01"
  6. Click the "Make Test JWT" button.

The long string that is generated is your Test JSON Web Token (JWT). We will use this string later in Step 4.

Do not share this JWT. It allows users to make authorized connections to your High Fidelity Spatial Audio Server.

Your JWT should look something like this sample JWT (this sample won't work in your app):

NYCytIANhIiUQL9OeBYfUWZuLxiQtclLOGyV31Z0YIjTCCnIJ106RX06Q79Mjt1kcXMVMMINyZNCjeDsflmCIDMTmdcNz0ieRxbY.ZMwlZTJXkBOn.ZVU0ZzNalLipDJ3L5niFQnYZ5aFGt7JC2TlWiJJOMw33IICaiDcQinWMpGizhjTjLjR9yQjJ004OmJCIVfwyWZZjmII8FhlLSjV2TIHOil61DEUNi-VWUzM5Ms

4. Write the HTML and JavaScript Code!

Here's the fun part! Now, we're going to write some code that, when executed in a browser, will connect users to a virtual 3D environment and allow them to talk to each other.

Open the index.html file from Step 2 in your favorite text editor.

Now, let's add to this file almost all of the code necessary to make this sample app work. Copy and paste the following code into index.html (or click here to download an HTML file containing the code):


<!doctype html>
<html lang="en">
    <head>
        <meta charset="utf-8">
        <title>Spatial Audio API Example - Simple</title>
    </head>
    
    <body style="width: 100%; height: 100%; margin: 0; padding: 0;">
        <button class="connectButton" style="width: 100%; height: 200px; margin: 0;" onclick="connectToHiFiAudio()">Click to Connect</button>
        <audio controls autoplay class="outputAudioEl" style="width: 100%; height: 75px; margin: 30px 0 0 0;"></audio>
    </body>

    <script src="./HighFidelityAudio-latest.js"></script>
    <script>
        // We use this to change the text of the "Connect" button to "Connected", and to disable that button after clicking it.
        let connectButton = document.querySelector('.connectButton');

        async function connectToHiFiAudio(stream) {
            // Disable the Connect button after the user clicks it so we don't double-connect.
            connectButton.disabled = true;
            connectButton.innerHTML = `Connecting...`;

            // Get the audio media stream associated with the user's default audio input device.
            let audioMediaStream;
            try {
                audioMediaStream = await navigator.mediaDevices.getUserMedia({ audio: HighFidelityAudio.getBestAudioConstraints(), video: false });
            } catch (e) {
                return;
            }

            // Set up the initial data for our user.
            // They'll be standing at the origin, facing "forward".
            let initialHiFiAudioAPIData = new HighFidelityAudio.HiFiAudioAPIData({
                position: new HighFidelityAudio.Point3D({ "x": 0, "y": 0, "z": 0 }),
                orientationEuler: new HighFidelityAudio.OrientationEuler3D({ "pitch": 0, "yaw": 0, "roll": 0 })
            });

            // Set up our `HiFiCommunicator` object, supplying our media stream and initial user data.
            let hifiCommunicator = new HighFidelityAudio.HiFiCommunicator({
                initialHiFiAudioAPIData: initialHiFiAudioAPIData
            });
            await hifiCommunicator.setInputAudioMediaStream(audioMediaStream);

            // Connect to the HiFi Audio API server!
            // Supply your own JWT here.
            const HIFI_AUDIO_JWT = "";
            try {
                await hifiCommunicator.connectToHiFiAudioAPIServer(HIFI_AUDIO_JWT);
            } catch (e) {
                console.error(`Error connecting to High Fidelity:\n${e}`);
                connectButton.disabled = false;
                connectButton.innerHTML = `Connection error. Retry?`;
                return;
            }

            // Show the user that we're connected by changing the text on the button.
            connectButton.innerHTML = `Connected!`;

            // Set the `srcObject` on our `audio` DOM element to the final, mixed audio stream from the High Fidelity Audio API Server.
            document.querySelector(`.outputAudioEl`).srcObject = hifiCommunicator.getOutputAudioMediaStream();
            // We explicitly call `play()` here because certain browsers won't play the newly-set stream automatically.
            document.querySelector(`.outputAudioEl`).play();
        }
    </script>
</html>

Save your index.html file.

Double-click on your index.html file and open it in your Web browser. You should see a mostly-blank Web page with a button and an audio element on it. The page's title should be Spatial Audio API Example - Simple. Progress!

At this stage, if you were to click the "Connect" button, the connection would fail. This is because you haven't authenticated your app with High Fidelity using your JWT.

Now, inside index.html, find const HIFI_AUDIO_JWT = "";. Paste the JWT you obtained during Step 3 inside those quotation marks in your index.html file, then save the file.

For example, that line of code may look like the following:

const HIFI_AUDIO_JWT = "NYCytIANhIiUQL9OeBYfUWZuLxiQtclLOGyV31Z0YIjTCCnIJ106RX06Q79Mjt1kcXMVMMINyZNCjeDsflmCIDMTmdcNz0ieRxbY.ZMwlZTJXkBOn.ZVU0ZzNalLipDJ3L5niFQnYZ5aFGt7JC2TlWiJJOMw33IICaiDcQinWMpGizhjTjLjR9yQjJ004OmJCIVfwyWZZjmII8FhlLSjV2TIHOil61DEUNi-VWUzM5Ms";


Refresh your browser. Click on the big "Connect" button at the top of the page. Your browser should ask you for microphone permissions. Accept the request, and you're connected!

To learn more about the code that you copy and pasted above, browse the code line-by-line and read the comments.

During this next test, we highly recommend that you wear headphones, as audio feedback may occur otherwise.


To test that it really was that simple, double-click index.html again to open a second instance of your Simple Web App in a separate browser tab or window. Click the "Connect" button in that second browser tab, accept the request for microphone permissions, and talk into your microphone. You should be able to hear yourself!

Your input audio is traveling from Browser Tab A to the High Fidelity servers, at which point it is spatialized and mixed with the audio from all other connected clients. Then, that mixed audio is sent back to all other connected clients, where it is played back thru the audio element in Browser Tab B. All of this happens in a small fraction of a second and in near real-time!

That's It!

In this guide, you created a simple Web application that makes use of the Spatial Audio API.

For detailed technical information about the High Fidelity Spatial Audio Client API, visit the API documentation.

If you have any questions or comments, please reach out to support@highfidelity.com.