ApsaraVideo VOD:Support for multiple video sources

What is a video source?

A video source is the data source for video playback, defining how a video is retrieved and authorized.

AliPlayerKit supports three types of video sources:

How to choose a video source type

Choose a video source type based on your business scenario and security needs:

Challenges addressed

• Inconsistent configuration methods for different video source types.

• Complex management of authorization credentials.

• Lack of a unified validation mechanism for video sources.

• Difficulty in distinguishing between different types of video resources.

Core value

Core capabilities

VidAuth mode (recommended)

Authorizes playback using a video ID (VID) and a PlayAuth.

Use cases:

• Video resources that require authorization.

• Video playback in most production environments.

• Scenarios that require a simple and secure authorization method.

Features:

• Simple, easy-to-integrate authorization.

• Provides basic security.

• Recommended for most business scenarios.

Parameters:

Example:

// Create a VidAuth-type video source
VideoSource.VidAuthSource videoSource = VideoSourceFactory.createVidAuthSource(
    "your_video_id",      // Video ID
    "your_play_auth"      // PlayAuth
);

// Create the player model
AliPlayerModel model = new AliPlayerModel.Builder()
    .videoSource(videoSource)
    .build(); 

VidSts mode

Authorizes playback using a video ID (VID) and a token from Alibaba Cloud Security Token Service (STS), providing enhanced security and access control.

Use cases:

• Scenarios that require temporary access credentials.

• Video resources with high security requirements.

• Scenarios that require fine-grained access control.

Features:

• Uses a temporary credential for high security.

• Supports fine-grained access control.

• Suitable for high-security scenarios.

Parameters:

Example:

// Create a VidSts-type video source
VideoSource.VidStsSource videoSource = VideoSourceFactory.createVidStsSource(
    "your_video_id",              // Video ID
    "your_access_key_id",         // Access key ID
    "your_access_key_secret",     // Access key secret
    "your_security_token",        // Security token
    "cn-shanghai"                 // Region (optional)
);

// Create the player model
AliPlayerModel model = new AliPlayerModel.Builder()
    .videoSource(videoSource)
    .build();   

URL mode

Plays a video using a direct URL. This mode is suitable for publicly accessible video resources.

Use cases:

• Public video resources that do not require authorization.

• Testing and demonstration scenarios.

• Simple video playback requirements.

Features:

• Simple to use; only the video URL is required.

• No extra authorization is needed.

• Provides lower security and is not suitable for sensitive content.

Parameters:

Example:

// Create a URL-type video source
VideoSource.UrlSource videoSource = VideoSourceFactory.createUrlSource(
    "https://example.com/video.mp4"
);

// Create the player model
AliPlayerModel model = new AliPlayerModel.Builder()
    .videoSource(videoSource)
    .build();

Basic playback flow

// 1. Create a video source (VidAuth mode is recommended)
VideoSource.VidAuthSource videoSource = VideoSourceFactory.createVidAuthSource(
    "your_video_id",
    "your_play_auth"
);

// 2. Create the player model
AliPlayerModel model = new AliPlayerModel.Builder()
    .videoSource(videoSource)
    .coverUrl("https://example.com/cover.jpg")
    .videoTitle("Sample Video")
    .sceneType(SceneType.VOD)
    .autoPlay(true)
    .build();

// 3. Create a controller
AliPlayerController controller = new AliPlayerController(this);

// 4. Attach the controller to the player view
controller.configure(model);
playerView.attach(controller);   

Switching video sources

// Before you switch videos, detach the current controller
playerView.detach();

// Create a new video source
VideoSource.VidAuthSource newSource = VideoSourceFactory.createVidAuthSource(
    "new_video_id",
    "new_play_auth"
);

// Create a new player model
AliPlayerModel newModel = new AliPlayerModel.Builder()
    .videoSource(newSource)
    .build();

// Create a new controller and attach it
AliPlayerController newController = new AliPlayerController(this);
playerView.attach(newController, newModel);  

Validate a video source

Before you configure the player, you can call the isValid() method to verify the video source configuration:

VideoSource.VidAuthSource videoSource = VideoSourceFactory.createVidAuthSource(vid, playAuth);

if (videoSource.isValid()) {
    // The configuration is valid; you can proceed.
    AliPlayerModel model = new AliPlayerModel.Builder()
        .videoSource(videoSource)
        .build();
    playerView.attach(controller, model);
} else {
    // The configuration is invalid. Check the parameters.
    Log.e(TAG, "Invalid video source configuration");
}   

Get authorization from your server

To avoid hard-coding sensitive data, get authorization information from your server:

// Recommended: Get the PlayAuth from your server
public void playVideo(String videoId) {
    // Request the PlayAuth from the server
    apiService.getPlayAuth(videoId, new Callback<PlayAuthResponse>() {
        @Override
        public void onSuccess(PlayAuthResponse response) {
            VideoSource.VidAuthSource videoSource = VideoSourceFactory.createVidAuthSource(
                videoId,
                response.getPlayAuth()
            );
            // Start playback...
        }

        @Override
        public void onError(Exception e) {
            Log.e(TAG, "Failed to get playAuth", e);
        }
    });
}   

Handle STS token expiration

In VidSts mode, handle security token expiration:

// Check if the token is about to expire
if (isTokenExpiringSoon(securityToken)) {
    // Refresh the token
    refreshSecurityToken(new TokenCallback() {
        @Override
        public void onTokenRefreshed(String newToken) {
            // Recreate the video source with the new token
            VideoSource.VidStsSource videoSource = VideoSourceFactory.createVidStsSource(
                vid, accessKeyId, accessKeySecret, newToken, region
            );
            // Continue playback...
        }
    });
}

Choosing a video source type

Security recommendations

Error handling

Handle errors when you create a video source:

try {
    VideoSource.VidAuthSource videoSource = VideoSourceFactory.createVidAuthSource(vid, playAuth);

    if (!videoSource.isValid()) {
        // Handle invalid configuration
        showError("Invalid video source configuration");
        return;
    }

    // Use the video source
    playVideo(videoSource);

} catch (IllegalArgumentException e) {
    // Handle parameter errors
    Log.e(TAG, "Invalid video source parameters", e);
    showError("Parameter error: " + e.getMessage());
}   

Example features

Run the example

In the demo app, select the Video Source example to see the result.

VideoSourceFactory methods

VideoSource methods

SourceType constants

MediaId generation rule

The MediaId enables player instance reuse. Video sources with the same MediaId share the same player instance.

Choose a video source type

• For content that requires authorization with standard security needs: Use VidAuth mode (Recommended).

• For content that requires high security and temporary access credentials: Use VidSts mode.

• For public videos: Use URL mode.

VidAuth vs. VidSts

Handle creation failures

Check the following:

1. Check for null or invalid parameters.

2. Check that the URL format is correct (for URL mode).

3. Check that the authorization information is valid (for VidAuth and VidSts).

4. Check for a stable network connection.

Common mistakes

// Do not hard-code sensitive information in the client
VideoSource.VidAuthSource videoSource = VideoSourceFactory.createVidAuthSource(
    "video_id",
    "hardcoded_play_auth_value"  // Security risk!
);

// Get authorization information from the server
String playAuth = fetchPlayAuthFromServer(videoId);
VideoSource.VidAuthSource videoSource = VideoSourceFactory.createVidAuthSource(videoId, playAuth);

// Using without validation
VideoSource.VidAuthSource videoSource = VideoSourceFactory.createVidAuthSource(vid, playAuth);
playerView.attach(controller, createModel(videoSource));  // The configuration might be invalid

// Validate before use
VideoSource.VidAuthSource videoSource = VideoSourceFactory.createVidAuthSource(vid, playAuth);

if (videoSource.isValid()) {
    playerView.attach(controller, createModel(videoSource));
} else {
    showError("Invalid video source configuration");
}

// Token expiration is not handled
VideoSource.VidStsSource videoSource = VideoSourceFactory.createVidStsSource(
    vid, accessKeyId, accessKeySecret, expiredToken, region
);
// Playback fails! The token has expired.

// Check the token's validity and refresh it if needed
if (isTokenExpired(securityToken)) {
    securityToken = refreshToken();
}
VideoSource.VidStsSource videoSource = VideoSourceFactory.createVidStsSource(
    vid, accessKeyId, accessKeySecret, securityToken, region
);

Debugging

1. Check logs: Filter Logcat by using tag:AliPlayerKit.

2. Call toString(): The toString() method of the video source outputs the configuration information with sensitive data redacted.

3. Validate parameters: Use the isValid() method to validate the configuration.

4. Check the network: Ensure the video resource is accessible.