ApsaraVideo VOD:Advanced features

To enable list playback for short videos, we recommend that you create multiple AliPlayer instances. The following items describe the limits on AliListPlayer. For more information, see Short video list player.

• AliListPlayer does not support playing M3U8 files in versions of ApsaraVideo Player SDK for Android earlier than V5.4.5.0. In ApsaraVideo Player SDK for Android V5.4.5.0 or later, you need to enable the local caching feature to play M3U8 files.

1. Create a player.

   Create an AliListPlayer instance by using the AliPlayerFactory class. Sample code:

   AliListPlayer aliyunListPlayer;
   .....
   aliyunListPlayer = AliPlayerFactory.createAliListPlayer(getApplicationContext());
   aliyunListPlayer.setTraceId("traceId"); // The trace ID is the unique identifier of the device or the user. In most cases, the value is the International Mobile Equipment Identity (IMEI) or the Identifier for Advertisers (IDFA) of the device.

2. Optional. Configure listeners.

   Listeners are optional when you create a short video list player. However, if you do not configure listeners, you cannot receive notifications of events related to the player, such as the failure and progress of the playback. We recommend that you configure the following listeners: OnPreparedListener, OnErrorListener, OnCompletionListener, OnLoadingStatusListener, and OnInfoListener.

   Show code

   aliyunListPlayer.setOnCompletionListener(new IPlayer.OnCompletionListener() {
       @Override
       public void onCompletion() {
           // Listen for the end of playback.
       }
   });
   aliyunListPlayer.setOnErrorListener(new IPlayer.OnErrorListener() {
       @Override
       public void onError(ErrorInfo errorInfo) {
           // Listen for the occurrence of errors.
       }
   });
   aliyunListPlayer.setOnPreparedListener(new IPlayer.OnPreparedListener() {
       @Override
       public void onPrepared() {
           // Listen for successful preparation.
       }
   });
   aliyunListPlayer.setOnVideoSizeChangedListener(new IPlayer.OnVideoSizeChangedListener() {
       @Override
       public void onVideoSizeChanged(int width, int height) {
           // Listen for the change of video resolution.
       }
   });
   aliyunListPlayer.setOnRenderingStartListener(new IPlayer.OnRenderingStartListener() {
       @Override
       public void onRenderingStart() {
           // Listen for the display of the first frame.
       }
   });
   aliyunListPlayer.setOnInfoListener(new IPlayer.OnInfoListener() {
       @Override
       public void onInfo(int type, long extra) {
           // Listen for other events. The type parameter contains multiple values that indicate various events, such as the start of loop playback, buffer position, current playback position, and the start of autoplay.
       }
   });
   aliyunListPlayer.setOnLoadingStatusListener(new IPlayer.OnLoadingStatusListener() {
       @Override
       public void onLoadingBegin() {
           // Listen for the start of buffering. 
       }
       @Override
       public void onLoadingProgress(int percent, float kbps) {
           // Listen for the buffering progress.
       }
       @Override
       public void onLoadingEnd() {
           // Listen for the end of buffering.
       }
   });
   aliyunListPlayer.setOnSeekCompleteListener(new IPlayer.OnSeekCompleteListener() {
       @Override
       public void onSeekComplete() {
           // Listen for the end of seeking.
       }
   });
   aliyunListPlayer.setOnSubtitleDisplayListener(new IPlayer.OnSubtitleDisplayListener() {
       @Override
       public void onSubtitleShow(long id, String data) {
           // Listen for the display of subtitles.
       }
       @Override
       public void onSubtitleHide(long id) {
           // Listen for the hiding of subtitles.
       }
   });
   aliyunListPlayer.setOnTrackChangedListener(new IPlayer.OnTrackChangedListener() {
       @Override
       public void onChangedSuccess(TrackInfo trackInfo) {
           // Listen for the successful switching between audio and video streams or between resolutions.
       }
       @Override
       public void onChangedFail(TrackInfo trackInfo, ErrorInfo errorInfo) {
           // Listen for the failed switching between audio and video streams or between resolutions.
       }
   });
   aliyunListPlayer.setOnStateChangedListener(new IPlayer.OnStateChangedListener() {
       @Override
       public void onStateChanged(int newState) {
           // Listen for the change of player status.
       }
   });
   aliyunListPlayer.setOnSnapShotListener(new IPlayer.OnSnapShotListener() {
       @Override
       public void onSnapShot(Bitmap bm, int with, int height) {
           // Listen for the capture of snapshots.
       }
   });

3. Specify the number of videos that you want to preload.

   You can specify the number of videos that you want to preload based on your business requirements. This helps reduce the startup time. Sample code:

   // Specify the number of videos that you want to preload. The total number of loaded videos equals one plus twice the specified number. 
   aliyunListPlayer.setPreloadCount(int count);

4. Add or remove multiple playback sources.

   List playback supports video playback based on Vid and UrlSource. You can use VidSts or VidPlayAuth to play videos based on Vid. Url is the playback URL of the video. Sample code:

   • Url: The playback URL can be the URL of an audio file or video file in ApsaraVideo VOD or on a third-party video-on-demand (VOD) platform. You can call the GetPlayInfo operation to obtain the playback URL of an audio file or video file in ApsaraVideo VOD. We recommend that you use ApsaraVideo VOD SDK to call this operation. This frees you from complex signature calculation. For more information about the GetPlayInfo operation, visit OpenAPI Explorer.

   • Vid: The audio or video ID. To obtain the ID, log on to the ApsaraVideo VOD console and choose Media Files > Audio/Video in the left-side navigation pane. Alternatively, you can call the SearchMedia operation.

   // Add a Vid playback source.
   aliyunListPlayer.addVid(String videoId, String uid);
   // Add a UrlSource playback source.
   aliyunListPlayer.addUrl(String url, String uid);
   // Remove a playback source.
   aliyunListPlayer.removeSource(String uid);

   Note

   The uid parameter indicates the unique ID of a video. You can use the unique ID to identify videos. Videos with the same unique ID are considered the same. If the player plays a video that you did not specify, check whether you have specified the same ID for multiple videos. You can set the unique ID to any string that you prefer.

5. Configure the view.

   You can call the SurfaceView or TextureView method to configure the view.

   • The following sample code describes how to use SurfaceView to configure the view:

     Show code

     SurfaceView surfaceView = findViewById(R.id.surface_view);
     surfaceView.getHolder().addCallback(new SurfaceHolder.Callback() {
         @Override
         public void surfaceCreated(SurfaceHolder holder) {
             aliyunListPlayer.setSurface(holder.getSurface());
         }
     
         @Override
         public void surfaceChanged(SurfaceHolder holder, int format, int width, int height) {
             aliyunListPlayer.surfaceChanged();
         }
     
         @Override
         public void surfaceDestroyed(SurfaceHolder holder) {
             aliyunListPlayer.setSurface(null);
         }
     });

   • The following sample code describes how to use TextureView to configure the view:

     Show code

     TextureView textureView = findViewById(R.id.texture_view);
     textureView.setSurfaceTextureListener(new TextureView.SurfaceTextureListener() {
         @Override
         public void onSurfaceTextureAvailable(SurfaceTexture surface, int width, int height) {
             aliyunListPlayer.setSurface(new Surface(surface));
         }
     
         @Override
         public void onSurfaceTextureSizeChanged(SurfaceTexture surface, int width, int height) {
             aliyunListPlayer.surfaceChanged();
         }
     
         @Override
         public boolean onSurfaceTextureDestroyed(SurfaceTexture surface) {
             aliyunListPlayer.setSurface(null);
             return false;
         }
     
         @Override
         public void onSurfaceTextureUpdated(SurfaceTexture surface) {
     
         }
     });

6. Play the video source.

   After you add one or more playback sources and enable autoplay, call moveTo to play the content from the specified playback source. Sample code:

   Show code

   // Enable autoplay.
   aliyunListPlayer.setAutoPlay(true);
   
   // Call the following method for URL-based playback.
   aliyunVodPlayer.moveTo(String uid);
   // Call the following method for Vid-based playback. You must obtain the Security Token Service (STS) token and AccessKey pair before you call this method. For more information, see Create a RAM role and grant temporary access permissions to the role by using STS. 
   aliyunVodPlayer.moveTo(String uid, StsInfo info);
   // Call the following method for Vid-based playback. You must obtain a playback credential for the video before you call this method and specify the PlayAuthInfo parameter when you call this method. 
   aliyunVodPlayer.moveTo(String uid, PlayAuthInfo info);

7. Play the previous or next video in the list.

   • After you call moveTo to play a video, you can call moveToPrev to play the previous video or call moveToNext to play the next video. Sample code:

     Note

     When you call moveto or moveToNext to switch the video source in the same view, the image flickers and black screen occurs. In this case, we recommend that you set mClearFrameWhenStop in PlayerConfig to false and call setConfig to apply the configuration when you call listPlayer to initialize the player.

     Show code

     // Enable autoplay.
     aliyunListPlayer.setAutoPlay(true);
     
     // Play the next video.   You can call this method only for URL-based playback. The method is invalid for Vid-based playback. 
     aliyunVodPlayer.moveToNext();
     // Play the previous video. You can call this method only for URL-based playback. The method is invalid for Vid-based playback. 
     aliyunVodPlayer.moveToPrev();
     // Play the next video. You can call this method only for Vid-based playback. 
     aliyunVodPlayer.moveToNext(StsInfo info);
     // Play the previous video. You can call this method only for Vid-based playback. 
     aliyunVodPlayer.moveToPrev(StsInfo info);
     // Play the next video. You can call this method only when you use playback credentials for Vid-based playback. 
     aliyunVodPlayer.moveToNext(PlayAuthInfo info);
     // Play the previous video. You can call this method only when you use playback credentials for Vid-based playback. 
     aliyunVodPlayer.moveToPrev(PlayAuthInfo info);

   • Before you call the MoveTo or MoveToNext method, obtain the playback credential. You can apply for playback credentials by using video IDs.

     Note

     To play a video based on VidPlayAuth, you must apply for a playback credential by using the video ID.

     Show code

     requestAuth(source.getVideoId(), new OnRequestAuthResultListener() {
         @Override
         public void onResult(VidAuth vidAuth) {
             mVideoListPlayer.moveToNext(createVidAuth(vidAuth));
         }
     });
     
     private PlayAuthInfo createVidAuth(VidAuth vidAuth) {
         if (vidAuth == null) {
             return new PlayAuthInfo();
         }
         PlayAuthInfo playAuthInfo = new PlayAuthInfo();
         playAuthInfo.setPlayAuth(vidAuth.getPlayAuth());
         return playAuthInfo;
     }

8. Optional. Enable the pre-rendering feature to ensure smooth video switching.

   Note

   This feature is supported only in ApsaraVideo Player SDK for Android V5.5.2.0 or later. You must enable local caching to use this feature. For more information, see Configure local caching.

   The getPreRenderPlayer and moveToNextWithPrerendered operations are provided in ApsaraVideo Player SDK for Android V5.5.2.0 or later. This allows you to improve the smoothness of video switching. The following section describes how to use the operations when you integrate different versions of ApsaraVideo Player SDK for Android:

   ApsaraVideo Player SDK for Android V5.5.2.0 or later integrated

   Use the getPreRenderPlayer operation. Sample code:

   Show code

   // You can use the getPreRenderPlayer operation only when you use the moveToNext operation. The local caching feature must be enabled. 
   IPlayer preRenderPlayer = listPlayer.getPreRenderPlayer();
   if (preRenderPlayer != null) {
       // Call the setSurface operation.
       preRenderPlayer.setSurface(surface);
     preRenderPlayer.start();
     listPlayer.setSurface(null);
     // Call the moveToNextWithPrerendered operation instead of the moveToNext operation if you use STS-based playback.
     listPlayer.moveToNextWithPrerendered(createStsInfo(source));
   }

   ApsaraVideo Player SDK for Android updated from an earlier version to V5.5.2.0 or later

   You must modify the code in the earlier version of ApsaraVideo Player SDK for Android. The following procedure describes how to modify the code.

   1. Modify the logic related to render views.

      Earlier versions of ApsaraVideo Player SDK for Android use a global render view. When you switch a video source, the previous render view is removed from the layout and a new render view is added. ApsaraVideo Player SDK for Android V5.5.2.0 or later supports multiple render views. You can add multiple views to the RecyclerView.ViewHolder layout. This way, you can preload the next video source before you switch the video. This ensures smooth video switching. You must delete the code of the render view from an earlier version of ApsaraVideo Player SDK for Android and add the code of multiple render views to the later version of ApsaraVideo Player SDK for Android. Sample code:

      Show code

      /*
      Delete the following code.
          The following lines of code of the earlier version of ApsaraVideo Player SDK for Android configure a render view. The following code adds a render view to FrameLayout and removes or adds mPlayerViewContainer when you switch the video source. 
      */
      private void initPlayer() {
          //...
          mPlayerViewContainer = View.inflate(getContext(), R.layout.layout_player_view, null);
          FrameLayout frameLayout = mPlayerViewContainer.findViewById(R.id.framelayout);
          FrameLayout.LayoutParams params = new FrameLayout.LayoutParams(FrameLayout.LayoutParams.MATCH_PARENT,
          FrameLayout.LayoutParams.MATCH_PARENT);
          View renderView = createRenderView(Common.RENDER_VIEW_NAME);
          frameLayout.addView(renderView, 0, params);
          //...
      }
      
      /*
      Add or modify the following code to add multiple render views.
          Modify the layout of items in RecyclerView and ViewHolder.
      */
      
      public final class MyHolder extends RecyclerView.ViewHolder {
          //...
          private Surface mSurface;
          MyHolder(@NonNull View itemView) {
              super(itemView);
              //...
              TextureView mTextureView = itemView.findViewById(R.id.texture_view);
              mTextureView.setSurfaceTextureListener(new TextureView.SurfaceTextureListener() {
                  @Override
                  public void onSurfaceTextureAvailable(SurfaceTexture surface, int width, int height) {
                      mSurface = new Surface(surface);
                  }
      
                  @Override
                  public void onSurfaceTextureSizeChanged(SurfaceTexture surface, int width, int height) {}
      
                  @Override
                  public boolean onSurfaceTextureDestroyed(SurfaceTexture surface) {
                      mSurface = null;
                      return false;
                  }
      
                  @Override
                  public void onSurfaceTextureUpdated(SurfaceTexture surface) {}
              });
          }
          //...
      
          // Add the getSurface operation. This operation is publicly accessible.
          public Surface getSurface() {
              return mSurface;
          }
      }

      The following sample code provides an example on how to modify the layout of items in RecyclerView:

      Show code

      <?xml version="1.0" encoding="utf-8"?>
      <FrameLayout xmlns:android="http://schemas.android.com/apk/res/android"
          xmlns:app="http://schemas.android.com/apk/res-auto"
          android:id="@+id/root_view"
          android:layout_width="match_parent"
          android:layout_height="match_parent"
          android:background="@android:color/black">
      
          <TextureView
              android:id="@+id/texture_view"
              android:layout_width="match_parent"
              android:layout_height="match_parent" />
      
      <!  -- Delete the thumbnail. If a black screen appears, you can retain the logic related to the thumbnail.   -->
      <!--    <FrameLayout-->
      <!--        android:id="@+id/player_view"-->
      <!--        android:layout_width="match_parent"-->
      <!--        android:layout_height="match_parent"-->
      <!--        android:clickable="false"-->
      <!--        android:clipChildren="false"-->
      <!--        android:focusable="false">-->
      
      <!--        <ImageView-->
      <!--            android:id="@+id/img_thumb"-->
      <!--            android:layout_width="match_parent"-->
      <!--            android:layout_height="match_parent"-->
      <!--            android:layout_gravity="center"-->
      <!--            android:adjustViewBounds="true"-->
      <!--            android:clickable="false"-->
      <!--            android:focusable="false"-->
      <!--            android:scaleType="fitXY" />-->
      
      <!--    </FrameLayout>-->
      
      </FrameLayout>

   2. Modify the logic for switching video sources.

      In ApsaraVideo Player SDK for Android V5.5.2.0 or later, the preRenderPlayer method is called when you call moveToNext. You must configure separate logic for the render view. The logic of the moveToNext, moveToPre, and moveTo operations is different. Sample code:

      Show code

      /*
          Note: mQuickPlayer is an instance of the AlivcQuickPlayer class and AlivcQuickPlayer encapsulates the ListPlayer operation. 
      */
      private void startPlay(int position, boolean isInitComplete) {
          //...
          // Query the ViewHolder instance based on the value of the position parameter.
          LittleVideoListAdapter.MyHolder holder = (LittleVideoListAdapter.MyHolder) recycler.findViewHolderForLayoutPosition(position);
      
          //...
      
          // 1. Specify Surface before you call the moveToPre operation.
          if (holder != null) {
              mQuickPlayer.setSurface(holder.getSurface());
          }
          mQuickPlayer.moveToPrev(video, position, mVideoSourceType);
      
          // 2. Specify Surface before you call the moveTo operation.
          if (holder != null) {
              mQuickPlayer.setSurface(holder.getSurface());
          }
          // Use mQuickPlayer.startPlay to call the moveTo operation in ApsaraVideo Player SDK.
          mQuickPlayer.startPlay(video, position, mVideoSourceType);
      
          // 3. Add a parameter to pass the value of Surface when you call the moveToPre operation.
          mQuickPlayer.moveToNext(video, position, mVideoSourceType, holder.getSurface());
      
          //...
      }

      The following sample code provides an example on how to modify the logic of the AlivcQuickPlayer class:

      Show code

      // Modify the logic of the moveToPre operation.
      public void moveToPrev(AlivcVideoInfo.Video source, final int position, VideoSourceType videoSourceType) {
          //...
          // Add the following code to your SDK.
          mVideoListPlayer.clearScreen();
          if (videoSourceType == VideoSourceType.TYPE_STS) {
              mVideoListPlayer.moveToPrev(createStsInfo(source));
          } else {
              mVideoListPlayer.moveToPrev();
          }
      }
      
      // Add a reload method for the moveToNext operation.
      public void moveToNext(AlivcVideoInfo.Video source, int position, VideoSourceType videoSourceType, Surface surface) {
          //...
          // Obtain and use the preRenderPlayer instance for playback when you call the moveToNext operation.
          IPlayer preRenderPlayer = mVideoListPlayer.getPreRenderPlayer();
          if (preRenderPlayer != null) {
              preRenderPlayer.clearScreen();
              preRenderPlayer.setSurface(surface);
              preRenderPlayer.start();
              mVideoListPlayer.setSurface(null);
          } else {
              mVideoListPlayer.clearScreen();
              mVideoListPlayer.setSurface(surface);
          }
      
          // Configure the STS-based playback.
          if (videoSourceType == VideoSourceType.TYPE_STS) {
              // If preRenderPlayer exists, call moveToNextWithPrerendered to play videos.
              if (preRenderPlayer != null) {
                  mVideoListPlayer.moveToNextWithPrerendered(createStsInfo(source));
              } else {
                  mVideoListPlayer.moveToNext(createStsInfo(source));
              }
          } else {
              // Configure the URL-based playback.
              if (preRenderPlayer != null) {
                  mVideoListPlayer.moveToNextWithPrerendered();
              } else {
                  mVideoListPlayer.moveToNext();
              }
          }
      }

   3. Optional. Modify the logic of playlist playback.

      You can modify the logic of playlist playback to start the playback of the next video when half of the view of the next video is displayed. Modify the code for the PagerLayoutManager class to switch the video source when half of the view of the next video is displayed on RecyclerView. Sample code:

      Show code

      recyclerView.addOnScrollListener(new OnScrollListener() {
          private int measuredHeight;
          private int mScrollDiff;
          @Override
          public void onScrollStateChanged(RecyclerView recyclerView, int newState) {
              super.onScrollStateChanged(recyclerView, newState);
      
              if (newState == RecyclerView.SCROLL_STATE_DRAGGING) {
                  measuredHeight = recyclerView.getMeasuredHeight();
                  mScrollDiff = 0;
              }
      
              if (newState == RecyclerView.SCROLL_STATE_IDLE) {
                  mScrollDiff = 0;
                  View viewIdle = mPagerSnapHelper.findSnapView(PagerLayoutManager.this);
                  if (viewIdle == null) {
                      return;
                  }
                  int positionIdle = getPosition(viewIdle);
                  if (mOnViewPagerListener != null && getChildCount() == 1 && mOldPosition != positionIdle) {
                      mOnViewPagerListener.onPageSelected(positionIdle, positionIdle == getItemCount() - 1, viewIdle);
                      mOldPosition = positionIdle;
                  }
              }
          }
      
          @Override
          public void onScrolled(RecyclerView recyclerView, int dx, int dy) {
              super.onScrolled(recyclerView, dx, dy);
              if (measuredHeight > 0 && mOnViewPagerListener != null) {
                  mScrollDiff += dy;
                  changeVideoAfterScrolled(recyclerView, dy >= 0);
              }
          }
      
          private void changeVideoAfterScrolled(RecyclerView recyclerView, boolean isNext) {
              if (Math.abs(mScrollDiff) >= measuredHeight / 2) {
                  View snapView = mPagerSnapHelper.findSnapView(PagerLayoutManager.this);
                  if (snapView != null) {
                      int position = getPosition(snapView);
                      if (mOldPosition != position) {
                          if (isNext) {
                              mOnViewPagerListener.onPageHideHalf(position - 1);
                          } else {
                              mOnViewPagerListener.onPageHideHalf(position + 1);
                          }
                          mOnViewPagerListener.onPageSelected(position, false, snapView);
                          mOldPosition = position;
                          recyclerView.smoothScrollToPosition(position);
                          mScrollDiff = 0;
                      }
                  }
              }
          }
      });