tencent cloud

Overview

The Tencent Cloud RT-Cube Player for Android is an open-source player component of Tencent Cloud. It integrates quality monitoring, video encryption, Top Speed Codec, definition selection, and small window playback and is suitable for all VOD and live playback scenarios. It encapsulates complete features and provides upper-layer UIs to help you quickly create a playback program comparable to mainstream video applications.

If the Player component cannot meet your custom requirements and you have development experience, you can integrate the RT-Cube Player SDK as instructed in Integration Guide to customize the player UI and playback features.

Prerequisites

1. To try out all features of the player, we recommend you activate VOD. If you don't have an account yet, sign up for one first. If you don't use the VOD service, you can skip this step; however, you will only be able to use basic player features after integration.
2. Download and install Android Studio. If you have already done so, skip this step.

Content Summary

1. How to integrate the Player component for Android
2. How to create and use the player

Directions

Step 1. Download the player code package

GitHub page: LiteAVSDK/Player_Android

You can download the Player for Android by downloading the Player component ZIP package or running the Git clone command.

Step 2. Integrate the component

This step describes how to integrate the player. You can integrate the project by using Gradle for automatic loading, manually downloading the AAR and importing it into your current project, or importing the JAR and SO libraries.

Step 3. Configure application permissions

Configure permissions for your application in AndroidManifest.xml. LiteAVSDK needs the following permissions:

<!--network permission-->
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
<!--VOD player floating window permission -->
<uses-permission android:name="android.permission.SYSTEM_ALERT_WINDOW" />
<!--storage-->
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" />

Step 4. Set obfuscation rules

In the proguard-rules.pro file, add the classes related to the TRTC SDK to the "do not obfuscate" list:

-keep class com.tencent.** { *;}

At this point, you have completed configuring permissions for the RT-Cube Player application for Android.

Step 5. Use the player features

This step describes how to create a player and use it for video playback.

1. Player creation
   The main class of the player is SuperPlayerView, and videos can be played back after it is created. FileId or URL can be integrated for playback. Create SuperPlayerView in the layout file:

   <!-- Player component -->
   <com.tencent.liteav.demo.superplayer.SuperPlayerView
   android:id="@+id/superVodPlayerView"
   android:layout_width="match_parent"
   android:layout_height="200dp" />
   

2. License configuration
   If you have the required license, get the license URL and key in the RT-Cube console.
   If you don't have the required license, contact us to get it.
   
   After obtaining the license information, before calling relevant APIs of the SDK, initialize the license through the following API. We recommend you set the following in the Application class:

   public class MApplication extends Application {
    @Override
   public void onCreate() {
       super.onCreate();
       String licenceURL = ""; // The license URL obtained
       String licenceKey = ""; // The license key obtained
       TXLiveBase.getInstance().setLicence(this, licenceURL, licenceKey);
       TXLiveBase.setListener(new TXLiveBaseListener() {
           @Override
           public void onLicenceLoaded(int result, String reason) {
               Log.i(TAG, "onLicenceLoaded: result:" + result + ", reason:" + reason);
           }
       });
   }
   }
   

3. Video playback
   This step describes how to play back a video. The RT-Cube Player for Android can be used for VOD and live playback as follows:
   • VOD playback: The Player component supports two VOD playback methods, namely, through FileID or URL.
   • Live playback: The Player component can use the playback through URL method for live playback. A live audio/video stream can be pulled for playback simply by passing in its URL. For more information on how to generate a Tencent Cloud live streaming URL, see Splicing Live Streaming URLs.
     • VOD and live playback through URL
     • VOD playback through `FileID`

     A URL can be the playback address of a VOD file or the pull address of a live stream. A video file can be played back simply by passing in its URL.
     

     SuperPlayerModel model = new SuperPlayerModel();
     model.appId = 1400329073; // Configure `AppId`
     model.url = "http://your_video_url.mp4";   // Configure a URL for your video for playback
     mSuperPlayerView.playWithModelNeedLicence(model);
     

     A video file ID is returned by the server after the video is uploaded.

     1. After a video is published from a client, the server will return a file ID to the client.
     2. After a video is uploaded to the server, the notification for successful upload will contain a file ID for the video.

     If the video you want to play is already saved with VOD, you can go to Media Assets to view its file ID.
     

     >!
     >- To play by VOD file ID, you need to use the Adaptive-HLS template (ID: 10) to transcode the video or use the player signature psign to specify the video to play; otherwise, the playback may fail. For more information on how to transcode a video and generate psign, see Play back a video with the Player component and Player Signature.
     >- If a "no v4 play info" exception occurs during playback through FileId, the above problem may exist. In this case, we recommend you make adjustments as instructed above. You can also directly get the playback link of the source video for playback through URL.
     >- We recommend you transcode videos for playback because untranscoded videos may experience compatibility issues during playback.
     

     // If you haven't enabled hotlink protection and a "no v4 play info" error occurs, we recommend you transcode your video using the Adaptive-HLS template (ID: 10) or get the playback URL of the video and play it by URL.
     
     SuperPlayerModel *model = [[SuperPlayerModel alloc] init];
     model.appId = 1400329071;// Configure AppId
     model.videoId = [[SuperPlayerVideoId alloc] init];
     model.videoId.fileId = @"5285890799710173650"; // Configure FileId
     // If you enable hotlink protection, you need to enter a psign (player signature) for playback. For more information on the signature and how to generate it, see Player Signature.
     //model.videoId.pSign = @"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhcHBJZCI6MTQwMDMyOTA3MSwiZmlsZUlkIjoiNTI4NTg5MDc5OTcxMDE3MzY1MCIsImN1cnJlbnRUaW1lU3RhbXAiOjEsImV4cGlyZVRpbWVTdGFtcCI6MjE0NzQ4MzY0NywidXJsQWNjZXNzSW5mbyI6eyJ0IjoiN2ZmZmZmZmYifSwiZHJtTGljZW5zZUluZm8iOnsiZXhwaXJlVGltZVN0YW1wIjoyMTQ3NDgzNjQ3fX0.yJxpnQ2Evp5KZQFfuBBK05BoPpQAzYAWo6liXws-LzU"; 
     [_playerView playWithModelNeedLicence:model];

4. Playback exit
   If the player is no longer needed, call resetPlayer to reset the player and free up memory.

   mSuperPlayerView.resetPlayer();
   

At this point, you have learned how to create a player, use it to play videos, and stop playback.

More Features

This section describes several common player features. For more features, see Demo. For features supported by the Player component, see Feature Description.

1. Full screen playback

The Player component supports full screen playback. In full screen mode, users can lock the screen, control volume and brightness with gestures, send on-screen comments, take screenshots, and switch the video definition. You can try out this feature in TCToolkit App > Player > Player Component, and you can enter the full screen playback mode by clicking the full screen icon in the bottom-right corner.

You can call the API below to enter full screen from the windowed playback mode:

mControllerCallback.onSwitchPlayMode(SuperPlayerDef.PlayerMode.FULLSCREEN);

Features of full screen playback mode

// API triggered after tapping
mControllerCallback.onBackPressed(SuperPlayerDef.PlayerMode.FULLSCREEN);
onSwitchPlayMode(SuperPlayerDef.PlayerMode.WINDOW);

// API triggered after tapping
toggleLockState();

// Step 1. Add an on-screen comment to the on-screen comment view
addDanmaku(String content, boolean withBorder);
// Step 2. Enable or disable on-screen commenting
toggleBarrage();

mSuperPlayer.snapshot(new TXLivePlayer.ITXSnapshotListener() {
 @Override
 public void onSnapshot(Bitmap bitmap) {
       // The captured screenshot can be saved here
 }
});

// The API for displaying the definition selection view triggered after the button is tapped
showQualityView();
// The callback API for tapping the definition option is as follows
mListView.setOnItemClickListener(new AdapterView.OnItemClickListener() {
 @Override
 public void onItemClick(AdapterView<?> parent, View view, int position, long id) {
   // The event of tapping the definition list view
   VideoQuality quality = mList.get(position);
   mCallback.onQualitySelect(quality);
 }
});
// Callback for the selected definition
@Override
public void onQualityChange(VideoQuality quality) {
  mFullScreenPlayer.updateVideoQuality(quality);
  mSuperPlayer.switchStream(quality);
}

2. Floating window playback

The Player component supports playback in a small floating window, which allows users to switch to another application without interrupting the video playback. You can try out this feature in TCToolkit App > Player > Player Component by clicking Back in the top-left corner.

Floating window playback relies on the following permission in AndroidManifest:

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

// The API triggered by switching to the floating window
mSuperPlayerView.switchPlayMode(SuperPlayerDef.PlayerMode.FLOAT);
// The API triggered by tapping the floating window to return to the main window
mControllerCallback.onSwitchPlayMode(SuperPlayerDef.PlayerMode.WINDOW);

3. Thumbnail

The Player component supports customizing a video thumbnail, which is displayed before the callback is received for playing back the first video frame. You can try out this feature in TCToolkit App > Player > Player Component > Thumbnail Customization Demo.

• When the Player component is set to the automatic playback mode PLAY_ACTION_AUTO_PLAY, the video will be played back automatically, and the thumbnail will be displayed before the first video frame is loaded.
• When the Player component is set to the manual playback mode PLAY_ACTION_MANUAL_PLAY, the video will be played back only after the user clicks Play. The thumbnail will be displayed until the first video frame is loaded.

You can set the thumbnail by specifying the URL of a local or online file. For detailed directions, see the code below. If you play by VOD file ID, you can also set the thumbnail in the VOD console.

SuperPlayerModel model = new SuperPlayerModel();
model.appId = "Your `appid`";
model.videoId = new SuperPlayerVideoId();
model.videoId.fileId = "Your `fileId`"; 
// Playback mode, which can be set to automatic (`PLAY_ACTION_AUTO_PLAY`) or manual (`PLAY_ACTION_MANUAL_PLAY`)
model.playAction = PLAY_ACTION_MANUAL_PLAY;
// Specify the URL of an online file to use as the thumbnail. If `coverPictureUrl` is not set, the thumbnail configured in the VOD console will be used.
model.coverPictureUrl = "http://1500005830.vod2.myqcloud.com/6c9a5118vodcq1500005830/cc1e28208602268011087336518/MXUW1a5I9TsA.png" 
mSuperPlayerView.playWithModelNeedLicence(model);

4. Video playlist loop

The Player component supports looping a video playlist:

• After a video ends, the next video in the list can be played automatically or users can manually start the next video.
• After the last video in the list ends, the first video in the list will start automatically.

This feature can be tried out in TCToolkit App > Player > Player Component > Video List Loop Demo.

// Step 1. Create a loop list<SuperPlayerModel>
ArrayList<SuperPlayerModel> list = new ArrayList<>();
SuperPlayerModel model = new VideoModel();
model = new SuperPlayerModel();
model.videoId = new SuperPlayerVideoId();
model.appid = 1252463788;
model.videoId.fileId = "4564972819219071568";
list.add(model);
model = new SuperPlayerModel();
model.videoId = new SuperPlayerVideoId();
model.appid = 1252463788;
model.videoId.fileId = "4564972819219071679";
list.add(model);
// Step 2. Call the loop API
mSuperPlayerView.playWithModelListNeedLicence(list, true, 0);

public void playWithModelListNeedLicence(List<SuperPlayerModel> models, boolean isLoopPlayList, int index);

API parameters:

5. Preview

The Player component supports the video preview feature, which allows non-member viewers to view a preview of the video. You can pass in different parameters to control the video preview duration, prompt message, and preview end screen. You can try out this feature in Tencent Cloud Toolkit App > Player > Player Component > Preview Feature Demo.

Method 1:
// Step 1. Create a video model
SuperPlayerModel mode = new SuperPlayerModel();
//... Add the video source information
// Step 2. Create a preview information model
VipWatchModel vipWatchModel = new VipWatchModel("You can preview %ss and activate the VIP membership to watch the full video",15);
mode.vipWatchMode = vipWatchModel;
// Step 3. Call the method for playing back videos
mSuperPlayerView.playWithModelNeedLicence(mode);
Method 2:
// Step 1. Create a preview information model
VipWatchModel vipWatchModel = new VipWatchModel("You can preview %ss and activate the VIP membership to watch the full video",15);
// Step 2. Call the method for setting the preview feature
mSuperPlayerView.setVipWatchModel(vipWatchModel);

public VipWatchModel(String tipStr, long canWatchTime)

VipWatchModel API parameter description:

6. Dynamic watermark

The Player component allows you to add a randomly moving text watermark to protect your content against piracy. Watermarks are visible in both the full screen mode and windowed mode. The text, font size, and color of a watermark are customizable. You can find a demo for this feature in the TCToolkit app: Player > Player Component > Dynamic Watermark Demo.

Method 1:
// Step 1. Create a video model
SuperPlayerModel mode = new SuperPlayerModel();
//... Add the video source information
// Step 2. Create a watermark information model
DynamicWaterConfig dynamicWaterConfig = new DynamicWaterConfig("shipinyun", 30, Color.parseColor("#80FFFFFF"));
mode.dynamicWaterConfig = dynamicWaterConfig;
// Step 3. Call the method for playing back videos
mSuperPlayerView.playWithModelNeedLicence(mode);
Method 2:
// Step 1. Create a watermark information model
DynamicWaterConfig dynamicWaterConfig = new DynamicWaterConfig("shipinyun", 30, Color.parseColor("#80FFFFFF"));
// Step 2. Call the method for setting the dynamic watermark feature
mSuperPlayerView.setDynamicWatermarkConfig(dynamicWaterConfig);

public DynamicWaterConfig(String dynamicWatermarkTip, int tipTextSize, int tipTextColor)

API parameters:

Demo

To try out more features, you can directly run the project demo or scan the QR code to download the TCToolkit App demo.

Running a demo project

1. Select File > Open on the navigation bar of Android Studio. In the pop-up window, select the $SuperPlayer_Android/Demo directory of the demo project. After the demo project is imported successfully, click Run app to run the demo.
2. After running the demo successfully, go to Player > Player Component to try out the player features.

TCToolkit app

You can try out more features of the Player component in TCToolkit App > Player.