すべてのプロダクト
Search
ドキュメントセンター

ApsaraVideo VOD:高度な機能

最終更新日:Nov 26, 2025

このトピックでは、ApsaraVideo Player SDK for Flutter の高度な機能の使用例について説明します。すべての機能の詳細については、API リファレンスをご参照ください。

再生

短いビデオリストの再生

  1. リストプレーヤーを作成します。

    FlutterAliListPlayer fAliListPlayer = FlutterAliPlayerFactory.createAliListPlayer();
  2. リソースを追加および削除します。

    リストプレーヤーは、UrlSource と VidSts からの再生のみをサポートします。

    // uid パラメーターは動画の一意の ID を指定します。UID を使用して動画を識別します。同じ UID を持つ動画は同一と見なされます。
    fAliListPlayer.addUrlSource(url,uid);
    fAliListPlayer.addVidSource(vid,uid);
    fAliListPlayer.removeSource(uid);
  3. プリロードする動画数の設定

    プリロードする動画の数を適切に設定すると、起動時間を効果的に短縮できます。次のコードに例を示します。

    // プリロードする動画の数を設定します。読み込まれる動画の総数は、次の数式で計算されます:1 + count × 2。
    fAliListPlayer.setPreloadCount(count);
  4. ビデオソースを再生します。

    // uid パラメーターは必須です。URL ベースの再生の場合は、UID のみを指定します。STS ベースの再生の場合は、STS 情報を指定します。
    fAliListPlayer.moveTo();

ソフトウェアデコードとハードウェアデコードの切り替え

ApsaraVideo Player SDK for Flutter は、H.264 と H.265 のハードウェアデコードをサポートします。この機能はデフォルトで有効になっており、setEnableHardwareDecoder メソッドを使用して制御できます。ハードウェアデコードの初期化に失敗した場合、プレーヤーは自動的にソフトウェアデコードに切り替わり、再生が中断されないようにします。次のコードに例を示します。

// ハードウェアデコードを有効にします。この機能はデフォルトで有効になっています。
fAliplayer.setEnableHardwareDecoder(enable);

ネットワーク状況に応じた動画解像度の切り替え

ApsaraVideo Player SDK for Flutter は、HLS および DASH 動画ストリームのアダプティブビットレートストリーミングをサポートします。prepare メソッドの呼び出しが成功した後、getMediaInfo メソッドを呼び出して各ストリームの情報を取得できます。この情報は TrackInfo として返されます。次のコードに例を示します。

fAliplayer.getMediaInfo().then((value) {
// value はマップです。value['tracks'] を使用して TrackInfo のリストを取得できます。TrackInfo の解析方法については、デモの AVPMediaInfo info = AVPMediaInfo.fromJson(value); をご参照ください。

});

再生中に、プレーヤーの selectTrack メソッドを呼び出して再生ストリームを切り替えることができます。このメソッドは、TrackInfotrackIndex をパラメーターとして使用します。切り替えの結果は、OnTrackChangedListener リスナーがトリガーされたときのコールバックで返されます。

// ビットレートを切り替えます。
fAliplayer.selectTrack(index);
// ビットレートを切り替え、アダプティブストリーミングを有効にします。
fAliplayer.selectTrack(-1);

スナップショットの撮影

ApsaraVideo Player SDK for Flutter では、現在の動画フレームのスナップショットを撮影できます。この機能は setOnSnapShot メソッドを使用して実装されます。

// スナップショット成功時のリスナー。
fAliplayer.setOnSnapShot((path,playerId) {

});
// スナップショットを撮影します。path は画像が保存されるパスです。
fAliplayer.snapshot(path);

ビデオのプレビュー

ApsaraVideo Player SDK for Flutter は、ApsaraVideo VOD と連携して動画プレビュー機能を有効にできます。プレビュー機能は、VidAuth ベースの再生 (推奨) と VidSts ベースの再生でサポートされています。プレビュー機能の設定と使用方法の詳細については、「動画プレビュー」をご参照ください。

プレビュー機能を設定した後、setVidAuth メソッドの previewTime パラメーターを使用して、プレーヤーのプレビュー時間を設定できます。次のコードに例を示します。

// previewTime はプレビュー時間 (秒) です。
// VidAuth ベースの再生
fAliplayer.setVidAuth(
 vid: "リソースの VID を入力してください",
 region: "リソースのリージョンを入力してください",
 playAuth: "リソースの PlayAuth を入力してください",
 previewTime: "プレビュー時間 (秒) を入力してください");

 // VidSts ベースの再生
 fAliplayer.setVidSts(
 vid: "リソースの VID を入力してください",
 region: "リソースのリージョンを入力してください",
 accessKeyId: "リソースの AccessKey ID を入力してください",
 accessKeySecret: "リソースの AccessKey Secret を入力してください",
 securityToken: "リソースのセキュリティトークンを入力してください",
 previewTime: "プレビュー時間 (秒) を入力してください");

その他の構成

ApsaraVideo Player SDK for Flutter は、その他の再生構成を提供します。これらの構成は、prepare() メソッドを呼び出す前にプレーヤーに適用する必要があります。

var configMap = {
 'mStartBufferDuration':_mStartBufferDurationController.text,// 再生開始前のバッファー時間 (ミリ秒)。
 'mHighBufferDuration':_mHighBufferDurationController.text,// バッファーのハイウォーターマーク (ミリ秒)。
 'mMaxBufferDuration':_mMaxBufferDurationController.text,// 最大バッファー時間 (ミリ秒)。
 'mMaxDelayTime': _mMaxDelayTimeController.text,// ライブストリーミングの最大遅延時間 (ミリ秒)。注意:このパラメーターはライブストリーミングでのみ有効です。
 'mNetworkTimeout': _mNetworkTimeoutController.text,// ネットワークタイムアウト期間 (ミリ秒)。
 'mNetworkRetryCount':_mNetworkRetryCountController.text,/// ネットワークタイムアウト後の再試行回数。
 'mMaxProbeSize': _mMaxProbeSizeController.text,// 最大プローブサイズ。
 'mReferrer': _mReferrerController.text,// リファラー。
 'mHttpProxy': _mHttpProxyController.text,// HTTP プロキシ。
 'mEnableSEI': mEnableSEI,// SEI を有効にするかどうかを指定します。
 'mClearFrameWhenStop': !mShowFrameWhenStop,/// 再生停止時に最後のフレームをクリアするかどうかを指定します。
 'mDisableVideo': mDisableVideo,// 動画を無効にするかどうかを指定します。
 'mDisableAudio': mDisableAudio,// 音声を無効にするかどうかを指定します。
 'mUserAgent':mUserAgent,// ユーザーエージェント。
};
// 構成を適用します。
fAliplayer.setConfig(configMap);

パフォーマンス

プリレンダリング

ApsaraVideo Player SDK for Flutter は、再生が開始される前に動画の最初のフレームをすばやく表示するためのプリレンダリングをサポートします。

以下に例を示します。

fAliplayer.setOption(FlutterAvpdef.ALLOW_PRE_RENDER, 1);

ローカルキャッシュ

ApsaraVideo Player SDK for Flutter は、再生中に動画をキャッシュするローカルキャッシュ機能を提供します。これにより、ユーザーが動画を繰り返し再生する際のデータトラフィック消費を削減できます。この機能を使用するには、prepare メソッドを呼び出す前に、プレーヤーの enableLocalCache を設定する必要があります。次のコードに例を示します。

/**
 *  ローカルキャッシュを有効にします。この機能が有効な場合、動画はローカルファイルにキャッシュされます。
 *
 *  @param enable - ローカルキャッシュ機能のスイッチ。true: ローカルキャッシュを有効にします。false: ローカルキャッシュを無効にします。デフォルト値:false。
 *  @param maxBufferMemoryKB - このパラメーターは非推奨であり、v5.4.7.1 以降では効果がありません。
 *  @param localCacheDir - キャッシュファイルのディレクトリ。これは絶対パスである必要があります。
 *  @param mDocTypeForIOS - iOS のサンドボックスディレクトリタイプ。
 */
FlutterAliplayer.enableLocalCache(bool enable,String maxBufferMemoryKB,String localCacheDir,DocTypeForIOS mDocTypeForIOS);

/**
  * キャッシュファイルのクリアに関する構成。
  *
  * @param expireMin - このパラメーターは非推奨であり、v5.4.7.1 以降では効果がありません。
  * @param maxCapacityMB - 最大キャッシュサイズ (MB)。デフォルト値:20 GB。システムがキャッシュをクリアする際、キャッシュされたファイルの合計サイズがこの制限を超えた場合、システムはキャッシュ項目を最終アクセス時間でソートし、合計サイズが制限以下になるまで最も古いファイルから順に削除します。
  * @param freeStorageMB - 最小空きディスク領域 (MB)。デフォルト値:0。システムがキャッシュをクリアする際、現在の空きディスク領域がこの値より小さい場合、システムは空きディスク領域がこの値以上になるか、すべてのキャッシュファイルが削除されるまで、最も古いキャッシュファイルから順に削除します。
  */
FlutterAliplayer.setCacheFileClearConfig(String expireMin,String maxCapacityMB,String freeStorageMB);

単一 URL のローカルキャッシュの有効化または無効化

単一 URL のローカルキャッシュを有効または無効にするには、player config でこの設定を構成できます。次のコードに例を示します。

// 構成を取得します。
fAliplayer.getPlayConfig().then((config){
  // ローカルキャッシュを無効または有効にします。
  config.enableLocalCache = false;
  // 設定を適用します。
  fAliplayer.setPlayConfig(config);
});

プリロード

ApsaraVideo Player SDK for Flutter は、ローカルキャッシュ機能を強化したプリロード機能を提供します。メモリ内の動画キャッシュサイズを指定できるようにすることで、動画の起動速度を向上させます。

プリロード機能には次の制限事項があります。

  • MP4、MP3、FLV、HLS などの単一メディアファイルの読み込みをサポートします。

  • UrlSource から再生される動画のプリロードをサポートします。VidAuth または VidSts から再生される動画のプリロードはサポートされていません。

  1. ローカルキャッシュ機能を有効にします。詳細については、「ローカルキャッシュ」をご参照ください。

  2. FlutterAliMediaLoaderV2 インスタンスを作成します。

    FlutterAliMediaLoaderV2 loaderV2 = FlutterAliMediaLoaderV2();
  3. プリロードタスクのリスナーを設定します。

    1. onError:エラーのリスナー。

      loaderV2.onError = (ErrorInfo error) {
      };
    2. onCompleted:タスク完了のリスナー。

      loaderV2.onCompleted = (taskId, urlOrVid) {
      };
    3. onCanceled:タスクキャンセルのリスナー。

      loaderV2.onCanceled = (taskId, urlOrVid) {
      };
  4. プリロードタスクのパラメーターを設定します。このステップはオプションであり、マルチビットレート動画にのみ適用されます。

    次のパラメーターのいずれかを設定できます:defaultQualitydefaultBandWidth、または defaultResolution

    PreloadConfig config = PreloadConfig();
    config.duration = 1000;  // デフォルト値:1000
    config.defaultQuality = "FD";
    config.defaultBandWidth = 200000;
    config.defaultResolution  = 1920 * 1080;
    loaderV2.setPreloadConfig(config);
  5. プリロードタスクを追加し、タスク ID を取得します。

    VidAuth (推奨)

    VidAuth auth = VidAuth(
       vid: "your videoId",
       playAuth: "your playAuth",
       region: "your region",
    );
    loaderV2.addTask(auth).then((taskId) {
        print("MediaLoaderV2: taskId: $taskId");
    });

    VidSts

    VidSts vidSts = VidSts(
        vid: "your vid",
        accessKeyId: "your accessKeyId",
        accessKeySecret: "your accessKeySecret",
        securityToken: "your securityToken",
    );
    loaderV2.addTask(vidSts).then((taskId) {
       print("MediaLoaderV2: taskId: $taskId");
    });

    UrlSource

    loaderV2.addTask(UrlSource(videoUrl: "videoUrl")).then((taskId) {
       print("MediaLoaderV2: taskId: $taskId");
    });
  6. プリロードタスクを一時停止します。

    loaderV2.pauseTask(taskId);
  7. プリロードタスクを再開します。

    loaderV2.resumeTask(taskId);
  8. プリロードタスクをキャンセルします。

    loaderV2.cancelTask(taskId);
  9. FlutterAliMediaLoaderV2 インスタンスを破棄します。

    loaderV2.dispose();

動画ダウンロード

ApsaraVideo Player SDK for Flutter では、オンデマンド動画をローカルデバイスにダウンロードしてオフライン再生できます。通常ダウンロードモードとセキュアダウンロードモードの両方をサポートします。

  • 通常のダウンロード

    このモードでダウンロードされた動画は Alibaba Cloud によって暗号化されず、サードパーティのプレーヤーで再生できます。

  • 安全なダウンロード

    このモードでダウンロードされた動画は Alibaba Cloud によって暗号化されます。ApsaraVideo Player SDK を使用してのみ再生できます。

注意事項

  • VidSts または VidAuth を使用して再生される動画のみをダウンロードできます。

  • 動画ダウンロード機能を使用するには、ApsaraVideo VOD コンソールでこの機能を有効にし、ダウンロードモードを設定する必要があります。詳細については、「オフラインダウンロード」をご参照ください。

  • 再開可能なダウンロードがサポートされています。

手順

  1. オプション: セキュアダウンロード用の暗号化および検証ファイルを設定します。このステップはセキュアダウンロードにのみ必要であり、通常ダウンロードの場合はスキップできます。

    説明

    設定された暗号化および検証ファイルがアプリ情報と一致していることを確認してください。一致しない場合、動画のダウンロードは失敗します。

    セキュアダウンロードモードを使用する場合、ApsaraVideo VOD コンソールで生成されたキーファイルを ApsaraVideo Player SDK に設定する必要があります。このキーファイルは、ダウンロードおよび再生中の動画の復号化と検証に使用されます。キーファイルの生成方法の詳細については、「セキュアダウンロード」をご参照ください。

    キーファイルの設定は一度だけ必要です。次のコードに例を示します。

    FlutterAliPlayerFactory.initService(byteData);
  2. ダウンローダーの作成と設定

    次のコードに例を示します。

    FlutterAliDownloader downloader = FlutterAliDownloader.init();
    /// 保存パスを設定します。
    downloader.setSaveDir(path)
  3. ダウンロードを開始します。

    ダウンロードを開始すると、リスナーが自動的に設定され、コールバック情報が返されます。次のコードに例を示します。

    /// 1. prepare
     /// パラメーターの説明:type パラメーターは FlutterAvpdef.DOWNLOADTYPE_STS または FlutterAvpdef.DOWNLOADTYPE_AUTH に設定できます。type を DOWNLOADTYPE_STS に設定した場合、vid、accessKeyId、accessKeySecret、および securityToken パラメーターが必要です。type を DOWNLOADTYPE_AUTH に設定した場合、vid および playAuth パラメーターが必要です。
     downloader.prepare(type, vid).then((value) {
     // value は、デモのカスタムダウンロードクラス DownloadModel に対応するマップです。
     DownloadModel downloadModel = DownloadModel.fromJson(value);
     // 2. selectItem。trackInfo に基づいてダウンロードする動画の解像度を選択します。
     List<TrackInfoModel> trackInfos = downloadModel.trackInfos;
     downloader.selectItem(vid,trackInfos[0].index);
     // 3. start
     downloader.start(vid, trackInfos[0].index).listen((event) {
     // 注意:event にはさまざまな種類の情報が含まれる場合があります。詳細については、FlutterAvpdef.EventChanneldef をご参照ください。次のコードに詳細を示します。
     if (event[EventChanneldef.TYPE_KEY] == EventChanneldef.DOWNLOAD_PROGRESS){
     // ダウンロードの進捗率 (%)。ダウンロードの進捗を取得します:event[EventChanneldef.DOWNLOAD_PROGRESS]。
     }else if(event[EventChanneldef.TYPE_KEY] == EventChanneldef.DOWNLOAD_PROCESS){
     // 処理の進捗率 (%)。処理の進捗を取得します:event[EventChanneldef.DOWNLOAD_PROCESS]。
     }else if(event[EventChanneldef.TYPE_KEY] == EventChanneldef.DOWNLOAD_COMPLETION){
     // ダウンロードが完了しました。event['vid'] と event['index'] を使用して、対応する vid と index を取得し、ダウンロードされた動画を識別できます。event['savePath'] を使用して、ダウンロードされた動画のローカルパスを取得します。
     }else if(event[EventChanneldef.TYPE_KEY] == EventChanneldef.DOWNLOAD_ERROR){
     // ダウンロードに失敗しました。event['vid'] と event['index'] を使用して、対応する vid と index を取得し、ダウンロードに失敗した動画を識別できます。event['errorCode'] と event['errorMsg'] を使用して、エラーコードとエラーメッセージを取得できます。
     }
     });
     });
  4. ダウンロードを停止します。

    次のコードに例を示します。

    downloader.stop(vid, index)
  5. ダウンロードの削除

    これにより、ダウンロードタスクが削除されます。タスクが正常に削除されると、対応するローカルファイルも削除されます。次のコードに例を示します。

    downloader.delete(vid, index)
  6. ダウンロードオブジェクトの解放

    ダウンロードオブジェクトが不要になった場合は、release メソッドを呼び出して解放し、メモリリークを防ぎます。次のコードに例を示します。

    downloader.release(vid, index)

暗号化された動画の再生

ApsaraVideo VOD は、HLS 暗号化、Alibaba Cloud 専用の暗号化、および DRM 暗号化をサポートしています。暗号化された動画の再生に関する詳細については、「暗号化された動画の再生」をご参照ください。