Operações comuns de áudio - ApsaraVideo Live: Central de Documentação do Alibaba Cloud

Configure a codificação de áudio, gerencie a captura e a reprodução, ative o monitoramento in-ear e defina o roteamento de áudio no ARTC SDK.

Visão geral

O ARTC SDK oferece suporte à codificação de áudio, seleção de modo de cenário, gerenciamento de captura e reprodução de áudio local, controle de reprodução de áudio remoto, monitoramento in-ear e configuração de roteamento de áudio.

Código de exemplo

Android: Android/ARTCExample/BasicUsage/src/main/java/com/aliyun/artc/api/basicusage/AudioBasicUsage/AudioBasicUsageActivity.java.

iOS: iOS/ARTCExample/BasicUsage/AudioBasicUsage/AudioBasicUsageVC.swift.

Harmony: Harmony/ARTCExample/entry/src/main/ets/pages/basicusage/AudioBasicUsage.ets.

Pré-requisitos

Tenha uma conta válida da Alibaba Cloud e crie um aplicativo do ApsaraVideo for RTC. Para mais informações, consulte Criar um aplicativo. Obtenha o AppID e a AppKey no console do ApsaraVideo Live.
Integre o ARTC SDK ao seu projeto e implemente os recursos básicos de áudio e vídeo em tempo real. Para obter detalhes sobre a integração do SDK, consulte Baixe e integre o SDK. Para implementar uma chamada de áudio e vídeo, consulte Implementar uma chamada de áudio e vídeo.

Implementação

1. Definir modos de codificação e cenário de áudio (antes de entrar em um canal)

O ARTC SDK permite definir o modo de codificação de áudio e o modo de cenário de áudio com o método setAudioProfile para otimizar a qualidade do áudio em diferentes cenários.

Nota

Chame setAudioProfile apenas antes de entrar em um canal. Não é possível alterar as configurações após a entrada.
Recomenda-se usar o modo de codificação de áudio de alta qualidade AliRtcEngineHighQualityMode e o modo de cenário de música AliRtcSceneMusicMode.

1,1. Modos de codificação de áudio (AliRtcAudioProfile)

Nota

Use o modo de alta qualidade (AliRtcEngineHighQualityMode).
Para interoperabilidade com clientes web, selecione um modo com taxa de amostragem de 48 kHz.
Para som estéreo, defina o modo como AliRtcEngineStereoHighQualityMode.

Enumeração	Descrição	Taxa de amostragem	Canais	Bitrate máximo
AliRtcEngineLowQualityMode	Modo de áudio de baixa qualidade	8000 Hz	Mono	12 kbps
AliRtcEngineBasicQualityMode	Modo de áudio de qualidade padrão	16000 Hz	Mono	24 kbps
AliRtcEngineHighQualityMode	Modo de áudio de alta qualidade	48000 Hz	Mono	64 kbps
AliRtcEngineStereoHighQualityMode	Modo de áudio estéreo de alta qualidade	48000 Hz	Estéreo	80 kbps
AliRtcEngineSuperHighQualityMode	Modo de áudio de altíssima qualidade	48000 Hz	Mono	96 kbps
AliRtcEngineStereoSuperHighQualityMode	Modo de áudio estéreo de altíssima qualidade	48000 Hz	Estéreo	128 kbps

1,2. Modos de cenário de áudio (AliRtcAudioScenario)

Enumeração	Descrição
AliRtcSceneDefaultMode	Modo padrão. Usa processamento 3A baseado em hardware e suporta captura de áudio de dispositivos Bluetooth. Use este modo para capturar áudio de um fone de ouvido Bluetooth.
AliRtcSceneMusicMode	(Recomendado) Cenário de música. Usa processamento 3A baseado em software e captura áudio do microfone integrado do dispositivo para maior fidelidade sonora.

1,3. Código de exemplo

Os exemplos a seguir mostram como configurar os modos de codificação e cenário de áudio para casos de uso comuns.

Para captura via Bluetooth

Android

// Set the audio scenario to AliRtcSceneDefaultMode.
mAliRtcEngine.setAudioProfile(AliRtcEngineHighQualityMode, AliRtcSceneDefaultMode);

iOS

// Set the audio scenario to AliRtcSceneDefaultMode.
engine.setAudioProfile(AliRtcAudioProfile.engineHighQualityMode, audio_scene: AliRtcAudioScenario.sceneDefaultMode)

Harmony

this.rtcEngine.setAudioProfile(AliRtcAudioProfile.AliRtcHighQualityMode, AliRtcAudioScenario.AliRtcSceneDefaultMode);

Mac

[self.engine setAudioProfile:AliRtcEngineHighQualityMode audio_scene:AliRtcSceneDefaultMode];

Windows

mAliRtcEngine->SetAudioProfile(AliEngineHighQualityMode, AliEngineSceneDefaultMode);

Para interoperabilidade com clientes web

Android

// Select an encoding mode with a 48 kHz sample rate, such as AliRtcEngineHighQualityMode.
mAliRtcEngine.setAudioProfile(AliRtcEngineHighQualityMode, AliRtcSceneMusicMode);

iOS

// Select an encoding mode with a 48 kHz sample rate, such as AliRtcEngineHighQualityMode.
engine.setAudioProfile(AliRtcAudioProfile.engineHighQualityMode, audio_scene: AliRtcAudioScenario.sceneMusicMode)

Harmony

this.rtcEngine.setAudioProfile(AliRtcAudioProfile.AliRtcHighQualityMode, AliRtcAudioScenario.AliRtcSceneMusicMode);

Mac

[self.engine setAudioProfile:AliRtcEngineHighQualityMode audio_scene:AliRtcSceneMusicMode];

Windows

mAliRtcEngine->SetAudioProfile(AliEngineHighQualityMode, AliEngineSceneMusicMode);

Para som estéreo

Android

// Set the mode to one that supports stereo, such as AliRtcEngineStereoHighQualityMode.
mAliRtcEngine.setAudioProfile(AliRtcEngineStereoHighQualityMode, AliRtcSceneMusicMode);

iOS

// Set the mode to one that supports stereo, such as AliRtcEngineStereoHighQualityMode.
engine.setAudioProfile(AliRtcAudioProfile.engineStereoHighQualityMode, audio_scene: AliRtcAudioScenario.sceneMusicMode)

Harmony

this.rtcEngine.setAudioProfile(AliRtcAudioProfile.AliRtcStereoHighQualityMode, AliRtcAudioScenario.AliRtcSceneMusicMode);

Mac

[self.engine setAudioProfile:AliRtcEngineStereoHighQualityMode audio_scene:AliRtcSceneMusicMode];

Windows

mAliRtcEngine->SetAudioProfile(AliEngineStereoHighQualityMode, AliEngineSceneMusicMode);

2. Captura de áudio local

Controle a captura de áudio local silenciando o microfone ou interrompendo a captura. A tabela a seguir compara as duas abordagens.

Método	`muteLocalMic`	`stopAudioCapture`/`startAudioCapture`
Funcionamento	Envia quadros silenciosos.	Interrompe ou inicia a captura do microfone.
Momento da chamada	Pode ser chamado antes ou depois de entrar em um canal.	Deve ser chamado após entrar em um canal.
Libera recursos do microfone	Não	Sim

2,1. Silenciar microfone local

Use o método muteLocalMic para silenciar o microfone local e a entrada de áudio externa. É possível chamar este método antes ou depois de entrar em um canal.

Nota

Diferentemente de stopAudioCapture, o método muteLocalMic não libera o recurso do microfone. Os módulos de captura e codificação continuam em execução, mas enviam quadros silenciosos com um bitrate extremamente baixo.

Os seguintes modos AliRtcMuteLocalAudioMode são suportados:

`AliRtcMuteAudioModeDefault`	Modo padrão. Mesmo comportamento de `AliRtcMuteAllAudioMode`.
`AliRtcMuteAllAudioMode`	Silencia todo o áudio. Interrompe a publicação de áudio tanto do microfone quanto da entrada PCM externa.
`AliRtcMuteOnlyMicAudioMode`	Silencia apenas o microfone. Interrompe a publicação de áudio capturado pelo microfone.

Código de exemplo:

Android

// Mute all audio
mAliRtcEngine.muteLocalMic(true, AliRtcEngine.AliRtcMuteLocalAudioMode.AliRtcMuteAllAudioMode);
// Unmute all audio
mAliRtcEngine.muteLocalMic(false, AliRtcEngine.AliRtcMuteLocalAudioMode.AliRtcMuteAllAudioMode);
// Mute only the microphone
mAliRtcEngine.muteLocalMic(true, AliRtcEngine.AliRtcMuteLocalAudioMode.AliRtcMuteOnlyMicAudioMode);

iOS

// Mute all audio
self.rtcEngine?.muteLocalMic(true, mode: .allAudioMode)
// Unmute all audio
self.rtcEngine?.muteLocalMic(false, mode: .allAudioMode)
// Mute only the microphone
self.rtcEngine?.muteLocalMic(true, mode: .onlyMicAudioMode)

Harmony

// Mute all audio
this.rtcEngine.muteLocalMic(true, AliRtcMuteLocalAudioMode.AliRtcMuteLocalAudioModeMuteAll);
// Unmute all audio
this.rtcEngine.muteLocalMic(false, AliRtcMuteLocalAudioMode.AliRtcMuteLocalAudioModeMuteAll);
// Mute only the microphone
this.rtcEngine.muteLocalMic(true, AliRtcMuteLocalAudioMode.AliRtcMuteLocalAudioModeMuteOnlyMic);

Mac

// Mute all audio
[self.engine muteLocalMic:TRUE mode:AliRtcMuteAllAudioMode];
// Unmute all audio
[self.engine muteLocalMic:FALSE mode:AliRtcMuteAllAudioMode];
// Mute only the microphone
[self.engine muteLocalMic:TRUE mode:AliRtcMuteOnlyMicAudioMode];

Windows

// Mute all audio
mAliRtcEngine->MuteLocalMic(true, AliEngineMuteLocalAudioModeMuteAll);
// Unmute all audio
mAliRtcEngine->MuteLocalMic(false, AliEngineMuteLocalAudioModeMuteAll);
// Mute only the microphone
mAliRtcEngine->MuteLocalMic(true, AliEngineMuteLocalAudioModeMuteOnlyMic);

2,2. Interromper ou retomar a captura do microfone

O SDK ativa a captura do microfone por padrão ao entrar em um canal. Para interromper a captura, chame stopAudioCapture. Essa chamada interrompe a captura de áudio e libera o recurso do microfone. Para retomar a captura, chame startAudioCapture.

Android

// Stop microphone capture.
mAliRtcEngine.stopAudioCapture();
// Resume microphone capture.
mAliRtcEngine.startAudioCapture();

iOS

// Stop microphone capture.
self.rtcEngine?.stopAudioCapture()
// Resume microphone capture.
self.rtcEngine?.startAudioCapture()

Harmony

// Stop microphone capture.
this.rtcEngine.stopAudioCapture();
// Resume microphone capture.
this.rtcEngine.startAudioCapture();

Mac

// Stop microphone capture.
[self.engine stopAudioCapture];
// Resume microphone capture.
[self.engine startAudioCapture];

Windows

// Stop microphone capture.
mAliRtcEngine->StopAudioCapture();
// Resume microphone capture.
mAliRtcEngine->StartAudioCapture();

3. Configurações de reprodução de áudio remoto

Controle o volume e o status de mudo da reprodução de áudio remoto.

3,1. Silenciar um usuário remoto

Use o método muteRemoteAudioPlaying para interromper ou retomar a reprodução de áudio de um usuário remoto específico.

public abstract int muteRemoteAudioPlaying(String uid, boolean mute);

Silenciar não afeta o recebimento e a decodificação do fluxo de áudio. Você pode definir essa configuração antes ou depois de entrar em uma sessão.
O silenciamento afeta apenas a reprodução local do áudio do usuário remoto, sem interferir na captura de áudio desse usuário.

3,2. Definir o volume de reprodução para um usuário remoto específico

Use o método setPlayoutVolume para controlar o volume de reprodução local.

/**
 * @brief Sets the playback volume.
 * @param volume The playback volume. The value ranges from 0 to 400.
 * - 0: Mute.
 * - <100: Decreases the volume.
 * - >100: Increases the volume.
 * @return
 * - 0: Success.
 * - A non-zero value: Failure.
 */
public abstract int setPlayoutVolume(int volume);

Use o método setRemoteAudioVolume para ajustar o volume de reprodução de áudio de um usuário remoto específico. Definir o volume como 0 produz o mesmo efeito que muteRemoteAudioPlaying.

/**
 * @brief Adjusts the volume of a specific remote user for local playback.
 * @param uid The user ID. This is a unique identifier assigned by your app server.
 * @param volume The playback volume. The value ranges from 0 to 100, where 0 means mute and 100 means the original volume.
 * @return
 * - 0: Success.
 * - A non-zero value: Failure.
 */
public abstract int setRemoteAudioVolume(String uid, int volume);

4. Monitoramento in-ear

O monitoramento in-ear permite ouvir o áudio do microfone pelos fones de ouvido em tempo real.

4,1. Ativar monitoramento in-ear

Chame o método enableEarBack antes ou depois de entrar em um canal para ativar o monitoramento in-ear. Para desativá-lo, chame enableEarBack novamente e defina o parâmetro como false.

Nota

Use fones de ouvido quando o monitoramento in-ear estiver ativado.

Android

rtcEngine.enableEarBack(true);

iOS

engine.enableEarBack(true)

Harmony

this.rtcEngine.enableEarBack(true);

Mac

[self.engine enableEarBack:YES];

Windows

mAliRtcEngine->EnableEarBack(TRUE);

4,2. Definir o volume do monitoramento in-ear

Chame o método setEarBackVolume para ajustar o volume do monitoramento in-ear. O parâmetro volume define o nível em uma escala de 0 a 100, onde 0 representa mudo e 100 o volume original. O valor padrão é 100.

Android

rtcEngine.setEarBackVolume(60);

iOS

rtcEngine?.setEarBackVolume(volume)

Harmony

this.rtcEngine.setEarBackVolume(value);

Mac

[self.engine setEarBackVolume:60];

Windows

mAliRtcEngine->SetEarBackVolume(volume);

5. Callbacks de volume do usuário e falante ativo

O ARTC fornece callbacks de volume do usuário e de falante ativo para detectar o status de fala dos usuários em tempo real.

Nota

Este recurso vem desativado por padrão. Chame enableAudioVolumeIndication para ativá-lo. Após a ativação, o sistema relata periodicamente o volume em tempo real de cada usuário e o falante ativo atual na frequência especificada. Use esses dados para impulsionar interações na UI.

5,1. Ativar o recurso de callback

Chame enableAudioVolumeIndication para habilitar o recurso e configurar os seguintes parâmetros:

interval: Intervalo do callback em milissegundos (ms). A faixa recomendada é de 300 ms a 500 ms. O valor mínimo é 10 ms. Um valor negativo desativa este recurso.
smooth: Fator de suavização. Um valor maior resulta em mudanças de volume mais suaves, enquanto um valor menor oferece melhor desempenho em tempo real. O valor recomendado é 3. A faixa válida vai de 0 a 9.
reportVad: Interruptor para detecção de falante ativo. Defina como 0 para desativar ou 1 para ativar.

Android

mAliRtcEngine.enableAudioVolumeIndication(500, 3,1);

iOS

// User volume callback and active speaker detection
engine.enableAudioVolumeIndication(500, smooth: 3, reportVad: 1)

Harmony

// User volume callback and active speaker detection
this.rtcEngine.enableAudioVolumeIndication(1000, 3, 1);

Mac

// User volume callback and active speaker detection
[self.engine enableAudioVolumeIndication:500 smooth:3 reportVad:1];

Windows

// User volume callback and active speaker detection
mAliRtcEngine->EnableAudioVolumeIndication(500, 3, 1);

5,2. Implementar e registrar callbacks

Chame o método registerAudioVolumeObserver para registrar os callbacks. O sistema então aciona os seguintes callbacks no intervalo especificado:

onAudioVolume: Relata periodicamente informações de volume de áudio para todos os usuários detectados, incluindo locais e remotos. Use isso para implementar feedback na UI, como animações de ondas sonoras ou indicadores de volume. Se mUserId for "0", a entrada refere-se ao volume capturado localmente. Se mUserId for "1", refere-se ao volume mixado de todos os usuários remotos. Outros valores indicam o volume de um usuário específico. totalVolume indica o volume total mixado de todos os usuários remotos.
onActiveSpeaker: Acionado pela detecção de atividade de voz (VAD) quando um usuário se torna o falante mais ativo com base no volume e duração da fala. Utilize para implementar recursos como foco automático no falante ativo durante uma conferência.

Android

private final AliRtcEngine.AliRtcAudioVolumeObserver mAliRtcAudioVolumeObserver = new AliRtcEngine.AliRtcAudioVolumeObserver() {
    // User volume callback
    @Override
    public void onAudioVolume(List<AliRtcEngine.AliRtcAudioVolume> speakers, int totalVolume){
        handler.post(() -> {
            if(!speakers.isEmpty()) {
                for(AliRtcEngine.AliRtcAudioVolume volume : speakers) {
                    if("0".equals(volume.mUserId)) {
                        // Volume of the local user

                    } else if ("1".equals(volume.mUserId)) {
                        // Overall volume of remote users

                    } else {
                        // Volume of a remote user

                    }
                }
            }
        });
    }

    // Active speaker detection callback
    @Override
    public void onActiveSpeaker(String uid){
        // Active speaker
        handler.post(() -> {
            String mag = "onActiveSpeaker uid:" + uid;
            ToastHelper.showToast(AudioBasicUsageActivity.this, mag, Toast.LENGTH_SHORT);
        });
    }
};
// Register the callback
mAliRtcEngine.registerAudioVolumeObserver(mAliRtcAudioVolumeObserver);

iOS

Nota

No iOS, não é necessário chamar um método para registrar os callbacks. Basta implementar os seguintes callbacks:

onAudioVolumeCallback
onActiveSpeaker

func onAudioVolumeCallback(_ array: [AliRtcUserVolumeInfo]?, totalVolume: Int32) {
    // User volume callback
    "onAudioVolumeCallback, totalVolume: \(totalVolume)".printLog()
}

func onActiveSpeaker(_ uid: String) {
    // Active speaker callback
    "onActiveSpeaker, uid: \(uid)".printLog()
}

Harmony

this.rtcEngineEventListener.onAudioVolumeCallback(
  (volumeInfo : AliRtcUserVolumeInfo[], volumeInfoCount : number, totalVolume : number) => {
    console.info(`Volume callback: volumeInfo=${volumeInfo}, volumeInfoCount=${volumeInfoCount}, totalVolume=${totalVolume}`);
  }
)

this.rtcEngineEventListener.onActiveSpeaker((uid: string) => {
  console.info(`Current active user: uid=${uid}`);
});

Mac

- (void)onAudioVolumeCallback:(NSArray <AliRtcUserVolumeInfo *> *)array totalVolume:(int)totalVolume {
    for(AliRtcUserVolumeInfo *info in array) {
        NSString *uid = info.uid;
        NSInteger volume = info.volume;
        dispatch_async(dispatch_get_main_queue(), ^{
            NSArray * volumeArray = [ _audioVolumeLabel.stringValue componentsSeparatedByString:@"\n"];

            if ([uid isEqualToString:@"1"]) { // Volume of remote users
                // Overall volume of remote users
            }else if ([uid isEqualToString:@"0"] ){ // Volume of the local user
                // Display the volume of the local user
            } else {

                // Overall volume of remote users
            }
        });
    }
}

- (void)onActiveSpeaker:(NSString *)uid {
    if ([uid isEqualToString:@"0"]) {
        [self log:[@"Active speaker: Self" UTF8String]];
    } else {
        NSDictionary *dic = [self.engine getUserInfo:uid];
        NSString *name = dic[@"displayName"];
        MyLog(@"Active speaker: %@",name);
    }
}

Windows

void CTutorialDlg::OnAudioVolumeCallback(const AliEngineUserVolumeInfo* volumeInfo, int volumeInfoCount, int totalVolume)
{
	CArray<AliEngineUserVolumeInfo*>* pArray = new CArray<AliEngineUserVolumeInfo*>;
	for (int i = 0; i < volumeInfoCount; i++)
	{
		AliEngineUserVolumeInfo* p = new AliEngineUserVolumeInfo;
		p->uid = volumeInfo[i].uid;
		p->volume = volumeInfo[i].volume;
		p->speechState = volumeInfo[i].speechState;
		p->sumVolume = volumeInfo[i].sumVolume;
		pArray->Add(p);
	}
    /* Notify the UI to refresh */
	PostMessage(MM_VOLUME_CALLBACK, (WPARAM)totalVolume, (LPARAM)pArray);
}

void CTutorialDlg::OnActiveSpeaker(const char *uid)
{
	m_strCurSpeaker = CString(uid);
    /* Notify the UI to refresh  */
	PostMessage(MM_ACTIVE_SPEAKER, NULL, NULL);
}

6. Configurar roteamento de áudio

O roteamento de áudio determina o dispositivo de reprodução durante uma chamada. Os tipos de dispositivo incluem:

Dispositivos de reprodução internos: Geralmente incluem o alto-falante e o auricular.
- Quando o áudio é direcionado ao alto-falante, o volume é suficiente para ouvir sem aproximar o telefone do ouvido, permitindo o uso do viva-voz.
- Ao direcionar o áudio para o auricular, o volume é mais baixo. É necessário segurar o telefone junto ao ouvido para ouvir claramente, o que garante maior privacidade e é ideal para atender chamadas.
Dispositivos externos: Incluem periféricos como fones de ouvido com fio e headsets Bluetooth, além de interfaces profissionais como placas de som externas.

O SDK troca automaticamente de dispositivo com base no status de conexão dos periféricos. O fluxograma abaixo ilustra esse processo:

6,1. Rota de áudio padrão

Defina a rota de áudio padrão como auricular ou alto-falante antes de entrar em um canal. Caso não seja definida, o alto-falante será utilizado.

Nota

Quando periféricos como headsets Bluetooth ou fones com fio forem desconectados, o áudio será reproduzido pelo dispositivo configurado nesta função.
Se nenhum dispositivo externo estiver conectado e o usuário não tiver definido um dispositivo atual, a configuração padrão do SDK será usada. O SDK utiliza o alto-falante como saída padrão. Para alterar essa configuração, chame setDefaultAudioRoutetoSpeakerphone.

/**
* @brief Sets whether the default audio output is the speaker. The default is the speaker.
* @param defaultToSpeakerphone
* - true: Speaker mode.
* - false: Earpiece mode.
* @return
* - 0: Success.
* - <0: Failure.
*/
public int setDefaultAudioRoutetoSpeakerphone(boolean defaultToSpeakerphone);

6,2. Rota de áudio atual

Defina a rota de áudio atual como auricular ou alto-falante durante uma chamada. Se não for definida, a rota de áudio padrão será utilizada.

Nota

Esta função não tem efeito quando um dispositivo periférico, como fones de ouvido com fio ou headset Bluetooth, está conectado.

Quando nenhum dispositivo externo estiver conectado, chame enableSpeakerphone para usar o alto-falante. Defina como false para usar o auricular. Para verificar se o dispositivo de áudio atual é o alto-falante ou o auricular, chame a interface isSpeakerOn.

/**
 * @brief Sets the audio output to the earpiece or the speaker.
 * @param enable   true: Speaker mode. false: Earpiece mode.
 * @return
 * - 0: Success.
 * - <0: Failure.
 */
public int enableSpeakerphone(boolean enable);
/**
* @brief Gets whether the current audio output is the earpiece or the speaker.
* @return 
* - true: Speaker mode.
* - false: Earpiece mode.
*/
public boolean isSpeakerOn();

6,3. Callback de alteração de rota de áudio

Registre e monitore o seguinte callback para receber notificações quando o dispositivo de reprodução de áudio mudar.

public abstract class AliRtcEngineEventListener {
    /**
     * @brief Warning notification.
     * @details Notifies the app through this callback if a warning occurs in the engine.
     * @param warn The warning type.
     * @param message The warning message.
     */
    public void onOccurWarning(int warn, String message);
}

A tabela a seguir mostra o mapeamento entre os valores de retorno de warn e os tipos de dispositivo.

Valor de retorno	Dispositivo
1	Fone de ouvido com fio com microfone
2	Auricular
3	Fone de ouvido com fio sem microfone
4	Alto-falante
6	Dispositivo Bluetooth SCO
7	Dispositivo Bluetooth A2DP