ApsaraVideo VOD:Fitur dasar SDK ApsaraVideo Player untuk iOS

Persiapan pemutaran

Panggil metode prepare untuk mempersiapkan video sebelum diputar.

[self.player prepare];

Callback onPlayerEvent dengan AVPEventPrepareDone dipanggil saat persiapan selesai.

Mulai pemutaran

Panggil metode start untuk memulai pemutaran video:

[self.player start];

Jeda pemutaran

Panggil metode pause untuk menjeda video:

[self.player pause];

Lanjutkan pemutaran

Panggil metode start untuk melanjutkan pemutaran setelah dijeda:

[self.player start];

Cari ke posisi tertentu

Panggil seekToTime untuk melompat ke posisi tertentu. Metode ini berguna saat pengguna menyeret bilah progres atau melanjutkan pemutaran dari posisi yang disimpan.

// Cari ke posisi tertentu (dalam milidetik)
// Pencarian akurat
[self.player seekToTime:position seekMode:AVP_SEEKMODE_ACCURATE];
// Pencarian tidak akurat
[self.player seekToTime:position seekMode:AVP_SEEKMODE_INACCURATE];

Mode pencarian:

• Pencarian akurat (AVP_SEEKMODE_ACCURATE): Mencari ke posisi tepat. Lebih lambat tetapi lebih presisi.

• Pencarian tidak akurat (AVP_SEEKMODE_INACCURATE): Mencari ke keyframe terdekat. Lebih cepat tetapi kurang presisi.

Mulai pemutaran dari posisi tertentu

Untuk memulai pemutaran dari posisi tertentu (bukan mencari selama pemutaran), panggil setStartTime sebelum memanggil prepare:

// Atur waktu mulai untuk pemanggilan prepare berikutnya (dalam milidetik).
// Pengaturan ini hanya berlaku untuk pemanggilan prepare berikutnya. Waktu mulai akan otomatis dihapus setelah prepare dipanggil.
// seekMode: pencarian akurat (AVP_SEEKMODE_ACCURATE) atau pencarian tidak akurat (AVP_SEEKMODE_INACCURATE).
[self.player setStartTime:time seekMode:seekMode];

Hentikan pemutaran

Panggil metode stop untuk menghentikan pemutaran:

[self.player stop];

Lepaskan tampilan pemutar

Setelah menghentikan pemutaran dan sebelum menghapus instans pemutar, lepaskan tampilan pemutar untuk melepas sumber daya rendering dan mencegah kebocoran memori.

// Lepaskan tampilan pemutar
self.player.playerView = nil;

Hancurkan pemutar

Anda dapat menghapus pemutar secara sinkron atau asinkron untuk melepas sumber daya.

// Hapus secara sinkron. Memblokir hingga sumber daya pemutar dilepas. Secara otomatis memanggil stop.
[self.player destroy];
// Hapus secara asinkron. Mengembalikan hasil segera. Secara otomatis memanggil stop.
[self.player destroyAsync];

Rekomendasi:

• Gunakan destroyAsync jika Anda memerlukan respons UI yang cepat.

• Jangan melakukan operasi apa pun pada objek pemutar selama proses penghapusan asinkron.

• Anda tidak perlu memanggil stop sebelum destroyAsync karena proses penghapusan sudah mencakup operasi stop asinkron.

Atur delegate pemutar

Implementasikan protokol AVPDelegate di view controller Anda untuk menerima callback pemutar.

Penting: Implementasikan callback onError dan onPlayerEvent untuk menangani error dan memantau perubahan status pemutaran.

@interface SimplePlayerViewController ()<AVPDelegate>
@end
- (void)viewDidLoad {
    self.player = [[AliPlayer alloc] init];
    self.player.playerView = self.avpPlayerView.playerView;
    self.player.delegate = self;
    //...
}
/**
 @brief Callback delegate untuk error pemutar.
 @param player Instans pemutar.
 @param errorModel Berisi detail error.
 */
- (void)onError:(AliPlayer*)player errorModel:(AVPErrorModel *)errorModel {
    // Tangani error (misalnya, tampilkan peringatan) dan hentikan pemutaran.
}
/**
 @brief Callback delegate untuk event pemutar.
 @param player Instans pemutar.
 @param eventType Jenis event. Lihat AVPEventType.
 */
-(void)onPlayerEvent:(AliPlayer*)player eventType:(AVPEventType)eventType{
    switch(eventType){
        case AVPEventPrepareDone:{
            // Dipicu saat media telah dipersiapkan dan siap diputar.
        }
            break;
        case AVPEventAutoPlayStart:
            // Dipicu saat putar otomatis dimulai.
            break;
        case AVPEventFirstRenderedStart:
            // Dipicu saat frame pertama dirender.
            break;
        case AVPEventCompletion:
            // Dipicu saat pemutaran selesai.
            break;
        case AVPEventLoadingStart:
            // Dipicu saat buffering dimulai.
            break;
        case AVPEventLoadingEnd:
            // Dipicu saat buffering selesai.
            break;
        case AVPEventSeekEnd:
            // Dipicu saat operasi pencarian selesai.
            break;
        case AVPEventLoopingStart:
            // Dipicu saat loop baru dimulai.
            break;
        default:
            break;
    }
}
/**
 @brief Callback untuk posisi pemutaran saat ini.
 @param player Instans pemutar.
 @param position Posisi pemutaran saat ini dalam milidetik.
 */
- (void)onCurrentPositionUpdate:(AliPlayer*)player position:(int64_t)position {
    // Perbarui bilah progres.
}
/**
 @brief Callback untuk posisi buffering saat ini.
 @param player Instans pemutar.
 @param position Posisi buffering saat ini dalam milidetik.
 */
- (void)onBufferedPositionUpdate:(AliPlayer*)player position:(int64_t)position {
    // Perbarui indikator progres buffer.
}
/**
 @brief Callback saat informasi track siap.
 @param player Instans pemutar.
 @param info Array objek AVPTrackInfo untuk stream yang tersedia.
 */
- (void)onTrackReady:(AliPlayer*)player info:(NSArray<AVPTrackInfo*>*)info {
    // Ambil informasi untuk bitrate/track yang tersedia.
}
/**
 @brief Callback saat subtitle harus ditampilkan.
 @param player Instans pemutar.
 @param index Indeks entri subtitle.
 @param subtitle Teks subtitle yang akan ditampilkan.
 */
- (void)onSubtitleShow:(AliPlayer*)player index:(int)index subtitle:(NSString *)subtitle {
    // Dapatkan dan tampilkan teks subtitle.
}
/**
 @brief Callback saat subtitle harus disembunyikan.
 @param player Instans pemutar.
 @param index Indeks entri subtitle yang ditampilkan.
 */
- (void)onSubtitleHide:(AliPlayer*)player index:(int)index {
    // Sembunyikan subtitle.
}
/**
 @brief Callback untuk permintaan tangkapan layar.
 @param player Instans pemutar.
 @param image Tangkapan layar sebagai UIImage.
 */
- (void)onCaptureScreen:(AliPlayer *)player image:(UIImage *)image {
    // Pratinjau atau simpan gambar yang ditangkap.
}
/**
 @brief Callback saat perubahan track selesai.
 @param player Instans pemutar.
 @param info Objek AVPTrackInfo untuk track aktif yang baru.
 */
- (void)onTrackChanged:(AliPlayer*)player info:(AVPTrackInfo*)info {
    // Notifikasi bahwa bitrate/track telah berubah.
}

Dengarkan perubahan status pemutar

Callback onPlayerStatusChanged dipanggil saat status pemutar berubah:

- (void)onPlayerStatusChanged:(AliPlayer*)player oldStatus:(AVPStatus)oldStatus newStatus:(AVPStatus)newStatus {
    switch (newStatus) {
    case AVPStatusIdle:{
           // Pemutar dalam keadaan idle
        }
 break;
        case AVPStatusInitialzed:{
           // Pemutar telah diinisialisasi
        }
 break;
        case AVPStatusPrepared:{
           // Pemutar telah dipersiapkan
        }
 break;
        case AVPStatusStarted:{
           // Pemutaran dimulai
        }
 break;
case AVPStatusPaused:{
           // Pemutaran dijeda
        }
 break;
case AVPStatusStopped:{
           // Pemutaran dihentikan
        }
 break;
case AVPStatusCompletion:{
           // Pemutaran selesai
        }
 break;
case AVPStatusError:{
           // Terjadi error pada pemutar
        }
 break;
        default:
            break;
    }
}

Mode penskalaan

SDK mendukung tiga mode penskalaan:

// Skala agar sesuai dengan tampilan sambil mempertahankan rasio aspek (letterboxing).
self.player.scalingMode = AVP_SCALINGMODE_SCALEASPECTFIT;
// Skala agar mengisi tampilan sambil mempertahankan rasio aspek (cropping).
self.player.scalingMode = AVP_SCALINGMODE_SCALEASPECTFILL;
// Regangkan agar mengisi tampilan. Rasio aspek tidak dipertahankan. Distorsi gambar mungkin terjadi.
self.player.scalingMode = AVP_SCALINGMODE_SCALETOFILL;

Rotasi

Putar video searah jarum jam dengan sudut tertentu:

// Tanpa rotasi
self.player.rotateMode = AVP_ROTATE_0;
// Putar 90 derajat searah jarum jam
self.player.rotateMode = AVP_ROTATE_90;
// Putar 180 derajat searah jarum jam
self.player.rotateMode = AVP_ROTATE_180;
// Putar 270 derajat searah jarum jam
self.player.rotateMode = AVP_ROTATE_270;

Pencerminan

Panggil setMirrorMode untuk mencerminkan video. SDK mendukung pencerminan horizontal dan vertikal:

// Tanpa pencerminan
self.player.mirrorMode = AVP_MIRRORMODE_NONE;
// Pencerminan horizontal
self.player.mirrorMode = AVP_MIRRORMODE_HORIZONTAL;
// Pencerminan vertikal
self.player.mirrorMode = AVP_MIRRORMODE_VERTICAL;

Progres pemutaran

Posisi pemutaran saat ini dikembalikan dalam callback onCurrentPositionUpdate:

- (void)onCurrentPositionUpdate:(AliPlayer*)player position:(int64_t)position {
// position dalam milidetik
NSString *position = [NSString stringWithFormat:@"%lld", position];
}

Durasi total

Ambil durasi total video setelah dimuat (misalnya, setelah event AVPEventPrepareDone):

-(void)onPlayerEvent:(AliPlayer*)player eventType:(AVPEventType)eventType {
  switch (eventType) {
    case AVPEventPrepareDone: {
      if (self.player.duration >= 0) {
       NSString *duration  = self.player.duration;
      }
    }
      break;
    default:
      break;
  }
}

Durasi pemutaran aktual

Ambil durasi pemutaran aktual secara real time. Nilai ini mengecualikan waktu saat pemutaran dijeda atau buffering.

 NSString *duration = [player getPlayedDuration];

Progres buffering

Progres buffering saat ini dikembalikan dalam callback onBufferedPositionUpdate:

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

Metrik rendering dan bitrate real time

Peroleh laju frame rendering, bitrate audio dan video, serta bitrate downstream jaringan secara real time.

// Laju frame rendering video. Mengembalikan nilai float.
[self.player getOption:AVP_OPTION_RENDER_FPS]
// Bitrate video. Mengembalikan nilai float dalam bit/s.
[self.player getOption:AVP_OPTION_VIDEO_BITRATE]
// Bitrate audio. Mengembalikan nilai float dalam bit/s.
[self.player getOption:AVP_OPTION_AUDIO_BITRATE]
// Bitrate downstream jaringan. Mengembalikan nilai float dalam bit/s.
[self.player getOption:AVP_OPTION_DOWNLOAD_BITRATE]

Sesuaikan volume

Panggil volume untuk mengubah volume. Nilai yang valid: 0 hingga 2, dengan 1 sebagai volume asli. Nilai lebih dari 1 akan memperkuat audio dan mungkin menimbulkan kebisingan. Kami menyarankan agar volume dijaga pada atau di bawah 1.

// Atur volume. Nilai yang valid: 0 hingga 2.
self.player.volume = 1.0f;
// Dapatkan volume saat ini.
self.player.volume

Bisukan video

Bisukan atau nyalakan kembali audio:

self.player.muted = YES;

Pemutaran berbasis VidAuth atau VidSts

Jika Anda menggunakan VidAuth atau VidSts untuk pemutaran VOD, SDK secara otomatis mengambil definisi video dari ApsaraVideo VOD. Tidak diperlukan konfigurasi tambahan.

- (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 {
 // Definisi dialihkan.
}

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

Streaming langsung berbasis UrlSource

Untuk detailnya, lihat Pemutaran streaming langsung standar.

Jenis stream yang didukung

Jenis stream berikut mendukung pengalihan track audio. Perilaku pengalihan bervariasi berdasarkan jenis stream.

Dapatkan track audio yang tersedia

Callback onSubTrackReady dipanggil saat informasi track audio tersedia:

  // onSubTrackReady. Biasanya dipicu sebelum event AVPEventPrepareDone.
- (void)onSubTrackReady:(AliPlayer*)player info:(NSArray<AVPTrackInfo*>*)info {
    // Panggil getSubMediaInfo setelah callback ini dipicu. Memanggilnya sebelum callback ini akan mengembalikan hasil kosong.
    AVPMediaInfo* subMediaInfo = [player getSubMediaInfo];
    // Iterasi melalui track audio yang tersedia
    for (int i=0; i<subMediaInfo.tracks.count; i++) {
    	AVPTrackInfo* track = [subMediaInfo.tracks objectAtIndex:i];
        // Temukan track audio target dari daftar track.
    }
}

Alihkan track audio

Panggil metode selectTrack untuk beralih ke track audio yang berbeda:

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

Metode 1: Lihat log di konsol alat pengembangan

Metode ini cocok untuk skenario di mana Anda dapat mereproduksi masalah secara lokal.

1. Aktifkan logging dan atur tingkat log:

   // Aktifkan logging SDK
   [AliPlayer setEnableLog:YES];
   // Atur tingkat log (default: LOG_LEVEL_INFO). Gunakan LOG_LEVEL_TRACE untuk troubleshooting detail.
   [AliPlayer setLogCallbackInfo:LOG_LEVEL_INFO callbackBlock:nil];

2. Aktifkan logging tingkat frame (opsional):

   // Aktifkan logging tingkat frame untuk troubleshooting detail
   // 0 = dinonaktifkan, 1 = diaktifkan
   [AliPlayer setLogOption:FRAME_LEVEL_LOGGING_ENABLED value:value];

   Catatan

   Logging tingkat frame menghasilkan volume log yang besar dan terutama digunakan untuk troubleshooting masalah pemutaran.

3. Kumpulkan log:

   Opsi A: Lihat log di konsol

   Setelah mereproduksi masalah, ambil log dari konsol alat pengembangan Anda, seperti XCode.

   Opsi B: Tulis log ke file

   Atur path lengkap untuk file log Anda dalam sandbox aplikasi.

   NSArray *paths =NSSearchPathForDirectoriesInDomains(NSDocumentDirectory,NSUserDomainMask, YES);
   NSString *documentDirectory = [paths objectAtIndex:0];
   // Tentukan path file log kustom Anda. Misalnya, buat file bernama 'xxxx.log'.
   NSString *logFilePath = [documentDirectory stringByAppendingPathComponent:@"xxxx.log"];

   Arahkan log ke file kustom dalam sandbox aplikasi:

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

   Setelah mereproduksi masalah, ambil file .log dari direktori kustom.

Metode 2: Atur LogCallback untuk menerima log secara terprogram

Gunakan metode ini saat Anda tidak dapat mereproduksi masalah secara andal di perangkat Anda. Callback ini mengekspor log ke saluran log aplikasi Anda.

1. Aktifkan logging dan atur tingkat log.

   // Aktifkan logging SDK
   [AliPlayer setEnableLog:YES];
   // Atur tingkat log. Nilai default: LOG_LEVEL_INFO. Untuk troubleshooting, atur ke LOG_LEVEL_TRACE.
   [AliPlayer setLogCallbackInfo:LOG_LEVEL_INFO callbackBlock:^(AVPLogLevel logLevel, NSString *strLog) {
    NSLog(@"strLog:%@", strLog);
   }];

2. Kumpulkan log:

   Setelah mereproduksi masalah, log akan secara otomatis diteruskan ke sistem logging aplikasi Anda.

Troubleshooting

Referensi

• Fitur lanjutan: Pelajari fitur lanjutan seperti Gambar-dalam-Gambar (PiP), pergeseran waktu, dan streaming bitrate adaptif.

• API: Jelajahi referensi API lengkap untuk SDK ApsaraVideo Player untuk iOS.

• Kode kesalahan seluler: Rujuk topik ini untuk troubleshooting.