NOTE: These sample applications use the Twilio Video 1.x APIs. For examples using our 2.x APIs, please see the 2.0 branch.

Twilio Video Quickstart for Android

Get started with Video on Android:

Quickstart - Run the quickstart app
Examples - Customize your video experience with these examples
Using an Emulator - Setup an emulator in Android Studio
Reducing APK Size - Use ABI splits to reduce your APK size
Troubleshooting Audio - Mitigate audio issues in your application
Setup an Access Token Server - Setup an access token server
More Documentation - More documentation related to the Video Android SDK
Issues & Support - Filing issues and general support

Quickstart

To get started with the Quickstart application follow these steps:

Open this project in Android Studio and select the quickstart app module.

Type in an identity and click on "Generate Access Token" from the Testing Tools page.

Paste the Access Token into the VideoActivity.java.

Run the quickstart app on an Android device or Android emulator.
Press the call button at the bottom right portion of the screen and type a room name to connect to a Room.

On another device, use an additional access token with a different identity to connect to the same room.

Examples

In addition to the quickstart we've also added a few examples of use cases that show you how to create and customize your media as follows:

Custom Video Capturer - Demonstrates how a custom VideoCapturer can be implemented to capture the contents of a View.
Custom Video Renderer - Demonstrates how to implement a custom VideoRenderer that captures a Bitmap of the last rendered frame.
Screen Capturer - Demonstrates how to use the screen capturer.
Advanced Camera Capturer - Demonstrates advanced use cases of CameraCapturer like injecting custom camera paremeters.
Video Invite - Demonstrates how to use Twilio Notify to invite other participants to a room.

Using an Emulator

Using an Emulator This guide will walk you through setting up and emulator that is compatible with the Video SDK.

Requirements

Android Studio 2.0+

Guide

Open Android Studio and navigate to Tools → Android → AVD Manager.

2. Create a virtual device.

3. Select your desired device.

4. Select a system image. We recommend either x86 or x86_64 images.

5. Click “Show Advanced Settings” and we recommend setting both cameras as “Emulated”. Note that other camera configurations will work with the exception of setting both cameras as “webcam()”.

6. Configure the rest of your device accordingly and click “Finish”.

Reducing APK Size

Our library is built using native libriares. As a result, if you use the default gradle build you will generate an APK with all four architectures(armeabi-v7a, arm64-v8a, x86, x86_64 in your APK.

APK splits allow developers to build multiple APKs for different screen sizes and ABIs. Enabling APK splits ensures that the minimum amount of files required to support a particular device are packaged into an APK.

The following snippet shows an example build.gradle with APK splits enabled.

apply plugin: 'com.android.application'

android {
    compileSdkVersion 24
    buildToolsVersion "24.0.2"

    defaultConfig {
        applicationId "com.twilio.video.quickstart"
        minSdkVersion 16
        targetSdkVersion 24
        versionCode 1
        versionName "1.0"
    }

    // Specify that we want to split up the APK based on ABI
    splits {
        abi {
            // Enable ABI split
            enable true

            // Clear list of ABIs
            reset()

            // Specify each architecture currently supported by the Video SDK
            include "armeabi-v7a", "arm64-v8a", "x86", "x86_64"

            // Specify that we do not want an additional universal SDK
            universalApk false
        }
    }
}

dependencies {
    compile "com.twilio:video-android:1.0.0-beta4"
}

The adoption of APK splits requires developers to submit multiple APKs to the Play Store. Refer to Google’s documentation for how to support this in your application.

Troubleshooting Audio

The following sections provide guidance on how to ensure optimal audio quality in your applications.

Configuring AudioManager

The following snippet shows how to configure AudioManager for optimal experience when sharing audio to a Room.

private void configureAudio(boolean enable) {
    if (enable) {
        previousAudioMode = audioManager.getMode();
        // Request audio focus before making any device switch.
        requestAudioFocus();
        /*
         * Use MODE_IN_COMMUNICATION as the default audio mode. It is required
         * to be in this mode when playout and/or recording starts for the best
         * possible VoIP performance. Some devices have difficulties with
         * speaker mode if this is not set.
         */
        audioManager.setMode(AudioManager.MODE_IN_COMMUNICATION);
        /*
         * Always disable microphone mute during a WebRTC call.
         */
        previousMicrophoneMute = audioManager.isMicrophoneMute();
        audioManager.setMicrophoneMute(false);
    } else {
        audioManager.setMode(previousAudioMode);
        audioManager.abandonAudioFocus(null);
        audioManager.setMicrophoneMute(previousMicrophoneMute);
    }
}

private void requestAudioFocus() {
    if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
        AudioAttributes playbackAttributes = new AudioAttributes.Builder()
                .setUsage(AudioAttributes.USAGE_VOICE_COMMUNICATION)
                .setContentType(AudioAttributes.CONTENT_TYPE_SPEECH)
                .build();
        AudioFocusRequest focusRequest =
                new AudioFocusRequest.Builder(AudioManager.AUDIOFOCUS_GAIN_TRANSIENT)
                        .setAudioAttributes(playbackAttributes)
                        .setAcceptsDelayedFocusGain(true)
                        .setOnAudioFocusChangeListener(
                                new AudioManager.OnAudioFocusChangeListener() {
                                    @Override
                                    public void onAudioFocusChange(int i) { }
                                })
                        .build();
        audioManager.requestAudioFocus(focusRequest);
    } else {
        audioManager.requestAudioFocus(null, AudioManager.STREAM_VOICE_CALL,
                AudioManager.AUDIOFOCUS_GAIN_TRANSIENT);
    }
}

Configuring Hardware Audio Effects

Our library performs acoustic echo cancellation (AEC), noise suppression (NS), and auto gain control (AGC) using device hardware by default. Using device hardware is more efficient, but some devices do not implement these audio effects well. If you are experiencing echo, background noise, or unexpected volume levels on certain devices reference the following snippet for enabling software implementations of AEC, NS, and AGC.

/*
 * Execute any time before creating a LocalAudioTrack and connecting 
 * to a Room.
 */

// Use software AEC
WebRtcAudioUtils.setWebRtcBasedAcousticEchoCanceler(true);

// Use sofware NS
WebRtcAudioUtils.setWebRtcBasedNoiseSuppressor(true);

// Use software AGC
WebRtcAudioUtils.setWebRtcBasedAutomaticGainControl(true);

Setup an Access Token Server

Using Twilio's Video client within your applications requires an access token.

You can run your own server that provides access tokens, based on your Twilio credentials. This server can either run locally on your development machine, or it can be installed on a server. If you run the server on your local machine, you should use the ngrok utility to give the server an externally accessible web address. That way, you can run the quickstart app on an Android device.

Configuring the Access Token Server

If you want to be a little closer to a real environment, you can download one of the video quickstart applications - for instance, Video Quickstart: Node and either run it locally, or install it on a server.

You'll need to gather a couple of configuration options from your Twilio developer console before running it, so read the directions on the quickstart. You'll copy the .env.example file to a .env file, and then add in these credentials:

Credential	Description
Twilio Account SID	Your main Twilio account identifier - find it on your dashboard.
API Key	Used to authenticate - generate one here.
API Secret	Used to authenticate - just like the above, you'll get one here.

A Note on API Keys

When you generate an API key pair at the URLs above, your API Secret will only be shown once - make sure to save this in a secure location.

Running the Video Quickstart with ngrok

If you run your video chat application on an Android device, you'll need to provide an externally accessible URL for the app. The ngrok tool creates a publicly accessible URL that you can use to send HTTP/HTTPS traffic to a server running on your localhost. Use HTTPS to make web connections that retrieve a Twilio access token.

When you get a URL from ngrok, go ahead and update VideoActivity.java with the new URL. At the very bottom is the retrieveAccessTokenfromServer() method. If you go down this path, be sure to follow the directions in the comments in the initializeTwilioSdk() method at the top of the source file - you will need to comment out everything under "OPTION 1" and uncomment the one line under "OPTION 2". You will also need to update the code if your ngrok URL changes.

Issues and Support

Please file any issues you find here on Github.

For general inquiries related to the Video SDK you can file a support ticket

mhdtouban/video-quickstart-android