Sync Audio SDK for Android (View): Quickstart

This page is for Android View.

See the Jetpack Compose version of this SDK.

The Sync Audio SDK allows you to add high-quality, real-time voice chat to your Android app quickly and easily, without tackling the complexities of building a real-time system on your own.

This SDK is powered by Aircore Flex Audio under the hood. It utilizes our advanced media optimization and adaptation framework and our world-wide media distribution system to provide your users with high-quality, low-latency multi-party voice chat features for groups of up to 24 participants.

This version of the SDK provides a view that you can customize completely and embed within your existing apps.

Try it now

To see this SDK in action in a production app, check out air.live:

Before starting

Enable Compose

To use this SDK, you must enable Jetpack Compose in your application. Add the following to your application module's build.gradle:

buildFeatures {
    compose true
}

Set the SDK version

Set the minimum Android SDK version to 26. A target of 33 is highly recommended.

android {
    defaultConfig {
        minSdk 26
        targetSdk 33
    }
}

Install the SDK

Download

To add the Aircore Sync Audio SDK for the View system to your app, include the following in your dependencies declaration inside your application module's build.gradle:

dependencies {
    implementation "io.aircore.panel:media-view:$sync_version"
}

Get required permissions

Declare the following permissions in your AndroidManifest.xml:

<application>
    ...
    <uses-permission android:name="android.permission.INTERNET" />
    <uses-permission android:name="android.permission.RECORD_AUDIO"/>
    <uses-permission android:name="android.permission.MODIFY_AUDIO_SETTINGS"/>
    <uses-permission android:name="android.permission.BLUETOOTH" />
    ...
</application>

The SDK handles requesting permissions at runtime.

Extra permission for API level 32 or earlier

If your app targets Android API level 33 or later, you can skip this step.

If your app targets level 32 or earlier, get this permission on devices running Android 13:

POST_NOTIFICATIONS

This SDK uses a foreground service for audio quality. Even without the POST_NOTIFICATIONS permission, the foreground service can start. Users can see the foreground service in the Task Manager.

If your app does have this permission, users see a notification when the service is running.

With API level 32 or earlier, Android 13 users see a request for the permission. If you don't set up the request, Android shows a default request. If a user ignores the request, they see it again every time the app starts until they make a choice.

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.

Initialize the client

The client object is the primary controller which powers this SDK. Besides authentication and initializing the low level AircoreMedia SDK under the hood, it allows you to configure user metadata that the MediaPanel relies upon, control logging, and provides methods to connect/disconnect to listen to important events that happen behind the scenes that your app might be interested to plug into.

The client allows your app to bring your existing user/channel models and seamlessly integrate them into the panel.

Use a publishable API key to create the client:

import io.aircore.panel.common.*;
import io.aircore.panel.media.*;

// Use a publishable API key directly from the Developer Console
Client client = Client.createWithPublishableApiKey(
        getApplication(),
        mPublishableApiKey,
        mUserId
        );

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

Once you create a client object, you can set properties for the user that represent them on the panel.

client.setUserDisplayName("Jane Doe");
        client.setUserAvatarUrl("http://user-profile-picture.png");

Configure the panel

To modify the panel's behavior or change the defaults of its various elements, create a mediaPanelConfiguration object.

MediaPanelConfiguration config = new MediaPanelConfiguration(
        "My Channel", // panelTitle
        "My Channel is a happy space where people can have fun", // panelSubtitle
        ...
        );

You can configure the text used in every element of the panel by setting the appropriate property.

MediaPanelStrings stringsConfig = new MediaPanelStrings(
        "Join", // joinButton
        "Joining...", // joiningButton
        "Leave", // leaveButton
        "Retry", // retryButton
        "No one is on the call yet.", // emptyCallTitle
        "Tap Join below to be the first!", // emptyCallSubtitle
        "Tap Join to start the audio session", // joinButtonTooltip
        "The channel is full", // channelIsFullLabel
        "Active", // usersActiveLabel
        "Something went wrong..." // genericErrorLabel
        );

        MediaPanelConfiguration config = new MediaPanelConfiguration(
        ...
        stringsConfig, // strings
        ...
        )

Set collapsed and expanded state options

You can further customize the expanded and collapsed state independently.

MediaPanelConfiguration config = new MediaPanelConfiguration(
        ...
        // collapsedStateOptions, Can be null to display Expanded state only
        new CollapsedStateOptions.Bar(
        3, // maxAvatars
        "Collpased Title", // panelTitle
        "Collpased Sub-title", // panelSubtitle
        "Collapsed Join", // joinButtonText
        ...
        ),
        // expandedStateOptions, Can be null to display Collapsed state only
        new ExpandedStateOptions(
        "Expanded Title", // panelTitle
        "Expanded Sub-title", // panelSubtitle
        "Expanded Join", // joinButtonText
        ...
        )
        ...
        )

Examples

Collapsed State

Expanded State

For the complete configuration options, refer to our configuration docs.

Customize the user experience

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

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

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 do this with 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.

Customize the theme

The view inherits its theming attributes such as text styles and color palette from your applications's Theme out of the box. It immediately fits with your brand and the feel of your application.

The PanelsTheme is an optional parameter that you can provide to the MediaPanel instance. It provides even more customization options for most of the visible elements.

PanelsTheme theme = new PanelsTheme(
        PanelColorsHelper.fromColorInt( // colors
        getColor(R.color.green_500), // primary
        getColor(R.color.white), // primaryContrast
        getColor(R.color.error), // danger
        getColor(R.color.white), // dangerContrast
        getColor(R.color.white), // background
        getColor(R.color.black), // text
        getColor(android.R.color.darker_gray), // subtext
        getColor(R.color.border) // border
        ),
        new PanelIconography(
        R.drawable.common_ic_collapse, // collapse
        R.drawable.common_ic_expand, // expand
        R.drawable.common_ic_share, // share
        R.drawable.common_ic_overflow, // overflowMenu
        R.drawable.common_ic_headphones, // join
        R.drawable.common_ic_close,  // leave
        R.drawable.common_ic_mic_on, // micEnabled
        R.drawable.common_ic_mic_off // micDisabled
        ),
        new Shapes()
        new AvatarStyle(
        RectangleShape,  // shape
        Color(getColor(R.color.green_500)) // backgroundColor
        ),
        new AvatarStackStyle(D
        pKt.getDp(-8) // spacing
        )
        );

Examples

Example 1

Example 2

For the complete theming options, see our theming docs.

Create the panel

Finally, we're ready to put all this together to create the MediaPanel and set it up in your app!

In your activity's layout file, add your MediaPanelView:

<LinearLayout
    android:layout_width="match_parent"
    android:layout_height="106dp"
    andorid:orientation="vertical">
    <io.aircore.panel.media.view.MediaPanelView
        android:id="@+id/media_panel_view"
        android:layout_width="match_parent"
        android:layout_height="match_parent"
    />
</LinearLayout>

Finally, find your MediaPanelView and connect:

client.connect(channelId = channel)

        MediaPanelView mediaPanelView = findViewById(R.id.media_panel_view);
        mediaPanelView.connect(client, channelId);

In the collapsed state, the MediaPanelView fills its container. In the expanded state, it appears in its own Android dialog.

Use listeners for events and errors

You can subscribe to useful events that may be relevant to your app's business logic, such as receiving errors and responding accordingly:

client.addListener(new ClientListener() {
    @Override
    public void onLocalUserJoined(@NonNull String channelId) {}
    
    @Override
    public void onLocalUserLeft(@NonNull String channelId) {}
    
    @Override
    public void onError(@NonNull Exception e) {}

    // Implement other notification handlers.
    // ...
});

For the complete reference, see our docs.

Tear down and clean up

When you are done with the panel, you can tear down the client and panel as follows:

// Disconnecting a specific Channel ID
client.disconnect(channel)

// Tear down of the client (it will disconnect automatically from all connected channels)
        client.destroy()

After you call destroy(), you cannot reuse the client with new panels. To continue, you must create a new instance of the client.

More info

To continue customizing the panel, see Customization.
Download the sample app
Download the SDK
See the full API reference