Android SDK Tutorial

Android SDK Tutorial

Android SDK Tutorial

  • Bistri SDK – Android tutorial

    This short tutorial will help you create your first Android application using the Bistri SDK.
  • Device compatibility

    Most android devices released in the past two years should be able to work with our native SDK.
    This SDK is supported by Android 3.0 (API level 11) or higher.
    The most popular ARMv7 architecture is supported. x86 will follow soon.

  • Prerequisites

    1. Download bistri SDK at this address:

    2. You must have created an application on the Bistri Developers portal in order to get your personal API keys.

    If you don’t already have a developer account, you can freely create one at the following address:

     In the ‘referrer filters’ section of your application dashboard, don’t forget to specify your application package name. For instance, ‘com.bistri.api_demo’ for Bistri demo application.

    3. Create a new Android project using your favorite IDE like Android Studio or Eclipse ADT and import the library into your project.

  • Android manifest

    Like other Android applications, you need to specify the permissions required by your application.
    In your AndroidManifest.xml file, please add the following permissions:

    <uses-permission android:name="android.permission.INTERNET"/>
    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
    <uses-permission android:name="android.permission.MODIFY_AUDIO_SETTINGS"/>
    <uses-permission android:name="android.permission.RECORD_AUDIO"/>
    <uses-permission android:name="android.permission.CAMERA"/>
    <uses-feature android:name=""/>
    <uses-feature android:name=""/>

    You certainly want to keep your device from sleeping during a call. To do this, add the following permission:

    <uses-permission android:name="android.permission.WAKE_LOCK"/>

    Don’t forget to manage correctly your call screen to keep it on. For instance, you can use android:keepScreenOn="true" property in your layout, or you can set the flag FLAG_KEEP_SCREEN_ON in your code like this:

  • Add bistri conference SDK into your application

    Import com.bistri.api package into your activity.

    import com.bistri.api.Conference;
    import com.bistri.api.Conference.*;

    To get or create a bistri conference instance call, you’ll use getInstance() method.

    conference = Conference.getInstance( getApplicationContext() );

     For all the following examples, “conference” shall be considered as an instance of com.bistri.api.Conference.

  • Configure SDK

    To be able to use bistri SDK you need to set the personal keys you got after registering your application on the Bistri Developers Portal.

    conference.setInfo( "38077edb" /* application ID */, "4f304359baa6d0fd1f9106aaeb116f33" /* application Key */ );
  • Open/close a session on the server

    When a network connection is available, you need to call connect() to open a session and disconnect() to close it.
    Once the connection is established the onConnectionEvent method of conference event listener is invoked.

    if ( conference.getStatus() == Status.DISCONNECTED ) {
  • Conference event listener

    To interact with your application, the Bistri conference uses an event listener.
    The conference is able to notify, for instance, the connection status or the arrival of a new member in the room.

    conference.addListener( new Conference.Listener() {
        public void onConnectionEvent(Status state) {
            // Connection status change.
        public void onError(ErrorEvent error) {
            // An error occurred.
        public void onRoomJoined(String room_name) {
            // A room as been joined.
        public void onRoomQuitted() {
            // A room as been quitted.
        public void onNewPeer(PeerStream peerStream) {
            // A new member is in room. Handle his peerStream here.
        public void onRemovedPeer(PeerStream peerStream) {
            // A member has left the room. Handle his peerStream here.
        public void onMediaStream(String peerId, MediaStream mediaStream) {
            // A mediaStream is available.

    When connected, use join() method with the desired room name. Rooms are virtual “meeting points”. This is the place to join, where other users are connected.

    conference.join( "test_room" );

    To quit a room, use leave().

    if ( conference.isInRoom() ) {
  • Display video stream

    Each member of a room have a corresponding PeerStream object.
    This object is used to handle a MediaStream object.
    When a PeerStream is available, the event callback onNewPeer() is called, with the PeerStream as a parameter.
    When a PeerStream is destroyed, the event callback onRemovedPeer() is invoked.

    To know the owner of a given PeerStream, call peerStream.getId().

    When a MediaStream is available, the event callback onMediaStream() of PeerStream.Handler is called.
    A MediaStream contains audio and/or video.
    To know if a MediaStream contains video, you can call the method hasVideo()

    A MediaStream with video can be displayed by retrieving the render with getRender()

    PeerStream.Handler mediaStreamHandler = new MediaStream.Handler() {
        public void onVideoRatioChange(String peer_id, MediaStream mediaStream, float ratio) {
    PeerStream.Handler peerStreamHandler = new PeerStream.Handler() {
        public void onMediaStream( String peer_id, MediaStream mediaStream ) {
            if ( !mediaStream.hasVideo() ) {
            mediaStream.setHandler( mediaStreamHandler );
            View renderView = mediaStream.getRender();
            // Add the render view into your video layout ( A layout of your choice )
            videoLayout.addView( renderView );
    public void onNewPeer(PeerStream peerStream) {
        // A new member is in room. Handle his peerStream here.
        peerStream.setHandler( peerStreamHandler );
  • DataChannels

    There is two ways to open a data channel:
    The first one is to call openDataChannel(String label) method of an existing PeerStream

    The second one is to call openDataChannel(String peerId, String label, String roomName) method of Conference.

    When the DataStream is got, don’t forget to set an handler ( using setHandler ). This allow you to be informed when data is received or if the status has changed.
    Send data using send method.
    Close the DataStream using close.

     See documentation for more details about DataStream

    // Open a DataStream
    DataStream dataStream = peerStream.openDataChannel( "TEST" );
    dataStream.setHandler( new DataStream.Handler() {
            public void onOpen(DataStream myself) {
                Log.d( "DataStream.Handler", "onOpen" );
            public void onMessage(DataStream myself, ByteBuffer message, boolean binary) {
                Log.d( "DataStream.Handler", "onMessage length:" + message.capacity() );
                if ( !binary ) {
                    byte[] b = new byte[message.remaining()];
                    Log.d( "DataStream.Handler", "message:" + new String(b) );
            public void onClose(DataStream myself) {
                Log.d( " DataStream.Handler", "onClose" );
            public void onError(DataStream myself, String error) {
                Log.d( " DataStream.Handler", "onError : " + error );
    } );
    // Send data
    dataStream.send( "Hello world" );
    // Close DataStream
  • Video/Audio options

    For more versatility, it is possible to customize audio and video quality with the following options.
    Use setVideoOption() to set a video option and setAudioOption() for audio.
    For instance, it is possible to set the video size of a video capture.

     See documentation for more details about available options

    conference.setVideoOption( VideoOption.MAX_WIDTH, 320 );
    conference.setVideoOption( VideoOption.MAX_HEIGHT, 240 );
    conference.setVideoOption( VideoOption.MAX_FRAME_RATE, 15 );
    conference.setAudioOption( AudioOption.PREFERRED_CODEC, AudioCodec.ISAC );
    conference.setAudioOption( AudioOption.PREFERRED_CODEC_CLOCKRATE, 16000 );
  • Toggle loudspeaker

    To enable or disable loud speaker, use setLoudspeaker().
    It is enabled by default.

    // Loudspeaker status member
    private boolean loudspeaker = true;
    public void toggleLoudspeaker(){
        loudspeaker = !loudspeaker; // Toggle status
        conference.setLoudspeaker( loudspeaker );