Getting started with the Android SDK

This article is to help setting an Android project using PhenixRTS Android SDK alongside our API documentation (found here).

Prerequisites:

Android studio and development environment. Installation instructions can be found here.

Instructions

To set up and build a project using our Android SDK, follow the instructions in this section.

  1. Open android studio and create a new project.

  2. Add the following dependency to app/build.gradle:

    1 implementation "com.phenixrts.android:phenix-sdk-android:2021.0.15"

     

    PhenixRTS SDK dependency in app/build.gradle

    If you are using a different version of the Phenix Android SDK, use that version number in place of 2021.0.15.

  3. Add maven credentials and url to the project’s settings.gradle file (replace values with your own).

    1 2 3 4 5 6 7 maven { credentials { username "YOUR_GIT_USERNAME" password "YOUR_GIT_KEY" } url "https://maven.pkg.github.com/PhenixRTS/AndroidSDK" }



    Git credentials in the project’s settings.gradle

     

  4. Once you have added the dependency and git settings, be sure to sync the gradle settings. The project will not compile without synchronizing these settings.

  5. Add a surface view to activity_main.xml as shown below:

    1 2 3 4 5 6 7 <SurfaceView android:id="@+id/surface" android:layout_width="match_parent" android:layout_height="match_parent" android:keepScreenOn="true" tools:layout_editor_absoluteX="52dp" tools:layout_editor_absoluteY="0dp"/>

     

  6. Add the following code to your MainActivity.kt, replacing the token and channel alias with actual values as indicated.

    1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 package com.example.phenixrtsandroidviewer import android.os.Bundle import android.util.Log import android.view.SurfaceView import androidx.appcompat.app.AppCompatActivity import com.phenixrts.common.RequestStatus import com.phenixrts.environment.android.AndroidContext import com.phenixrts.express.* import com.phenixrts.pcast.AspectRatioMode import com.phenixrts.pcast.Renderer import com.phenixrts.pcast.RendererOptions import com.phenixrts.pcast.android.AndroidVideoRenderSurface import com.phenixrts.room.RoomService class MainActivity : AppCompatActivity() { private var currentRoomService: RoomService? = null private var currentRenderer: Renderer? = null private var currentSubscriber: ExpressSubscriber? = null; override fun onCreate(savedInstanceState: Bundle?) { super.onCreate(savedInstanceState) setContentView(R.layout.activity_main) val surfaceView = findViewById<SurfaceView>(R.id.surface) // must set Context first AndroidContext.setContext(applicationContext) render(surfaceView) } private fun render(surfaceView: SurfaceView) { //Replace with your viewing token and channel alias: val token = "DIGEST:..." val channelAlias = "yourAlias" Log.e("StreamingApi", "Creating StreamingApi") Log.e("StreamingApi", "token: $token") val renderSurface = AndroidVideoRenderSurface(surfaceView.holder) val pcastExpressOptions = PCastExpressFactory.createPCastExpressOptionsBuilder() .withAuthenticationToken(token) .withMinimumConsoleLogLevel("info") .withUnrecoverableErrorCallback { status: RequestStatus?, description: String? -> Log.e("StreamingApi", "Unrecoverable Error: $description") } .buildPCastExpressOptions() val roomExpressOptions = RoomExpressFactory.createRoomExpressOptionsBuilder() .withPCastExpressOptions(pcastExpressOptions) .buildRoomExpressOptions() val channelExpressOptions = ChannelExpressFactory.createChannelExpressOptionsBuilder() .withRoomExpressOptions(roomExpressOptions) .buildChannelExpressOptions() //channel express created with options val channelExpress = ChannelExpressFactory.createChannelExpress(channelExpressOptions) // Just an example (you can omit renderer options if defaults are ok) val rendererOptions = RendererOptions().apply { aspectRatioMode = AspectRatioMode.LETTERBOX } val joinRoomOptions = RoomExpressFactory.createJoinRoomOptionsBuilder() .withRoomAlias(channelAlias) .withCapabilities(arrayOf()) .buildJoinRoomOptions() val joinChannelOptions = ChannelExpressFactory.createJoinChannelOptionsBuilder() .withJoinRoomOptions(joinRoomOptions) .withStreamToken(token) .withRenderer(renderSurface) .withRendererOptions(rendererOptions) .buildJoinChannelOptions() Log.e("StreamingApi", "joining channel") channelExpress.joinChannel( joinChannelOptions, { status: RequestStatus, roomService: RoomService? -> if (status != RequestStatus.OK) { Log.e( "StreamingApi", "Could not join room: ${status.name}, ${roomService?.toString()}" ) // Handle room join error return@joinChannel } Log.e("StreamingApi", "status is OK") // Important: Store room service reference, otherwise we will leave channel again // as soon as this RoomService instance is garbage collected: currentRoomService = roomService } ) { status: RequestStatus?, subscriber: ExpressSubscriber?, renderer: Renderer? -> when (status) { RequestStatus.OK -> { Log.e("StreamingApi", "Stream connected") currentSubscriber = subscriber; currentRenderer = renderer; // Successfully subscribed to a stream. No need to hold on to any references } RequestStatus.NO_STREAM_PLAYING -> { Log.e("StreamingApi", "No streams currently playing") // No stream playing in channel, update UI accordingy } else -> { Log.e("StreamingApi", "Failed to join room") // We failed to subscribe and retry attempts must have failed } } } } }

     

  7. Run project to view stream (either on a device or an emulator).

Troubleshooting

  1. Be sure to have a stream published that corresponds to the alias and token that you used in the code snippet above.

  2. Double check that you have setup your GitHub to use an access token.

  3. Confirm that you have android:keepScreenOn="true" on your SurfaceView object in the main_activity.xml.

More information

More information about the Phenix Android SDK and GitHub can be found at the following links.