ApsaraVideo VOD:iOS 向け ApsaraVideo Player SDK の基本的な機能

再生の準備

prepare メソッドを呼び出して、動画の再生準備を行います。

[self.player prepare];

準備が完了すると、AVPEventPrepareDone を伴う onPlayerEvent コールバックが呼び出されます。

再生の開始

start メソッドを呼び出して、動画の再生を開始します。

[self.player start];

再生の一時停止

pause メソッドを呼び出して、動画を一時停止します。

[self.player pause];

再生の再開

一時停止後に再生を再開するには、start メソッドを呼び出します。

[self.player start];

特定位置へのシーク

seekToTime を呼び出して、特定の位置にシークします。このメソッドは、ユーザーが進行バーをドラッグする場合や、保存した位置から再生を再開する場合に便利です。

// 特定の位置へシーク (ミリ秒)
// 正確なシーク
[self.player seekToTime:position seekMode:AVP_SEEKMODE_ACCURATE];
// 不正確なシーク
[self.player seekToTime:position seekMode:AVP_SEEKMODE_INACCURATE];

シークモード：

• 正確なシーク (AVP_SEEKMODE_ACCURATE)：正確な位置にシークします。処理は遅くなりますが、精度が高くなります。

• 不正確なシーク (AVP_SEEKMODE_INACCURATE)：最も近いキーフレームにシークします。処理は速くなりますが、精度は下がります。

特定位置からの再生開始

再生中にシークするのではなく、特定の位置から再生を開始するには、prepare を呼び出す前に setStartTime を呼び出します。

// 次回の prepare 呼び出しの開始時刻を設定します (ミリ秒)。
// この設定は、直後の prepare 呼び出しにのみ有効です。prepare が呼び出されると、開始時刻は自動的にクリアされます。
// seekMode：正確なシーク (AVP_SEEKMODE_ACCURATE) または不正確なシーク (AVP_SEEKMODE_INACCURATE)。
[self.player setStartTime:time seekMode:seekMode];

再生の停止

stop メソッドを呼び出して、再生を停止します。

[self.player stop];

プレーヤービューのバインド解除

再生を停止した後、プレーヤーインスタンスを破棄する前に、プレーヤービューをバインド解除してレンダリングリソースを解放し、メモリリークを防止します。

// プレーヤービューをバインド解除
self.player.playerView = nil;

プレーヤーの破棄

リソースを解放するために、プレーヤーを同期または非同期で破棄できます。

// 同期破棄。プレーヤーリソースが解放されるまでブロックします。stop が自動的に呼び出されます。
[self.player destroy];
// 非同期破棄。直ちに戻ります。stop が自動的に呼び出されます。
[self.player destroyAsync];

推奨事項：

• UI の応答を速くしたい場合は、destroyAsync を使用します。

• 非同期で破棄している間は、プレーヤーオブジェクトを操作しないでください。

• 破棄処理には非同期の停止処理が含まれるため、destroyAsync の前に stop を呼び出す必要はありません。

プレーヤーデリゲートの設定

ビューコントローラーで AVPDelegate プロトコルを実装して、プレーヤーのコールバックを受信します。

重要： onError および onPlayerEvent コールバックを実装して、エラーを処理し、プレーヤーの状態の変更を監視します。

@interface SimplePlayerViewController ()<AVPDelegate>
@end
- (void)viewDidLoad {
    self.player = [[AliPlayer alloc] init];
    self.player.playerView = self.avpPlayerView.playerView;
    self.player.delegate = self;
    //...
}
/**
 @brief プレーヤーエラー発生時のコールバックです。
 @param player プレーヤーインスタンス。
 @param errorModel エラー詳細です。
 */
- (void)onError:(AliPlayer*)player errorModel:(AVPErrorModel *)errorModel {
    // エラーを処理し (アラートの表示など)、再生を停止します。
}
/**
 @brief プレーヤーイベントのコールバックです。
 @param player プレーヤーインスタンス。
 @param eventType イベントのタイプです。詳細は AVPEventType を参照してください。
 */
-(void)onPlayerEvent:(AliPlayer*)player eventType:(AVPEventType)eventType{
    switch(eventType){
        case AVPEventPrepareDone:{
            // メディアの準備が完了し、再生可能になったときに呼び出されます。
        }
            break;
        case AVPEventAutoPlayStart:
            // 自動再生が開始したときに呼び出されます。
            break;
        case AVPEventFirstRenderedStart:
            // 最初のフレームがレンダリングされたときに呼び出されます。
            break;
        case AVPEventCompletion:
            // 再生が完了したときに呼び出されます。
            break;
        case AVPEventLoadingStart:
            // バッファリングが開始したときに呼び出されます。
            break;
        case AVPEventLoadingEnd:
            // バッファリングが終了したときに呼び出されます。
            break;
        case AVPEventSeekEnd:
            // シーク操作が完了したときに呼び出されます。
            break;
        case AVPEventLoopingStart:
            // 新しいループが開始したときに呼び出されます。
            break;
        default:
            break;
    }
}
/**
 @brief 現在の再生位置に関するコールバックです。
 @param player プレーヤーインスタンス。
 @param position 現在の再生位置 (ミリ秒単位)。
 */
- (void)onCurrentPositionUpdate:(AliPlayer*)player position:(int64_t)position {
    // プログレスバーを更新します。
}
/**
 @brief 現在のバッファリングされた位置に関するコールバックです。
 @param player プレーヤーインスタンス。
 @param position 現在のバッファリングされた位置 (ミリ秒単位)。
 */
- (void)onBufferedPositionUpdate:(AliPlayer*)player position:(int64_t)position {
    // バッファリングの進捗インジケーターを更新します。
}
/**
 @brief トラック情報が利用可能になった際のコールバックです。
 @param player プレーヤーインスタンス。
 @param info 利用可能なストリームに関する AVPTrackInfo オブジェクトの配列です。
 */
- (void)onTrackReady:(AliPlayer*)player info:(NSArray<AVPTrackInfo*>*)info {
    // 利用可能なビットレート/トラックの情報を取得します。
}
/**
 @brief 字幕を表示する際のコールバックです。
 @param player プレーヤーインスタンス。
 @param index 字幕エントリのインデックス。
 @param subtitle 表示する字幕テキスト。
 */
- (void)onSubtitleShow:(AliPlayer*)player index:(int)index subtitle:(NSString *)subtitle {
    // 字幕テキストを取得して表示します。
}
/**
 @brief 字幕を非表示にする際のコールバックです。
 @param player プレーヤーインスタンス。
 @param index 表示されていた字幕エントリのインデックス。
 */
- (void)onSubtitleHide:(AliPlayer*)player index:(int)index {
    // 字幕を非表示にします。
}
/**
 @brief 画面キャプチャのコールバックです。
 @param player プレーヤーインスタンス。
 @param image キャプチャされたスクリーンショット (UIImage)。
 */
- (void)onCaptureScreen:(AliPlayer *)player image:(UIImage *)image {
    // キャプチャした画像をプレビューまたは保存します。
}
/**
 @brief トラックの変更が完了した際のコールバックです。
 @param player プレーヤーインスタンス。
 @param info 新しくアクティブになったトラックの AVPTrackInfo オブジェクトです。
 */
- (void)onTrackChanged:(AliPlayer*)player info:(AVPTrackInfo*)info {
    // ビットレート/トラックが変更されたことの通知。
}

プレーヤーステータスの変更の監視

onPlayerStatusChanged コールバックは、プレーヤーステータスが変更されたときに呼び出されます。

- (void)onPlayerStatusChanged:(AliPlayer*)player oldStatus:(AVPStatus)oldStatus newStatus:(AVPStatus)newStatus {
    switch (newStatus) {
    case AVPStatusIdle:{
           // プレーヤーはアイドル状態です。
        }
 break;
        case AVPStatusInitialzed:{
           // プレーヤーは初期化済みです。
        }
 break;
        case AVPStatusPrepared:{
           // プレーヤーは準備完了です。
        }
 break;
        case AVPStatusStarted:{
           // 再生が開始されました。
        }
 break;
case AVPStatusPaused:{
           // 再生が一時停止されました。
        }
 break;
case AVPStatusStopped:{
           // 再生が停止されました。
        }
 break;
case AVPStatusCompletion:{
           // 再生が完了しました。
        }
 break;
case AVPStatusError:{
           // プレーヤーでエラーが発生しました。
        }
 break;
        default:
            break;
    }
}

スケーリングモード

SDK は 3 つのスケーリングモードをサポートしています：

// アスペクト比を維持したままビューに合わせてスケーリングします (レターボックス)。
self.player.scalingMode = AVP_SCALINGMODE_SCALEASPECTFIT;
// アスペクト比を維持したままビューを埋めるようにスケーリングします (クロッピング)。
self.player.scalingMode = AVP_SCALINGMODE_SCALEASPECTFILL;
// ビューを埋めるように引き伸ばします。アスペクト比は維持されません。画像が歪むことがあります。
self.player.scalingMode = AVP_SCALINGMODE_SCALETOFILL;

回転

指定した角度でビデオを時計回りに回転させます：

// 回転なし
self.player.rotateMode = AVP_ROTATE_0;
// 時計回りに 90 度回転
self.player.rotateMode = AVP_ROTATE_90;
// 時計回りに 180 度回転
self.player.rotateMode = AVP_ROTATE_180;
// 時計回りに 270 度回転
self.player.rotateMode = AVP_ROTATE_270;

ミラーリング

ビデオをミラーリングするには、mirrorMode プロパティを設定します。SDK は、水平ミラーリングと垂直ミラーリングをサポートしています：

// ミラーリングなし
self.player.mirrorMode = AVP_MIRRORMODE_NONE;
// 水平ミラーリング
self.player.mirrorMode = AVP_MIRRORMODE_HORIZONTAL;
// 垂直ミラーリング
self.player.mirrorMode = AVP_MIRRORMODE_VERTICAL;

再生進捗

現在の再生位置は、 onCurrentPositionUpdate コールバックで返されます。

- (void)onCurrentPositionUpdate:(AliPlayer*)player position:(int64_t)position {
    // position はミリ秒単位です
    NSString *positionString = [NSString stringWithFormat:@"%lld", position];
}

総再生時間

ビデオのロード後 (例： AVPEventPrepareDone イベント後) に、ビデオの総再生時間を取得します。

-(void)onPlayerEvent:(AliPlayer*)player eventType:(AVPEventType)eventType {
  switch (eventType) {
    case AVPEventPrepareDone: {
      if (self.player.duration >= 0) {
       NSString *durationString = [NSString stringWithFormat:@"%lld", self.player.duration];
      }
    }
      break;
    default:
      break;
  }
}

実際の再生時間

実際の再生時間をリアルタイムで取得します。この値には、一時停止中またはバッファリング中の時間は含まれません。

int64_t duration = [player getPlayedDuration];

バッファリング進捗

現在のバッファリング進捗は、 onBufferedPositionUpdate コールバックで返されます。

- (void)onBufferedPositionUpdate:(AliPlayer*)player position:(int64_t)position {
    NSString *bufferPosition = [NSString stringWithFormat:@"%lld", position];
}

リアルタイムレンダリングおよびビットレートメトリクス

レンダリングフレームレート、オーディオビットレート、ビデオビットレート、およびネットワークダウンストリームビットレートをリアルタイムで取得します。

// ビデオレンダリングフレームレート。フロート値を返します。
[self.player getOption:AVP_OPTION_RENDER_FPS]
// ビデオビットレート。bit/s 単位のフロート値を返します。
[self.player getOption:AVP_OPTION_VIDEO_BITRATE]
// オーディオビットレート。bit/s 単位のフロート値を返します。
[self.player getOption:AVP_OPTION_AUDIO_BITRATE]
// ネットワークダウンストリームビットレート。bit/s 単位のフロート値を返します。
[self.player getOption:AVP_OPTION_DOWNLOAD_BITRATE]

音量の調整

volume を呼び出して、音量を変更します。有効な値は 0 から 2 です。このとき、 1 は元の音量を表します。1 より大きい値はオーディオを増幅し、ノイズが発生する可能性があります。音量は 1 以下に保つことを推奨します。

// 音量を設定します。有効な値： 0 から 2。
self.player.volume = 1.0f;
// 現在の音量を取得します。
self.player.volume

オーディオのミュート

オーディオをミュートまたはミュート解除します。

self.player.muted = YES;

VidAuth または VidSts ベースの再生

VOD 再生に VidAuth または VidSts を使用する場合、SDK は ApsaraVideo VOD からビデオの解像度情報を自動的に取得します。追加の設定は不要です。

- (void)onTrackReady:(AliPlayer*)player info:(NSArray<AVPTrackInfo*>*)info {
    for (int i=0; i<info.count; i++) {
        AVPTrackInfo* track = [info objectAtIndex:i];
        switch (track.trackType) {
            case AVPTRACK_TYPE_VIDEO: {
                int trackBitrate = track.trackBitrate;
            }
                break;
        }
    }
}

[self.player selectTrack:index];

- (void)onTrackChanged:(AliPlayer*)player info:(AVPTrackInfo*)info {
 // 解像度が切り替わりました。
}

AVPConfig *config = [self.player getConfig];
config.selectTrackBufferMode = 1;
[self.player setConfig:config];

UrlSource ベースのライブストリーミング

詳細については、「標準ライブストリーム再生」をご参照ください。

サポートされるストリームタイプ

次のストリームタイプは、オーディオトラックの切り替えに対応しています。切り替えの動作は、ストリームタイプによって異なります。

利用可能なオーディオトラックの取得

オーディオトラック情報が利用可能になると、onSubTrackReady コールバックが呼び出されます：

  // onSubTrackReady。 通常は AVPEventPrepareDone イベントの前にトリガーされます。
- (void)onSubTrackReady:(AliPlayer*)player info:(NSArray<AVPTrackInfo*>*)info {
    // このコールバックがトリガーされた後に getSubMediaInfo を呼び出します。このコールバックより前に呼び出すと、結果は空になります。
    AVPMediaInfo* subMediaInfo = [player getSubMediaInfo];
    // 利用可能なオーディオトラックを反復処理します
    for (int i=0; i<subMediaInfo.tracks.count; i++) {
    	AVPTrackInfo* track = [subMediaInfo.tracks objectAtIndex:i];
        // トラックリストから対象のオーディオトラックを見つけます。
    }
}

オーディオトラックの切り替え

別のオーディオトラックに切り替えるには、selectTrack メソッドを呼び出します：

[self.player selectTrack:myTrack.trackIndex accurate:YES]

方法 1：開発ツールコンソールでのログ表示

この方法は、ローカルで問題を再現できる場合に適しています。

1. ログ記録の有効化とログレベルの設定：

   // SDK ログを有効化します
   [AliPlayer setEnableLog:YES];
   // ログレベルを設定します。デフォルト値は LOG_LEVEL_INFO です。詳細なトラブルシューティングには LOG_LEVEL_TRACE を使用します。
   [AliPlayer setLogCallbackInfo:LOG_LEVEL_TRACE callbackBlock:nil];

2. フレームレベルのログ記録の有効化 (オプション)：

   // 詳細なトラブルシューティングのためにフレームレベルのログ記録を有効化します
   // 0: 無効、1: 有効
   [AliPlayer setLogOption:FRAME_LEVEL_LOGGING_ENABLED value:value];

   説明

   フレームレベルのログ記録は大量のログを生成し、主に再生に関する問題のトラブルシューティングに使用されます。

3. ログの収集：

   オプション A：コンソールでログを表示

   問題を再現した後、XCode などの開発ツールのコンソールからログを取得します。

   オプション B：ログをファイルに書き込む

   アプリケーションのサンドボックス内にログファイルのフルパスを設定します。

   NSArray *paths =NSSearchPathForDirectoriesInDomains(NSDocumentDirectory,NSUserDomainMask, YES);
   NSString *documentDirectory = [paths objectAtIndex:0];
   // カスタムログファイルのパスを定義します。例： `xxxx.log` という名前のファイルを作成します。
   NSString *logFilePath = [documentDirectory stringByAppendingPathComponent:@"xxxx.log"];

   アプリのサンドボックス内のカスタムファイルにログをリダイレクトします：

   freopen([logFilePath cStringUsingEncoding:NSASCIIStringEncoding],"a+", stdout);
   freopen([logFilePath cStringUsingEncoding:NSASCIIStringEncoding],"a+", stderr);

   問題を再現した後、カスタムディレクトリから .log ファイルを取得します。

方法 2：LogCallback によるログ受信

この方法は、デバイスで問題を確実に再現できない場合に使用します。コールバックは、アプリケーションのログチャネルにログをエクスポートします。

1. ログ記録を有効化し、ログレベルを設定します。

   // SDK ログを有効化します
   [AliPlayer setEnableLog:YES];
   // ログレベルを設定します。デフォルト値は LOG_LEVEL_INFO です。トラブルシューティングでは、LOG_LEVEL_TRACE に設定します。
   [AliPlayer setLogCallbackInfo:LOG_LEVEL_TRACE callbackBlock:^(AVPLogLevel logLevel, NSString *strLog) {
    NSLog(@"strLog:%@", strLog);
   }];

2. ログの収集：

   問題を再現した後、ログはアプリのロギングシステムに自動的に転送されます。

トラブルシューティング

参考資料

• 高度な機能：ピクチャーインピクチャー (PiP) 、タイムシフト、アダプティブビットレートストリーミングなどの高度な機能について説明します。

• API リファレンス： ApsaraVideo Player SDK for iOS の完全な API リファレンスです。

• モバイルエラーコード：トラブルシューティングは、このトピックを参照してください。