Topik ini menjelaskan API Python, callback, dan tipe data AOQ Client SDK untuk Linux.
aoq_client_sdk. Semua callback dipicu pada thread native, sehingga Anda harus memastikan keamanan thread sendiri.
Indeks API
Siklus hidup engine
API | Deskripsi |
|---|---|
create_engine | Membuat instans engine (singleton) |
destroy | Menghapus instans engine |
get_version | Mendapatkan versi SDK |
connect | Menghubungkan ke server relay |
disconnect | Memutus koneksi dari server |
Manajemen perangkat audio
API | Deskripsi |
|---|---|
start_audio_capture | Memulai pengambilan audio (implementasi kosong di Linux; tidak membuka mikrofon) |
stop_audio_capture | Menghentikan pengambilan audio (tidak berpengaruh di Linux) |
mute_audio_capture | Membisukan atau mengaktifkan kembali pengambilan audio (pengambilan perangkat tidak tersedia di Linux) |
start_audio_player | Memulai pemutaran audio (implementasi kosong di Linux; tidak membuka speaker) |
stop_audio_player | Menghentikan pemutaran audio (tidak berpengaruh di Linux) |
pause_audio_player | Menjeda pemutaran audio (pemutaran perangkat tidak tersedia di Linux) |
resume_audio_player | Melanjutkan pemutaran audio (pemutaran perangkat tidak tersedia di Linux) |
interrupt_audio_player | Menginterupsi sesi audio saat ini |
Konfigurasi pengkodean audio
API | Deskripsi |
|---|---|
set_audio_encoder_config | Menetapkan parameter pengkodean audio |
set_audio_decoder_config | Menetapkan parameter dekode audio |
Manajemen perangkat video
API | Deskripsi |
|---|---|
start_video_capture | Memulai pengambilan video (hanya mode pengambilan eksternal yang didukung di Linux) |
stop_video_capture | Menghentikan pengambilan video (hanya berlaku untuk mode pengambilan eksternal di Linux) |
set_local_view | Menetapkan atau menghapus jendela rendering video lokal (tidak ada implementasi rendering di Linux) |
set_remote_view | Menetapkan atau menghapus jendela rendering video remote (tidak ada implementasi rendering di Linux) |
Kodek video dan input eksternal
API | Deskripsi |
|---|---|
set_video_encoder_config | Menetapkan parameter pengkodean video |
set_video_decoder_config | Menetapkan parameter dekode video |
push_external_video_frame | Mendorong frame video yang diambil secara eksternal |
push_external_video_encoded_frame | Mendorong frame video terkode yang diambil secara eksternal |
Kontrol aliran media
API | Deskripsi |
|---|---|
enable_send_media_stream | Mengaktifkan atau menonaktifkan pengiriman aliran media lokal |
Pemutaran file audio
API | Deskripsi |
|---|---|
start_audio_file | Memulai pemutaran file audio lokal ke aliran penerbitan |
stop_audio_file | Menghentikan pemutaran file audio |
pause_audio_file | Menjeda pemutaran file audio |
resume_audio_file | Melanjutkan pemutaran file audio |
get_audio_file_duration | Menanyakan durasi total file audio |
get_audio_file_current_position | Menanyakan posisi pemutaran saat ini dari file audio |
set_audio_file_position_millis | Menetapkan posisi pemutaran file audio (seek) |
set_audio_file_volume | Menetapkan volume file audio |
get_audio_file_volume | Menanyakan volume saat ini dari file audio |
Aliran audio eksternal
API | Deskripsi |
|---|---|
add_audio_external_stream | Menambahkan aliran audio eksternal |
remove_audio_external_stream | Menghapus aliran audio eksternal |
push_audio_external_stream_data | Memberikan data PCM audio eksternal |
set_audio_external_stream_volume | Menetapkan volume aliran audio eksternal |
get_audio_external_stream_volume | Menanyakan volume aliran audio eksternal |
clear_audio_external_stream_buffer | Mengosongkan buffer aliran audio eksternal |
Pesan real-time
API | Deskripsi |
|---|---|
send_data_msg | Mengirim pesan data real-time |
Callback frame audio
API | Deskripsi |
|---|---|
set_audio_frame_observer | Menetapkan listener callback data frame audio |
enable_audio_frame_observer | Mengaktifkan atau menonaktifkan callback frame audio pada posisi tertentu |
Callback frame video
API | Deskripsi |
|---|---|
set_video_frame_observer | Menetapkan listener callback data frame video |
enable_video_frame_observer | Mengaktifkan atau menonaktifkan callback frame video pada posisi tertentu |
Antarmuka callback
Callback | Deskripsi |
|---|---|
on_error | Callback error engine |
on_connection_status_change | Callback perubahan status koneksi |
on_data_msg | Callback untuk pesan data real-time yang diterima |
IAudioFrameObserver | Kelas dasar untuk listener data frame audio |
IVideoFrameObserver | Kelas dasar untuk listener data frame video |
Fungsi utilitas
API | Deskripsi |
|---|---|
load_library | Secara manual menentukan dan memuat library shared native |
Detail API
Siklus hidup engine
create_engine
Membuat instans engine (metode kelas). SDK menyimpan engine sebagai singleton global, sehingga pemanggilan berikutnya akan mengembalikan instans yang sudah ada. Setelah destroy, Anda harus memanggil create_engine lagi sebelum dapat melanjutkan penggunaan engine.
Parameter | Tipe | Deskripsi |
|---|---|---|
config | AoqCreateConfig | Konfigurasi pembuatan engine |
listener | AoqEngineEventListener | Listener callback event engine |
destroy
Menghapus instans engine (metode kelas) dan melepaskan semua sumber daya.
get_version
Mendapatkan versi SDK saat ini (metode statis).
connect
Menghubungkan ke server relay. Server aplikasi memperoleh parameter koneksi AOQ sementara berdasarkan protokol yang digunakan dan mengirimkannya ke klien. Untuk informasi selengkapnya, lihat Otentikasi token.
Parameter | Tipe | Deskripsi |
|---|---|---|
config | AoqConnectConfig | Konfigurasi koneksi, yang mencakup token, SID, dan daftar titik akses relay |
disconnect
Memutus koneksi dari server dan melepaskan sumber daya yang terkait dengan koneksi tersebut.
Manajemen perangkat audio
start_audio_capture
stop_audio_capture
mute_audio_capture
start_audio_player
stop_audio_player / pause_audio_player / resume_audio_player
interrupt_audio_player
Konfigurasi pengkodean audio
Manajemen perangkat video
start_video_capture, atur is_external ke True dan berikan frame dengan memanggil push_external_video_frame. Metode set_local_view, set_remote_view, dan properti AoqVideoCanvas.view tidak memiliki efek nyata di Linux. Untuk pratinjau video, peroleh frame melalui callback frame video dan lakukan rendering sendiri.
Kodek video dan input eksternal
- Untuk set_video_decoder_config, hanya bidang track_type, codec_type, width, height, fps, dan bitrate yang berlaku.
- push_external_video_frame hanya dikonsumsi setelah start_video_capture(is_external=True). Untuk format packed (NV12/NV21/BGRA/RGBA), isi
frame.data; untuk tiga plane I420, isiframe.data_y/u/vdan stride yang sesuai. Jika buffer penuh, metode ini mengembalikan AoqErrorCode.VIDEO_EXTERNAL_BUFFER_FULL(210). - push_external_video_encoded_frame memerlukan start_video_capture(is_external=True) dan set_video_encoder_config(codec_type=VIDEO_JPEG), serta menggunakan jalur bypass tanpa pengkodean ulang.
Kontrol aliran media
Pemutaran file audio
Aliran audio eksternal
Pesan real-time
Callback bingkai audio
Callback frame video
Antarmuka callback
AoqEngineEventListener
Kelas dasar untuk callback event engine. Semua metode bersifat opsional dengan implementasi default kosong. Callback dipicu pada thread native, sehingga Anda harus memastikan keamanan thread sendiri.
on_error
on_connection_status_change
on_data_msg
IAudioFrameObserver
Kelas dasar untuk listener data frame audio. Semua metode bersifat opsional dengan implementasi default kosong.
AoqAudioFrameData.data sudah merupakan salinan bytes dan dapat digunakan secara aman secara asinkron.
IVideoFrameObserver
Kelas dasar untuk listener data frame video. Semua metode bersifat opsional dan mengembalikan False secara default.
Fungsi utilitas
load_library
libAoqClientSdk.so dicari dalam urutan berikut: variabel lingkungan AOQ_CLIENT_SDK_LIB, direktori modul, direktori lib pada tingkat yang sama, dan path sistem default. Jika pemuatan gagal, OSError akan dilemparkan. Penyebab umumnya adalah library dependen tidak tersedia di LD_LIBRARY_PATH.
Tipe data dan enumerasi
Semua tipe data adalah dataclass Python. Anda dapat membuatnya secara langsung dan memberikan nilai ke bidang-bidangnya.
Tipe umum
AoqCreateConfig
Bidang | Tipe | Nilai default | Deskripsi |
|---|---|---|---|
work_dir | str | "" | Direktori kerja SDK |
enable_dump_audio | bool | False | Menentukan apakah akan mengaktifkan dump audio (untuk debugging) |
extras | str | "" | String parameter tambahan |
AoqConnectConfig
Bidang | Tipe | Nilai default | Deskripsi |
|---|---|---|---|
token | str | "" | Token otentikasi koneksi |
sid | str | "" | ID sesi |
certificate | str | "" | Sidik jari sertifikat server |
relay_endpoints | List[AoqRelayEndpoint] | None | Daftar titik akses relay |
workspace_id_hash | str | "" | Hash ID ruang kerja |
publish_tracks | List[AoqTrackParam] | None | Daftar track lokal yang diterbitkan |
subscribe_tracks | List[AoqTrackParam] | None | Daftar track lokal yang berlangganan |
AoqRelayEndpoint
Bidang | Tipe | Nilai default | Deskripsi |
|---|---|---|---|
endpoint | str | "" | Nama domain atau alamat IP server relay |
port | int | 0 | Port server relay |
route_index | int | -1 | Indeks path, yang disejajarkan dengan routeIndex di SDK platform lain. Jika nilainya kurang dari 0, SDK akan mengisinya secara otomatis berdasarkan subscript array. |
AoqTrackParam
Bidang | Tipe | Nilai default | Deskripsi |
|---|---|---|---|
track_type | AoqTrackType | AoqTrackType.AUDIO | Jenis track |
AoqDataMsg
Bidang | Tipe | Nilai default | Deskripsi |
|---|---|---|---|
data | bytes | b"" | Data pesan (string byte) |
Enumerasi
AoqErrorCode
Nilai enum | Nilai | Deskripsi |
|---|---|---|
OK | 0 | Berhasil |
PARAM_INVALID | 1 | Parameter tidak valid |
STATE_INVALID | 2 | Status tidak valid |
AUDIO | 100 | Error audio umum |
AUDIO_EXTERNAL_BUFFER_FULL | 110 | Buffer audio eksternal penuh |
AUDIO_DEVICE | 120 | Error perangkat audio umum |
AUDIO_DEVICE_RECORDING_AUTH_FAILED | 121 | Izin perekaman tidak diberikan |
AUDIO_DEVICE_RECORDING_OCCUPIED | 122 | Perangkat perekaman sedang digunakan |
AUDIO_DEVICE_RECORDING_START_FAIL | 124 | Gagal memulai perekaman |
AUDIO_DEVICE_PLAYOUT_OCCUPIED | 125 | Perangkat pemutaran sedang digunakan |
AUDIO_DEVICE_PLAYOUT_START_FAIL | 127 | Gagal memulai pemutaran |
VIDEO | 200 | Error video umum |
VIDEO_EXTERNAL_BUFFER_FULL | 210 | Buffer video eksternal penuh |
AoqConnectionStatus
Nilai enum | Nilai | Deskripsi |
|---|---|---|
DISCONNECTED | 0 | Terputus |
CONNECTING | 1 | Menghubungkan |
CONNECTED | 2 | Tersambung |
FAILED | 3 | Koneksi gagal |
AoqTrackType
Nilai enum | Nilai | Deskripsi |
|---|---|---|
AUDIO | 0 | Track audio |
VIDEO | 1 | Video Track |
DATA | 2 | Track pesan data |
AoqEncoderType
Nilai enum | Nilai | Deskripsi |
|---|---|---|
UNKNOWN | 0 | Format tidak diketahui |
AUDIO_PCM | 1 | Audio PCM |
AUDIO_OPUS | 2 | Audio Opus |
VIDEO_H264 | 3 | Video H.264 |
VIDEO_JPEG | 4 | Video JPEG |
DATA_TEXT | 5 | Teks pesan |
AoqMirrorMode
Nilai enum | Nilai | Deskripsi |
|---|---|---|
DISABLED | 0 | Menonaktifkan mirroring |
ENABLED | 1 | Mengaktifkan mirroring |
AoqOrientationMode
Nilai enum | Nilai | Deskripsi |
|---|---|---|
AUTO | 0 | Auto-fit |
PORTRAIT | 1 | Portrait |
LANDSCAPE | 2 | Landscape |
AoqRenderMode
Nilai enum | Nilai | Deskripsi |
|---|---|---|
AUTO | 0 | Mode adaptif |
STRETCH | 1 | Mode stretch |
FILL | 2 | Mode fill |
CROP | 3 | Mode crop |
AoqVideoPixelFormat
Nilai enum | Nilai | Deskripsi |
|---|---|---|
UNKNOWN | 0 | Format tidak diketahui |
I420 | 1 | I420 (format planar YUV) |
NV12 | 2 | NV12 (format semi-planar YUV) |
NV21 | 3 | NV21 (format semi-planar YUV) |
BGRA | 4 | BGRA (32-bit) |
RGBA | 5 | RGBA (32-bit) |
AoqCameraDirection
Nilai enum | Nilai | Deskripsi |
|---|---|---|
FRONT | 0 | Kamera depan (nilai enum generik platform; pengambilan kamera tidak didukung di Linux) |
BACK | 1 | Kamera belakang (nilai enum generik platform; pengambilan kamera tidak didukung di Linux) |
Tipe audio
AoqAudioCaptureConfig
Bidang | Tipe | Nilai default | Deskripsi |
|---|---|---|---|
is_external | bool | False | Menentukan apakah akan menggunakan mode pengambilan eksternal |
channel | int | 1 | Jumlah channel (mono secara default) |
AoqAudioPlaybackConfig
Bidang | Tipe | Nilai default | Deskripsi |
|---|---|---|---|
is_external | bool | False | Menentukan apakah akan menggunakan mode pemutaran eksternal |
channel | int | 1 | Jumlah channel (mono secara default) |
AoqAudioCodecConfig
Bidang | Type | Nilai default | Deskripsi |
|---|---|---|---|
track_type | AoqTrackType | AUDIO | Jenis track |
codec_type | AoqEncoderType | AUDIO_PCM | Format kodek |
sample_rate | int | 48000 | Laju sampel, dalam Hz |
channel | int | 1 | Jumlah channel |
bitrate | int | 32000 | Bitrate, dalam bit/s |
AoqAudioFileMixConfig
Bidang | Type | Nilai default | Deskripsi |
|---|---|---|---|
file_name | str | "" | Nama file (termasuk path). Tidak boleh kosong. |
cycles | int | -1 | Jumlah loop. -1 menunjukkan looping tak terbatas. |
start_pos_ms | int | 0 | Posisi mulai pemutaran, dalam milidetik |
publish_volume | int | 100 | Volume penerbitan. Nilai valid: 0 hingga 100. |
playout_volume | int | 100 | Volume pemutaran. Nilai valid: 0 hingga 100. |
AoqAudioExternalStreamConfig
Bidang | Tipe | Nilai default | Deskripsi |
|---|---|---|---|
track_type | AoqTrackType | AUDIO | Jenis track audio |
codec_type | AoqEncoderType | AUDIO_PCM | Format aliran audio |
channels | int | 1 | Jumlah channel |
sample_rate | int | 48000 | Laju sampel, dalam Hz |
playout_volume | int | 100 | Volume pemutaran. Nilai valid: 0 hingga 100. |
publish_volume | int | 100 | Volume penerbitan. Nilai valid: 0 hingga 100. |
max_buffer_duration | int | 1000 | Durasi buffer maksimum, dalam milidetik |
enable_3a | bool | False | Menentukan apakah akan menerapkan pemrosesan 3A pada PCM input |
AoqAudioFrameData
Data audio mentah, yang digunakan untuk input eksternal atau callback observer.
Bidang | Tipe | Nilai default | Deskripsi |
|---|---|---|---|
data | bytes | b"" | Data PCM audio mentah (salinan bytes dalam callback) |
num_of_samples | int | 0 | Jumlah sampel (per channel) |
bytes_per_sample | int | 0 | Byte per sampel |
num_of_channels | int | 0 | Jumlah channel |
samples_per_sec | int | 0 | Jumlah sampel per detik (laju sampel) |
push_sequence | int | 0 | Ronde input PCM |
time_stamp | int | 0 | Timestamp |
auto_gen_mute | bool | False | True menunjukkan data senyap yang dihasilkan oleh SDK |
AoqAudioObserverConfig
Bidang | Tipe | Nilai default | Deskripsi |
|---|---|---|---|
sample_rate | int | 48000 | Laju sampel audio callback, dalam Hz |
channels | int | 1 | Jumlah channel audio dalam callback |
mode | AoqAudioObserverMode | READ_ONLY | Mode baca-tulis |
AoqAudioStreamDirection
Nilai enum | Nilai | Deskripsi |
|---|---|---|
PUBLISH | 0 | Aliran penerbitan |
PLAYOUT | 1 | Aliran pemutaran (aliran berlangganan) |
AoqAudioExternalStreamToggle
Nilai enum | Nilai | Deskripsi |
|---|---|---|
NORMAL | 0 | Status normal |
PAUSE | 1 | Status dijeda |
AoqAudioSource
Nilai enum | Nilai | Deskripsi |
|---|---|---|
CAPTURED | 0 | Data audio yang diambil |
PROCESS_CAPTURED | 1 | Data audio setelah pemrosesan 3A |
PUBLISH | 2 | Data audio yang akan diterbitkan |
PLAYBACK | 3 | Data audio yang akan diputar |
AoqAudioObserverMode
Nilai enum | Nilai | Deskripsi |
|---|---|---|
READ_ONLY | 0 | Mode hanya baca |
READ_WRITE | 1 | Mode baca-tulis |
Tipe video
AoqVideoCaptureConfig
Bidang | Tipe | Nilai default | Deskripsi |
|---|---|---|---|
width | int | 1280 | Lebar pengambilan, dalam piksel. Parameter ini tidak berlaku saat is_external=True. |
height | int | 720 | Tinggi pengambilan, dalam piksel. Parameter ini tidak berlaku saat is_external=True. |
fps | int | 15 | Laju frame pengambilan. Parameter ini tidak berlaku saat is_external=True. |
is_external | bool | False | Menentukan apakah akan menggunakan pengambilan eksternal. Linux hanya mendukung True. Setelah Anda memanggil start_video_capture, berikan frame dengan memanggil push_external_video_frame. |
camera_direction | AoqCameraDirection | FRONT | Arah kamera untuk platform mobile. Linux tidak memiliki kemampuan yang sesuai. Pertahankan nilai FRONT. |
AoqVideoCodecConfig
Parameter kodek video, yang digunakan baik untuk pengkodean maupun dekode. Untuk dekode, hanya bidang track_type, codec_type, width, height, fps, dan bitrate yang berlaku; bidang lainnya hanya digunakan untuk pengkodean.
Bidang | Type | Nilai default | Deskripsi |
|---|---|---|---|
track_type | AoqTrackType | VIDEO | Jenis track |
codec_type | AoqEncoderType | VIDEO_H264 | Format kodek |
width | int | 540 | Lebar pengkodean, dalam piksel |
height | int | 960 | Tinggi pengkodean, dalam piksel |
fps | int | 5 | Laju frame pengkodean |
bitrate | int | 500000 | Bitrate target, dalam bit/s |
min_bitrate | int | 128000 | Bitrate minimum, dalam bit/s |
keyframe_interval | int | 2 | Interval keyframe, dalam detik |
mirror_mode | AoqMirrorMode | DISABLED | Mode mirror |
orientation_mode | AoqOrientationMode | AUTO | Mode orientasi video |
AoqVideoCanvas
Bidang | Type | Nilai default | Deskripsi |
|---|---|---|---|
view | int | 0 | Handle jendela rendering. Linux tidak memiliki backend rendering, sehingga bidang ini tidak berpengaruh. Pertahankan nilai 0. |
render_mode | AoqRenderMode | AUTO | Mode rendering. Linux tidak memiliki backend rendering, sehingga bidang ini tidak berpengaruh. |
AoqVideoFrame
Frame video eksternal atau data callback frame video. Untuk format packed (NV12/NV21/BGRA/RGBA), isi data. Untuk tiga plane I420, isi data_y/u/v beserta stride yang sesuai. Kedua metode ini saling eksklusif.
Bidang | Tipe | Nilai default | Deskripsi |
|---|---|---|---|
format | AoqVideoPixelFormat | UNKNOWN | Format piksel |
width | int | 0 | Lebar video, dalam piksel |
height | int | 0 | Tinggi video, dalam piksel |
data | bytes | b"" | Data format packed (NV12/NV21/BGRA/RGBA) |
data_y | bytes | b"" | Data plane Y I420 |
data_u | bytes | b"" | Data plane U I420 |
data_v | bytes | b"" | Data plane V I420 |
stride_y | int | 0 | Stride plane Y |
stride_u | int | 0 | Stride plane U |
stride_v | int | 0 | Stride plane V |
time_stamp | int | 0 | Timestamp, dalam milidetik. Jika bernilai 0, SDK akan mengisinya dengan jam lokal. |
AoqVideoEncodedFrame
Frame video terkode eksternal, seperti frame JPEG.
Bidang | Type | Nilai default | Deskripsi |
|---|---|---|---|
codec | AoqEncoderType | VIDEO_JPEG | Format kodek |
data | bytes | b"" | Data terkode |
width | int | 0 | Lebar, dalam piksel |
height | int | 0 | Tinggi, dalam piksel |
time_stamp | int | 0 | Timestamp, dalam milidetik. Jika bernilai 0, SDK akan mengisinya dengan jam lokal. |
AoqVideoObserverConfig
Bidang | Tipe | Nilai default | Deskripsi |
|---|---|---|---|
format | AoqVideoPixelFormat | I420 | Format piksel yang diharapkan dari data callback |
alignment | AoqVideoObserverAlignment | DEFAULT | Kebijakan penyelarasan lebar |
mode | AoqVideoObserverMode | READ_ONLY | Mode baca-tulis |
mirror_applied | bool | False | Menentukan apakah akan mencerminkan data callback |
AoqVideoSource
Nilai enum | Nilai | Deskripsi |
|---|---|---|
CAPTURED | 0 | Data video yang diambil sebelum preprocessing |
PRE_ENCODE | 1 | Data video sebelum pengkodean, setelah preprocessing |
REMOTE | 2 | Data video remote setelah dekode dan sebelum rendering |
AoqVideoObserverMode
Nilai enum | Nilai | Deskripsi |
|---|---|---|
READ_ONLY | 0 | Mode hanya baca |
READ_WRITE | 1 | Mode baca-tulis |
AoqVideoObserverAlignment
Nilai enum | Nilai | Deskripsi |
|---|---|---|
DEFAULT | 0 | Penyelarasan default |
EVEN | 1 | Penyelarasan angka genap |
ALIGN_4 | 2 | Penyelarasan 4-byte |
ALIGN_8 | 3 | Penyelarasan 8-byte |
ALIGN_16 | 4 | Penyelarasan 16-byte |