Skip to main content

You are looking at Video Calling v3.x Docs. The newest version is  Video Calling v4.x

Start a Video Call

People engage longer when they see, hear, and interact with each other. The Agora SDK enables you to embed real-time voice and video interaction in any app, on any device, anywhere.

This page shows the minimum code you need to add video call into your app by using the Agora Video SDK for Android.

Understand the tech

The following figure shows the workflow to integrate into your app in order to add Video Call functionality.

1627550978702

As shown in the figure, the workflow for adding Video Call in your project is as follows:

  1. Retrieve a token A token is the credential that authenticates a user when your app client joins a channel. In a test or production environment, your app client retrieves tokens from a server in your security infrastructure.

  2. Join a channel Call joinChannel to create and join a channel. App clients that pass the same channel name join the same channel.

  3. Publish and subscribe to audio and video in the channel After joining a channel, the app client automatically publishes and subscribes to audio and video in the channel.

For an app client to join a channel, you need the following information:

  • The App ID: A randomly generated string provided by Agora for identifying your app. You can get the App ID from Agora Console.
  • The user ID: The unique identifier of a user. You need to specify the user ID yourself, and ensure that it is unique in the channel.
  • A token: In a test or production environment, your app client retrieves tokens from a server in your security infrastructure. For this page, you use a temporary token with a validity period of 24 hours that you retrieve from Agora Console.
  • The channel name: A string that identifies the channel for the video call.

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.

Project setup

Follow the steps to create the environment necessary to add video call into your app.

  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 Video SDK into your project with Maven Central. For more integration methods, see Other approaches to integrate the SDK.

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


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

    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 Video SDK into your Android project:


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

  3. Add permissions for network and device access.

    In /app/Manifests/AndroidManifest.xml, add the following permissions after </application>:


    _9
    <uses-permission android:name="android.permission.INTERNET" />
    _9
    <uses-permission android:name="android.permission.CAMERA" />
    _9
    <uses-permission android:name="android.permission.RECORD_AUDIO" />
    _9
    <uses-permission android:name="android.permission.MODIFY_AUDIO_SETTINGS" />
    _9
    <uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
    _9
    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
    _9
    <uses-permission android:name="android.permission.BLUETOOTH" />
    _9
    <!-- Add the following permission on devices running Android 12.0 or later -->
    _9
    <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:


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

Implement a client for Video Call

This section shows how to use the Agora Video SDK to implement Video Call into your app step by step.

Create the UI

In the interface, you have one frame for local video and another for remote video. In /app/res/layout/activity_main.xml, replace the content with the following:


_27
<?xml version="1.0" encoding="UTF-8"?>
_27
<RelativeLayout xmlns:android="http://schemas.android.com/apk/res/android"
_27
xmlns:tools="http://schemas.android.com/tools"
_27
android:id="@+id/activity_main"
_27
android:layout_width="match_parent"
_27
android:layout_height="match_parent"
_27
tools:context=".MainActivity">
_27
_27
<FrameLayout
_27
android:id="@+id/local_video_view_container"
_27
android:layout_width="match_parent"
_27
android:layout_height="match_parent"
_27
android:background="@android:color/white" />
_27
_27
<FrameLayout
_27
android:id="@+id/remote_video_view_container"
_27
android:layout_width="160dp"
_27
android:layout_height="160dp"
_27
android:layout_alignParentEnd="true"
_27
android:layout_alignParentRight="true"
_27
android:layout_alignParentTop="true"
_27
android:layout_marginEnd="16dp"
_27
android:layout_marginRight="16dp"
_27
android:layout_marginTop="16dp"
_27
android:background="@android:color/darker_gray" />
_27
_27
</RelativeLayout>

Handle the Android system logic

Take the following steps to import the necessary Android classes and handle the Android permissions.

  1. Import Android classes

    In /app/java/com.example.<projectname>/MainActivity, add the following lines after package com.example.<projectname>:


    _8
    // Java
    _8
    import androidx.core.app.ActivityCompat;
    _8
    import androidx.core.content.ContextCompat;
    _8
    _8
    import android.Manifest;
    _8
    import android.content.pm.PackageManager;
    _8
    import android.view.SurfaceView;
    _8
    import android.widget.FrameLayout;


    _8
    // Kotlin
    _8
    import androidx.core.app.ActivityCompat
    _8
    import androidx.core.content.ContextCompat
    _8
    _8
    import android.Manifest
    _8
    import android.content.pm.PackageManager
    _8
    import android.view.SurfaceView
    _8
    import android.widget.FrameLayout

  2. Handle the Android permissions

    When your app launches, check if the permissions necessary to insert video calling functionality into the app are granted. If the permissions are not granted, use the built-in Android functionality to request them; if they are, return true.

    To implement the system logic, in /app/java/com.example.<projectname>/MainActivity, add the following lines before the onCreate function:


    _16
    // Java
    _16
    private static final int PERMISSION_REQ_ID = 22;
    _16
    _16
    private static final String[] REQUESTED_PERMISSIONS = {
    _16
    Manifest.permission.RECORD_AUDIO,
    _16
    Manifest.permission.CAMERA
    _16
    };
    _16
    _16
    private boolean checkSelfPermission(String permission, int requestCode) {
    _16
    if (ContextCompat.checkSelfPermission(this, permission) !=
    _16
    PackageManager.PERMISSION_GRANTED) {
    _16
    ActivityCompat.requestPermissions(this, REQUESTED_PERMISSIONS, requestCode);
    _16
    return false;
    _16
    }
    _16
    return true;
    _16
    }


    _14
    // Kotlin
    _14
    private val PERMISSION_REQ_ID_RECORD_AUDIO = 22
    _14
    private val PERMISSION_REQ_ID_CAMERA = PERMISSION_REQ_ID_RECORD_AUDIO + 1
    _14
    _14
    private fun checkSelfPermission(permission: String, requestCode: Int): Boolean {
    _14
    if (ContextCompat.checkSelfPermission(this, permission) !=
    _14
    PackageManager.PERMISSION_GRANTED) {
    _14
    ActivityCompat.requestPermissions(this,
    _14
    arrayOf(permission),
    _14
    requestCode)
    _14
    return false
    _14
    }
    _14
    return true
    _14
    }

Implement the Video Call logic

When your app opens, you create an RtcEngine instance, enable the video, join a channel, and publish the local video to the lower frame layout in the UI. When another user joins the channel, you app catches the join event and adds the remote video to the top frame layout in the UI.

The following figure shows the API call sequence of implementing Video Call.

1630573668305

To implement this logic, take the following steps:

  1. Import the Agora classes.

    In /app/java/com.example.<projectname>/MainActivity, add the following lines after import android.os.Bundle;:


    _4
    // Java
    _4
    import io.agora.rtc.IRtcEngineEventHandler;
    _4
    import io.agora.rtc.RtcEngine;
    _4
    import io.agora.rtc.video.VideoCanvas;


    _4
    // Kotlin
    _4
    import io.agora.rtc.IRtcEngineEventHandler
    _4
    import io.agora.rtc.RtcEngine
    _4
    import io.agora.rtc.video.VideoCanvas

  2. Create the variables that you use to create and join a video call channel.

    In /app/java/com.example.<projectname>/MainActivity, add the following lines after AppCompatActivity {:


    _22
    // Java
    _22
    // Fill the App ID of your project generated on Agora Console.
    _22
    private String appId = "";
    _22
    // Fill the channel name.
    _22
    private String channelName = "";
    _22
    // Fill the temp token generated on Agora Console.
    _22
    private String token = "";
    _22
    private RtcEngine mRtcEngine;
    _22
    _22
    private final IRtcEngineEventHandler mRtcEventHandler = new IRtcEngineEventHandler() {
    _22
    @Override
    _22
    // Listen for the remote user joining the channel to get the uid of the user.
    _22
    public void onUserJoined(int uid, int elapsed) {
    _22
    runOnUiThread(new Runnable() {
    _22
    @Override
    _22
    public void run() {
    _22
    // Call setupRemoteVideo to set the remote video view after getting uid from the onUserJoined callback.
    _22
    setupRemoteVideo(uid);
    _22
    }
    _22
    });
    _22
    }
    _22
    };


    _19
    // Kotlin
    _19
    // Fill the App ID of your project generated on Agora Console.
    _19
    private val APP_ID = ""
    _19
    // Fill the channel name.
    _19
    private val CHANNEL = ""
    _19
    // Fill the temp token generated on Agora Console.
    _19
    private val TOKEN = ""
    _19
    _19
    private var mRtcEngine: RtcEngine ?= null
    _19
    _19
    private val mRtcEventHandler = object : IRtcEngineEventHandler() {
    _19
    // Listen for the remote user joining the channel to get the uid of the user.
    _19
    override fun onUserJoined(uid: Int, elapsed: Int) {
    _19
    runOnUiThread {
    _19
    // Call setupRemoteVideo to set the remote video view after getting uid from the onUserJoined callback.
    _19
    setupRemoteVideo(uid)
    _19
    }
    _19
    }
    _19
    }

  3. Initialize the app and join the channel.

    Call the following core methods to join a channel in the MainActivity class. In the following sample code, the initializeAndJoinChannel function encapsulates these core methods.

    In /app/java/com.example.<projectname>/MainActivity, add the following lines after the onCreate function:


    _21
    // Java
    _21
    private void initializeAndJoinChannel() {
    _21
    try {
    _21
    mRtcEngine = RtcEngine.create(getBaseContext(), appId, mRtcEventHandler);
    _21
    } catch (Exception e) {
    _21
    throw new RuntimeException("Check the error.");
    _21
    }
    _21
    _21
    // By default, video is disabled, and you need to call enableVideo to start a video stream.
    _21
    mRtcEngine.enableVideo();
    _21
    _21
    FrameLayout container = findViewById(R.id.local_video_view_container);
    _21
    // Call CreateRendererView to create a SurfaceView object and add it as a child to the FrameLayout.
    _21
    SurfaceView surfaceView = RtcEngine.CreateRendererView(getBaseContext());
    _21
    container.addView(surfaceView);
    _21
    // Pass the SurfaceView object to Agora so that it renders the local video.
    _21
    mRtcEngine.setupLocalVideo(new VideoCanvas(surfaceView, VideoCanvas.RENDER_MODE_FIT, 0));
    _21
    _21
    // Join the channel with a token.
    _21
    mRtcEngine.joinChannel(token, channelName, "", 0);
    _21
    }


    _21
    // Kotlin
    _21
    private fun initializeAndJoinChannel() {
    _21
    try {
    _21
    mRtcEngine = RtcEngine.create(baseContext, APP_ID, mRtcEventHandler)
    _21
    } catch (e: Exception) {
    _21
    _21
    }
    _21
    _21
    // By default, video is disabled, and you need to call enableVideo to start a video stream.
    _21
    mRtcEngine!!.enableVideo()
    _21
    _21
    val localContainer = findViewById(R.id.local_video_view_container) as FrameLayout
    _21
    // Call CreateRendererView to create a SurfaceView object and add it as a child to the FrameLayout.
    _21
    val localFrame = RtcEngine.CreateRendererView(baseContext)
    _21
    localContainer.addView(localFrame)
    _21
    // Pass the SurfaceView object to Agora so that it renders the local video.
    _21
    mRtcEngine!!.setupLocalVideo(VideoCanvas(localFrame, VideoCanvas.RENDER_MODE_FIT, 0))
    _21
    _21
    // Join the channel with a token.
    _21
    mRtcEngine!!.joinChannel(TOKEN, CHANNEL, "", 0)
    _21
    }

  4. Add the remote interface when a remote user joins the channel.

    In /app/java/com.example.<projectname>/MainActivity, add the following lines after the initializeAndJoinChannel function:


    _8
    // Java
    _8
    private void setupRemoteVideo(int uid) {
    _8
    FrameLayout container = findViewById(R.id.remote_video_view_container);
    _8
    SurfaceView surfaceView = RtcEngine.CreateRendererView(getBaseContext());
    _8
    surfaceView.setZOrderMediaOverlay(true);
    _8
    container.addView(surfaceView);
    _8
    mRtcEngine.setupRemoteVideo(new VideoCanvas(surfaceView, VideoCanvas.RENDER_MODE_FIT, uid));
    _8
    }


    _9
    // Kotlin
    _9
    private fun setupRemoteVideo(uid: Int) {
    _9
    val remoteContainer = findViewById(R.id.remote_video_view_container) as FrameLayout
    _9
    _9
    val remoteFrame = RtcEngine.CreateRendererView(baseContext)
    _9
    remoteFrame.setZOrderMediaOverlay(true)
    _9
    remoteContainer.addView(remoteFrame)
    _9
    mRtcEngine!!.setupRemoteVideo(VideoCanvas(remoteFrame, VideoCanvas.RENDER_MODE_FIT, uid))
    _9
    }

Start and stop your app

Now you have created the Video Call functionality, start and stop the app. In this implementation, a video call starts when the user opens your app. The call ends when the user closes your app.

To implement this function, do the following:

  1. Check that the app has the correct permissions. If permissions are granted, call initializeAndJoinChannel to join a video call channel.

    In /app/java/com.example.<projectname>/MainActivity, replace onCreate with the following code in the MainActivity class.


    _12
    // Java
    _12
    @Override
    _12
    protected void onCreate(Bundle savedInstanceState) {
    _12
    super.onCreate(savedInstanceState);
    _12
    setContentView(R.layout.activity_main);
    _12
    _12
    // If all the permissions are granted, initialize the RtcEngine object and join a channel.
    _12
    if (checkSelfPermission(REQUESTED_PERMISSIONS[0], PERMISSION_REQ_ID) &&
    _12
    checkSelfPermission(REQUESTED_PERMISSIONS[1], PERMISSION_REQ_ID)) {
    _12
    initializeAndJoinChannel();
    _12
    }
    _12
    }


    _10
    // Kotlin
    _10
    override fun onCreate(savedInstanceState: Bundle?) {
    _10
    super.onCreate(savedInstanceState)
    _10
    setContentView(R.layout.activity_main)
    _10
    _10
    // If all the permissions are granted, initialize the RtcEngine object and join a channel.
    _10
    if (checkSelfPermission(Manifest.permission.RECORD_AUDIO, PERMISSION_REQ_ID_RECORD_AUDIO) && checkSelfPermission(Manifest.permission.CAMERA, PERMISSION_REQ_ID_CAMERA)) {
    _10
    initializeAndJoinChannel()
    _10
    }
    _10
    }

  2. When the user closes this app, clean up all the resources you created in initializeAndJoinChannel.

    In /app/java/com.example.<projectname>/MainActivity, add onDestroy after the onCreate function.


    _7
    // Java
    _7
    protected void onDestroy() {
    _7
    super.onDestroy();
    _7
    _7
    mRtcEngine.leaveChannel();
    _7
    mRtcEngine.destroy();
    _7
    }


    _7
    // Kotlin
    _7
    override fun onDestroy() {
    _7
    super.onDestroy()
    _7
    _7
    mRtcEngine?.leaveChannel()
    _7
    RtcEngine.destroy()
    _7
    }

Test your app

To test your app, follow the steps:

  1. Fill in the appId and token parameters with the App ID and temporary token that you retrieve from Agora Console. Fill channelName with the channel name that you use to generate the temporary token.
  2. Connect an Android device to your computer, and click Run 'app' on your Android Studio. A moment later you will see the project installed on your device.
  3. When the app launches, you should be able to see yourself on the local view.
  4. Ask a friend to join the video call with you on the demo app. Enter the same App ID and channel name. After your friend joins the channel, you should be able to see and hear each other.

Next steps

Generating a token by hand is not helpful in a production context. Authenticate Your Users with Tokens shows you how to start video calling with a token that you retrieve from your server.

See also

This section provides additional information for your reference.

Sample project

Agora provides an open-source sample project Basic Video Call on GitHub that implements one-to-one video call and group video call for your reference.

Other approaches to integrate the SDK

In addition to integrating the Agora Video 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 Video 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.
File or subfolderPath of your project
agora-rtc-sdk.jar file/app/libs/
arm64-v8a folder/app/src/main/jniLibs/
armeabi-v7a folder/app/src/main/jniLibs/
x86 folder/app/src/main/jniLibs/
x86_64 folder/app/src/main/jniLibs/
include folder/app/src/main/jniLibs/
If you use the armeabi architecture, copy files from the armeabi-v7a folder to the armeabi file of your project. Contact support@agora.io if you encounter any incompability issue.