ApsaraVideo VOD:カスタム設定

基本概念

3 レベル構成システム

AliPlayerKit の構成システムには、3 つのレベルがあります：

┌─────────────────────────────────────────────────────────┐
│              1. グローバル設定 (OnGlobalInitBlock)              │
│         アプリの起動時に 1 回実行され、すべてのプレーヤーインスタンスに影響します                │
├─────────────────────────────────────────────────────────┤
│              2. モデル設定 (AliPlayerModel)                 │
│         configure: が呼び出されるたびに、プロパティを使用して再生パラメーターを設定します               │
├─────────────────────────────────────────────────────────┤
│           3. プレーヤー設定 (onPlayerConfigBlock)               │
│       configure: が呼び出されるたびに、prepare の前に基盤となるプレーヤーへのコールバックを提供します          │
└─────────────────────────────────────────────────────────┘

グローバル設定

ユースケース

• グローバルログレベルなど、グローバルオプションを設定する

• HTTP/2 多重化を有効にする

• グローバルな DNS 名前解決ストラテジーを設定する

• プレーヤーインスタンスが作成される前に有効にする必要があるその他のグローバルな動作を実装する

仕組み

• +[AliPlayerKit setOnGlobalInitBlock:] を使用して、コールバックブロックを登録します。

• このコールバックは、+setup が内部初期化を完了した後に 1 回トリガーされます。

• 実行後、システムはブロックを nil に設定するため、再度トリガーされることはありません。

• この時点で、基礎となる SDK の準備が整い、グローバル API を安全に呼び出すことができます。

使用方法

application:didFinishLaunchingWithOptions: 内で、+setup を呼び出す前にコールバックを登録します：

- (BOOL)application:(UIApplication *)application
    didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {

    // 1. グローバル設定のコールバックを登録します。
    //    これは setup の前に呼び出す必要があります。
    [AliPlayerKit setOnGlobalInitBlock:^{
        // 例： HTTP/2 多重化を有効にします。
        [AliPlayerFactory setOption:ALLOW_H2_MULTIPLEX value:1];

        // 例： グローバルログレベルを設定します。
        // [AliPlayerFactory setLogLevel:AF_LOG_LEVEL_INFO];
    }];

    // 2. SDK を初期化します。 これにより、内部初期化の完了後、上記で登録されたコールバックがトリガーされます。
    [AliPlayerKit setup];

    return YES;
}

設定シーケンス

application:didFinishLaunchingWithOptions:
    │
    ├── [AliPlayerKit setOnGlobalInitBlock:block]   ← コールバックを登録
    │
    └── [AliPlayerKit setup]
            │
            ├── [GlobalManager setup]    ← 基礎となる SDK を初期化
            │
            ├── sInitialized = YES
            │
            └── block()                  ← グローバル設定コールバックをトリガー (1 回のみ)

注意事項

プレーヤー設定

ユースケース

• バッファリング戦略 (例：maxBufferDuration および highBufferDuration) をカスタマイズします。

• Referer ホットリンク保護を設定します。

• HTTP ヘッダーを設定します。

• インスタンスレベルのオプションを設定します。

• AliPlayerKit が直接公開していない他のプレーヤーインターフェイスにアクセスします。

仕組み

• AliPlayerModel.onPlayerConfigBlock プロパティにコールバックブロックを設定します。

• コールバックは [controller configure:model] が呼び出されるたびにトリガーされます。

• コールバックは setDataSource: の後、prepare の前に実行されます。

• コールバックのパラメーターは、MediaPlayer プロトコルに準拠した、基になるプレーヤーインスタンスです。

使用方法

AliPlayerModel をビルドする際、onPlayerConfigBlock を設定します：

VideoSource *source = [VideoSource urlSourceWithUrl:@"https://example.com/video.mp4"];
AliPlayerModel *model = [[AliPlayerModel alloc] initWithVideoSource:source];

// インスタンスレベルのカスタム設定コールバックを設定します
model.onPlayerConfigBlock = ^(id<MediaPlayer> player) {
    // 既存の設定を取得します
    AVPConfig *config = [player getConfig];

    // 例 1： バッファリング戦略をカスタマイズします
    config.maxBufferDuration = 50000;       // 最大バッファ期間： 50 秒
    config.highBufferDuration = 3000;       // 高ウォーターマーク： 3 秒
    config.startBufferDuration = 500;       // 開始バッファ期間： 500 ms

    // 例 2： Referer ホットリンク保護を設定します
    config.referer = @"https://your-domain.com";

    // 例 3： インスタンスレベルのオプションを設定します
    // [player setOption:key value:value];

    // 全ての設定を一度に適用します
    [player setConfig:config];
};

// ビデオを設定して再生します
[controller configure:model];

設定シーケンス

[controller configure:model]
    │
    ├── lifecycleStrategy.acquire()             ← プレーヤーインスタンスを取得
    │
    ├── [mediaPlayer setDataSource:model]       ← ビデオソースを設定
    │
    ├── model.onPlayerConfigBlock(mediaPlayer)  ← プレーヤー設定コールバックをトリガー
    │
    ├── [strategyManager start/reset]           ← 戦略システムを開始
    │
    └── [mediaPlayer prepare]                   ← 再生準備を開始

使用上の注意

組み込み設定項目

AliPlayerKit グローバル設定

AliPlayerKit クラスのメソッドを使用することで、組み込み設定オプションを直接設定できます。

AliPlayerModel プレーヤー設定

AliPlayerModel プロパティによって設定されるインスタンスレベルの設定項目です。

AliPlayerController ランタイム設定

AliPlayerController によって実行時に動的に調整される設定です。

設定の優先順位

優先順位のルール

同じ項目が複数のレベルで設定されている場合、設定は次の優先順位で適用されます。

プレーヤー設定 (onPlayerConfigBlock) > AliPlayerModel のプロパティ > グローバル設定 > SDK のデフォルト値

設定スコープ

設定例

コード例

// ===== グローバル設定 (AppDelegate 内、1 回のみ) =====
- (BOOL)application:(UIApplication *)application
    didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {

    // グローバルカスタム設定
    [AliPlayerKit setOnGlobalInitBlock:^{
        // HTTP/2 多重化を有効にする
        [AliPlayerFactory setOption:ALLOW_H2_MULTIPLEX value:1];
    }];

    // 初期化
    [AliPlayerKit setup];

    // グローバル組み込み設定 (setup の後に呼び出す必要があります)
    [AliPlayerKit setLogLevel:LogLevelWarn];
    [AliPlayerKit enableConsoleLog:YES];

    return YES;
}

// ===== プレーヤー設定 (プレーヤービューコントローラー内、各再生ごと) =====
- (void)startPlayback {
    VideoSource *source = [VideoSource urlSourceWithUrl:videoUrl];
    AliPlayerModel *model = [[AliPlayerModel alloc] initWithVideoSource:source];

    // モデルプロパティ設定
    model.sceneType = SceneTypeVOD;
    model.videoTitle = @"Awesome Video";
    model.coverUrl = coverImageUrl;
    model.autoPlay = YES;
    model.hardwareDecode = YES;
    model.startTime = resumePosition; // 最後の位置から再開

    // インスタンスレベルのカスタム設定 (基礎となる SDK 用)
    model.onPlayerConfigBlock = ^(id<MediaPlayer> player) {
        AVPConfig *config = [player getConfig];
        config.maxBufferDuration = 50000;
        config.highBufferDuration = 3000;
        config.startBufferDuration = 500;
        config.referer = @"https://your-domain.com";
        [player setConfig:config];
    };

    [_controller configure:model];
}

API クイックリファレンス

グローバル設定 API

プレーヤー設定 API

関連ファイル

API の一覧については、「API リファレンス」をご参照ください。

よくある質問

設定の実行順序

グローバル設定は、アプリケーション起動時に +setup で一度実行され、プレーヤー設定は各 configure: 呼び出し中に prepare の前に実行されます。この 2 つは互いに干渉しません。

デフォルトの動作

AliPlayerKit には、ベストプラクティスに基づいた組み込み設定が含まれているため、カスタム設定を行わなくても、ほとんどのユースケースに適しています。

コールバック内での非同期処理

これは推奨されません。コールバックは同期的に実行されます。そのため、プレーヤーはコールバックが完了するまで prepare の実行を続行しません。コールバックで時間のかかる操作を実行すると、プレーヤーの起動プロセスがブロックされます。

コールバック内でのビデオソースの変更

これは推奨されません。ビデオソースは、コールバックの前に setDataSource: を使用してすでに設定されています。コールバック内で変更すると、予期しない動作を引き起こす可能性があります。プレーヤー設定コールバックは、バッファリング戦略や Referer などの再生パラメーターを設定する場合にのみ使用してください。

+setup 後の setOnGlobalInitBlock: の呼び出し

有効になりません。+setup メソッドは dispatch_once を使用して、一度だけ実行されることを保証します。+setup メソッドが呼び出された後にブロックを設定しても、そのブロックが実行されることはありません。

ログ設定のタイミング

setLogLevel: と enableConsoleLog: は、LogHub シングルトンを直接操作するため、+setup の後で呼び出す必要があります。ただし、setOnGlobalInitBlock: は +setup の前に設定する必要があります。