ApsaraVideo VOD:シーンタイプ

はじめに

SceneType とは

SceneType は、プレーヤーの 現在のビジネスシナリオ を指定する列挙型です。SceneType を設定すると、AliPlayerKit は自動的に以下を実行します：

• ライブストリーミングのシナリオでサムネイルを非表示にするなど、スロットの可視性を 調整 します。

• ライブストリーミングや視聴制限のあるシナリオではシークや再生速度調整を無効にし、ビデオリストのシナリオでは垂直ジェスチャーを無効にするなど、ジェスチャーを フィルタリング します。

• 視聴制限のあるシナリオでユーザーがコンテンツを完全かつ順番に視聴するようにするなど、機能の制限に 対応 します。

列挙型の値を設定するだけで、フレームワークはこれらの適応を自動的に処理します。これにより、さまざまなビジネスシナリオに合わせてプレーヤーをカスタマイズする手間を大幅に削減できます。

コアバリュー

機能

シナリオの概要

AliPlayerKit には、ほとんどの再生要件に対応する 5 つの組み込みシーンタイプが用意されています。

列挙型の定義

// SceneType.h
typedef NS_ENUM(NSInteger, SceneType) {
    /** VOD シナリオ (デフォルト) */
    SceneTypeVOD = 0,

    /** ライブストリーミングシナリオ */
    SceneTypeLive = 1,

    /** ビデオリストまたはショートビデオストリームシナリオ */
    SceneTypeVideoList = 2,

    /** 制限付き再生シナリオ */
    SceneTypeRestricted = 3,

    /** ミニマル再生ページシナリオ */
    SceneTypeMinimal = 4,
};

シナリオ別機能マトリクス

スロットの可視性

スロットシステムは、シーンタイプに基づいてコンポーネントの可視性を自動的に制御します。次のマトリクスに、DefaultSlotFactory.defaultConfigs のデフォルトルールを示します。

可視性ルールの説明：

• PlayerSurface と 再生状態 は、すべてのシナリオで表示されます (excludedScenes の設定なし)。

• Cover は、ライブ、制限付き、または ミニマル のシナリオでは表示されません。

• その他のスロット (GestureControl、LandscapeHint、CenterDisplay、LogPanel、TopBar、BottomBar、SettingMenu、OptionPanel) は、ミニマル シナリオでのみ表示されません。

ジェスチャー動作の相違点

GestureControlSlot は、currentSceneType に基づいて、各処理メソッド内でジェスチャーを内部的にフィルタリングします。

フィルターロジックの説明：

• ミニマル：すべてのジェスチャー処理メソッド (handleSingleTap:、handleDoubleTap:、handleLongPress:、および handlePan:) は、エントリポイントで即座に return を実行します。

• ライブ / 制限付き：長押しと水平ドラッグは無効になります。これは handleLongPress: と tryStartDragWithCurrentPoint: でチェックされます。

• ビデオリスト：垂直ドラッグは無効になります。tryStartDragWithCurrentPoint: メソッドは、SceneTypeVideoList を検出すると即座に return を実行します。

使用方法

基本的な使用方法

AliPlayerModel.sceneType プロパティを使用してシーンタイプを指定できます。デフォルトは SceneTypeVOD で、明示的に設定する必要はありません。

VOD シナリオ (デフォルト、設定不要)：

VideoSource *source = [VideoSource urlSourceWithUrl:@"https://example.com/video.mp4"];
AliPlayerModel *model = [[AliPlayerModel alloc] initWithVideoSource:source];
// model.sceneType はデフォルトで SceneTypeVOD のため、設定は不要です

[controller configure:model];

ライブストリーミングシナリオ：

VideoSource *source = [VideoSource urlSourceWithUrl:@"https://live.example.com/stream.m3u8"];
AliPlayerModel *model = [[AliPlayerModel alloc] initWithVideoSource:source];
model.sceneType = SceneTypeLive;
model.videoTitle = @"Live Channel";

[controller configure:model];

動画リストシナリオ：

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

[controller configure:model];

各シナリオの詳細

VOD - VOD シナリオ (デフォルト)

利用シーン：標準的な動画再生、オンラインコース、メディアライブラリの閲覧など。

機能：

• 11 個すべてのデフォルトスロットに対応します

• 6 つすべてのジェスチャーに対応します

• シーク、再生速度調整、解像度切り替えに対応します

• フルスクリーン切り替えに対応します

// SceneType を明示的に指定する必要はありません。デフォルトは VOD です
AliPlayerModel *model = [[AliPlayerModel alloc] initWithVideoSource:source];
model.coverUrl = @"https://example.com/cover.jpg";
model.videoTitle = @"Great Video";
model.autoPlay = YES;

[controller configure:model];

Live - ライブストリーミングシナリオ

利用シーン：リアルタイムのライブストリーミング、スポーツイベントのライブ配信、ライブコマースなど。

VOD との主な相違点：

• 無効：ライブストリームには固定の再生時間がないため、シーク (水平ジェスチャー) と再生速度調整 (長押しジェスチャー) は無効になります。

• 非表示：ライブストリームにはサムネイルが不要なため、サムネイルスロットは非表示になります。

• 維持：クリック/ダブルクリックジェスチャー、音量/明るさ調整は維持されます。

AliPlayerModel *model = [[AliPlayerModel alloc] initWithVideoSource:liveSource];
model.sceneType = SceneTypeLive;
model.videoTitle = @"Popular Live Stream";
model.autoPlay = YES;

[controller configure:model];

VideoList - 動画リストシナリオ

利用シーン：フィードへの埋め込み動画、ショート動画リスト、スクロール可能な動画コレクションなど。

VOD との主な相違点：

• 無効：リストの UIScrollView スクロールとの競合を避けるため、垂直ドラッグジェスチャーは無効になります。

• 維持：シーク、再生速度調整、クリック/ダブルクリック/長押しジェスチャーなど、他のすべての機能は維持されます。

AliPlayerModel *model = [[AliPlayerModel alloc] initWithVideoSource:source];
model.sceneType = SceneTypeVideoList;
model.autoPlay = YES;

[controller configure:model];

Restricted - 制限付き再生シナリオ

利用シーン：オンライン試験の監視動画、トレーニングおよび認定コース、著作権保護シナリオなど。

VOD との主な相違点：

• 無効：ユーザーがコンテンツを最後まで順番に視聴するように、シーク (水平ジェスチャー) と再生速度調整 (長押しジェスチャー) は無効になります。

• 非表示：サムネイルスロットは非表示になります。

• 維持：クリック/ダブルクリックジェスチャー、音量/明るさ調整は維持されます。

AliPlayerModel *model = [[AliPlayerModel alloc] initWithVideoSource:source];
model.sceneType = SceneTypeRestricted;
model.videoTitle = @"Security Training Course";
model.autoPlay = YES;
// 通常、スクリーンショット防止機能と併用されます
model.disableScreenshot = YES;

[controller configure:model];

Minimal - ミニマルモード

利用シーン：バックグラウンド再生、完全なカスタム UI、プレビューサムネイル再生など。

VOD との主な相違点：

• 非表示：ほぼすべての UI コントロールスロットが非表示になります。PlayerSurface と PlayState のみが維持されます。

• 無効：すべてのジェスチャーが無効になります。GestureControl スロットはミニマルシナリオでは表示されず、その内部のジェスチャー処理メソッドはすべて即座に return します。

• ユースケース：再生コントロール UI の完全なカスタム実装が必要なシナリオ。

AliPlayerModel *model = [[AliPlayerModel alloc] initWithVideoSource:source];
model.sceneType = SceneTypeMinimal;

[controller configure:model];
// すべてのコントロールは、コントローラーの API を使用して実装する必要があります
// 例：[controller play]; [controller pause]; [controller seekTo:position];

カスタム開発

スロットの可視性のファインチューニング

あるシナリオにプリセットされているスロットの可視性が要件を満たさない場合、SlotConfig を使用してファインチューニングできます：

// 例： Live シナリオで TopBar を非表示にする
SlotConfig *topBarConfig = [SlotConfig configWithSlotType:SlotTypeTopBar
                                           excludedScenes:[NSSet setWithObjects:
                                               @(SceneTypeMinimal),
                                               @(SceneTypeLive), nil]];

// SlotManager に登録します (このスロットタイプのデフォルト SlotConfig をオーバーライドします)
[playerView.slotManager registerSlotConfig:topBarConfig];

また、hideSlot: を使用してスロット全体を直接非表示にすることもできます。このメソッドはシナリオに依存しません：

// TopBar を無条件で非表示にします (有効にするには rebuildSlots の呼び出しが必要です)
[playerView.slotManager hideSlot:SlotTypeTopBar];

ジェスチャー動作のファインチューニング

ジェスチャーコントロールのファインチューニングには、2 つの方法があります：

方法 1： SlotManager の要素ビットマスク API を使用して特定のジェスチャーを無効にします。この方法を推奨します。attach を呼び出す前に設定する必要があります。

// VOD シナリオで、長押しによる早送りを無効にする
[playerView.slotManager hideElements:GestureElementLongPress
                             forSlot:SlotTypeGestureControl];

方法 2： GestureControlSlotConfig を使用してジェスチャーを直接制御します。attach を呼び出した後にスロットインスタンスを取得する必要があります：

// ジェスチャーコントロールスロットのインスタンスを取得する
GestureControlSlot *gestureSlot = (GestureControlSlot *)[playerView.slotManager slotViewForType:SlotTypeGestureControl];

// 設定を変更します (即座に有効になります)
GestureControlSlotConfig *config = [GestureControlSlotConfig defaultConfig];
config.longPressEnabled = NO;
config.horizontalDragEnabled = NO;
gestureSlot.config = config;

Minimal シナリオでのカスタムスロットの登録

Minimal シナリオでは、ほとんどのデフォルトスロットはシーン設定によって除外されます。スロットを復元するには、その SlotConfig をオーバーライドします：

AliPlayerModel *model = [[AliPlayerModel alloc] initWithVideoSource:source];
model.sceneType = SceneTypeMinimal;

// BottomBar のシーン設定をオーバーライドして、Minimal 除外ルールを削除します
[playerView.slotManager registerSlotConfig:
    [SlotConfig configWithSlotType:SlotTypeBottomBar]]; // excludedScenes がない = すべてのシナリオで表示

[controller configure:model];

動的な可視性条件

SlotConfig の visibilityCondition コールバックを使用して、ランタイムに動的な制御を実装できます：

SlotConfig *coverConfig = [SlotConfig configWithSlotType:SlotTypeCover
                                          excludedScenes:nil
                                     visibilityCondition:^BOOL{
    // カバー URL が存在する場合にのみカバースロットを表示する
    return model.coverUrl != nil;
}];

[playerView.slotManager registerSlotConfig:coverConfig];

シーン選択ガイド

決定フロー

プレーヤーコントロール UI が必要ですか？
├── いいえ → SceneTypeMinimal
└── はい → ライブストリームですか？
         ├── はい → SceneTypeLive
         └── いいえ → プレーヤーはスクロール可能なリストに埋め込まれていますか？
                   ├── はい → SceneTypeVideoList
                   └── いいえ → ユーザーのスキップを防止する必要がありますか？
                             ├── はい → SceneTypeRestricted
                             └── いいえ → SceneTypeVOD (デフォルト)

シーン選択の概要表

API クイックリファレンス

SceneType 列挙型

SlotConfig

GestureControlSlotConfig

SlotManager シナリオ関連 API

関連ファイル

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

ベストプラクティス

注意事項

よくある質問

AliPlayerModel *model = [[AliPlayerModel alloc] initWithVideoSource:source];
model.sceneType = SceneTypeMinimal;
[controller configure:model];

// コントローラー API を通じて直接制御
[controller play];
[controller pause];
[controller seekTo:30000]; // 30 秒にシーク

// 水平ドラッグジェスチャー (プログレスシーク) を復元
[playerView.slotManager showElements:GestureElementHorizontalDrag
                             forSlot:SlotTypeGestureControl];