HLS Streaming: Android SDK – Video API

HLS Streaming helps you to reach extremely large number of audiences with your video session in real time. It supports adaptive bitrate streaming to get best quality video based on available network bandwidth at receiving end.

Table of Contents

• Overview
• Service Subscription
• HLS View
• HLS-enabled Room
• Audience Token to join
• Room Notifications
• HLS Player

Overview

HLS Streaming helps to scale up your reach to a larger audience with your video session, meetings, webinar in real time. Audiences receive best quality video streaming based on available bandwidth at their end. A web-based Video UI may be linked to define the view of your streaming which will be played across devices.

At the background, the linked Video UI is made to join the video room automatically and a HLS Stream is created using the same view. As the Stream is ready, end points receive a HLS Stream URL to play in HLS Player.

Service Subscription

HLS Streaming Infrastructure is owned and managed by EnableX Therefore, it’s a subscription based service. Connect to Sales/Account Manager for subscription.

In case you look to livestream to YouTube, Vimeo, LinkedIn and/or Facebook; you need RTMP Live Streaming.

HLS View

HLS Streaming experience for audiences may be achieved through the Video UI presented to them. You can have a Video UI or HLS View in either of the following ways:

• Use Default View: The simplest and quickest way is to use the default view for HLS Streaming. You needn’t code for it. It’s available with EnableX. There are limited customization option available.
• Develop Custom View: To have a custom view, a Web-based Application needs to be developed, hosted over publicly accessible “https” URL and linked to video room. Read everything you need to know to develop custom view for your stream.

HLS Enabled Room

Even if HLS service is subscribed, the following Room Level “settings” needs to be done to have HLS Streaming in Video Session.

• audiences: Numeric. Optional. Number of audience needed in the room. It can’t be greater than capping set at subscription. If any of the following settings are being set with room, audience count must be set to some positive number. 
• send_audiences_stats: Boolean, true or false. Default false. Set it to true, if end-point needs to receive user-connected and user-disconnected event on entry and exit of an audience.
• hls_view_url: String. URL. Optional. A custom view URL. If not passed, the default HLS Streaming View will be used. However, you may explicitly pass “DEFAULT” as value to this key.

• Know how to define custom Streaming View?
• Know how to create video room?

Example: Room Definition JSON Payload to enable HLS Streaming.

{
  "name": "HLS Trial",
  "owner_ref": "XOXO",
  "settings": {
    "description": "HLS Trial",
    "mode": "group",
    "scheduled": false,
    "adhoc": false,
    "duration": 30,
    "moderators": "1",
    "participants": "2",
    "audiences": 6,
    "hls_view_url": "https://URL-DOMAIN/PATH/?token=",
    "send_audiences_stats": true,
    "auto_recording": false,
    "quality": "SD"
  }
}

Note: If HLS is not subscribed, room definition with HLS related settings is not permitted.  

Audience Token to join

A new role has been introduced for HLS Audience joining a room. It’s audience. Get a token for audience role to join a session. As soon as the first audience joins video room, HLS streaming gets initiated automatically. HLS Streaming stops when all audiences exit or disconnect from the video room.

Know how to create Token?

Example: Create Token JSON Payload for audience role

{
  "name": "John",
  "user_ref": "XOXO",
  "role": "audience"
}

Room Notifications

HLS Streaming starts as soon as first audience joins the video room and it stops when last audience exits/disconnects from the room. So, use related HLS Callbacks handle UI to create user experience.

Observer: public void setEnxHlsObserver(EnxHlsStreamObserver enxHlsObserver) – Add this Observer to start receiving HLS Notifications.

Callbacks:

• onHlsStarted: When HLS Stream gets started, it’s sent to publisher and logged in audiences. Subsequently it’s sent to new audience on room connection. It carries hls_url to play.
• onHlsStopped: When HLS Stream stops. It’s sent to the publisher when the last audience leaves video room.
• onHlsWaiting: When HLS Stream initiation process is on and waiting to get started. It sent to audiences only.
• onHlsFailed – WHen HLS Stream fails.

Example:

//Set Observer 
enxRoom.setEnxHlsObserver(this);
 
// On HLS Start
public void onHlsStarted(JSONObject jsonObject) {
	// JSON has hls_url key to play in HLS Player
}

// On HLS Stop
public void onHlsStopped(JSONObject jsonObject) {

}
 
// On HLS Waiting
public void onHlsWaiting(JSONObject jsonObject) {

}

// On HLS Failure
public void onHlsFailed(JSONObject jsonObject) {

}

Error Codes

Error	Description
	On HLS Start
7501	Start HLS Streaming input parameters missing, Internal Server Error
7502	Start HLS Streaming timeout, Internal Server Error
7503	Start HLS Streaming request is in process
7504	Start HLS Streaming request timeout, Internal Server Error
7505	HLS Streaming request is in waiting, will be started
7506	HLS Streaming can’t be started now, Please try after 2 minutes
7507	Start HLS Streaming input parameters missing, Internal Server
7508	Start HLS Streaming input parameters missing, Internal Server Error
	On HLS Stop
7520	HLS Streaming request was in waiting, successfully removed the request from waiting.
7521	Stop HLS Streaming failed, Internal Server Error
7522	Stop HLS Streaming timeout, Internal Server Error
	On HLS Waiting
7509	HLS Streaming cannot be started, Internal Server Error, please try after 2 minutes
7510	HLS Streaming start failed, Internal Server Error, please try after 2 minutes
7511	Last HLS streaming request is in waiting
7512	HLS Streaming can’t be started, please try again. Internal Server Error
7513	HLS Streaming failed to start, Internal Server Error
	HLS Generic Error
7000	Start HLS Streaming input parameters missing, Internal Server Error

HLS Player

HLS Stream URL received through Video SDK needs to be played using HLS Player. The following code explains how to use ExoPlayer to play HLS Stream.

<com.google.android.exoplayer2.ui.PlayerView
    android:id="@+id/exoplayer"
    android:layout_width="match_parent"
    android:layout_height="wrap_content"
    android:minHeight="100dp"
    app:resize_mode="fixed_width"
/>
 
 
PlayerView ePlayer= findViewById(R.id.exoplayer);
 
String m3u8URL = "https://moctobpltc-i.akamaihd.net/hls/live/571329/eight/playlist.m3u8";
// Create a data source factory.
DefaultHttpDataSource.Factory dataSourceFactory = new DefaultHttpDataSource.Factory();
// Create a HLS media source pointing to a playlist uri.
HlsMediaSource hlsMediaSource =
    new HlsMediaSource.Factory(dataSourceFactory)
	    .createMediaSource(MediaItem.fromUri(m3u8URL));
// Create a player instance.
ExoPlayer player = new ExoPlayer.Builder(context).build();
// Set the media item to be played.
player.setMediaSource(hlsMediaSource);
// Prepare the player.
player.prepare();
ePlayer.setPlayer(player);