AOQ Client SDK menyediakan kemampuan video yang komprehensif, mencakup video capture, rendering, konfigurasi codec, callback data frame, dan input video eksternal. Dokumen ini memperkenalkan fitur video umum untuk Android (Java), iOS (Objective-C), dan HarmonyOS (ArkTS).
1. Video capture
1.1 Ikhtisar
Video capture membuka kamera perangkat dan mengalirkan frame video real-time ke pipeline encoding SDK. SDK mendukung dua mode capture:
- Internal capture (default): SDK secara otomatis mengelola kamera—membukanya, menangkap frame, dan menutupnya. Mode ini mendukung pergantian antara kamera depan dan belakang.
- External capture: Aplikasi mengelola kamera atau sumber video lainnya. Frame yang ditangkap dimasukkan ke SDK melalui
pushExternalVideoCapturedFrame.
1.2 Parameter konfigurasi capture
Parameter | Type | Default | Description |
|---|---|---|---|
width | int | 1280 | Lebar capture dalam piksel. Tidak digunakan dalam mode external capture. |
height | int | 720 | Tinggi capture dalam piksel. Tidak digunakan dalam mode external capture. |
fps | int | 15 | Laju frame capture. Dalam mode external capture, laju frame ditentukan oleh seberapa cepat frame didorong. |
isExternal | bool | false | Apakah akan menggunakan mode external capture. |
cameraDirection | AoqCameraDirection | Front(0) | Arah kamera. Tidak digunakan dalam mode external capture. |
1.3 Enumerasi arah kamera
Nilai enum | Nomor | Description |
|---|---|---|
AoqCameraDirectionFront | 0 | Kamera menghadap depan |
AoqCameraDirectionBack | 1 | Kamera menghadap belakang |
1.4 Referensi API
Fungsi | Android | iOS | HarmonyOS |
|---|---|---|---|
Mulai capture | startVideoCapture(config) | startVideoCapture:config: | startVideoCapture(config) |
Hentikan capture | stopVideoCapture() | stopVideoCapture | stopVideoCapture() |
Ganti kamera | switchCamera(direction) | switchCamera: | switchCamera(direction) |
1.5 Contoh
AndroidAoqVideoCaptureConfig config = new AoqVideoCaptureConfig();
config.width = 1280;
config.height = 720;
config.fps = 15;
config.cameraDirection = AoqCameraDirection.AoqCameraDirectionFront;
engine.startVideoCapture(config);
AoqVideoCaptureConfig *config = [[AoqVideoCaptureConfig alloc] init];
config.width = 1280;
config.height = 720;
config.fps = 15;
config.cameraDirection = AoqCameraDirectionFront;
[engine startVideoCapture:config];
let config: AoqVideoCaptureConfig = {
width: 1280,
height: 720,
fps: 15,
cameraDirection: AoqCameraDirection.AoqCameraDirectionFront
};
engine.startVideoCapture(config);
2. Video rendering
2.1 Ikhtisar
Video rendering menampilkan frame video yang ditangkap secara lokal atau diterima dari jarak jauh pada layar. SDK mendukung pengaturan jendela pratinjau lokal dan jendela rendering remote. Gunakan trackType untuk membedakan antara aliran video (Video) dan aliran berbagi layar (Screen).
2.2 Mode rendering
Nilai enum | Nomor | Description |
|---|---|---|
AoqRenderModeAuto | 0 | Mode otomatis |
AoqRenderModeStretch | 1 | Meregangkan hingga penuh. Gambar mungkin terdistorsi. |
AoqRenderModeFill | 2 | Sesuai dengan letterboxing. Seluruh gambar ditampilkan. |
AoqRenderModeCrop | 3 | Mode crop. Bagian gambar mungkin terpotong. |
2.3 Konfigurasi kanvas
Parameter | Type | Default | Description |
|---|---|---|---|
view | Platform view | null | Tampilan rendering. Android: SurfaceView atau TextureView. iOS: UIView. HarmonyOS: XComponent. |
renderMode | AoqRenderMode | Auto(0) | Mode tampilan rendering |
2.4 Referensi API
Fungsi | Android | iOS | HarmonyOS |
|---|---|---|---|
Atur pratinjau lokal | setLocalView(trackType, canvas) | setLocalView:trackType:canvas: | setLocalView(trackType, canvas) |
Atur tampilan remote | setRemoteView(trackType, canvas) | setRemoteView:trackType:canvas: | setRemoteView(trackType, canvas) |
CatatanPerbedaan platform: Android menggunakan SurfaceView atau TextureView sebagai kontainer rendering. iOS menggunakan UIView (dibungkus secara internal oleh AoqRenderView dengan akselerasi Metal). HarmonyOS menggunakan XComponent (dikelola oleh AoqXComponentController untuk rendering native).
3. Konfigurasi codec video
3.1 Ikhtisar
Konfigurasikan parameter encoding video, termasuk format encoding, resolusi, laju frame, bitrate, interval keyframe, pencerminan, dan orientasi. Gunakan trackType untuk menerapkan konfigurasi encoding berbeda pada track video dan track berbagi layar.
3.2 Parameter konfigurasi encoding
Parameter | Type | Default | Description |
|---|---|---|---|
trackType | AoqTrackType | Video(1) | Jenis track: Video |
codecType | AoqEncoderType | VideoH264(3) | Format encoding |
width | int | 720 | Lebar hasil encode |
height | int | 1280 | Tinggi hasil encode |
fps | int | 5 | Laju frame encoding |
bitrate | int | 500000 | Bitrate target (bps) |
minBitrate | int | 128000 | Bitrate minimum (bps) |
keyframeInterval | int | 2 | Interval keyframe (detik) |
mirrorMode | AoqMirrorMode | Disabled(0) | Mode pencerminan |
orientationMode | AoqOrientationMode | Auto(0) | Mode orientasi |
isExternal | bool | false | Mode encoding eksternal. Jika true, aplikasi mendorong frame yang telah di-encode sebelumnya. |
3.3 Enumerasi format encoding
Nilai enum | Nomor | Description |
|---|---|---|
AoqEncoderTypeVideoH264 | 3 | Pengkodean H.264 |
AoqEncoderTypeVideoJpeg | 4 | Pengkodean JPEG (untuk frame yang telah di-encode secara eksternal) |
3.4 Mode pencerminan
Nilai enum | Nomor | Description |
|---|---|---|
AoqMirrorModeDisabled | 0 | Pencerminan dinonaktifkan |
AoqMirrorModeEnabled | 1 | Pencerminan diaktifkan |
3.5 Mode orientasi
Nilai enum | Nomor | Description |
|---|---|---|
AoqOrientationModeAuto | 0 | Orientasi otomatis |
AoqOrientationModePortrait | 1 | Orientasi potret |
AoqOrientationModeLandscape | 2 | Orientasi lanskap |
3.6 Referensi API
Fungsi | Android | iOS | HarmonyOS |
|---|---|---|---|
Atur konfigurasi encoding | setVideoEncoderConfig(config) | setVideoEncoderConfig: | setVideoEncoderConfig(config) |
4. Input frame video eksternal
4.1 Ikhtisar
Input frame video eksternal memungkinkan aplikasi Anda mendorong data frame video kustom ke SDK untuk skenario external capture atau external encoding. Dua metode dorong didukung:
- Dorong frame mentah: Dorong data piksel yang belum di-encode (I420, NV12, NV21, BGRA, RGBA, dan format serupa) ke SDK. SDK melakukan encoding terhadap data tersebut.
- Dorong frame yang telah di-encode: Dorong data yang sudah di-encode (misalnya, JPEG) langsung ke SDK. SDK mengemas dan mengirimnya tanpa melakukan re-encoding.
Routing dikendalikan oleh trackType: AoqTrackTypeVideo mengarah ke track capture video; AoqTrackTypeScreen mengarah ke track berbagi layar.
4.2 Enumerasi format piksel
Nilai enum | Nomor | Description | Dukungan platform |
|---|---|---|---|
AoqVideoPixelFormatI420 | 1 | I420 tri-planar | Semua platform |
AoqVideoPixelFormatNV12 | 2 | NV12 bi-planar | Semua platform |
AoqVideoPixelFormatNV21 | 3 | NV21 bi-planar | Semua platform |
AoqVideoPixelFormatBGRA | 4 | BGRA packed | Semua platform |
AoqVideoPixelFormatRGBA | 5 | RGBA packed | Semua platform |
AoqVideoPixelFormatCVPixelBuffer | 6 | Zero-copy Apple | Hanya iOS |
AoqVideoPixelFormatTextureOES | 7 | OES texture | Hanya Android |
AoqVideoPixelFormatTexture2D | 8 | 2D texture | Hanya Android |
4.3 Struktur data frame video mentah (AoqVideoFrame)
Field | Type | Description |
|---|---|---|
format | AoqVideoPixelFormat | Format piksel |
width | int | Lebar dalam piksel |
height | int | Tinggi dalam piksel |
data | byte[] / ArrayBuffer | Data format packed (NV12/NV21/BGRA/RGBA) |
dataY / dataU / dataV | byte[] / ArrayBuffer | Data I420 tri-planar |
strideY / strideU / strideV | int | Stride I420 tri-planar |
textureId | int | ID tekstur (berlaku untuk TextureOES/Texture2D Android) |
transformMatrix | float[16] | Matriks transformasi tekstur 4×4 (Android) |
eglContext | EGLContext | Konteks EGL bersama (Android) |
pixelBuffer | CVPixelBufferRef | Zero-copy Apple (iOS) |
timeStamp | long | Timestamp dalam ms. Jika 0, SDK menggunakan jam lokal. |
4.4 Struktur data frame video yang telah di-encode (AoqVideoEncodedFrame)
Field | Type | Default | Description |
|---|---|---|---|
codec | AoqVideoCodecType | JPEG(0) | Format encoding |
data | byte[] / ArrayBuffer | - | Data yang telah di-encode |
width | int | - | Lebar dalam piksel |
height | int | - | Tinggi dalam piksel |
timeStamp | long | 0 | Timestamp dalam ms |
4.5 Referensi API
Fungsi | Android | iOS | HarmonyOS |
|---|---|---|---|
Dorong frame mentah | pushExternalVideoCapturedFrame(trackType, frame) | pushExternalVideoCapturedFrame:frame: | pushExternalVideoCapturedFrame(trackType, frame) |
Dorong frame yang telah di-encode | pushExternalVideoEncodedFrame(trackType, frame) | pushExternalVideoEncodedFrame:frame: | pushExternalVideoEncodedFrame(trackType, frame) |
5. Panggilan balik frame video
5.1 Ikhtisar
Callback frame video memungkinkan Anda memperoleh data frame mentah pada berbagai titik dalam pipeline video untuk digunakan dalam analisis video, pemrosesan kustom, perekaman, dan skenario serupa. SDK mendukung mode read-only dan read-write. Dalam mode read-write, Anda dapat memodifikasi data frame dan menulisnya kembali ke SDK.
5.2 Posisi sumber data yang didukung
Sumber data | Nilai enum | Description |
|---|---|---|
Captured | 0 | Data video setelah capture, sebelum pra-pemrosesan |
PreEncode | 1 | Data video sebelum encoding, setelah pra-pemrosesan |
Remote | 2 | Data video remote setelah decoding, sebelum rendering |
5.3 Parameter konfigurasi callback
Parameter | Type | Default | Description |
|---|---|---|---|
format | AoqVideoPixelFormat | I420(1) | Format piksel untuk data callback |
alignment | AoqVideoObserverAlignment | Default(0) | Kebijakan penyelarasan lebar |
mode | AoqVideoObserverMode | ReadOnly(0) | Mode read-only (0) atau read-write (1) |
mirrorApplied | bool | false | Apakah pencerminan diterapkan pada data callback |
5.4 Enumerasi penyelarasan lebar
Nilai enum | Nomor | Description |
|---|---|---|
AoqVideoObserverAlignmentDefault | 0 | Penyelarasan default |
AoqVideoObserverAlignmentEven | 1 | Penyelarasan 2-byte |
AoqVideoObserverAlignment4 | 2 | Penyelarasan 4-byte |
AoqVideoObserverAlignment8 | 3 | Penyelarasan 8-byte |
AoqVideoObserverAlignment16 | 4 | Penyelarasan 16-byte |
5.5 Langkah penggunaan
- Daftarkan observer: Panggil
setVideoFrameObserveruntuk mengatur pendengar callback frame video. - Aktifkan sumber data: Panggil
enableVideoFrameObserveruntuk memilih posisi sumber data dan memulai callback. - Tangani data callback: Peroleh data frame di dalam callback. Data frame hanya valid selama callback berlangsung. Salin data tersebut jika Anda memerlukannya secara asinkron.
5.6 Referensi API
Fungsi | Android | iOS | HarmonyOS |
|---|---|---|---|
Daftarkan observer | setVideoFrameObserver(listener) | setVideoFrameObserver: | setVideoFrameObserver(observer) |
Aktifkan callback | enableVideoFrameObserver(enabled, source, config) | enableVideoFrameObserver:videoSource:config: | enableVideoFrameObserver(enabled, source, config) |
5.7 Metode callback
Callback | Android | iOS | HarmonyOS |
|---|---|---|---|
Data yang Ditangkap | onCapturedVideoFrame(frame) | onCapturedVideoFrame: | onCapturedVideoFrame(frame) |
Data pre-encode | onPreEncodeVideoFrame(trackType, frame) | onPreEncodeVideoFrame:frame: | onPreEncodeVideoFrame(trackType, frame) |
Data remote | onRemoteVideoFrame(trackType, frame) | onRemoteVideoFrame:frame: | onRemoteVideoFrame(trackType, frame) |
CatatanMengembalikan true/YES dari callback menunjukkan bahwa data telah dimodifikasi dan harus ditulis kembali ke SDK. Ini hanya berlaku dalam mode ReadWrite dengan format I420.
7. Kontrol pengiriman aliran media
7.1 Ikhtisar
Kontrol apakah aliran media lokal dikirim. Gunakan trackType untuk menargetkan track tertentu (Audio, Video, atau Screen). Saat pengiriman dinonaktifkan, capture dan encoding tetap berjalan, tetapi data tidak dikirim ke ujung remote.
7.2 Referensi API
Fungsi | Android | iOS | HarmonyOS |
|---|---|---|---|
Kontrol pengiriman aliran | enableSendMediaStream(trackType, enable) | enableSendMediaStream:enable: | enableSendMediaStream(trackType, enable) |
7.3 Enumerasi jenis track
Nilai enum | Nomor | Description |
|---|---|---|
AoqTrackTypeAudio | 0 | Track audio |
AoqTrackTypeVideo | 1 | Track video |
AoqTrackTypeData | 2 | Track data |
8. Pemantauan status perangkat video
8.1 Ikhtisar
SDK secara otomatis memantau perubahan status kamera dan memberi tahu lapisan aplikasi melalui callback onVideoDeviceStateChanged.
8.2 Kode status perangkat
Kode provinsi | Nilai | Description |
|---|---|---|
AoqVideoDeviceNone | 0 | Status awal |
AoqVideoDeviceCaptureStarting | 1 | Capture sedang dimulai |
AoqVideoDeviceCaptureStarted | 2 | Capture telah dimulai |
AoqVideoDeviceCaptureStopping | 3 | Capture sedang dihentikan |
AoqVideoDeviceCaptureStopped | 4 | Capture telah dihentikan |
AoqVideoDeviceCaptureFail | 5 | Capture gagal |
8.3 Referensi callback
Callback | Android | iOS | HarmonyOS |
|---|---|---|---|
Perubahan status perangkat | onVideoDeviceStateChanged(state) | onVideoDeviceStateChanged: | onVideoDeviceStateChanged(state) |
9. Kode kesalahan dan peringatan video
9.1 Kode kesalahan video
Kode kesalahan | Nilai | Description |
|---|---|---|
AoqErrorCodeVideo | 200 | Kesalahan video umum |
VideoExternalBufferFull | 210 | Buffer eksternal video penuh |
VideoDevice | 220 | Kesalahan perangkat video umum |
CameraOpenFail | 221 | Gagal membuka kamera |
CameraAuthFailed | 222 | Izin kamera ditolak |
CameraOccupied | 223 | Kamera sedang digunakan oleh proses lain |
CameraRunningError | 224 | Kesalahan kamera saat berjalan |
VideoCodec | 230 | Kesalahan codec video umum |
EncoderInitFail | 231 | Inisialisasi encoder gagal |
VideoRender | 240 | Kesalahan rendering video umum |
RenderCreateFail | 241 | Pembuatan renderer gagal |
RenderDrawError | 242 | Kesalahan rendering saat menggambar |
Screen | 300 | Kesalahan berbagi layar umum |
CatatanKode kesalahan Android tambahan: ScreenPermissionDenied(310) — izin berbagi layar ditolak; ScreenForegroundServiceFailed(311) — layanan foreground gagal dimulai.
9.2 Kode peringatan video
Kode peringatan | Nilai | Description |
|---|---|---|
AoqWCVideo | 200 | Peringatan video umum |
CameraEnumerateError | 201 | Kesalahan enumerasi kamera |
EncoderSwitched | 202 | Peringatan encoder beralih |
RenderDowngrade | 203 | Menampilkan peringatan penurunan spesifikasi |
Lampiran: Daftar lengkap metode API video
Kategori | Metode | Description |
|---|---|---|
Kontrol capture | startVideoCapture | Buka perangkat capture video |
Kontrol capture | stopVideoCapture | Tutup perangkat capture video |
Kontrol Penangkapan | switchCamera | Beralih antara kamera depan dan belakang |
Kontrol rendering | setLocalView | Atur jendela pratinjau lokal |
Kontrol rendering | setRemoteView | Atur jendela rendering remote |
Codec | setVideoEncoderConfig | Atur parameter encoding video |
Input eksternal | pushExternalVideoCapturedFrame | Dorong frame video mentah |
Input eksternal | pushExternalVideoEncodedFrame | Dorong frame video yang telah di-encode |
Berbagi layar | startScreenCapture | Mulai capture layar |
Berbagi layar | stopScreenCapture | Hentikan capture layar |
Kontrol aliran | enableSendMediaStream | Kontrol pengiriman aliran media |
Frame callbacks | setVideoFrameObserver | Daftarkan observer frame video |
Frame callback | enableVideoFrameObserver | Aktifkan atau nonaktifkan callback frame video |