Menu

Lumen help

Legacy Integration for VOPlayer on Android

Note: This integration is deprecated and will be sunset. We strongly recommend using Mesh Delivery Android SDK 22.01 and above.

Mesh Delivery for Streaming can be easily integrated with VOPlayer into your Android and Android TV app, in just a few simple steps using our Legacy SDK for Android. In this guide, we will show you how to integrate legacy Mesh Delivery using VOPlayer on Android.

Project setup

Dependencies

 

The easiest way to get the Lumen SDK is to add it as a Gradle dependency. We assume you are using Android Studio with the latest tools updates as recommended by Google. If not, write to us at cdnsupport@lumen.com.

                repositories {
    maven {
        url 'https://sdk.streamroot.io/android'
    }
}

Next, add the Mesh Delivery dependency to the build.gradle file of your app module.

                implementation 'io.streamroot.dna:dna-core:3.23.0'

Android version requirement

 

Mesh Delivery is validated on Android Lollipop, version 5.0 and above.

 

Mesh Delivery can still be included as a dependency for build targets Android kitKat 4.4 and lower, however the peer-to-peer module will be disabled at runtime. Google doesn't support Android 4.4 and lower anymore.

 

Java version requirement

 

The latest versions of our SDK use the lambda feature of Java 8, which is supported by all Android devices.

As mentioned in the official documentation, you must configure your project with the following snippet:

                android {
// Configure only for each module that uses Java 8
// language features (either in its source code or
// through dependencies).
compileOptions {
      sourceCompatibility JavaVersion.VERSION_1_8
      targetCompatibility JavaVersion.VERSION_1_8
  }
}

Integrate Lumen SDK

1. Set streamrootKey

 

Before doing anything, you must set the streamrootKey as a metadata in the application manifest.

                <meta-data
        android:name="io.streamroot.dna.StreamrootKey"
        android:value="streamrootKey"/>

streamrootKey: Refers to your Lumen unique identifier that you will find in the Account section of the Mesh Delivery Dashboard. If you don't have one, you can ask for a free trial on our website.

Note: It is also possible to pass your streamrootKey at Lumen Delivery Client instantiation and initialization.

2. Create a new Lumen Delivery Client instance

 

Now that you have set the streamrootKey, you are able to create the Lumen Delivery Client instances.

                private DnaClient initStreamroot(VOPlayer voMediaPlayer) {
    DnaClient dnaClient = null
    
    try {
        dnaClient = DnaClient.newBuilder()
            .context(applicationContext)
            .playerInteractor(new VOPlayerInteractor(voMediaPlayer, mLatencyPerChunkCount))
            .start(mMediaUri)
    } catch (e: Exception) {
        Toast.makeText(applicationContext, e.message, Toast.LENGTH_LONG).show()
    }

    return dnaClient
}

Builder parameters:

 

  • context: An instance of context.

  • streamrootKey : A method to pass your streamrootKey. It will override the one set in the application manifest.

  • playerInteractor: An object that implements playerInteractor. See below for more details.

  • latency: A method that works for HLS and MPEG-DASH on live content. If it's set for a VoD content, this parameter will be ignored. The value must be strictly positive and in seconds. We recommend setting the value to 30s.

  • start : A method that will create and start a new instance of the SDK. It expects the URL of your stream.
     

Other DNA options can be called in the builder. Please refer to dnaConfig overview for android to learn more about them.

Note: In a Live use case, to optimize the efficiency of our solution, you will need to customize the latency at player's level. This will impact the time we have to do any p2p exchange.

 

On the VO Player, you will be need to use the `latencyPerChunkCount` parameter passed in the class constructor. As this parameters is in "number of chunks", it depends on your packaging parameters. Your latency in seconds will then be `latencyPerChunkCount` multiplied by the duration of your chunks.

 

The minimum buffer level of the VO Player is 20 seconds, so we advise on putting at least a 30 seconds latency to have efficient results. The latency needs also to be lower than the playlist duration.

 

For VOD, put 0 there.

3. Give your player the new URL


Once you have a running instance of the SDK, you must retrieve the final URL and input it to your player instead of your original one. The SDK exposes a getManifestUrl() method that will do it as expected.

                dnaClient.getManifestUrl() : <Uri>

4. Implement the playerInteractor

This player interactor module is how our SDK gets accurate metrics regarding the client session. The SDK will need the following information to work optimally:
 

  • Looper
    looper must return the looper used to create the player.
 
  • Loaded TimeRanges
    loadedTimeRanges must return a list of TimeRange (in milliseconds).
    Each TimeRange represents a continuous interval of content present in the buffer. It is mandatory to return at least the TimeRange going from the playback time to the end of the buffered interval containing the playback time.

  • Current playback time
    playbackTime must return the current time of the player in milliseconds.

  • Buffer target
    bufferTarget must return the target the player will try to buffer.
    setBufferTarget allows us to dynamically change the buffer target of the player to optimize DNA performances.
       
                import android.os.Looper;
import com.viaccessorca.voplayer.VOPlayer;
import org.jetbrains.annotations.NotNull;
import org.jetbrains.annotations.Nullable;
import java.util.ArrayList;
import java.util.HashMap;
import java.util.List;
import io.streamroot.dna.core.PlayerInteractor;
import io.streamroot.dna.core.TimeRange;

public final class VOPlayerInteractor implements PlayerInteractor {
    private final VOPlayer mPlayer;

    private final int mBufferTarget;

    public VOPlayerInteractor(final VOPlayer player, int latencyPerChunkCount) {
        mPlayer = player;

        mBufferTarget = getBufferTarget(
                VOPlayer.AbrControls.ABR_CONTROLS_MAX_BUFFER_LEVEL_MIN,
                VOPlayer.AbrControls.ABR_CONTROLS_MAX_BUFFER_LEVEL_MAX
        );

        if (latencyPerChunkCount > 0) {
            customizeLatency(latencyPerChunkCount);
        }
        customizeBufferTarget();
    }

    @NotNull
    @Override
    public List<TimeRange> loadedTimeRanges() {
        return new ArrayList<TimeRange>() {{
            add(new TimeRange(
                    mPlayer.getCurrentPositionAbsolute(),
                    mPlayer.getCurrentBufferLevel()));
        }};
    }

    @Nullable
    @Override
    public Looper looper() {
        return Looper.getMainLooper();
    }

    @Override
    public long playbackTime() {
        return mPlayer.getCurrentPositionAbsolute();
    }

    @Override
    public double bufferTarget() {
        return mBufferTarget;
    }

    @Override
    public void setBufferTarget(double v) {
    }

    private int getBufferTarget(int min, int max) {
        return (int) (Math.random() * (max - min) + min);
    }

    private void customizeLatency(int latencyInChunkCount) {
        HashMap<String, Object> customization = new HashMap<>();

        customization.put(VOPlayer.CustomMode.LIVE_LATENCY, latencyInChunkCount);
        mPlayer.setCustomMode(customization);
    }

    private void customizeBufferTarget() {
        VOPlayer.AbrControls abrControls = new VOPlayer.AbrControls();

        abrControls.m_iMaxBufferValue = mBufferTarget;
        mPlayer.setHttpStreamingAbrControlSettings(abrControls);
    }
}
 

5. Implement the BandwidthMeter

 

The BandwidthMeter allows for estimating the bandwidth needed to download video chunks. The SDK will need:

 

  • A bandwidth listener: Implementation of Mesh Delivery BandwidthListener.

 

Please refer to the example below.

                import com.viaccessorca.voplayer.VOPlayer;
import io.streamroot.dna.core.BandwidthListener;

public final class VOBandwidthListener implements BandwidthListener {
    private final VOPlayer mPlayer;

    public VOBandwidthListener(final VOPlayer player) {
        mPlayer = player;
    }

    @Override
    public void onBandwidthChange(long l) {
        mPlayer.setHttpStreamingMaximumBitrate((int) l);
    }
}

Then call the bandwidthListener in the builder.

                DnaClient dnaClient = DnaClient.newBuilder()
     .context(<Context>)
     .playerInteractor(new VOPlayerInteractor(voMediaPlayer, mLatencyPerChunkCount))
     ...

     .bandwidthListener(new VOBandwidthListener(voMediaPlayer))

     ...
     .start(<URI>);

6. Integrate the QoS Module (optional)

 

This QoS module will link VOPlayer events to our SDK to get accurate metrics on the client session. If the QoS module is not implemented, a default module directly embedded in the SDK will be used instead.

 

The following is an example of the class to add to the app to do so.

                import com.viaccessorca.voplayer.VOPlayer;
import io.streamroot.dna.core.PlaybackState;
import io.streamroot.dna.core.QosModule;

public final class VOQoSModule extends QosModule implements
        VOPlayer.OnBufferingUpdateListener,
        VOPlayer.OnCompletionListener,
        VOPlayer.OnSeekCompleteListener,
        VOPlayer.OnErrorListener,
        VOPlayer.OnInfoListener {

    public VOQoSModule(final VOPlayer player) {
        player.setOnBufferingUpdateListener(this);
        player.setOnCompletionListener(this);
        player.setOnSeekCompleteListener(this);
        player.setOnErrorListener(this);
        player.setOnInfoListener(this);
    }

    @Override
    public void onBufferingUpdate(VOPlayer voPlayer, int i) {
        if (i == 100) {
            if (voPlayer.isPlaying()) {
                playbackStateChange(PlaybackState.PLAYING);
            } else {
                playbackStateChange(PlaybackState.PAUSING);
            }
        } else {
            playbackStateChange(PlaybackState.BUFFERING);
        }
    }

    @Override
    public void onCompletion(VOPlayer voPlayer) {
        playbackStateChange(PlaybackState.ENDED);
    }

    @Override
    public void onSeekComplete(VOPlayer voPlayer) {
        playbackStateChange(PlaybackState.SEEKING);
    }

    @Override
    public boolean onError(VOPlayer voPlayer, int i, int i1) {
        playbackErrorOccurred();
        return true;
    }

    @Override
    public boolean onInfo(VOPlayer voPlayer, int what, int extra) {
        if (what == VOPlayer.MEDIA_INFO_HTTP_STREAMING && VOPlayer.MEDIA_INFO_ALTERNATE_CHANGE == extra) {
            trackSwitchOccurred();
        }

        return false;
    }
}

You must then call the VOQosModule in the builder.

                DnaClient dnaClient = DnaClient.newBuilder()
     .context(<Context>)
     .playerInteractor(new VOPlayerInteractor(voMediaPlayer, mLatencyPerChunkCount))
     ...

     .qosModule(new VOQoSModule(voMediaPlayer))
     ...
     .start(<URI>);

7. Stop the Mesh Delivery Client

 

Once the video is done playing, you must stop the SDK you created earlier. Calling the following method will finish the ongoing tasks and release the resources.

                dnaClient.close();

8. Network security configuration

 

Starting with Android 9 (API level 28), cleartext support is disabled by default.
 

As Streamroot SDK works as a local HTTP proxy, it is required to do one of the following
 

  • Activate back cleartext to reactivate all HTTP calls in the AndroidManifest.xml (Not recommended)
                <?xml version="1.0" encoding="utf-8"?>
<manifest ...>
    <application
        ...
        android:usesCleartextTraffic="true">
        ...
    </application>
</manifest>
  • Add 'localhost' in the allowed domains in a new network_security_config.xml file
                <?xml version="1.0" encoding="utf-8"?>
<network-security-config>
    <domain-config cleartextTrafficPermitted="true">
        <domain includeSubdomains="true">localhost</domain>
    </domain-config>
</network-security-config>
  • And add this file in the AndroidManifest.xml file
                <?xml version="1.0" encoding="utf-8"?>
<manifest ...>
    <application
        ...
        android:networkSecurityConfig="@xml/network_security_config">
        ...
    </application>
</manifest>

More info can be found in the Android documentation.