Start Live Interactive Video Streaming

Use this guide to quickly start the interactive live audio streaming with the Agora Voice SDK for Android.

Prerequisites

Before proceeding, ensure that your development environment meets the following requirements:

• Java Development Kit.
• Android Studio 3.0 or later.
• Android SDK API Level 16 or higher.
• A valid Agora account.
• An active Agora project with an App ID and a temporary token. For details, see Get Started with Agora.
• A computer with access to the internet. If your network has a firewall, follow the instructions in Firewall Requirements.
• A mobile device that runs Android 4.1 or later.

Set up the development environment

1. For new projects, in Android Studio, create a Phone and Tablet Android project with an Empty Activity.

   After creating the project, Android Studio automatically starts gradle sync. Ensure that the sync succeeds before you continue.

2. Integrate the Voice SDK into your project with Maven Central. For more integration methods, see Other approaches to intergrate the SDK.

   a. In /Gradle Scripts/build.gradle(Project: <projectname>), add the following lines to add the Maven Central dependency:

    buildscript {
        repositories {
            ...
            mavenCentral()
        }
        ...
   }
   
    allprojects {
        repositories {
            ...
            mavenCentral()
        }
   }

   The way to add the Maven Central dependency can be different if you set dependencyResolutionManagement in your Android project.

   b. In /Gradle Scripts/build.gradle(Module: <projectname>.app), add the following lines to integrate the Agora Voice SDK into your Android project:

    ...
    dependencies {
     ...
     // For x.y.z, fill in a specific SDK version number. For example, 3.5.0 or 3.7.0.2.
     // Get the latest version number through the release notes.
     implementation 'io.agora.rtc:voice-sdk:x.y.z'
    }

3. Add permissions for network and device access.

   In /app/Manifests/AndroidManifest.xml, add the following permissions after </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.ACCESS_WIFI_STATE" />
    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
    <uses-permission android:name="android.permission.BLUETOOTH" />
    <!-- Add the following permission on devices running Android 12.0 or later -->
    <uses-permission android:name="android.permission.BLUETOOTH_CONNECT"  />

4. To prevent obfuscating the code in the Agora SDK, add the following line to /Gradle Scripts/proguard-rules.pro:

    -keep class io.agora.**{*;}

Implement the basic interactive live audio streaming

This section introduces how to use the Agora Voice SDK to start the interactive live audio streaming. The following figure shows the API call sequence of the interactive live audio streaming.

1. Create the UI

Create the user interface (UI) for the audio streaming in the layout file of your project. Skip to Import Classes if you already have a UI in your project.

<?xml version="1.0" encoding="UTF-8"?>
<FrameLayout xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    android:keepScreenOn="true"
    tools:context=".ui.LiveRoomActivity">

    <RelativeLayout
        android:layout_width="match_parent"
        android:layout_height="match_parent">

        <TextView
            android:id="@+id/room_name"
            android:layout_width="wrap_content"
            android:layout_height="wrap_content"
            android:layout_alignParentTop="true"
            android:layout_centerHorizontal="true"
            android:layout_marginTop="6dp"
            android:textColor="@color/dark_black"
            android:textSize="16sp"
            android:textStyle="bold" />

        <io.agora.propeller.ui.AGLinearLayout
            android:id="@+id/bottom_container"
            android:layout_width="match_parent"
            android:layout_height="wrap_content"
            android:layout_alignParentBottom="true"
            android:layout_alignParentLeft="true"
            android:layout_alignParentStart="true"
            android:orientation="vertical">

            <ImageView
                android:id="@+id/bottom_action_end_call"
                android:layout_width="54dp"
                android:layout_height="54dp"
                android:layout_gravity="center_horizontal"
                android:onClick="onEndCallClicked"
                android:scaleType="center"
                android:src="@drawable/btn_endcall" />

            <RelativeLayout
                android:id="@+id/bottom_action_container"
                android:layout_width="match_parent"
                android:layout_height="54dp"
                android:gravity="center_vertical"
                android:orientation="horizontal">

                <ImageView
                    android:id="@id/switch_broadcasting_id"
                    android:layout_width="54dp"
                    android:layout_height="match_parent"
                    android:layout_alignParentLeft="true"
                    android:layout_alignParentStart="true"
                    android:scaleType="center"
                    android:src="@drawable/btn_request_broadcast" />

                <LinearLayout
                    android:layout_width="wrap_content"
                    android:layout_height="match_parent"
                    android:layout_centerInParent="true"
                    android:orientation="horizontal">

                    <ImageView
                        android:id="@id/switch_speaker_id"
                        android:layout_width="54dp"
                        android:layout_height="match_parent"
                        android:onClick="onSwitchSpeakerClicked"
                        android:scaleType="center"
                        android:src="@drawable/btn_speaker" />

                    <ImageView
                        android:id="@id/mute_local_speaker_id"
                        android:layout_width="54dp"
                        android:layout_height="match_parent"
                        android:onClick="onVoiceMuteClicked"
                        android:scaleType="center"
                        android:src="@drawable/btn_mute" />

                </LinearLayout>

            </RelativeLayout>
        </io.agora.propeller.ui.AGLinearLayout>

        <EditText
            android:id="@+id/msg_list"
            android:layout_width="match_parent"
            android:layout_height="match_parent"
            android:layout_above="@id/bottom_container"
            android:layout_below="@id/room_name"
            android:layout_marginBottom="8dp"
            android:layout_marginTop="6dp"
            android:enabled="true"
            android:focusable="false"
            android:gravity="start|top"
            android:inputType="none"
            android:scrollbars="vertical" />

    </RelativeLayout>
</FrameLayout>

2. Import Classes

Import the following classes in the activity file of your project:

import io.agora.rtc.IRtcEngineEventHandler;
import io.agora.rtc.RtcEngine;

3. Get the device permission

Call the checkSelfPermission method to access the microphone of the Android device when launching the activity.

private static final int PERMISSION_REQ_ID_RECORD_AUDIO = 22;

// Ask for Android device permissions at runtime.
@Override
protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.activity_voice_chat_view);

    // Initialize RtcEngine and join the channel after getting the permission.
    if (checkSelfPermission(Manifest.permission.RECORD_AUDIO, PERMISSION_REQ_ID_RECORD_AUDIO)) {
        initAgoraEngineAndJoinChannel();
    }
}

public boolean checkSelfPermission(String permission, int requestCode) {
    Log.i(LOG_TAG, "checkSelfPermission " + permission + " " + requestCode);
    if (ContextCompat.checkSelfPermission(this,
            permission)
            != PackageManager.PERMISSION_GRANTED) {

        ActivityCompat.requestPermissions(this,
                new String[]{permission},
                requestCode);
        return false;
    }
    return true;
}

4. Initialize RtcEngine

Create and initialize the RtcEngine object before calling any other Agora APIs.

In the string.xml file, replace agora_app_id with your App ID. Call the create method and pass in the App ID to initialize the RtcEngine object.

You can also listen for callback events, such as when the local user joins the channel. Do not implement UI operations in these callbacks.

private RtcEngine mRtcEngine;
private final IRtcEngineEventHandler mRtcEventHandler = new IRtcEngineEventHandler() {
    @Override
    // Listen for the onJoinChannelSuccess callback.
    // This callback occurs when the local user successfully joins the channel.
    public void onJoinChannelSuccess(String channel, final int uid, int elapsed) {
        runOnUiThread(new Runnable() {
            @Override
            public void run() {
                Log.i("agora","Join channel success, uid: " + (uid & 0xFFFFFFFFL));
            }
        });
    }



    @Override
    // Listen for the onUserOffline callback.
    // This callback occurs when the host leaves the channel or drops offline.
    public void onUserOffline(final int uid, int reason) {
        runOnUiThread(new Runnable() {
            @Override
            public void run() {
                Log.i("agora","User offline, uid: " + (uid & 0xFFFFFFFFL));
                onRemoteUserLeft();
            }
        });
    }
};

...

// Initialize the RtcEngine object.
private void initializeEngine() {
    try {
        mRtcEngine = RtcEngine.create(getBaseContext(), getString(R.string.agora_app_id), mRtcEventHandler);
    } catch (Exception e) {
        Log.e(TAG, Log.getStackTraceString(e));
        throw new RuntimeException("NEED TO check rtc sdk init fatal error\n" + Log.getStackTraceString(e));
    }
}

5. Set the channel profile

After initializing the RtcEngine object, call the setChannelProfile method to set the channel profile as LIVE_BROADCASTING.

One RtcEngine object uses one profile only. If you want to switch to another profile, release the current RtcEngine object with the destroy method and create a new one before calling the setChannelProfile method.

private void setChannelProfile() {
    mRtcEngine.setChannelProfile(Constants.CHANNEL_PROFILE_LIVE_BROADCASTING);
}

6. Set the user role and user level

In a live-streaming channel, you need to set the role and level of a user:

• The user role determines the permissions that the SDK grants to a user, such as permission to send local streams, receive remote streams, and push streams to a CDN address. A live-streaming channel has two user roles: host and audience. A host can both send and receive streams, but an audience member can only receive stream. The default role is audience.
• The user level determines the level of services that a user can enjoy within the permissions of the user's role. For example, an audience member can choose to receive remote streams with low latency or ultra low latency. Levels affect prices.

You may use the following steps to set the user role and level in your app:

1. Allow the end user to set the role as host or audience.

2. Call the setClientRole method and set the role and options parameters according to the user's choice:

   • When you set role as CLIENT_ROLE_BROADCASTER, set options as null. The latency between two hosts is < 400 ms.
   • When you set role as CLIENT_ROLE_AUDIENCE, set the audienceLatencyLevel parameter in options as AUDIENCE_LATENCY_LEVEL_LOW_LATENCY. The latency from the host's client to the audience's client is 1500 ms - 2000 ms.

Host:

engine.setClientRole(IRtcEngineEventHandler.ClientRole.CLIENT_ROLE_BROADCASTER);

Audience:

ClientRoleOptions clientRoleOptions = new ClientRoleOptions();
clientRoleOptions.audienceLatencyLevel = isLowLatency ? Constants.AUDIENCE_LATENCY_LEVEL_ULTRA_LOW_LATENCY : Constants.AUDIENCE_LATENCY_LEVEL_LOW_LATENCY;
engine.setClientRole(IRtcEngineEventHandler.ClientRole.CLIENT_ROLE_AUDIENCE, clientRoleOptions);

7. Join a channel

After setting the user role, you can call the joinChannel method to join a channel. In this method, set the following parameters:

• token: Pass a token that identifies the role and privilege of the user. You can set it as one of the following values:

  • A temporary token generated in Console. A temporary token is valid for 24 hours. For details, see Get a Temporary Token. When joining a channel, ensure that the channel name is the same with the one you use to generate the temporary token.
  • A token generated at the server. This applies to scenarios with high-security requirements. For details, see Generate a token from Your Server. When joining a channel, ensure that the channel name and uid is the same with those you use to generate the token.
  • If your project has enabled the app certificate, ensure that you provide a token.
  • Ensure that you do not set token as "".

• channelName: Specify the channel name that you want to join.

• uid: ID of the local user that is an integer and should be unique. If you set uid as 0, the SDK assigns a user ID for the local user and returns it in the onJoinChannelSuccess callback.

For more details on the parameter settings, see joinChannel.

private void joinChannel() {
    // Join a channel with a token.
    private String mRoomName;
    mRoomName = getIntent().getStringExtra("CName");
    mRtcEngine.joinChannel(YOUR_TOKEN, mRoomName, "Extra Optional Data", 0);
}

8. Additional steps

You can implement more advanced features and functionalities in the interactive live audio streaming.

Call the muteLocalAudioStream method to stop or resume sending the local audio stream to mute or unmute the local user.

public void onLocalAudioMuteClicked(View view) {
    mMuted = !mMuted;
    mRtcEngine.muteLocalAudioStream(mMuted);
}

9. Leave the channel

Call the leaveChannel method to leave the current channel according to your scenario, for example, when the interactive live streaming ends, when you need to close the app, or when your app runs in the background.

@Override
protected void onDestroy() {
    super.onDestroy();
    if (!mCallEnd) {
        leaveChannel();
    }
    RtcEngine.destroy();
}

private void leaveChannel() {
    // Leave the current channel.
    mRtcEngine.leaveChannel();
}

Run the project

Run the project on your Android device. When the audio streaming starts, all the audience can hear the host in the app.

See also

Other approaches to integrate the SDK

In addition to integrating the Agora Voice SDK for Android through MavenCentral, you can also import the SDK into your project by manually copying the SDK files.

1. Go to SDK Downloads, download the latest version of the Agora Voice SDK, and extract the files from the downloaded SDK package.
2. Copy the following files or subfolders from the libs folder of the downloaded SDK package to the path of your project.