ApsaraVideo VOD:Basic features

Configure a playback source (DataSource)

• The ApsaraVideo Player SDK for Android supports four video-on-demand (VOD) playback methods: VidAuth (recommended for ApsaraVideo VOD users), VidSts, UrlSource, and encrypted playback.

• The ApsaraVideo Player SDK for Android supports two live streaming playback methods: UrlSource and encrypted playback.

Play a video on demand

VidAuth vidAuth = new VidAuth();
   vidAuth.setVid("The video ID");// Required. The ID of the video (VideoId).
   vidAuth.setPlayAuth("<yourPlayAuth>");// Required. The playback credential. To obtain the credential, call the GetVideoPlayAuth operation of ApsaraVideo VOD.
   vidAuth.setRegion("The region ID");// This parameter is deprecated for player SDK V5.5.5.0 and later. You do not need to set this parameter because the player automatically parses the region. For player SDKs earlier than V5.5.5.0, this parameter is required. It specifies the region of the ApsaraVideo VOD service. The default value is cn-shanghai.
   // vidAuth.setAuthTimeout(3600);// The validity period of the playback URL, in seconds. This period overwrites the validity period for URL signing that is configured in the ApsaraVideo VOD console. If you do not specify this parameter, the default value 3600 is used. If you set this parameter, make sure that the value is greater than the actual video duration to prevent the playback URL from expiring before the playback is complete.
        
   // If you enable HLS encryption parameter pass-through in the VOD console and the default parameter name is MtsHlsUriToken, you must set the config and pass it to the vidAuth object, as shown in the following code.
   VidPlayerConfigGen vidConfig = new VidPlayerConfigGen();
   vidConfig.setMtsHlsUriToken("<yourMtsHlsUriToken>");
   vidAuth.setPlayerConfig(vidConfig);
   aliPlayer.setDataSource(vidAuth);

VidSts vidSts = new VidSts();
       vidSts.setVid("video ID"); // Required parameter. The video ID (VideoId).
       vidSts.setAccessKeyId("<yourAccessKeyId>"); // Required parameter. The AccessKey ID of the temporary STS AccessKey pair. You must call the AssumeRole operation of Security Token Service (STS) to generate this value.
       vidSts.setAccessKeySecret("<yourAccessKeySecret>"); // Required parameter. The AccessKey secret of the temporary STS AccessKey pair. You must call the AssumeRole operation of Security Token Service (STS) to generate this value.
       vidSts.setSecurityToken("<yourSecurityToken>"); // Required parameter. The Security Token Service (STS) token. You must call the AssumeRole operation of Security Token Service (STS) to generate this value.
       vidSts.setRegion("region"); // Required parameter. The region where the ApsaraVideo VOD service is accessed. Default value: cn-shanghai.
       // vidSts.setAuthTimeout(3600); // The validity period of the playback URL, in seconds. This value overrides the validity period of URL signing that you configure in the ApsaraVideo VOD console. If you do not specify this parameter, the default value 3600 is used. If you set this parameter, make sure that the value is greater than the actual duration of the video to prevent the playback URL from expiring before playback completes.
        
       // If you enable HLS encryption parameter pass-through in the ApsaraVideo VOD console and the default parameter name is MtsHlsUriToken, you must configure vidConfig and pass it to vidSts. For more information, see the following code.
       // If you do not enable HLS encryption parameter pass-through in the ApsaraVideo VOD console, you do not need to integrate the following code.
       VidPlayerConfigGen vidConfig = new VidPlayerConfigGen();
       vidConfig.setMtsHlsUriToken("<yourMtsHlsUriToken>");
       vidSts.setPlayerConfig(vidConfig);
       aliPlayer.setDataSource(vidSts);

 UrlSource urlSource = new UrlSource();
        urlSource.setUri("Playback URL");// Required. The playback URL. It can be generated by ApsaraVideo VOD or a third-party service, or it can be the URL of a local video.
        aliPlayer.setDataSource(urlSource);

Live streaming

For more information, see Standard live streaming playback.

Manage playback

The ApsaraVideo Player SDK for Android lets you manage media playback. For example, you can start, pause, or stop playback, or start playback from a specific point in time.

Prepare the player

aliPlayer.prepare();

Start playback

aliPlayer.start();

Play a video from a specified point in time

// The position parameter specifies the point in time. Unit: milliseconds.
aliPlayer.seekTo(long position);

// Set the start time (in milliseconds) for the next prepare call. This setting takes effect only for the next prepare call.
// After prepare is called, this value is automatically cleared. If you do not call this method again before the next prepare, playback starts normally.
// The seekMode parameter specifies accurate or inaccurate seeking.
aliPlayer.setStartTime(time, seekMode);

Pause playback

aliPlayer.pause();

Resume playback

aliPlayer.start();

Stop playback

aliPlayer.stop();

Destroy the player

// Synchronously destroys the player. The system automatically calls the stop operation.
aliPlayer.release();
// Asynchronously destroys the player. The system automatically calls the stop operation.
aliPlayer.releaseAsync();	

Monitor player status

The ApsaraVideo Player SDK for Android lets you set listeners and monitor playback status.

Set listeners

aliPlayer.setOnErrorListener(new IPlayer.OnErrorListener() {
    // This callback is triggered if any error occurs while using the player.

    @Override
    public void onError(ErrorInfo errorInfo) {
        ErrorCode errorCode = errorInfo.getCode(); // The error code.
        String errorMsg = errorInfo.getMsg(); // The error message.
        // errorExtra contains additional error information in JSON format. Example:
        //{ "Url": "xxx",
   		//	"Module": "NetWork",
    	//	"ModuleCode": "-377",
   		//  "ModuleMessage": "Redirect to a url that is not a media"}
        String errorExtra= errorInfo.getExtra();         
        // Stop the player if an error occurs.
        aliPlayer.stop();
    }
});
aliPlayer.setOnPreparedListener(new IPlayer.OnPreparedListener() {
    // After you call aliPlayer.prepare(), the player starts reading and parsing data. This callback is triggered after successful parsing.

    @Override
    public void onPrepared() {
        // Preparation completed.
    }
});
aliPlayer.setOnCompletionListener(new IPlayer.OnCompletionListener() {
    // This callback is triggered after playback completes.
    @Override
    public void onCompletion() {
        // Call stop to stop playback.
        aliPlayer.stop();
    }
});
aliPlayer.setOnInfoListener(new IPlayer.OnInfoListener() {
    // This callback provides information such as current playback progress and buffer position.
    @Override
    public void onInfo(InfoBean infoBean) {
        InfoCode code = infoBean.getCode(); // The information code.
        String msg = infoBean.getExtraMsg();// The information content.
        long value = infoBean.getExtraValue(); // The information value.

        // Current progress: InfoCode.CurrentPosition
        // Current buffer position: InfoCode.BufferedPosition
    }
});
aliPlayer.setOnLoadingStatusListener(new IPlayer.OnLoadingStatusListener() {
    // This callback reports the loading status. It is used to display a loading indicator when the network is unstable.

    @Override
    public void onLoadingBegin() {
        // Loading starts. Video and audio cannot be played yet.
        // Display a circular loading indicator.
    }

    @Override
    public void onLoadingProgress(int percent, float netSpeed) {
        // Loading progress. Shows percentage and network speed.
        // netSpeed is a reserved field and is currently 0.
    }

    @Override
    public void onLoadingEnd() {
        // Loading ends. Video and audio can now be played.
        // Hide the circular loading indicator.
    }
});

Monitor playback status

aliPlayer.setOnStateChangedListener(new IPlayer.OnStateChangedListener() {
    @Override
    public void onStateChanged(int newState) {
        /*
          int idle = 0;
          int initalized = 1;
          int prepared = 2;
          int started = 3;
          int paused = 4;
          int stopped = 5;
          int completion = 6;
          int error = 7;
      */
    }
});

Set the video display mode

The ApsaraVideo Player SDK for Android lets you configure display settings for playback. For example, you can specify how video images are scaled, rotated, or mirrored.

Padding

// Scale in the video to fit the view. The aspect ratio of the video is maintained.
aliPlayer.setScaleMode(ScaleMode.SCALE_ASPECT_FIT);
// Scale out the video to fill the view. The aspect ratio of the video is maintained.
aliPlayer.setScaleMode(ScaleMode.SCALE_ASPECT_FILL);
// Stretch the video to fill the view. The aspect ratio of the video is not maintained. If the aspect ratios of the video and the view are different, image distortion may occur.
aliPlayer.setScaleMode(ScaleMode.SCALE_TO_FILL);

Rotating

// Set the rotation angle to 0° in the clockwise direction.
aliPlayer.setRotateMode(RotateMode.ROTATE_0);
// Set the rotation angle to 90° in the clockwise direction.
aliPlayer.setRotateMode(RotateMode.ROTATE_90);
// Set the rotation angle to 180° in the clockwise direction.
aliPlayer.setRotateMode(RotateMode.ROTATE_180);
// Set the rotation angle to 270° in the clockwise direction.
aliPlayer.setRotateMode(RotateMode.ROTATE_270);
// Query the rotation angle.
aliPlayer.getRotateMode();

Mirroring

// Specify no mirroring for the video images.
aliPlayer.setMirrorMode(MirrorMode.MIRROR_MODE_NONE);
// Specify horizontal mirroring for the video images.
aliPlayer.setMirrorMode(MirrorMode.MIRROR_MODE_HORIZONTAL);
// Specify vertical mirroring for the video images.
aliPlayer.setMirrorMode(MirrorMode.MIRROR_MODE_VERTICAL);

Obtain playback information

The ApsaraVideo Player SDK for Android lets you obtain playback information, such as the current playback progress, playback duration, and buffering progress.

Obtain the playback progress

aliPlayer.setOnInfoListener(new IPlayer.OnInfoListener() {
    @Override
    public void onInfo(InfoBean infoBean) {
        if(infoBean.getCode() == InfoCode.CurrentPosition){
            // extraValue indicates the current playback position. Unit: milliseconds.
            long extraValue = infoBean.getExtraValue();
        }
    }
});

Obtain the playback duration

long duration = aliPlayer.getDuration();

Obtain the actual playback duration

long duration = aliPlayer.getPlayedDuration();

Retrieve Buffering Progress

aliPlayer.setOnInfoListener(new IPlayer.OnInfoListener() {
    @Override
    public void onInfo(InfoBean infoBean) {
        if(infoBean.getCode() == InfoCode.BufferedPosition){
            // extraValue indicates the buffering progress. Unit: milliseconds.
            long extraValue = infoBean.getExtraValue();
        }
    }
});

Obtain the rendering frame rate, audio and video bitrate, and network downlink bitrate in real time

// Obtain the current frame rate for video rendering. The returned data is of the FLOAT data type.
aliPlayer.getOption(IPlayer.Option.RenderFPS);
// Obtain the current video bitrate. The returned data is of the FLOAT data type. Unit: bit/s.
aliPlayer.getOption(IPlayer.Option.VideoBitrate);
// Obtain the current audio bitrate. The returned data is of the FLOAT data type. Unit: bit/s.
aliPlayer.getOption(IPlayer.Option.AudioBitrate);
// Obtain the current network downlink bitrate. The returned data is of the FLOAT data type. Unit: bit/s.
aliPlayer.getOption(IPlayer.Option.DownloadBitrate);

Callback for audio and video out of sync

aliPlayer.setOnAVNotSyncStatusListener(new IPlayer.OnAVNotSyncStatusListener() {
    @Override
    public void onAVNotSyncStart(int type) {
        if (type == 0) {
            // Reduce playback speed.
            if (aliPlayer.getSpeed() > 1) {
                aliPlayer.setSpeed(1);
            }
        }
        Toast.makeText(getContext(), "Out-of-sync starts" , Toast.LENGTH_SHORT).show();
    }

    @Override
    public void onAVNotSyncEnd() {
        Toast.makeText(getContext(), "Out-of-sync ends" , Toast.LENGTH_SHORT).show();
    }
});

Specify the volume

You can set the mute mode and the volume.

Change the volume

// Set the volume to a real number from 0 to 2.
aliPlayer.setVolume(1f);
// Obtain the volume.
aliPlayer.getVolume();

Mute settings

aliPlayer.setMute(true);

Configure the playback speed

// Playback speeds ranging from 0.5x to 5x are supported. Common playback speeds are multiples of 0.5x, such as 0.5x, 1x, and 1.5x.
aliPlayer.setSpeed(1.0f);

Multiple Resolution Settings

UrlSource-based live streaming

For more information, see Standard live streaming playback.

VidAuth or VidSts-based playback

If you use VidAuth or VidSts to play on-demand videos, no additional settings are required. The ApsaraVideo Player SDK for Android automatically retrieves video definitions from ApsaraVideo VOD.

Query the definition

After the video is loaded, you can retrieve the definitions of the video.

// Obtain information about all streams of the video.
List<TrackInfo> trackInfos = aliPlayer.getMediaInfo().getTrackInfos();
// Traverse all streams to obtain the video definitions.
for (TrackInfo trackInfo : trackInfos) {
     if(trackInfo.getType() == TrackInfo.Type.TYPE_VOD){
             // Obtain the video definition.
        String vodDefinition = trackInfo.getVodDefinition();
     }
}

Switch Quality

You can call selectTrack to switch definitions by specifying the corresponding index. You can obtain this index from the TrackInfo parameter.

aliPlayer.selectTrack(index);

Resolution Switching Notifications

Set the callbacks for successful and failed definition switching.

aliPlayer.setOnTrackChangedListener(new IPlayer.OnTrackChangedListener() {
    @Override
    public void onChangedSuccess(TrackInfo trackInfo) { }

    @Override
    public void onChangedFail(TrackInfo trackInfo, ErrorInfo errorInfo) { }
});

Quick switching

After you enable fast switching mode, manual calls to selectTrack always receive a quick (response).

PlayerConfig config = aliPlayer.getConfig();
config.mSelectTrackBufferMode = 1;
aliPlayer.setConfig(config)

Enable loop playback

aliPlayer.setLoop(true);

aliPlayer.setOnInfoListener(new IPlayer.OnInfoListener() {
    @Override
    public void onInfo(InfoBean infoBean) {
        if (infoBean.getCode() == InfoCode.LoopingStart){
            // Listen to the start of loop playback.
        }
    }
});

Switch audio tracks

The ApsaraVideo Player SDK for Android supports audio track switching. This lets you switch audio tracks in different languages during video playback.

Usage examples

1. Configure callbacks.

   aliPlayer.setOnSubTrackReadyListener(new IPlayer.OnSubTrackReadyListener() {
       @Override
       // Configure the onSubTrackReady callback. In most cases, the onSubTrackReady callback is fired before the prepare callback.
       public void onSubTrackReady(MediaInfo mediaInfo) {
           if (mPlayerTrackFragment != null) {
               //mPlayerTrackFragment.showMediaInfo();
               // Call the getSubMediaInfo operation and obtain MediaInfo from the response. You must call the getSubMediaInfo operation after the onSubTrackReady callback is fired. Otherwise, an empty string is returned.
               MediaInfo subMediaInfo = aliPlayer.getSubMediaInfo();
               TrackInfos = subMediaInfo.getTrackInfos();
               // Find the track to which you want to switch.
               myTrack = myfunc(TrackInfos)
           }
       }
   });

2. Switch to the desired track.

   index = myTrack.getIndex();
   aliPlayer.selectTrack(index);

Thumbnail usage

Before you use thumbnails in the ApsaraVideo Player SDK, ensure that thumbnails are configured for your video. Specifically, generate sprite snapshots for your video. In the ApsaraVideo VOD console, create a snapshot template and select Image Sprite as the Snapshot Type. Then, create a workflow to process the video using this template. For more information, see Video snapshots. The following sample code shows how to use thumbnails in the ApsaraVideo Player SDK:

mAliPlayer.setOnPreparedListener(new IPlayer.OnPreparedListener() {
    @Override
    public void onPrepared() {
        // 1. Create the ThumbnailHelper class.
        ThumbnailHelper mThumbnailHelper = new ThumbnailHelper(URL);
        // 2. Configure a listener.
        mThumbnailHelper.setOnPrepareListener(new ThumbnailHelper.OnPrepareListener() {
            @Override
            public void onPrepareSuccess() {
                // 4. After the thumbnail is loaded, you can request to obtain the thumbnail at a specified playback position.
            }
            @Override
            public void onPrepareFail() {}
        });

        mThumbnailHelper.setOnThumbnailGetListener(new ThumbnailHelper.OnThumbnailGetListener() {
            @Override
            public void onThumbnailGetSuccess(long positionMs, ThumbnailBitmapInfo thumbnailBitmapInfo) {
                // 5. Obtain the thumbnail bitmap at a specified playback position.
                Bitmap thumbnailBitmap = thumbnailBitmapInfo.getThumbnailBitmap();
            }
            @Override
            public void onThumbnailGetFail(long positionMs, String errorMsg) {}
        });

        // 3. Load the thumbnail.
        mThumbnailHelper.prepare();
    }
});

Obtain SDK logs

SDK logs are generated when you use the ApsaraVideo Player SDK. The logs contain detailed information such as request status, invocation results, and permission application results. You can debug code and troubleshoot problems by viewing the SDK logs to facilitate development. You can use one of the following methods to obtain SDK logs.

Method 1: obtain player SDK logs through the console of the development tool

This method captures logs on your local device. It is suitable for scenarios where you can reliably reproduce the error on your device.

1. Enable the logging feature and set the log level.

   // Logs are stored under com.cicada.player.utils.
   // Enable the logging feature.
   Logger.getInstance(context).enableConsoleLog(true);
   // Set the log level. Default value: AF_LOG_LEVEL_INFO. To troubleshoot problems, set this parameter to AF_LOG_LEVEL_TRACE.
   Logger.getInstance(context).setLogLevel(Logger.LogLevel.AF_LOG_LEVEL_INFO);

2. Configure frame-level logs.

   // Configure frame-level log printing.
   // Valid values of the value parameter: 0 and 1. A value of 0 indicates disabled. A value of 1 indicates enabled.
   Logger.getInstance(this).setLogOption(Logger.LogOption.FRAME_LEVEL_LOGGING_ENABLED,value);

   Note

   This feature is used in troubleshooting scenarios.

3. Collect logs.

   Reproduce the error and retrieve the error log in the console of your development tool such as Logcat.

Method 2: Set LogCallback to receive ApsaraVideo Player SDK logs

This method uses the LogCallback method. It is suitable for scenarios where the error occurs on the client side but you cannot reliably reproduce the error and capture logs on your device. You can call LogCallback to listen to the log export of the ApsaraVideo Player SDK and automatically export error logs to the log channel of your application.

1. Enable the logging feature and set the log level.

   // Logs are stored under com.cicada.player.utils.
   // Set the log level. Default value: AF_LOG_LEVEL_INFO. To troubleshoot problems, set this parameter to AF_LOG_LEVEL_TRACE.
   Logger.getInstance(context).setLogLevel(Logger.LogLevel.AF_LOG_LEVEL_INFO);
   Logger.getInstance(mContext).setLogCallback(newLogger.OnLogCallback(){
           @Override
           public void onLog(Logger.LogLevel logLevel,Strings){
               // The logs.
           }
   });

2. Collect logs.

   After an error occurs, the system automatically exports the error log to the log channel of your application.

References

• For more information, see API references.

• For more information about advanced features, see Advanced features.

• For more information about common playback errors and corresponding solutions, see Troubleshoot playback errors, Android player FAQ, and Mobile error codes.