全部产品
Search
文档中心

ApsaraVideo VOD:Referensi API Aliplayer

更新时间:Jan 17, 2026

Topik ini menjelaskan properti, metode, dan event yang didukung oleh Aliplayer.

Catatan

Jika Anda mengalami masalah, lihat FAQ pemutar web atau Pemecahan masalah pengecualian pemutaran.

Properti

Saat melakukan inisialisasi Aliplayer, Anda dapat mengatur berbagai properti, termasuk pengaturan lisensi, sumber daya pemutaran, gaya pemutar, serta perilaku pemutaran.

Name

Type

Description

id

String

ID elemen DOM dari kontainer luar pemutar.

source

String

Saat menggunakan pemutaran berbasis URL, gunakan properti source untuk menentukan URL pemutaran video.

Catatan
  • Pemutaran berbasis URL memiliki prioritas tertinggi dibandingkan metode lain seperti VidAuth dan VidSts. Artinya, saat Anda menggunakan metode seperti VidAuth atau VidSts, jangan tentukan properti source. Jika Anda menentukan properti source, pemutar akan memprioritaskan URL dalam properti source untuk pemutaran. Kami menyarankan agar Anda hanya mengatur satu metode pemutaran.

  • Metode pemutaran berbasis URL mendukung multi-definisi. Gunakan properti source untuk menentukan URL aliran video dengan berbagai definisi. Untuk informasi selengkapnya, lihat Pemutaran multi-definisi. Contoh kode berikut:

    source: '{"HD":"address1","SD":"address2"}'

vid

String

ID media di ApsaraVideo Media Processing.

playauth

String

Kredensial pemutaran. Untuk mendapatkan kredensial pemutaran, lihat Mendapatkan kredensial pemutaran audio dan video.

customVodServer

String

Nama domain proxy VOD kustom. Properti ini berlaku untuk metode pemutaran VidAuth pada versi 2.32.0 dan yang lebih baru. Anda harus menerapkan layanan proxy permintaan khusus. Jika nama domain VOD default (`*.aliyuncs.com`) tidak dapat diakses, pemutar secara otomatis beralih ke layanan proxy Anda. Hal ini secara efektif dapat mengurangi risiko pembajakan ISP dan secara signifikan meningkatkan stabilitas serta tingkat keberhasilan pemutaran.

playConfig

JSON

Bidang pengaturan kustom untuk pemutaran berbasis Vid (VidAuth dan VidSts). Pengaturan ini diteruskan ke API VOD. Untuk informasi tentang bidang kustom yang didukung beserta deskripsinya, lihat Pengaturan pemutaran media kustom (PlayConfig). Contoh nilai berikut:

{"PlayDomain":"vod.test_domain","PreviewTime":"20","MtsHlsUriToken":"yqCD7******oVjslp5Q"}

authTimeout

Number

Periode validitas URL pemutaran video yang diperoleh melalui pemutaran berbasis Vid (VidAuth dan VidSts). Satuan: detik. Nilai default: 7200.

Pastikan periode ini lebih panjang daripada durasi video aktual untuk mencegah URL pemutaran kedaluwarsa sebelum pemutaran selesai.

height

String

Tinggi pemutar. Nilai yang valid:

  • 100%

  • 100px

width

String

Lebar pemutar. Nilai yang valid:

  • 100%

  • 100px

autoSize

Boolean | String

Ukuran pemutar secara otomatis menyesuaikan konten video. Nilai yang valid: 'height', 'width'.

Contohnya, Anda dapat menentukan `width: '500px', autoSize: 'height'`. Pemutar mempertahankan lebar 500px dan secara otomatis menyesuaikan tinggi berdasarkan rasio aspek video aktual.

Atau, Anda dapat menentukan `height: '500px', autoSize: 'width'`. Pemutar mempertahankan tinggi 500px dan secara otomatis menyesuaikan lebar berdasarkan rasio aspek video aktual.

Catatan: `autoSize: true` setara dengan `autoSize: 'height'`, artinya tinggi bersifat adaptif secara default.

videoWidth

String

Lebar video. Untuk informasi selengkapnya, lihat Mengatur mode tampilan.

videoHeight

String

Tinggi video. Untuk informasi selengkapnya, lihat Mengatur mode tampilan.

preload

Boolean

Pemutar memuat secara otomatis.

cover

String

Gambar mini default pemutar. Masukkan URL gambar yang valid. Properti ini hanya berlaku ketika `autoplay` diatur ke false.

isLive

Boolean

Menentukan apakah konten merupakan streaming langsung. Jika ya, pemutar mencegah pengguna menyeret bilah progres. Nilai default adalah false. Atur ke true saat memutar streaming langsung.

autoplay

Boolean

Menentukan apakah pemutar memutar video secara otomatis. Properti autoplay tidak berlaku pada perangkat seluler. Nilai yang valid:

  • true: Mengaktifkan putar otomatis.

  • false (default): Menonaktifkan putar otomatis.

Catatan

Karena pembatasan browser, Web Player SDK mungkin gagal memutar video secara otomatis dalam beberapa skenario. Untuk informasi selengkapnya, lihat Fitur lanjutan.

autoplayPolicy

Object

Kebijakan putar otomatis senyap adaptif untuk pemutar. Properti ini hanya berlaku ketika autoplay diatur ke true. Contoh konfigurasi berikut:

autoplayPolicy: {
  fallbackToMute: true, // Menentukan apakah akan beralih ke putar otomatis senyap jika putar otomatis dengan suara gagal. Default: false.
  showUnmuteBtn: true, // Menentukan apakah akan menampilkan tombol unmute besar di tengah selama putar otomatis senyap. Default: true.
}
Catatan
  • Saat putar otomatis senyap berhasil, event mutedAutoplay dipicu.

  • Saat putar otomatis diaktifkan (autoplay diatur ke true) dan putar otomatis senyap adaptif juga diaktifkan (autoplayPolicy.fallbackToMute diatur ke true), pemutar pertama-tama mencoba memutar otomatis dengan suara. Jika gagal, pemutar beralih ke mencoba putar otomatis senyap. Perlu dicatat bahwa putar otomatis senyap tidak dijamin 100% berhasil.

rePlay

Boolean

Pemutar secara otomatis mengulang pemutaran.

useH5Prism

Boolean

Menentukan pemutar H5 yang digunakan.

playsinline

Boolean

Menentukan apakah akan memutar video inline di H5. Ini mungkin tidak berfungsi di beberapa browser Android.

skinRes

Url

Gambar skin. Kami menyarankan agar Anda tidak mengubah bidang ini. Untuk melakukan perubahan, lihat Mengatur skin pemutar.

skinLayout

Array | Boolean

Konfigurasi tata letak untuk komponen fungsional. Jika Anda tidak menentukan bidang ini, tata letak default digunakan. Nilai `false` menyembunyikan semua komponen fungsional. Untuk informasi selengkapnya, lihat Mengonfigurasi properti skinLayout.

skinLayoutIgnore

Array

Komponen UI yang disembunyikan. Untuk nama komponen, lihat Parameter komponen VOD. Contoh konfigurasi berikut:

skinLayoutIgnore: [
  'bigPlayButton', // Menyembunyikan tombol play besar.
  'controlBar.fullScreenButton' // Menyembunyikan tombol full screen pada bilah kontrol (memilih sub-komponen menggunakan notasi titik).
]
Catatan

Properti `skinLayoutIgnore` memiliki prioritas lebih tinggi daripada properti `skinLayout`.

controlBarVisibility

String

Implementasi panel kontrol. Nilai yang valid:

  • click: Klik area pemutar.

  • hover (default): Arahkan kursor ke area pemutar.

  • always: Bilah kontrol selalu ditampilkan.

  • never: Menyembunyikan seluruh bilah kontrol.

showBarTime

Number

Waktu dalam milidetik sebelum bilah kontrol secara otomatis disembunyikan.

enableSystemMenu

Boolean

Menentukan apakah menampilkan menu klik kanan sistem. Nilai default adalah false.

format

String

Menentukan format URL pemutaran. Nilai yang valid:

  • mp4

  • hls atau m3u8

  • flv

  • mp3

Nilai default kosong.

mediaType

String

Menentukan apakah mengembalikan audio atau video. Ini hanya didukung saat Anda menggunakan metode pemutaran `vid`. Nilai default adalah video. Nilai yang valid:

  • video: Video.

  • audio: Untuk format video yang hanya berisi audio, seperti file audio MP4.

qualitySort

String

Menentukan urutan pengurutan. Ini hanya didukung saat Anda menggunakan metode pemutaran Vid + PlayAuth. Nilai yang valid:

  • desc: Mengurutkan secara menurun (dari terbesar ke terkecil).

  • asc: Mengurutkan secara menaik (dari terkecil ke terbesar).

Nilai default: asc.

definition

String

Definisi video yang ditampilkan, dipisahkan dengan koma (,). Misalnya, 'FD,LD'. Nilai ini merupakan subset dari definisi yang tersedia untuk `vid`. Nilai yang valid:

  • FD (definisi rendah)

  • LD (definisi standar)

  • HD (High Definition)

  • HD (resolusi ultra-tinggi)

  • OD (kualitas asli)

  • 2K (2K)

  • 4K (4K)

defaultDefinition

String

Definisi video default. Nilai ini harus merupakan salah satu definisi yang tersedia untuk `vid`. Nilai yang valid:

  • FD (definisi rendah)

  • LD (definisi standar)

  • HD (High Definition)

  • HD (resolusi ultra-tinggi)

  • OD (kualitas asli)

  • 2K (2K)

  • 4K (4K)

autoPlayDelay

Number

Penundaan sebelum pemutaran dimulai. Satuan: detik.

language

String

Bahasa untuk internasionalisasi. Nilai default adalah zh-cn. Jika tidak diatur, bahasa browser digunakan. Nilai yang valid:

  • zh-cn: Bahasa Tiongkok.

  • en-us: Bahasa Inggris.

languageTexts

JSON

Objek JSON untuk teks internasionalisasi kustom. Kunci harus sesuai dengan nilai properti `language`. Contoh: {jp:{Play:"Play"}}. Untuk struktur JSON, lihat struktur JSON.

snapshotWatermark

Object

Mengatur watermark untuk tangkapan layar di H5.

useHlsPluginForSafari

Boolean

Menentukan apakah akan mengaktifkan plugin HLS untuk pemutaran di browser Safari, kecuali Safari 11. Nilai yang valid:

  • true: Diaktifkan.

  • false (default): Menonaktifkan plugin.

enableStashBufferForFlv

Boolean

Saat memutar aliran FLV di H5, menentukan apakah akan mengaktifkan cache pemutaran. Ini hanya berfungsi untuk streaming langsung. Nilai yang valid:

  • true (default): Mengaktifkan cache.

  • false: Dinonaktifkan.

stashInitialSizeForFlv

Number

Saat memutar aliran FLV di H5, ini adalah ukuran cache awal. Ini hanya berfungsi untuk streaming langsung. Nilai default adalah 32 KB.

Nilai yang lebih kecil dapat mempercepat pemutaran awal, tetapi jika nilainya terlalu kecil, dapat menyebabkan tersendat setelah pemutaran berlangsung sebentar.

loadDataTimeout

Number

Durasi buffering dalam detik setelah itu pemutar meminta pengguna untuk beralih ke definisi yang lebih rendah. Nilai default adalah 20 detik.

waitingTimeout

Number

Periode timeout buffering maksimum. Jika periode ini terlampaui, kesalahan akan ditampilkan. Satuan: detik. Nilai default adalah 60 detik.

diagnosisButtonVisible

Boolean

Menentukan apakah akan menampilkan tombol diagnosis. Nilai yang valid:

  • true (default): Menampilkan tombol.

  • false: Tidak menampilkan tombol.

disableSeek

Boolean

Menonaktifkan pencarian pada bilah progres. Nilai yang valid:

  • true: Dinonaktifkan.

  • false (default): Tidak menonaktifkan.

encryptType

Number

Menentukan apakah memutar video yang dienkripsi dengan enkripsi pribadi Alibaba Cloud. Nilai default adalah 0. Nilai yang valid:

  • 0: Memutar video tanpa enkripsi.

  • 1: Memutar video yang dienkripsi secara pribadi.

Catatan
  • Enkripsi pribadi menggunakan metode VID + Playauth untuk pemutaran.

  • Untuk enkripsi standar di web, gunakan metode pemutaran URL. Lihat Pemutaran terenkripsi.

progressMarkers

Array

Array konten untuk menandai bilah progres. Untuk informasi selengkapnya, lihat Penanda bilah progres.

vodRetry

Number

Jumlah upaya pengulangan untuk pemutaran VOD yang gagal. Nilai default adalah 3.

liveRetry

Number

Jumlah upaya pengulangan untuk pemutaran langsung yang gagal. Nilai default adalah 5.

hlsFrameChasing

Boolean

Dalam mode streaming langsung HLS, menentukan apakah akan mengaktifkan sinkronisasi frame. Nilai yang valid:

  • true: Mengaktifkan sinkronisasi frame.

  • false (default): Menonaktifkan sinkronisasi frame.

Catatan

Parameter ini hanya didukung di Web Player SDK versi sebelum 2.21.0. Untuk versi 2.21.0 dan yang lebih baru, untuk mengatur sinkronisasi frame dalam mode streaming langsung HLS, lihat properti hlsOption.maxLiveSyncPlaybackRate.

chasingFirstParagraph

Number

Durasi segmen sinkronisasi frame pertama. Satuan: detik. Nilai default adalah 20 detik.

Catatan

Parameter ini hanya didukung di Web Player SDK versi sebelum 2.21.0. Untuk versi 2.21.0 dan yang lebih baru, untuk mengatur sinkronisasi frame dalam mode streaming langsung HLS, lihat properti hlsOption.maxLiveSyncPlaybackRate.

chasingSecondParagraph

Number

Durasi segmen sinkronisasi frame kedua. Satuan: detik. Nilai default adalah 40 detik.

Catatan

Parameter ini hanya didukung di Web Player SDK versi sebelum 2.21.0. Untuk versi 2.21.0 dan yang lebih baru, untuk mengatur sinkronisasi frame dalam mode streaming langsung HLS, lihat properti hlsOption.maxLiveSyncPlaybackRate.

chasingFirstSpeed

Number

Kecepatan pemutaran untuk segmen sinkronisasi frame pertama. Nilai default adalah 1.1x.

Catatan

Parameter ini hanya didukung di Web Player SDK versi sebelum 2.21.0. Untuk versi 2.21.0 dan yang lebih baru, untuk mengatur sinkronisasi frame dalam mode streaming langsung HLS, lihat properti hlsOption.maxLiveSyncPlaybackRate.

chasingSecondSpeed

Number

Kecepatan pemutaran untuk segmen sinkronisasi frame kedua. Nilai default adalah 1.2x.

Catatan

Parameter ini hanya didukung di Web Player SDK versi sebelum 2.21.0. Untuk versi 2.21.0 dan yang lebih baru, untuk mengatur sinkronisasi frame dalam mode streaming langsung HLS, lihat properti hlsOption.maxLiveSyncPlaybackRate.

hlsOption.maxLiveSyncPlaybackRate

Number

Dalam mode streaming langsung HLS, mengatur kecepatan pemutaran untuk sinkronisasi frame langsung. Nilai default adalah 1, yang berarti sinkronisasi frame dinonaktifkan.

  • Contoh konfigurasi:

    hlsOption: {
      maxLiveSyncPlaybackRate: 1.5, // Mengatur kecepatan pemutaran untuk sinkronisasi frame.
      liveSyncDurationCount: 3 // Mengatur jumlah segmen tertunda yang memicu sinkronisasi frame.
    }
  • Makna contoh: Saat latensi streaming langsung lebih besar dari durasi 3 segmen, pemutar memutar dengan kecepatan 1.5x untuk mengejar ketinggalan hingga latensi 3 segmen. Karena pemutar memerlukan buffer tertentu untuk menangani fluktuasi jaringan, ubah nilai liveSyncDurationCount dengan hati-hati. Nilai yang terlalu kecil dapat menyebabkan tersendat.

Catatan

Parameter ini hanya didukung di Web Player SDK 2.21.0 dan yang lebih baru.

flvFrameChasing

Boolean

Dalam mode streaming langsung FLV, menentukan apakah akan mengaktifkan sinkronisasi frame. Nilai yang valid:

  • true: Mengaktifkan sinkronisasi frame.

  • false: Menonaktifkan sinkronisasi frame.

Nilai default adalah false.

keyShortCuts

Boolean

Menentukan apakah akan mengaktifkan pintasan keyboard. Nilai yang valid:

  • true: Mengaktifkan pintasan keyboard.

  • false: Menonaktifkan pintasan keyboard.

Nilai default adalah false.

Catatan

Tombol panah kiri dan kanan mengontrol mundur cepat dan maju cepat. Tombol panah atas dan bawah mengontrol volume. Spasi menjeda dan melanjutkan pemutaran.

keyFastForwardStep

Number

Interval waktu untuk maju cepat dan mundur cepat. Satuan: detik. Nilai default adalah 10 detik.

rtsFallback

Boolean

Saat browser tidak mendukung RTS atau penarikan aliran RTS gagal, pemutar secara otomatis mencoba beralih ke FLV atau HLS untuk pemutaran. Pemutar memprioritaskan FLV untuk latensi yang lebih rendah. Jika browser tidak mendukung FLV, pemutar beralih ke HLS.

Fitur ini diaktifkan secara default. Untuk menonaktifkannya, Anda dapat mengirimkan `false`.

rtsFallbackType

String

Menentukan protokol yang akan digunakan sebagai fallback dari RTS. Nilai yang valid adalah HLS atau FLV. Jika Anda tidak mengirimkan parameter ini, pemutar secara otomatis memilih protokol. Pemutar memprioritaskan FLV untuk latensi yang lebih rendah. Jika browser tidak mendukung FLV, pemutar beralih ke HLS.

rtsFallbackSource

String

Kami menyarankan agar Anda menggunakan kebijakan fallback default pemutar. Namun, jika Anda ingin menentukan URL penarikan aliran tetap untuk fallback, gunakan parameter ini.

traceId

String

`traceId` adalah pengidentifikasi pengguna unik Anda sendiri. Kirimkan `traceId` ke instrumen publik untuk pelacakan log yang dilaporkan. Secara default, Web Player SDK telah mengaktifkan pelaporan log. Mengirimkan `traceId` membantu Anda mengidentifikasi pengguna. Jika Anda tidak mengirimkannya, Web Player SDK menghasilkan UUID (pengidentifikasi unik yang dihasilkan oleh SDK pemutar) dan menyimpannya di cache browser.

Catatan

Didukung di Web Player SDK 2.10.0 dan yang lebih baru.

textTracks

Array

Mengatur keterangan eksternal WebVTT. Contoh kode berikut:

textTracks: [
  { kind: 'subtitles', label: 'Chinese', src: 'caption_url', srclang: 'zh-CN', default: true },
	{ kind: 'subtitles', label: 'English (US)', src: 'caption_url', srclang: 'en-US' }
],

Deskripsi bidang:

  • kind: Jenis VTT. Nilai yang valid termasuk `subtitles` dan `captions`.

  • label: Nama keterangan yang akan ditampilkan.

  • srclang: Bahasa keterangan.

  • src: URL keterangan. Izinkan akses lintas domain.

  • default: Menentukan apakah keterangan akan ditampilkan secara default. Nilai yang valid adalah `true` dan `false`. Bidang ini hanya didukung di Web Player SDK 2.15.7 dan yang lebih baru.

Catatan
  • Didukung di Web Player SDK 2.12.0 dan yang lebih baru.

  • Keterangan eksternal WebVTT tidak didukung di browser berikut:

    • IE

    • Browser QQ untuk Android, browser sistem untuk OPPO/OnePlus

    • Browser lain yang membajak tag video

  • Untuk deskripsi detail properti keterangan, lihat spesifikasi HTML.

  • Untuk pengaturan keterangan lanjutan, lihat Keterangan eksternal.

ratio

Number

Mengatur pemutar untuk diskalakan pada rasio aspek tetap. Misalnya, jika video memiliki rasio aspek 16:9, Anda dapat mengatur parameter pemutar menjadi width: "100%", ratio: 16/9. Ini menjaga rasio aspek pemutar konsisten dengan konten video dan memungkinkannya diskalakan secara proporsional saat halaman diubah ukurannya.

extLanguageTexts

Object

SDK Pemutar memiliki set teks UI bawaan dalam bahasa Tiongkok dan Inggris. Anda dapat menggunakan properti ini untuk menyesuaikan teks tampilan untuk bagian-bagian UI. Misalnya, untuk mengubah teks tampilan untuk resolusi HD, yang secara default adalah High definition (high definition), Anda dapat mengubahnya menjadi 1080p sebagai berikut:

extLanguageTexts: {
    'zh-cn': {
      'HD': "1080p"
    }
}

speedLevels

Array

Mengatur array daftar kecepatan pemutaran kustom. `key` merepresentasikan nilai kecepatan, dan `text` merepresentasikan teks UI. Jika tidak dikirimkan, daftar default digunakan. Contoh nilai parameter berikut:

speedLevels: [
  {"key": 0.25, "text": "0.25"},
  {"key": 0.5, "text": "0.5"},
  {"key": 1, "text": "Normal"},
  {"key": 1.25, "text": "1.25"},
  {"key": 1.5, "text": "1.5"},
  {"key": 2,"text": "2"}
]

logo

Array

Mengatur gambar logo kustom. Contoh kode berikut:

    logo: [{
      width: 30,
      position: 'bottom-right',
      origin: 'content',
      src: 'a.png'
    },
    {
      width: 20,
      position: 'bottom-right',
      offsetY: -20,
      origin: 'content',
      src: 'b.png'
    }]

Deskripsi bidang:

  • src: URL gambar logo.

  • origin: Objek referensi untuk pemosisian. Nilai yang valid:

    • box: Pemutar

    • content: Konten video

  • width/height: Lebar/tinggi logo sebagai persentase (dihitung berdasarkan `origin`). Jika Anda hanya menentukan satu dimensi, dimensi lainnya diskalakan secara proporsional berdasarkan rasio aspek gambar.

  • position: Posisi relatif logo, diposisikan relatif terhadap `origin`. Nilai yang valid:

    • top-left: Kiri atas

    • top-right: Kanan atas

    • bottom-left: Kiri bawah

    • bottom-right: Kanan bawah

  • offsetX/offsetY: Offset dari `position`, sebagai persentase (dihitung berdasarkan `origin`).

license

Object

Untuk menggunakan layanan bernilai tambah seperti Pemantauan Kualitas Pemutaran (Versi Lama), Pelacakan titik tunggal, dan memutar aliran video yang dikodekan H.265/H.266, pertama-tama isi Formulir Permohonan Layanan Bernilai Tambah Web Player SDK untuk mengajukan lisensi. Kemudian, integrasikan lisensi sebagai berikut:

// Domain adalah nama domain yang Anda berikan saat mengajukan lisensi.
// Kunci adalah kunci lisensi.
license: {
    domain: "example.com",
    key: "example-key"
  }

mute

Boolean

Mengatur apakah akan memutar video dalam mode senyap. Saat browser melarang putar otomatis, Anda dapat mengonfigurasi parameter ini untuk putar otomatis senyap. Untuk informasi selengkapnya, lihat Fitur lanjutan.

clickPause

Boolean

Klik layar video untuk menjeda atau memutar.

  • true: Diaktifkan.

  • false: Dinonaktifkan.

Nilai default adalah `true` di PC dan `false` di perangkat seluler. Jangan gunakan properti ini bersamaan dengan properti `dbClickSkip` untuk menghindari konflik interaksi.

disablePip

Boolean

Menyembunyikan tombol Picture-in-Picture (PiP) asli browser.

Catatan
  • Didukung di Web Player SDK 2.20.0 dan yang lebih baru.

  • Hanya didukung di Firefox 116 dan yang lebih baru.

env

String

Data instrumentasi pemutar diunggah ke pusat data Tiongkok secara default. Jika Anda memiliki persyaratan kepatuhan data untuk wilayah di luar Tiongkok, kirimkan parameter `env: 'SEA'`. Data akan diunggah ke pusat data Singapura.

watchStartTime

Number

Jika digunakan sendiri, ini merepresentasikan waktu mulai pemutaran.

Jika digunakan bersama `watchEndTime`, ini mengaktifkan pemutaran rentang, memungkinkan pemutaran dan pencarian hanya dalam rentang waktu mulai dan akhir yang ditentukan.

Satuan: detik

watchEndTime

Number

Digunakan bersama `watchStartTime` untuk mengaktifkan pemutaran rentang, memungkinkan pemutaran dan pencarian hanya dalam rentang waktu mulai dan akhir yang ditentukan.

Jika nilai parameter ini kurang dari `watchStartTime`, `watchStartTime` menjadi tidak valid.

Satuan: detik

start

Number

Digunakan bersama `end` untuk memotong bagian video dan memperlakukannya sebagai video terpisah. Misalnya, untuk video berdurasi 60 detik, mengatur `start:10` dan `end:30` menghasilkan video dengan durasi tampilan 20 detik, dimulai dari tanda 10 detik video asli.

end

Number

Digunakan bersama `start` untuk memotong bagian video dan memperlakukannya sebagai video terpisah. Misalnya, untuk video berdurasi 60 detik, mengatur `start:10` dan `end:30` menghasilkan video dengan durasi tampilan 20 detik, dimulai dari tanda 10 detik video asli.

dbClickFullscreen

Boolean

Menentukan apakah akan mengaktifkan klik ganda untuk masuk mode layar penuh. Ini diaktifkan secara default di PC.

longPressFastForward

Boolean

Fitur tekan lama untuk maju cepat (hanya seluler). Nilai yang valid:

  • true (default): Diaktifkan.

  • false: Dinonaktifkan.

dbClickSkip

Boolean

Fitur klik ganda untuk melewati (hanya seluler), di mana klik ganda area kiri mundur cepat dan area kanan maju cepat. Nilai yang valid:

  • true (default): Diaktifkan.

  • false: Dinonaktifkan.

Jangan gunakan properti ini bersamaan dengan properti `clickPause` untuk menghindari konflik interaksi.

enableMockFullscreen

Boolean

Fitur layar penuh halaman web. Pemutar secara default memanggil API layar penuh browser. Di browser iOS dan beberapa browser Android, mode layar penuh diambil alih oleh pemutar sistem, yang dapat menyebabkan masalah seperti UI menghilang. Untuk mencegah hal ini, Anda dapat mengaktifkan parameter ini untuk mengimplementasikan layar penuh semu menggunakan CSS. Nilai default adalah false.

Metode

Metode harus dipanggil setelah event `ready` terjadi. Anda dapat memanggil metode tersebut dalam fungsi callback `ready` dari konstruktor pemutar, seperti pada contoh kode berikut:

// Metode 1:
var player = new Aliplayer({}, function (player) {
  player.play();
});

// Metode 2:
var player = new Aliplayer({});
function handleReady(player) {
  player.play();
};
player.on('ready', handleReady);

Metode berikut dapat dipanggil pada instans Aliplayer:

play()

Memutar video.

Definisi fungsi

() => Player

pause()

Menjeda video.

(showPlayButton?: boolean) => Player

Parameter

Name

Parameter type

Required

Description

showPlayButton

Boolean

No

Menentukan apakah akan menampilkan tombol play.

replay()

Memutar ulang video.

Definisi fungsi

() => Player

seek()

Mencari ke waktu tertentu untuk pemutaran.

Definisi fungsi

(time: number) => Player 

Parameter

Name

Parameter type

Required

Description

time

number

Yes

Waktu yang akan dicari. Satuan: detik.

dispose()

Menghapus pemutar.

Definisi fungsi

() => void

getCurrentTime()

Mengambil waktu pemutaran saat ini dalam detik.

Definisi fungsi

() => number

getDuration()

Mengambil durasi total video dalam detik. Anda dapat memanggil metode ini setelah video dimuat, misalnya setelah event `play` terjadi.

Definisi fungsi

() => number

getVolume()

Mengambil volume saat ini. Nilai yang dikembalikan adalah bilangan real dari 0 hingga 1. Fitur ini mungkin tidak didukung di iOS atau beberapa perangkat Android.

Definisi fungsi

() => number | undefined

setVolume()

Mengatur volume.

Definisi fungsi

(volume: number) => void

Parameter

Name

Parameter type

Required

Description

volume

number

Yes

vol adalah bilangan real dari 0 hingga 1. Ini mungkin tidak berfungsi di iOS dan beberapa perangkat Android.

mute()

Menyenyapkan pemutar.

Definisi fungsi

(quiet?: boolean) => Player

Parameter

Name

Parameter type

Required

Description

quiet

boolean

No

Menentukan apakah akan menyembunyikan prompt teks di pojok kiri bawah saat menyenyapkan.

unMute()

Mengaktifkan kembali suara.

Definisi fungsi

(quiet?: boolean) => Player

Parameter

Name

Parameter type

Required

Description

quiet

boolean

No

Menentukan apakah akan menyembunyikan prompt teks di pojok kiri bawah saat membatalkan penyenyapan.

getPlayTime()

Mengambil durasi pemutaran aktual pengguna dalam detik. Durasi ini mengecualikan waktu saat video dijeda dan memperhitungkan waktu yang berlalu selama perubahan kecepatan.

Definisi fungsi

() => number

loadByUrl()

Memuat video baru berdasarkan URL. Metode ini mendukung pergantian antar video dengan format yang sama, seperti MP4, HLS, atau FLV. Untuk beralih antar video dengan format berbeda, Anda harus menghapus instans pemutar saat ini dan membuat yang baru.

Definisi fungsi

(url: string, seconds?: number, autoPlay?: boolean) => void

Parameter

Name

Parameter type

Required

Description

url

string

Yes

URL video yang akan dialihkan.

seconds

number

No

Posisi awal setelah beralih.

autoPlay

boolean

No

Menentukan apakah akan memutar otomatis setelah beralih.

replayByVidAndPlayAuth()

Memutar ulang video VOD. Metode ini hanya mendukung peralihan antar video dengan format yang sama.

Definisi fungsi

(vid: string, playauth: string) => void

Parameter

Name

Parameter type

Required

Description

vid

string

Yes

ID video.

playauth

string

Yes

Kredensial pemutaran.

replayByVidAndAuthInfo()

ApsaraVideo Media Processing (MPS) hanya mendukung peralihan antar video dengan format yang sama.

Definisi fungsi

(vid: string, accId: string, accSecret: string, stsToken: string, authInfo: string, domainRegion: string) => void

Untuk informasi selengkapnya, lihat Pemutaran MPS.

replayByMediaAuth()

Peralihan video di Layanan Media Umum terbatas pada video dengan format yang sama.

Definisi fungsi

(mediaAuth: string) => void

Parameter

Name

Parameter type

Required

Description

mediaAuth

string

Yes

Kredensial pemutaran.

getBuildInComponent()

Mengambil komponen UI bawaan, seperti tombol layar penuh atau bilah progres.

Definisi fungsi

(name: string) => BuildInComponent;

Parameter

Name

Parameter type

Required

Description

name

string

Yes

Untuk nama komponen bawaan (seperti `fullScreenButton`), lihat Mengonfigurasi properti skinLayout. Setiap komponen mendukung metode `hide()` dan `show()` untuk mengontrol visibilitasnya.

setPlayerSize()

Mengatur ukuran pemutar.

Definisi fungsi

(width: string, height: string) => void

Parameter

Name

Parameter type

Required

Description

width

string

Yes

Mengatur ukuran pemutar. Nilai yang valid:

  • 400px

  • 60%

height

string

Yes

setSpeed()

Mengatur kecepatan pemutaran. Fitur ini mungkin tidak didukung di beberapa perangkat seluler, seperti di WeChat untuk Android. Secara default, UI kecepatan pemutaran diaktifkan.

Definisi fungsi

(speed: number) => void

Parameter

Name

Parameter type

Required

Description

speed

number

Yes

Mendukung kecepatan pemutaran dari 0.5x hingga 2x.

Catatan

Cara menonaktifkan kontrol kecepatan pemutaran:

  • Anda tidak dapat menonaktifkan atau menyesuaikan opsi kecepatan individual. Anda hanya dapat menonaktifkan seluruh menu pengaturan.

  • Solusi alternatif untuk menonaktifkan kontrol kecepatan adalah dengan mengganti gaya:

    .prism-setting-speed {
       display: none !important;
     }

setTraceId()

Mengirimkan nilai kustom ke layanan instrumentasi untuk pelacakan log.

Definisi fungsi

(traceId: string) => void

Parameter

Name

Parameter type

Required

Description

traceId

string

Yes

Pengidentifikasi unik.

Catatan

Fitur ini didukung di Web Player SDK 2.10.0 dan yang lebih baru.

setSanpshotProperties()

Mengatur parameter snapshot.

Definisi fungsi

(width: number, height: number, rate: number) => void

Parameter

Name

Parameter type

Required

Description

width

number

Yes

Tinggi dan lebar dalam satuan px. Kualitas tangkapan layar adalah angka antara 0 dan 1, dengan nilai default 1. Untuk informasi detail tentang tangkapan layar video, lihat Tangkapan layar video.

height

number

Yes

rate

number

Yes

fullscreenService.requestFullScreen()

Masuk ke mode layar penuh.

Definisi fungsi

() => Player

fullscreenService.cancelFullScreen()

Keluar dari mode layar penuh. Pemanggilan ini tidak berpengaruh di iOS.

Definisi fungsi

() => Player

fullscreenService.getIsFullScreen()

Mengambil status layar penuh pemutar.

Definisi fungsi

() => boolean

getStatus()

Mengambil status pemutar. Nilai string yang dikembalikan dapat berupa salah satu dari berikut:

  • init: Diinisialisasi.

  • ready: Siap.

  • loading: Memuat.

  • play: Putar.

  • pause: Dijeda.

  • playing: Sedang memutar.

  • waiting: Menunggu buffer.

  • error: Kesalahan.

  • ended: Selesai.

Definisi fungsi

() => string

liveShiftSerivce.setLiveTimeRange()

Mengatur waktu mulai dan akhir streaming langsung. Metode ini digunakan saat fitur pergeseran waktu diaktifkan.

Definisi fungsi

(start: string, end: string) => void

Parameter

Name

Parameter type

Required

Description

start

string

Yes

start adalah waktu mulai streaming langsung.

end

string

Yes

end adalah waktu akhir streaming langsung.

Contoh

player.liveShiftSerivce.setLiveTimeRange('2025/03/21 12:43:00', '2025/03/21 23:31:00')

setRotate()

Mengatur sudut rotasi pemutar.

Definisi fungsi

(rotate: number) => void

Parameter

Name

Parameter type

Required

Description

rotate

number

Yes

Bilangan positif menunjukkan rotasi searah jarum jam, dan bilangan negatif menunjukkan rotasi berlawanan arah jarum jam. Contoh: `setRotate(90)`. Untuk informasi selengkapnya, lihat Mengatur mode tampilan.

getRotate()

Mengambil sudut rotasi pemutar.

Definisi fungsi

() => number

Untuk informasi selengkapnya, lihat Mengatur mode tampilan.

setImage()

Mengatur pencerminan gambar.

Definisi fungsi

(type: string) => void

Parameter

Name

Parameter type

Required

Description

type

string

Yes

Nilai yang valid:

  • horizon: Horizontal.

  • vertical: Vertikal.

Contoh: `setImage('horizon')`. Untuk informasi selengkapnya, lihat Mengatur mode tampilan.

setCover()

Anda dapat mengatur thumbnail.

Definisi fungsi

(coverUrl: string) => void

Parameter

Name

Parameter type

Required

Description

coverUrl

string

Yes

URL gambar mini.

setProgressMarkers()

Menentukan titik data.

Definisi fungsi

(markers: Array<{ time: number, text: string }>) => void

Parameter

Name

Parameter type

Required

Description

markers

Array<markers>

Yes

markers: Kumpulan data penanda. Wajib.

marker.time: Waktu penanda. Wajib.

marker.text: Teks untuk penanda. Wajib.

Untuk informasi selengkapnya, lihat parameter `progressMarkers`.

setPreviewTime()

Mengatur durasi pratinjau.

Definisi fungsi

(time: number) => void

Parameter

Name

Parameter type

Required

Description

time

number

Yes

Satuan: detik. Untuk informasi selengkapnya, lihat Pratinjau.

getPreviewTime()

Mengambil durasi pratinjau.

Definisi fungsi

() => number

isPreview()

Memeriksa apakah pemutaran saat ini merupakan pratinjau.

Definisi fungsi

() => boolean

getCurrentPDT()

Untuk video dalam format HLS, metode ini mengambil Program-Date-Time (PDT) real-time.

Definisi fungsi

() => number | undefined

setTextTracks()

Mengatur sekelompok keterangan WebVTT.

Definisi fungsi

(textTracks: Array<{ kind: string, label: string, src: string, srclang: string }>) => void

Parameter

Name

Parameter type

Required

Description

textTracks

Array<object>

Yes

Contohnya:

player.setTextTracks([ { kind: 'subtitles', label: 'Chinese', src: 'caption_url', srclang: 'zh-CN' },{ kind: 'subtitles', label: 'English (US)', src: 'caption_url', srclang: 'en-US' }])
Catatan

Didukung di Web Player SDK 2.12.0 dan yang lebih baru.

setLogo()

Mengatur gambar logo kustom.

Definisi fungsi

(logoList: Array<{ width: number, position: string, origin: string, src: string }>) => void

Parameter

Name

Parameter type

Required

Description

logoList

Array<object>

Yes

Contohnya:

player.setLogo([{
      width: 30,
      position: 'bottom-right',
      origin: 'content',
      src: 'a.jpg'
    },
    {
      width: 20,
      position: 'bottom-right',
      offsetY: -20,
      origin: 'content',
      src: 'b.jpg'
    }])

Untuk deskripsi detail setiap bidang, lihat properti `logo`.

setWatchTime()

Memperbarui secara dinamis `watchStartTime` dan `watchEndTime` untuk video saat ini.

Definisi fungsi

(start: number, end: number) => void

Parameter

Name

Parameter type

Required

Description

start

string

Yes

start adalah waktu mulai.

end

string

Yes

end adalah waktu akhir.

setNextWatchTime()

Mengatur `watchStartTime` dan `watchEndTime` untuk video berikutnya. Jika Anda berencana beralih video menggunakan `loadByUrl` atau `replayByVidAndPlayAuth`, Anda dapat memanggil metode ini untuk mengatur rentang pemutaran untuk video berikutnya.

Definisi fungsi

(start: number, end: number) => void

Parameter

Name

Parameter type

Required

Description

start

string

Yes

start adalah waktu mulai.

end

string

Yes

end adalah waktu akhir.

setStartEnd()

Memperbarui secara dinamis waktu `start` dan `end` untuk video saat ini.

Definisi fungsi

(start: number, end: number) => void

Parameter

Name

Parameter type

Required

Description

start

string

Yes

start adalah waktu mulai.

end

string

Yes

end adalah waktu akhir.

setNextStartEnd()

Mengatur waktu `start` dan `end` untuk video berikutnya. Jika Anda berencana beralih video menggunakan `loadByUrl` atau `replayByVidAndPlayAuth`, Anda dapat memanggil metode ini untuk mengatur rentang pemotongan untuk video berikutnya.

Definisi fungsi

(start: number, end: number) => void

Parameter

Name

Parameter type

Required

Description

start

string

Yes

start adalah waktu mulai.

end

string

Yes

end adalah waktu akhir.

takeSnapshot()

Mengambil snapshot. Metode ini mengembalikan string base64 yang dapat langsung dimuat oleh `img.src`. Anda dapat menggunakan `setSnapshotProperties` untuk mengatur kualitas snapshot dan `snapshotWatermark` untuk menambahkan watermark.

Catatan: Fitur snapshot mungkin tidak tersedia di beberapa browser seluler, seperti UC Browser atau QQ Browser, di mana elemen video dibajak.

Definisi fungsi

() => { time: number, base64: string, binary: string, error: Error | null }

Nilai kembalian

Name

Parameter type

Description

time

string

Waktu snapshot.

base64

string

Konten base64 snapshot.

binary

string

Snapshot menunjukkan string biner.

error

Error

Detail pengecualian snapshot.

showControlBar()

Menampilkan bilah kontrol.

Definisi fungsi

() => void

hideControlBar()

Menyembunyikan bilah kontrol.

Definisi fungsi

() => void

Peristiwa

Event pemutar

Name

Description

ready

Tombol inisialisasi video pemutar telah selesai dirender. Pengaturan UI awal untuk pemutar harus dipicu setelah event ini untuk mencegahnya ditimpa oleh inisialisasi.

Catatan

Metode yang disediakan oleh pemutar hanya dapat dipanggil setelah event ini terjadi.

play

Dipicu saat video melanjutkan pemutaran dari keadaan dijeda.

pause

Dipicu saat video dijeda.

canplay

Terjadi saat audio dan video dapat mulai diputar. Dapat dipicu beberapa kali. Ini hanya untuk pemutar H5.

playing

Dipicu beberapa kali selama pemutaran.

ended

Dipicu saat video saat ini selesai diputar.

liveStreamStop

Dipicu saat streaming langsung terputus. Untuk streaming langsung HLS, ini dipicu setelah 5 kali percobaan ulang yang gagal. Ini menunjukkan ke lapisan atas bahwa aliran terputus atau video perlu dimuat ulang.

Catatan

Jika streaming langsung HLS terputus atau mengalami kesalahan, pemutar secara otomatis mencoba ulang 5 kali. Tidak perlu menambahkan logika percobaan ulang di lapisan atas.

onM3u8Retry

Event percobaan ulang setelah streaming langsung HLS terputus. Dipicu hanya sekali per gangguan.

hideBar

Event untuk bilah kontrol yang secara otomatis disembunyikan.

showBar

Event untuk bilah kontrol yang secara otomatis ditampilkan.

waiting

Event buffering data.

timeupdate

Dipicu saat posisi pemutaran berubah. Anda dapat mendapatkan waktu pemutaran saat ini menggunakan metode `getCurrentTime`.

snapshoted

Event penyelesaian snapshot.

requestFullScreen

Event layar penuh.

cancelFullScreen

Event keluar dari layar penuh. Tidak dipicu di iOS.

error

Event kesalahan.

startSeek

Memulai pencarian. Parameter mengembalikan waktu titik pencarian.

completeSeek

Menyelesaikan pencarian. Parameter mengembalikan waktu titik pencarian.

resolutionChange

Dalam streaming langsung, titik akhir ingest telah mengganti resolusi.

seiFrame

Pesan SEI diterima untuk HLS atau FLV.

rtsFallback

Dipicu saat RTS melakukan fallback. Parameter reason menunjukkan penyebab fallback, dan parameter fallbackUrl adalah URL yang digunakan sebagai fallback.

settingSelected

Dipicu saat item dalam daftar pengaturan (seperti kecepatan pemutaran, definisi, atau keterangan) dipilih.

Catatan

Karena plugin kecepatan pemutaran open-source tidak disinkronkan dengan pengaturan pemutar, penggunaannya memerlukan kode kustom dan rekompilasi. Anda dapat mendefinisikan pendengar event. Untuk menggunakan settingSelected pemutar, Anda harus menghapus plugin ini.

/**
 * Item daftar pengaturan dipilih, misalnya, mengganti kecepatan menjadi 1.25x:
 * {name: 'Speed', type: 'speed', text: '1.25X', key: 1.25}
 */

rtsTraceId

Dipicu saat penarikan aliran RTS berhasil. Dengan berlangganan event ini, Anda bisa mendapatkan RTS TraceId. Dalam pencetakan log, bidang `traceId` dalam parameter data.paramData adalah TraceId penarikan aliran, dan `source` adalah URL pemutaran aliran RTS saat ini.

player.on('rtsTraceId', function(data) {
  console.log('[EVENT]rtsTraceId', data.paramData);
})

autoplay

Dipicu saat putar otomatis berhasil atau gagal. Parameter callback event.paramData adalah true jika putar otomatis berhasil. Ini adalah false jika putar otomatis gagal, dalam hal ini diperlukan interaksi pengguna untuk memulai pemutaran.

mutedAutoplay

Dipicu saat putar otomatis senyap berhasil, jika autoplayPolicy.fallbackToMute diatur ke true.

videoUnavailable

Dipicu saat pemutaran video menghasilkan Layar hitam karena format encoding video tidak didukung. Misalnya, saat memutar video H.265 di browser yang tidak mendukung H.265, layar video menjadi hitam, tetapi audio tetap diputar. Event ini dipicu dalam kasus seperti itu.

Berlangganan event

  • Anda dapat berlangganan event menggunakan metode `on` dari instans pemutar. Contoh kode berikut:

    function handleReady() {};
    player.on('ready', handleReady);
    // Beberapa event dipicu secara sering. Anda dapat menggunakan player.one untuk mendengarkan hanya sekali.
    player.one('canplay', () => {});
  • Anda dapat berhenti berlangganan event menggunakan metode `off` dari instans pemutar. Contoh kode berikut:

    player.off('ready',handleReady);