Multiple video source support

Key concepts

What is a video source?

A video source specifies the origin of a video and the authorization method required for playback.

AliPlayerKit uses the VideoSource class to encapsulate three types of video sources:

How to choose a video source type

Design features

• Immutable object: All properties of a VideoSource object are read-only and cannot be modified after creation.

• Factory method creation: The init and new methods are marked as NS_UNAVAILABLE. Use the provided class factory methods to create instances.

• Parameter validation: Factory methods validate that required parameters are not nil or empty strings. If validation fails, they return nil.

• Validity check: The isValid method lets you perform a secondary check before configuring the player.

• Unique identifier: The uniqueId property is automatically derived based on the source type. It returns the vid for VidAuth and VidSts sources, and the url for URL sources. The player uses this ID to reuse instances during lifecycle management.

Video source types

VidAuth mode (Recommended)

This mode authorizes playback by using a video ID (VID) and a PlayAuth. Its simple authorization and easy integration make it the recommended choice for most production environments.

Use cases:

• Video resources that require authorization.

• Video playback in most production environments.

• Scenarios that require a simple and secure authorization method.

Parameters:

Example:

VideoSource *videoSource =
    [VideoSource vidAuthSourceWithVid:@"your_video_id"
                             playAuth:@"your_play_auth"];

AliPlayerModel *model = [[AliPlayerModel alloc] initWithVideoSource:videoSource];
model.sceneType = SceneTypeVOD;
model.autoPlay = YES;

VidSts mode

This mode uses a video ID (VID) and an Alibaba Cloud Security Token Service (STS) temporary credential to authorize playback. It offers a higher level of 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.

Parameters:

Example:

VideoSource *videoSource =
    [VideoSource vidStsSourceWithVid:@"your_video_id"
                         accessKeyId:@"your_access_key_id"
                     accessKeySecret:@"your_access_key_secret"
                       securityToken:@"your_security_token"
                              region:@"cn-shanghai"];

AliPlayerModel *model = [[AliPlayerModel alloc] initWithVideoSource:videoSource];
model.sceneType = SceneTypeVOD;
model.autoPlay = YES;

URL mode

This mode plays a video directly from a URL, making it suitable for publicly accessible video resources.

Use cases:

• Public video resources that do not require authorization.

• Testing and demo scenarios.

• Playback of a live stream.

Parameters:

Example:

VideoSource *videoSource =
    [VideoSource urlSourceWithUrl:@"https://example.com/video.mp4"];

AliPlayerModel *model = [[AliPlayerModel alloc] initWithVideoSource:videoSource];

Comparison of video source types

Usage

Basic usage: Create a source

Create a video source by using the VideoSource factory class method:

// VidAuth (Recommended)
VideoSource *authSource =
    [VideoSource vidAuthSourceWithVid:@"your_video_id"
                             playAuth:@"your_play_auth"];

// VidSts
VideoSource *stsSource =
    [VideoSource vidStsSourceWithVid:@"your_video_id"
                         accessKeyId:@"your_access_key_id"
                     accessKeySecret:@"your_access_key_secret"
                       securityToken:@"your_security_token"
                              region:@"cn-shanghai"];

// URL
VideoSource *urlSource =
    [VideoSource urlSourceWithUrl:@"https://example.com/video.mp4"];

Basic usage: Validate the source

Before you configure the player, call isValid to validate the video source configuration:

VideoSource *source =
    [VideoSource vidAuthSourceWithVid:vid playAuth:playAuth];

if (source && [source isValid]) {
    AliPlayerModel *model = [[AliPlayerModel alloc] initWithVideoSource:source];
    [self.controller configure:model];
} else {
    NSLog(@"Invalid video source configuration: %@", source);
}

Validation rules for isValid:

Basic usage: End-to-end playback flow

@interface PlayerViewController ()
@property (nonatomic, strong) AliPlayerView *playerView;
@property (nonatomic, strong) AliPlayerController *playerController;
@end

@implementation PlayerViewController

- (void)viewDidLoad {
    [super viewDidLoad];

    // 1. Create a video source. We recommend fetching the PlayAuth from your server.
    VideoSource *videoSource =
        [VideoSource vidAuthSourceWithVid:@"your_video_id"
                                 playAuth:@"server_returned_play_auth"];

    // 2. Validate the video source.
    if (!videoSource || ![videoSource isValid]) {
        NSLog(@"Invalid video source configuration: %@", videoSource);
        return;
    }

    // 3. Create the player model.
    AliPlayerModel *model = [[AliPlayerModel alloc] initWithVideoSource:videoSource];
    model.sceneType = SceneTypeVOD;
    model.coverUrl = @"https://example.com/cover.jpg";
    model.autoPlay = YES;

    // 4. Create and configure the controller.
    self.playerController = [[AliPlayerController alloc] init];
    [self.playerController configure:model];

    // 5. Attach the controller to the player view.
    [self.playerView attach:self.playerController];
}

- (void)dealloc {
    [_playerView detach];
    [_playerController destroy];
}

@end

Advanced usage: Switch video sources

To switch between different video sources on the same controller, simply use a new AliPlayerModel to recall configure::

- (void)switchToNewVideo:(NSString *)newVid playAuth:(NSString *)newPlayAuth {
    VideoSource *newSource =
        [VideoSource vidAuthSourceWithVid:newVid playAuth:newPlayAuth];

    AliPlayerModel *newModel = [[AliPlayerModel alloc] initWithVideoSource:newSource];
    newModel.videoTitle = @"New Video";

    // Re-configure the same controller.
    [self.playerController configure:newModel];
}

Best practices

Security recommendations

// Recommended: Fetch credentials from a server.
- (void)playVideoWithId:(NSString *)videoId {
    [self.apiService fetchPlayAuthForVideoId:videoId
                                  completion:^(NSString *playAuth, NSError *error) {
        if (error) {
            NSLog(@"Failed to get PlayAuth: %@", error);
            return;
        }

        VideoSource *source =
            [VideoSource vidAuthSourceWithVid:videoId playAuth:playAuth];
        AliPlayerModel *model = [[AliPlayerModel alloc] initWithVideoSource:source];
        [self.playerController configure:model];
    }];
}

Common mistakes

Mistake 1: Not checking the return value of a factory method

// ✗ Incorrect: The factory method can return nil, but its return value is not checked.
VideoSource *source = [VideoSource vidAuthSourceWithVid:vid playAuth:playAuth];
AliPlayerModel *model = [[AliPlayerModel alloc] initWithVideoSource:source]; // `source` can be nil.

// ✓ Correct: Check the return value.
VideoSource *source = [VideoSource vidAuthSourceWithVid:vid playAuth:playAuth];
if (source && [source isValid]) {
    AliPlayerModel *model = [[AliPlayerModel alloc] initWithVideoSource:source];
    [self.playerController configure:model];
}

Mistake 2: Hard-coding sensitive information on the client

// ✗ Incorrect: `playAuth` is hard-coded, which is a security risk.
VideoSource *source =
    [VideoSource vidAuthSourceWithVid:@"video_id"
                             playAuth:@"hardcoded_play_auth_value"];

// ✓ Correct: Fetch from your server.
NSString *playAuth = [self fetchPlayAuthFromServer:videoId];
VideoSource *source =
    [VideoSource vidAuthSourceWithVid:videoId playAuth:playAuth];

Mistake 3: Not handling expired STS security tokens

// ✗ Incorrect: Using an expired token.
VideoSource *source = [VideoSource vidStsSourceWithVid:vid
                                           accessKeyId:accessKeyId
                                       accessKeySecret:accessKeySecret
                                         securityToken:expiredToken
                                                region:region];

// ✓ Correct: Check the token and refresh it if needed.
if ([self isTokenExpired:securityToken]) {
    securityToken = [self refreshSecurityToken];
}
VideoSource *source = [VideoSource vidStsSourceWithVid:vid
                                           accessKeyId:accessKeyId
                                       accessKeySecret:accessKeySecret
                                         securityToken:securityToken
                                                region:region];

Mistake 4: Creating an instance with init

// ✗ Compile error: `init` and `new` are marked as NS_UNAVAILABLE.
VideoSource *source = [[VideoSource alloc] init];

// ✓ Correct: Use a class factory method.
VideoSource *source = [VideoSource urlSourceWithUrl:@"https://example.com/video.mp4"];

API reference

VideoSourceType enum

VideoSource properties

VideoSource methods

Related files

For complete API details, see the API reference.

Example

The PlayerKitUsages/UsageVideoSource module provides a complete example of how to use video sources, covering the creation, parameter validation, and playback processes for three types of video sources.