ApsaraVideo VOD:Basic features

Set the data 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.

VOD playback

VidAuth vidAuth = new VidAuth();
   vidAuth.setVid("The video ID.");// Required. The video ID.
   vidAuth.setPlayAuth("<yourPlayAuth>");// Required. The playback credential. You must call the GetVideoPlayAuth operation of ApsaraVideo VOD to generate the credential.
   vidAuth.setRegion("The region where ApsaraVideo VOD is activated.");// This parameter is deprecated for ApsaraVideo Player SDK V5.5.5.0 and later. You do not need to set the region because the player automatically parses it. For versions earlier than V5.5.5.0, this parameter is required. The region where ApsaraVideo VOD is activated. Default value: cn-shanghai.
   // vidAuth.setAuthTimeout(3600);// The validity period of the playback URL in seconds. This value overwrites the validity period of URL signing that is set in the ApsaraVideo VOD console. If you do not set this parameter, the default value of 3600 is used. If you set this parameter, make sure that the validity period is longer than the actual video duration to prevent the playback URL from expiring before the playback is complete.
        
   //If you enable pass-through of HLS encryption parameters in the ApsaraVideo VOD console and the default parameter name is MtsHlsUriToken, you must set the config and pass it to the vid. For more information, see the following code.
   VidPlayerConfigGen vidConfig = new VidPlayerConfigGen();
   vidConfig.setMtsHlsUriToken("<yourMtsHlsUriToken>");
   vidAuth.setPlayerConfig(config);
   aliPlayer.setDataSource(vidAuth);

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

 UrlSource urlSource = new UrlSource();
        urlSource.setUri("The playback URL.");// Required. The playback URL. The URL can be a third-party VOD URL, a playback URL in ApsaraVideo VOD, or a local video address.
        aliPlayer.setDataSource(urlSource);

Live streaming playback

For more information, see Standard live streaming playback.

Control playback

The ApsaraVideo Player SDK for Android supports operations such as starting playback from a specified time, starting playback, pausing playback, and stopping playback.

Prepare for playback

aliPlayer.prepare();

Start playback

aliPlayer.start();

Start playback from a specified time

// position is the specified time in milliseconds.
aliPlayer.seekTo(long position);

// Set the start time in milliseconds for the next prepare call of the player. This setting is valid only for the immediately following prepare call.
// After you call prepare, this value is automatically reset to zero. If you do not call this method again before the next prepare call, playback starts in the normal way.
// You can set seekMode to accurate or inaccurate mode.
aliPlayer.setStartTime(time, seekMode);

Pause playback

aliPlayer.pause();

Resume playback

aliPlayer.start();

Stop playback

aliPlayer.stop();

Destroy the player

//Synchronous destruction. The stop method is automatically called.
aliPlayer.release();
//Asynchronous destruction. The stop method is automatically called.
aliPlayer.releaseAsync();	

Listen for player states

The ApsaraVideo Player SDK for Android lets you set player listeners and listen for player states.

Set player listeners

aliPlayer.setOnErrorListener(new IPlayer.OnErrorListener() {
    //This callback is invoked if any error occurs when you use the player.

    @Override
    public void onError(ErrorInfo errorInfo) {
        ErrorCode errorCode = errorInfo.getCode(); //The error code.
        String errorMsg = errorInfo.getMsg(); //The error description.
        //errorExtra indicates the extra error information in the JSON string format. Example: Note that ModuleCode is not completely equivalent to errorCode.
        //{ "Url": "xxx",
   		//	"Module": "NetWork",
    	//	"ModuleCode": "-377",
   		//  "ModuleMessage": "Redirect to a url that is not a media"}
        String errorExtra= errorInfo.getExtra();         
        //After an error occurs, you must stop the player.
        aliPlayer.stop();
    }
});
aliPlayer.setOnPreparedListener(new IPlayer.OnPreparedListener() {
    // After you call the aliPlayer.prepare() method, the player starts to read and parse data. If the operation is successful, this callback is invoked.

    @Override
    public void onPrepared() {
        // Preparation is complete.
    }
});
aliPlayer.setOnCompletionListener(new IPlayer.OnCompletionListener() {
    //After the playback is complete, this callback is invoked.
    @Override
    public void onCompletion() {
        //You can call stop to stop video playback.
        aliPlayer.stop();
    }
});
aliPlayer.setOnInfoListener(new IPlayer.OnInfoListener() {
    //Information about the player, including the current progress and buffered 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 buffered position: InfoCode.BufferedPosition
    }
});
aliPlayer.setOnLoadingStatusListener(new IPlayer.OnLoadingStatusListener() {
    //The loading status of the player. When the network is poor, this is used to display the loading screen.

    @Override
    public void onLoadingBegin() {
        //Loading starts. The video and audio are not ready for playback.
        //You can display a loading circle here.
    }

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

    @Override
    public void onLoadingEnd() {
        //Loading is complete. The video and audio are ready for playback.
        //You can hide the loading circle here.
    }
});

Listen for 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 display mode

The ApsaraVideo Player SDK for Android supports display settings such as fill, rotate, and mirror.

Fill

// Set the mode to aspect ratio fit. The video is scaled down to fit within the view without deforming the image.
aliPlayer.setScaleMode(ScaleMode.SCALE_ASPECT_FIT);
// Set the mode to aspect ratio fill. The video is scaled up to fill the view without deforming the image.
aliPlayer.setScaleMode(ScaleMode.SCALE_ASPECT_FILL);
// Set the mode to stretch to fill. If the aspect ratio of the video does not match the aspect ratio of the view, the image is deformed.
aliPlayer.setScaleMode(ScaleMode.SCALE_TO_FILL);

Rotate

// Rotate the image 0 degrees clockwise.
aliPlayer.setRotateMode(RotateMode.ROTATE_0);
// Rotate the image 90 degrees clockwise.
aliPlayer.setRotateMode(RotateMode.ROTATE_90);
// Rotate the image 180 degrees clockwise.
aliPlayer.setRotateMode(RotateMode.ROTATE_180);
// Rotate the image 270 degrees clockwise.
aliPlayer.setRotateMode(RotateMode.ROTATE_270);
// Obtain the rotation angle.
aliPlayer.getRotateMode();

Mirror

// Set the mode to no mirror.
aliPlayer.setMirrorMode(MirrorMode.MIRROR_MODE_NONE);
// Set the mode to horizontal mirror.
aliPlayer.setMirrorMode(MirrorMode.MIRROR_MODE_HORIZONTAL);
// Set the mode to vertical mirror.
aliPlayer.setMirrorMode(MirrorMode.MIRROR_MODE_VERTICAL);

Obtain playback information

The ApsaraVideo Player SDK for Android provides access to information such as the current playback progress, playback duration, and buffering progress.

Obtain the current playback progress

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

Obtain the playback duration

long duration = aliPlayer.getDuration();

Obtain the actual playback duration

long duration = aliPlayer.getPlayedDuration();

Obtain the buffering progress

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

Obtain the real-time rendering frame rate, audio and video bitrates, and network download bitrate

// Obtain the current rendering frame rate. 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 desynchronization

aliPlayer.setOnAVNotSyncStatusListener(new IPlayer.OnAVNotSyncStatusListener() {
    @Override
    public void onAVNotSyncStart(int type) {
        if (type == 0) {
            // Set a lower 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();
    }
});

Set the volume

Setting the volume includes adjusting the volume and muting the playback.

Adjust the volume

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

Mute the playback

aliPlayer.setMute(true);

Set the playback speed

// Set the playback speed. The supported speed range is 0.5 to 5.0. We recommend that you set the speed in multiples of 0.5, for example, 0.5, 1.0, and 1.5.
aliPlayer.setSpeed(1.0f);

Set multiple resolutions

Live streaming with UrlSource

For more information, see Standard live streaming playback.

VOD playback with Vid (VidAuth or VidSts)

If you use Vid-based playback (VidAuth or VidSts), no extra settings are required. The ApsaraVideo Player SDK for Android obtains the resolution list from ApsaraVideo VOD.

Obtain the resolution

After the video is loaded, you can obtain the video resolution.

//Obtain all stream information of the media asset.
List<TrackInfo> trackInfos = aliPlayer.getMediaInfo().getTrackInfos();
//Traverse the streams and obtain the resolution.
for (TrackInfo trackInfo : trackInfos) {
     if(trackInfo.getType() == TrackInfo.Type.TYPE_VOD){
             //Obtain the video resolution.
        String vodDefinition = trackInfo.getVodDefinition();
     }
}

Switch the resolution

You can call the selectTrack method to switch the resolution. Pass the index of the corresponding TrackInfo as a parameter.

aliPlayer.selectTrack(index);

Notifications for resolution switching

The SDK provides callbacks for successful and failed resolution switching.

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

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

Fast switching mode

After you enable fast switching mode, manual calls to selectTrack receive a fast 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 for the event when loop playback starts.
        }
    }
});

Switch audio tracks

The ApsaraVideo Player SDK for Android provides a feature to switch audio tracks. This applies to scenarios where users can switch between different languages when watching a video with multi-language audio.

Examples

1. Set a callback.

   aliPlayer.setOnSubTrackReadyListener(new IPlayer.OnSubTrackReadyListener() {
       @Override
       //The onSubTrackReady callback is usually triggered before the prepare callback.
       public void onSubTrackReady(MediaInfo mediaInfo) {
           if (mPlayerTrackFragment != null) {
               //mPlayerTrackFragment.showMediaInfo();
               //You can call getSubMediaInfo to obtain the MediaInfo information. You can call this method only after you receive the onSubTrackReady callback. Otherwise, null is returned.
               MediaInfo subMediaInfo = aliPlayer.getSubMediaInfo();
               TrackInfos = subMediaInfo.getTrackInfos();
               //Determine the track to select.
               myTrack = myfunc(TrackInfos)
           }
       }
   });

2. Switch the audio track.

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

Use thumbnails

Before you use thumbnails in the ApsaraVideo Player SDK, make sure that you have configured thumbnails for the video. This requires that a sprite has been generated for the video. In the ApsaraVideo VOD console, create a sprite screenshot template. Then, use a workflow to process the video with the sprite screenshot template to generate sprite data. For more information, see Video screenshots. The following example shows how to use thumbnails in the ApsaraVideo Player SDK:

mAliPlayer.setOnPreparedListener(new IPlayer.OnPreparedListener() {
    @Override
    public void onPrepared() {
        //1. Obtain the thumbnail URL.
        List<Thumbnail> thumbnailList = mAliPlayer.getMediaInfo().getThumbnailList();
        //2. Create a thumbnail helper class.
        ThumbnailHelper mThumbnailHelper = new ThumbnailHelper(thumbnailList.get(0).mURL);
        //3. Set a listener.
        mThumbnailHelper.setOnPrepareListener(new ThumbnailHelper.OnPrepareListener() {
            @Override
            public void onPrepareSuccess() {
                //5. After the thumbnail is loaded, you can request the thumbnail at a specified position.
            }
            @Override
            public void onPrepareFail() {}
        });

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

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

Note: If you use URL-based playback, AliPlayer may not be able to obtain the ThumbnailList. Specify the thumbnail URL directly.

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

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

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

Obtain SDK logs

During the runtime of the ApsaraVideo Player SDK, detailed log information is generated. This includes the status of network requests, the results of system calls, and permission requests. This helps developers debug code or troubleshoot issues and improves development efficiency.

Method 1: Obtain SDK logs from the console of your development tool

This method applies to scenarios where you can reproduce an issue locally and capture logs.

1. Enable logging and set the log level.

   // Logger is in com.cicada.player.utils.
   // Enable logging.
   Logger.getInstance(context).enableConsoleLog(true);
   // Set the log level. Default value: AF_LOG_LEVEL_INFO. To troubleshoot issues, you can set the level to AF_LOG_LEVEL_TRACE.
   Logger.getInstance(context).setLogLevel(Logger.LogLevel.AF_LOG_LEVEL_INFO);

2. Set frame-level logging.

   //Set frame-level log printing.
   //A value of 0 for the option indicates that the feature is disabled. A value of 1 indicates that the feature is enabled.
   Logger.getInstance(this).setLogOption(Logger.LogOption.FRAME_LEVEL_LOGGING_ENABLED,value);

   Note

   The frame-level logging feature is mainly used for troubleshooting.

3. Collect logs.

   After you reproduce the issue, you can obtain logs from the console of your development tool, such as Logcat.

Method 2: Use LogCallback to listen for the output logs of the SDK

This method applies to scenarios where an issue occurs on the user side and you cannot reproduce it locally to capture logs. You can use LogCallback to listen for the output logs of the SDK and automatically output them to your app's log channel.

1. Enable logging and set the log level.

   // Logger is in com.cicada.player.utils.
   // Set the log level. Default value: AF_LOG_LEVEL_INFO. To troubleshoot issues, you can set the level 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){
               // Log
           }
   });

2. Collect logs.

   After you reproduce the issue, the logs are automatically output to your app's log file through your app's log channel.

References

• For detailed API descriptions, see API reference.

• For more information about how to use advanced features, see Advanced features.

• For common issues and solutions for playback exceptions, see Troubleshoot playback exceptions, FAQ about ApsaraVideo Player for Android, and Error codes for mobile.