All Products
Search

This Product

    Alibaba Cloud Model Studio:Fitur audio umum

    Document Center

    Alibaba Cloud Model Studio:Fitur audio umum

    Last Updated:Sep 02, 2026

    AOQ Client SDK menyediakan kemampuan audio yang komprehensif, mencakup audio capture, playback, konfigurasi codec, manajemen speaker, mixing file, injeksi aliran audio eksternal, dan callback data frame audio. Dokumen ini memperkenalkan fitur audio umum untuk Android (Java), iOS (Objective-C), dan HarmonyOS (ArkTS).

    Audio capture

    Audio capture membuka mikrofon perangkat dan mengalirkan data audio real-time ke pipeline encoding SDK. SDK mendukung dua mode capture:

    • Internal capture (default): SDK secara otomatis mengelola mikrofon—membuka, merekam, dan menutupnya.
    • External capture: Aplikasi mengelola mikrofon secara langsung dan mengalirkan data PCM hasil capture ke SDK melalui API external audio stream.

    Parameter konfigurasi

    Parameter

    Type

    Default

    Description

    isExternal

    bool

    false

    Apakah akan menggunakan mode external capture

    isVoipMode

    bool

    false

    Apakah akan mengaktifkan mode VoIP (hardware AEC). Berlaku di perangkat mobile. Jika konfigurasi capture dan playback keduanya diatur, pengaturan yang pertama kali ditetapkan akan berlaku.

    channel

    int

    1

    Jumlah channel capture. Mendukung 1 (mono) atau 2 (stereo).

    Referensi API

    Function

    Android

    iOS

    HarmonyOS

    Start capture

    startAudioCapture(config)

    startAudioCapture:config:

    startAudioCapture(config)

    Stop capture

    stopAudioCapture()

    stopAudioCapture

    stopAudioCapture()

    Mute/unmute

    muteAudioCapture(mute)

    muteAudioCapture:

    muteAudioCapture(mute)

    Contoh

    Android 
    AoqAudioCaptureConfig config = new AoqAudioCaptureConfig();
config.isVoipMode = true;
config.channel = 1;
engine.startAudioCapture(config);
    iOS 
    AoqAudioCaptureConfig *config = [[AoqAudioCaptureConfig alloc] init];
config.isVoipMode = YES;
config.channel = 1;
[engine startAudioCapture:config];
    HarmonyOS 
    const config: AoqAudioCaptureConfig = { isVoipMode: true, channel: 1 };
engine.startAudioCapture(config);

    Audio playback

    Audio playback merender data audio remote yang diterima ke speaker atau headset lokal. SDK mendukung kontrol lanjutan, termasuk pause/resume dengan fade in/out serta interupsi giliran percakapan audio saat ini.

    Parameter konfigurasi

    Parameter

    Type

    Default

    Description

    isVoipMode

    bool

    false

    Apakah akan mengaktifkan mode VoIP (hardware AEC). Berlaku di perangkat mobile. Jika konfigurasi capture dan playback keduanya diatur, pengaturan yang pertama kali ditetapkan akan berlaku.

    isDefaultSpeaker

    bool

    true

    Apakah akan menggunakan speaker secara default. Berlaku di perangkat mobile dan hanya dalam mode non-VoIP.

    isExternal

    bool

    false

    Apakah akan menggunakan mode playback eksternal.

    channel

    int

    1

    Jumlah channel playback. Mendukung 1 (mono) atau 2 (stereo).

    Referensi API

    Function

    Android

    iOS

    HarmonyOS

    Start playback

    startAudioPlayer(config)

    startAudioPlayer:config:

    startAudioPlayer(config)

    Stop playback

    stopAudioPlayer()

    stopAudioPlayer

    stopAudioPlayer()

    Pause playback

    pauseAudioPlayer(fadeMs)

    pauseAudioPlayer:

    pauseAudioPlayer(fadeMs)

    Resume playback

    resumeAudioPlayer(fadeMs)

    resumeAudioPlayer:

    resumeAudioPlayer(fadeMs)

    Interrupt conversation

    interruptAudioPlayer(trackType, fadeMs)

    interruptAudioPlayer:fadeMs:

    interruptAudioPlayer(trackType, fadeMs)

    CatatanParameter fadeMs: Durasi fade-in atau fade-out dalam milidetik saat menjeda atau melanjutkan playback. Atur ke 0 untuk pergantian langsung.

    Manajemen speaker

    Beralih perangkat output audio antara speaker dan earpiece.

    Function

    Android

    iOS

    HarmonyOS

    Switch speaker

    enableSpeakerphone(enable)

    enableSpeakerphone:

    enableSpeakerphone(enable)

    Query speaker state

    isSpeakerphoneEnabled()

    isSpeakerphoneEnabled

    isSpeakerphoneEnabled()

    CatatanPengalihan speaker hanya diizinkan dalam mode VoIP. Di luar mode VoIP, pemanggilan enableSpeakerphone akan memicu Notifikasi kesalahan OnError(AoqECAudioDeviceEarpieceRequiresVoipMode).

    CatatanPerilaku khusus iOS: Perangkat iPad hanya memiliki mode speaker. Jika kategori AVAudioSession bukan PlayAndRecord, metode ini selalu mengembalikan YES.

    Konfigurasi codec audio

    Konfigurasikan format encoding, laju sampel, jumlah channel, dan bitrate untuk uplink audio (encoder) dan downlink (decoder). Pengaturan ini menentukan format untuk publishing dan pulling stream.

    Parameter konfigurasi

    Parameter

    Type

    Default

    Description

    trackType

    AoqTrackType

    Audio

    Tipe track audio. Saat ini hanya satu aliran audio yang didukung.

    codecType

    AoqEncoderType

    AudioPCM

    Tipe encoding: AudioPCM(1) atau AudioOpus(2)

    sampleRate

    int

    48000

    Laju sampel. Opus mendukung 8K/16K/48K. PCM mendukung 8K/16K/32K/48K.

    channel

    int

    1

    Jumlah channel. Mendukung 1 (mono) atau 2 (stereo).

    bitrate

    int

    32000

    Bitrate dalam bps.

    Referensi API

    Function

    Android

    iOS

    HarmonyOS

    Set encoder config

    setAudioEncoderConfig(config)

    setAudioEncoderConfig:

    setAudioEncoderConfig(config)

    Set decoder config

    setAudioDecoderConfig(config)

    setAudioDecoderConfig:

    setAudioDecoderConfig(config)

    Format encoding yang didukung

    Enum value

    Number

    Description

    AoqEncoderTypeAudioPCM

    1

    Raw PCM audio

    AoqEncoderTypeAudioOpus

    2

    Opus encoding

    Mixing file audio

    Mix file audio lokal ke dalam aliran audio saat ini untuk publishing dan/atau playback lokal. Setiap file audio diidentifikasi oleh fileId yang ditetapkan aplikasi, sehingga memungkinkan pengelolaan beberapa instance file secara bersamaan.

    Parameter konfigurasi mixing

    Parameter

    Type

    Default

    Description

    fileName

    String

    -

    Jalur file audio (termasuk nama file)

    cycles

    int

    -1

    Jumlah loop. -1 berarti loop tanpa henti.

    startPosMs

    long

    0

    Posisi mulai playback dalam milidetik

    publishVolume

    int

    100

    Volume publishing [0–100]

    playoutVolume

    int

    100

    Volume playback lokal [0–100]

    Referensi API

    Function

    Android

    iOS

    HarmonyOS

    Start playback

    startAudioFile(fileId, config)

    startAudioFile:config:

    startAudioFile(fileId, config)

    Stop playback

    stopAudioFile(fileId)

    stopAudioFile:

    stopAudioFile(fileId)

    Pause

    pauseAudioFile(fileId)

    pauseAudioFile:

    pauseAudioFile(fileId)

    Resume

    resumeAudioFile(fileId)

    resumeAudioFile:

    resumeAudioFile(fileId)

    Get file duration

    getAudioFileDuration(fileId)

    getAudioFileDuration:

    getAudioFileDuration(fileId)

    Get current position

    getAudioFileCurrentPosition(fileId)

    getAudioFileCurrentPosition:

    getAudioFileCurrentPosition(fileId)

    Seek to position

    setAudioFilePositionMillis(fileId, pos)

    setAudioFilePositionMillis:positionMillis:

    setAudioFilePositionMillis(fileId, pos)

    Set volume

    setAudioFileVolume(fileId, type, vol)

    setAudioFileVolume:type:volume:

    setAudioFileVolume(fileId, type, vol)

    Get volume

    getAudioFileVolume(fileId, type)

    getAudioFileVolume:type:

    getAudioFileVolume(fileId, type)

    CatatanArah volume (type): AoqAudioStreamPublish(0) mengontrol volume publishing. AoqAudioStreamPlayout(1) mengontrol volume playback lokal.

    Callback status

    State code

    Value

    Description

    AoqAudioFileNone

    0

    Status awal

    AoqAudioFileStarted

    1

    Playback dimulai

    AoqAudioFileStopped

    2

    Playback dihentikan

    AoqAudioFilePaused

    3

    Playback dijeda

    AoqAudioFileResumed

    4

    Playback dilanjutkan

    AoqAudioFileEnded

    5

    Playback selesai

    AoqAudioFileBuffering

    6

    Buffering

    AoqAudioFileBufferingEnd

    7

    Buffering selesai

    AoqAudioFileFailed

    8

    Playback gagal

    Aliran audio eksternal

    Aliran audio eksternal memungkinkan Anda menginjeksikan data audio PCM yang dihasilkan aplikasi ke pipeline audio SDK untuk publishing dan/atau playback lokal. Kasus penggunaan umum mencakup output sintesis TTS, output audio model AI, dan efek suara latar. Setiap aliran audio eksternal diidentifikasi oleh streamId yang ditetapkan aplikasi.

    Parameter konfigurasi

    Parameter

    Type

    Default

    Description

    trackType

    AoqTrackType

    Audio

    Tipe track audio

    codecType

    AoqEncoderType

    AudioPCM

    Format aliran audio

    channels

    int

    1

    Jumlah channel

    sampleRate

    int

    48000

    Laju sampel. Mendukung 8/12/16/24/32/44.1/48/64/88.2/96/176.4/192 kHz.

    playoutVolume

    int

    100

    Volume playback lokal [0–100]

    publishVolume

    int

    100

    Volume publishing [0–100]

    maxBufferDuration

    int

    600000

    Durasi buffer maksimum dalam milidetik. Rentang valid: [100, ~]. Push gagal jika buffer penuh.

    enable3A

    bool

    false

    Apakah akan menerapkan pemrosesan 3A pada input PCM

    Referensi API

    Function

    Android

    iOS

    HarmonyOS

    Add external stream

    addAudioExternalStream(streamId, config)

    addAudioExternalStream:config:

    addAudioExternalStream(streamId, config)

    Push audio data

    pushAudioExternalStreamData(streamId, data)

    pushAudioExternalStreamData:data:

    pushAudioExternalStreamData(streamId, data)

    Set volume

    setAudioExternalStreamVolume(streamId, type, vol)

    setAudioExternalStreamVolume:type:volume:

    setAudioExternalStreamVolume(streamId, type, vol)

    Get volume

    getAudioExternalStreamVolume(streamId, type)

    getAudioExternalStreamVolume:type:

    getAudioExternalStreamVolume(streamId, type)

    Clear buffer

    clearAudioExternalStreamBuffer(streamId, fadeoutMs)

    clearAudioExternalStreamBuffer:fadeoutMs:

    clearAudioExternalStreamBuffer(streamId, fadeoutMs)

    Remove stream

    removeAudioExternalStream(streamId)

    removeAudioExternalStream:

    removeAudioExternalStream(streamId)

    Praktik terbaik untuk push data

    • Panggil pushAudioExternalStreamData dalam loop untuk memastikan data berhasil dipush.
    • Jika kode kesalahan 110 (buffer penuh) dikembalikan, tunggu selama 30 ms lalu coba lagi. Jangan buang data.
    • Sebelum engine keluar, hentikan loop push terlebih dahulu, lalu panggil removeAudioExternalStream.
    • Untuk capture real-time, setiap frame berdurasi 10 ms—panggil push setiap kali data tersedia. Untuk input berbasis file, setiap frame berdurasi 40 ms—panggil push sekali setiap 30 ms.

    Panggilan balik frame audio

    Callback frame audio memungkinkan Anda memperoleh data PCM mentah pada berbagai titik dalam pipeline audio untuk digunakan dalam analisis audio, pemrosesan kustom, perekaman, dan skenario serupa.

    Posisi sumber data yang didukung

    Data source

    Enum value

    Description

    Captured

    0

    Data audio mentah setelah capture, sebelum pemrosesan 3A

    ProcessCaptured

    1

    Data audio setelah pemrosesan 3A. Callback dimulai hanya setelah koneksi berhasil.

    Publish

    2

    Data audio yang akan dipublikasikan. Memerlukan koneksi yang berhasil.

    Playback

    3

    Data audio yang akan diputar (downlink remote)

    Parameter konfigurasi callback

    Parameter

    Type

    Default

    Description

    sampleRate

    int

    48000

    Laju sampel untuk audio callback

    channels

    int

    1

    Jumlah channel untuk audio callback. Mendukung 1 atau 2.

    mode

    AoqAudioObserverMode

    ReadOnly

    Mode read-only (0) atau read-write (1)

    Langkah penggunaan

    1. Daftarkan observer: Panggil setAudioFrameObserver untuk mengatur listener callback frame audio.
    2. Aktifkan sumber data: Panggil enableAudioFrameObserver untuk memilih posisi sumber data dan memulai callback.
    3. Proses data callback: Proses data PCM dalam callback.

    Referensi API

    Function

    Android

    iOS

    HarmonyOS

    Register observer

    setAudioFrameObserver(listener)

    setAudioFrameObserver:

    setAudioFrameObserver(observer)

    Enable callbacks

    enableAudioFrameObserver(enabled, source, config)

    enableAudioFrameObserver:audioSource:config:

    enableAudioFrameObserver(enabled, source, config)

    Metode callback

    Callback

    Android

    iOS

    HarmonyOS

    Captured data

    onCapturedAudioFrame(frame)

    onCapturedAudioFrame:

    onCapturedAudioFrame(frame)

    Post-3A data

    onProcessCapturedAudioFrame(frame)

    onProcessCapturedAudioFrame:

    onProcessCapturedAudioFrame(frame)

    Publish data

    onPublishAudioFrame(trackType, frame)

    onPublishAudioFrame:frame:

    onPublishAudioFrame(trackType, frame)

    Playback data

    onPlaybackAudioFrame(frame)

    onPlaybackAudioFrame:

    onPlaybackAudioFrame(frame)

    Status dan routing audio

    SDK secara otomatis memantau perubahan status perangkat audio dan pergantian routing, serta memberi tahu lapisan aplikasi melalui callback.

    Kode status perangkat

    State code

    Value

    Description

    AoqAudioDeviceNone

    0

    Status awal

    RecordStarting

    1

    Capture dimulai

    RecordStarted

    2

    Capture dimulai

    RecordStopping

    3

    Capture dihentikan

    RecordStopped

    4

    Capture dihentikan

    RecordFail

    5

    Capture gagal

    PlayStarting

    6

    Playback dimulai

    PlayStarted

    7

    Playback dimulai

    PlayStopping

    8

    Playback dihentikan

    PlayStopped

    9

    Playback dihentikan

    PlayFail

    10

    Playback gagal

    Jenis routing perangkat

    Route

    Value

    Description

    Default

    0

    Default

    Headset

    1

    Headset kabel

    Earpiece

    2

    Earpiece

    HeadsetNoMic

    3

    Headset tanpa mikrofon

    SpeakerPhone

    4

    Speaker

    Usb

    5

    Perangkat USB

    Bluetooth

    6

    Bluetooth SCO

    BluetoothA2dp

    7

    Bluetooth A2DP

    Referensi callback

    Callback

    Android

    iOS

    HarmonyOS

    Device state change

    onAudioDeviceStateChanged(state)

    onAudioDeviceStateChanged:

    onAudioDeviceStateChanged(state, reason)

    Route change

    onAudioDeviceRouteChanged(routeType)

    onAudioDeviceRouteChanged:

    onAudioDeviceRouteChanged(routeType)

    Device interrupted

    onAudioDeviceInterrupted(interrupt)

    onAudioDeviceInterrupted:

    onAudioDeviceInterrupted(interrupt)

    File state

    onAudioFileState(state)

    onAudioFileState:

    onAudioFileState(fileId, stateCode, errorCode)

    Kode kesalahan dan peringatan audio

    Kode kesalahan audio

    Error code

    Value

    Description

    AoqErrorCodeAudio

    100

    Kesalahan audio umum

    AudioExternalBufferFull

    110

    Buffer eksternal penuh

    AudioDevice

    120

    Kesalahan perangkat umum

    RecordingAuthFailed

    121

    Izin mikrofon ditolak

    RecordingOccupied

    122

    Mikrofon sedang digunakan oleh proses lain

    RecordingBackgroundStart

    123

    Memulai perekaman di latar belakang

    RecordingStartFail

    124

    Gagal memulai perekaman

    PlayoutOccupied

    125

    Perangkat playback sedang digunakan oleh proses lain

    PlayoutBackgroundStart

    126

    Memulai playback di latar belakang

    PlayoutStartFail

    127

    Gagal memulai playback

    EarpieceRequiresVoipMode

    128

    Earpiece memerlukan mode VoIP agar diaktifkan

    Kode peringatan audio

    Warning code

    Value

    Description

    AoqWCAudio

    100

    Peringatan audio umum

    AudioHowling

    101

    Howling terdeteksi

    AudioDevice

    120

    Peringatan perangkat umum

    MicEnumerateError

    121

    Kesalahan enumerasi mikrofon

    MicStartTimeout

    122

    Timeout saat memulai mikrofon

    RecordingError

    123

    Kesalahan perekaman

    SpeakerEnumerateError

    124

    Kesalahan enumerasi speaker

    SpeakerStartTimeout

    125

    Timeout saat memulai speaker

    PlayoutError

    126

    Kesalahan playback

    Hanya iOS: Kontrol AVAudioSession

    Di iOS, API setAudioSessionRestriction memberikan kontrol detail halus atas cara SDK mengelola AVAudioSession sistem.

    Control

    Description

    SetCategory

    Apakah SDK dapat mengatur kategori sesi

    ConfigureSession

    Apakah SDK dapat mengonfigurasi parameter sesi

    DeactivateSession

    Apakah SDK dapat menonaktifkan sesi

    ActivateSession

    Apakah SDK dapat mengaktifkan sesi

    Gunakan kombinasi bitwise dari nilai restriksi untuk membatasi kontrol SDK atas AVAudioSession dan mencegah konflik dengan komponen audio lain di lapisan aplikasi.