Sync Audio SDK for Web: Quickstart

The Aircore Sync Audio SDK for Web allows you to add high-quality, real-time voice chat to your web app quickly and easily without the need to understand the complexities of building a real-time system on your own.

Apps that use the Aircore Sync Audio SDK for Web automatically take advantage of Aircore's advanced media optimization and adaptation framework and leverage Aircore's world-wide media distribution system.

This SDK also works seamlessly with the Sync Chat SDK. For more on the integrated UI, see Combine with Sync Chat below.

Try it now

There are multiple ways to try out the SDK before you start integrating.

Live apps

Go to air.live to see this SDK in action in a production app. You can instantly start an audio chat and invite anyone using a link.
Use our Chrome extension as a no-code solution to try out this SDK on your own site.

Code pens

Play with interactive examples in different frameworks in your browser.

These code pens are for Sync Audio only. See Combine with Sync Chat below for a code pen with both SDKs.

Mock app

You can use the mock app below to play with the style and other options. To keep your customization, click Copy as JSON and paste the style or configuration directly into your app.

Before starting

Supported browsers and devices

Desktop: Chrome, Edge, Firefox, and Safari
iOS: Chrome and Safari

Installation

The recommended way of installing is using NPM Package Manager.

Install the Sync Audio SDK using the following command

npm install @aircore/aircore-panel-core @aircore/aircore-media-panel

Alternatively, you can install the standalone Sync Audio SDK using the CDN

<script type="importmap">
  {
    "imports": {
      "@aircore/aircore-panel-core": "https://unpkg.com/@aircore/aircore-panel-core/dist/index.js"
    }
  }
</script>
<script src="https://unpkg.com/@aircore/aircore-panel-core/dist/index.js"></script>
<script src="https://unpkg.com/@aircore/aircore-media-panel/dist/index.js"></script>

or via

<script async src="https://ga.jspm.io/npm:es-module-shims@1.7.0/dist/es-module-shims.js"></script>
<script type="importmap">
  {
    "imports": {
      "@aircore/aircore-panel-core": "https://unpkg.com/@aircore/aircore-panel-core/dist/index.js"
    }
  }
</script>
<script type="module">
  import { createClientWithPublishableKey } from 'https://unpkg.com/@aircore/aircore-panel-core/dist/index.js';
  import { MediaPanel } from 'https://unpkg.com/@aircore/aircore-media-panel/dist/index.js';
</script>

Authenticate

This guide uses a publishable API key for a quick setup. To get your API key:

Create an app in the Developer Console.
Copy your publishable API key and use it in the next section.

Copying a publishable API key from the console.

For an overview of API keys, see Authentication.

Use a publishable API key to create the client:

import { createClientWithPublishableKey } from '@aircore/aircore-panel-core';
import { MediaPanel } from '@aircore/aircore-media-panel';

// Create a client by passing the publishable key and the current user ID.
const client = createClientWithPublishableKey(
  'INSERT_PUBLISHABLE_KEY_HERE',
  'INSERT_USER_ID_HERE'
);

// Set the current user name and avatar.
client.setUserDisplayName('John Doe');
client.setUserAvatarUrl('https://avatar.com/40');

// Connect to the desired channel.
client.connect('INSERT_CHANNEL_ID_HERE');

// Render the panel.
const MyPanel = MediaPanel(
  '#myMediaPanel', // Selector DOM target.
  {
    client: client,
    channelId: 'INSERT_CHANNEL_ID_HERE',
  }
);

For more detailed security controls, you can use a secret API key instead. See Customization.

Configuration

You configure the panel with two distinct objects:

MediaPanelConfiguration includes all audio panel-specific configuration, such as the title, share link, and other text.
Theme includes all visual configuration of the panel, such as fonts and colors.

Here is an example of how you can pass these two objects when rendering the panel:

// Render the selector target on the page first.
// Then render the panel by passing a selector, the client, and the channel ID
// that you want to connect to.
const targetElement = document.querySelector('#myMediaPanel');

const myPanel = MediaPanel(
  targetElement,
  {
    client: client,
    channelId: 'INSERT_CHANNEL_ID_HERE',
    theme: {
      // You can specify a base theme to start from.
      base: 'light',
    },
    config: {
      // You can specify a title for the panel.
      panelTitle: 'John and Leila call',
    }
  }
);

The chat panel has two distinct states: collapsed and expanded. Here is an example configuration for the panel:

const myPanelConfiguration = {
  panelTitle: 'John and Leila call', // Custom title for your panel.
  panelSubtitle: 'Talking about adding a Sync panel', // Custom subtitle.
  shareLinkUrl: 'http://yourDomain.com/call/1234', // Custom link to this call
                                                   // in your app.

  string: {
    startConversation: "Start", // You can override the strings displayed.
    // Add other strings that you want to customize.
  },

  collapsedStateOptions: {
    maxAvatars: 5, // Maximum number of avatars to show. The rest are shown as
                   // "+99 others".
    // Add other collapsed state options that you want to customize.
  },

  expandedStateOptions: {
    placement: 'topLeft', // The expanded view is placed relative to the
                          // collapsed view.
    // Add other expanded state options that you want to customize.
  }
};

You can launch the panel in collapsed mode only by disabling the expanded state:

const myPanelConfiguration = {
  expandedStateOptions: null,
  // Add other properties that you want to customize.
};

Similarly, you can also disable the collapsed state and only display the expanded state:

const myPanelConfiguration = {
  collapsedStateOptions: null,
  // Add other properties that you want to customize.
};

Combine with Sync Chat

If you use both the Sync Audio and Sync Chat SDKs, you can show a combined panel.

Use MediaPanel() and ChatPanel() to create the panels, using the same channel ID for both.
Call the mediaPanel object's combine() method on the chatPanel object.

    const mediaPanel = MediaPanel(
      '#my-media-panel',
      {
        client,
        channelId,
      }
    );

    const chatPanel = ChatPanel(
      null,
      {
        client,
        channelId,
      }
    );

    mediaPanel.combine(chatPanel);

To play with the combined panel, see the code pen.

You can download the source code for sample apps for this SDK from GitHub.

User experience

To customize the user experience, you can choose which users can publish audio. You can also customize how users publish audio.

The panel shows all users as they join. By default, users start with a muted microphone. To unmute and start publishing audio, users tap the microphone button on the panel once.

Create an audience

You can change the panel options and permissions to build an app in which some users speak and others just listen.

To create an audience, you can stop users from unmuting. To hide the microphone button, set showMicrophoneButton to false.

It's best to also keep the audience muted by using permissions. To do this, use a secret API key. You can't use a publishable API key because it lets all users publish audio.

To mute certain users, request and send out session auth tokens that don't allow publishing audio.

Token permissions don't affect the showMicrophoneButton setting. If the setting is true, users that can't publish audio can still see and press the button, but it doesn't do anything.

Automatically publish audio

To have users publish automatically, set autoPublishMicOnJoin to true.

Enable push-to-talk

With push-to-talk, users publish audio only while pushing a button. To enable this, set pushToTalkMode to true.

On mobile, users tap and hold the microphone button to talk. When they release the button, the stream is muted again.

On desktop, users push and hold the spacebar to talk. To use a different key, update the value of pushToTalkKey.

Theming

The Theme object has a base theme with overriding variables that you can use to customize the look and feel of your panel.

The default base theme is light. You can also choose dark or another base theme:

const myCustomTheme = {
  base: 'dark',
  overrides: {
    // You can override any of the values using your own colors.
    primaryColor: '#228B22', // Your brand color.
    textColor: '#FFFFFF',
    backgroundColor: '#000000',
    borderRadius: '20px',
    font: 'Arial', // Name of your custom font.
    // Add other values that you want to override.
    icons: {
      join: '/assets/join.svg', // Local path to your icon.
      // Add other icons that you want to customize.
    }
  }
};

You can reuse the theme across multiple panels as needed. Just define it somewhere in your app and reuse it every time you render a new panel.

Events

The client object provides events you can hook to in order to react to something that is happening on the panel.

For example, you might want to call your backend when a user join a call in order to trigger notification to other users that might want to join the same call.

Here is how an example of how you can subscribe and unsubscribe to events:

function onEventTriggeredCallback() {
  // Your business logic here.
};

// Subscribe to an event.
client.on(client.EVENTS.EVENT_NAME, onEventTriggeredCallback);

// Unsubscribe from the same event.
client.off(client.EVENTS.EVENT_NAME, onEventTriggeredCallback);

Full events reference can be found here

Teardown and cleanup

When you are done with the panel, you can teardown the client and the panel as follow

// Disconnect from a specific channel ID.
client.disconnect('YOUR_CHANNEL_ID');

// Teardown of the panel.
myPanel.destroy();

// Teardown of the client.
// It disconnects automatically from all connected channels.
client.destroy();

More info

To continue customizing the panel, see Customization.
See the full API reference.
Download our sample apps.