Configure video capture, encoding, and display - ARTC SDK - ApsaraVideo Live: Central de Documentação do Alibaba Cloud

1. Defina configuração de captura da câmera

Use setCameraCapturerConfiguration para definir a direção da câmera e a taxa de quadros de captura.

Nota

Chame este método antes de iniciar a câmera, por exemplo, antes de chamar startPreview ou joinChannel (que inicia a câmera automaticamente).
Chamar enableLocalVideo(false) para desativar a captura da câmera libera os recursos da câmera. Em seguida, redefina a configuração.

Definição do método:

/**
 * @brief Sets the capture preference.
 * @param cameraCapturerConfiguration The camera capture settings.
 *      - preference:
 *        - {@link AliRtcCaptureOutputPreference#ALIRTC_CAPTURER_OUTPUT_PREFERENCE_PREVIEW} Preview priority. Prioritizes video preview quality.
 *        - {@link AliRtcCaptureOutputPreference#ALIRTC_CAPTURER_OUTPUT_PREFERENCE_PERFORMANCE} Performance priority. Prioritizes device performance by selecting a resolution close to that of the published stream.
 *        - {@link AliRtcCaptureOutputPreference#ALIRTC_CAPTURER_OUTPUT_PREFERENCE_AUTO} Auto. The SDK automatically adjusts the capture resolution.
 *      - cameraDirection: The camera direction. You can set it to the front or rear camera.
 * @return
 * - 0: Success.
 * - A non-zero value: Failure.
 * @note You must call this method before you start the camera, for example, before you call {@link #startPreview} or {@link #joinChannel}.
 */
public abstract int setCameraCapturerConfiguration(AliEngineCameraCapturerConfiguration cameraCapturerConfiguration);

Parâmetros:

Parâmetro	Tipo	Descrição
`preference`	AliRtcCaptureOutputPreference	Preferência de captura. CAPTURER_OUTPUT_PREFERENCE_AUTO: O SDK ajusta as configurações automaticamente. CAPTURER_OUTPUT_PREFERENCE_PERFORMANCE: Prioridade de desempenho. O SDK seleciona configurações de captura que melhor correspondem aos parâmetros de codificação. CAPTURER_OUTPUT_PREFERENCE_PREVIEW: Prioridade de pré-visualização. O SDK seleciona parâmetros de entrada da câmera de alta qualidade para priorizar a pré-visualização.
`cameraDirection`	AliRtcCameraDirection	Direção da câmera (frontal ou traseira).
`fps`	int	Taxa de quadros de captura. Valor padrão: -1. O SDK usa o fps da configuração de codificação (o padrão interno do SDK é 15).
`cameraCaptureProfile`	AliRtcCameraCaptureProfile	Resolução de captura de vídeo. Padrão: Segue as configurações do codificador. 1080p.
`textureEncode`	int	(Apenas Android) Indica se deve ativar a codificação de textura.
`cameraTextureCapture`	int	(Apenas Android) Indica se deve ativar a captura de textura para a câmera.

Código de exemplo:

Android

AliRtcEngine.AliEngineCameraCapturerConfiguration config = new AliRtcEngine.AliEngineCameraCapturerConfiguration();
config.preference = AliRtcEngine.AliRtcCaptureOutputPreference.ALIRTC_CAPTURER_OUTPUT_PREFERENCE_AUTO;
config.cameraCaptureProfile = AliRtcEngine.AliRtcCameraCaptureProfile.ALIRTC_CAMERA_CAPTURER_PROFILE_DEFAULT;
config.cameraDirection = AliRtcEngine.AliRtcCameraDirection.CAMERA_FRONT;
config.fps = 30;
mAliRtcEngine.setCameraCapturerConfiguration(config);

iOS

let cameraCaptureConfig: AliRtcCameraCapturerConfiguration = AliRtcCameraCapturerConfiguration()
cameraCaptureConfig.preference = .auto
cameraCaptureConfig.cameraCaptureProfile = .profileDefault
cameraCaptureConfig.cameraDirection = .front
cameraCaptureConfig.fps = 30
engine.setCameraCapturerConfiguration(cameraCaptureConfig)

Harmony

const cameraConfig = new AliRtcCameraCaptureConfiguration();
cameraConfig.preference = AliRtcCaptureOutputPreference.AliRtcCaptureOutputPreferenceAuto;
cameraConfig.cameraDirection = AliRtcCameraDirection.AliRtcCameraDirectionFront;
cameraConfig.cameraCaptureProfile = AliRtcCameraCaptureProfile.AliRtcCameraCaptureProfileDefault;
cameraConfig.fps = 30;
this.rtcEngine?.setCameraCaptureConfiguration(cameraConfig);

macOS

AliRtcCameraCapturerConfiguration *configuration = [[AliRtcCameraCapturerConfiguration alloc] init];
configuration.preference = (AliRtcCaptureOutputPreference)outputBox.indexOfSelectedItem;
configuration.cameraCaptureProfile = AliRtcCameraCaptureProfileDefault;
configuration.fps = 15;
[self.engine setCameraCapturerConfiguration:configuration];

Windows

AliEngineCameraCapturerConfiguration config ;
config.preference = AliEngineCaptureOutputPreferencePerformance;
config.cameraCaptureProfile = AliEngineCameraCaptureProfileDefault;
config.fps = 30;
mAliRtcEngine->setCameraCapturerConfiguration(config);

2. Defina configuração do codificador de vídeo

Use setVideoEncoderConfiguration para definir a resolução de vídeo, a taxa de quadros, a taxa de bits e o intervalo de quadros-chave.

Nota

Chame setVideoEncoderConfiguration antes ou depois de entrar em um canal. Se for chamado apenas uma vez por chamada, faça-o antes de entrar.

Parâmetros:

Parâmetro	Tipo	Descrição
`dimensions`	AliRtcVideoDimensions	Resolução de vídeo. Padrão: 640x480. Máximo: 1920x1080.
`frameRate`	int	Taxa de quadros de codificação de vídeo. Padrão: 15. Máximo: 30.
`bitrate`	int	Taxa de bits de vídeo em kbps. Padrão: 512. Defina como 0 para cálculo automático com base na resolução e na taxa de quadros. Se a taxa de bits estiver fora do intervalo recomendado, o SDK a ajustará automaticamente. Os intervalos recomendados estão nos comentários do código de exemplo.
`keyFrameInterval`	int	Intervalo de quadros-chave em milissegundos. Padrão: 0 (controlado pelo SDK). Nota Este parâmetro é necessário para transmissão interativa e interoperabilidade com mini programas.
`forceStrictKeyFrameInterval`	boolean	Indica se deve forçar a geração estrita de quadros-chave no intervalo definido. Padrão: `false`. `false`: O codificador responde a solicitações de quadro-chave, por exemplo, quando outro usuário entra no canal. O intervalo de quadros-chave pode não corresponder estritamente ao valor definido. `true`: O codificador não responde a outras solicitações de quadro-chave e gera estritamente quadros-chave no intervalo definido. Isso pode aumentar o tempo até o primeiro quadro para os assinantes.
`mirrorMode`	AliRtcVideoEncoderMirrorMode	Modo de espelhamento para o vídeo codificado. Nota Você também pode usar o método `setVideoMirrorMode` para definir o modo de espelhamento.
`orientationMode`	AliRtcVideoEncoderOrientationMode	Modo de orientação do vídeo codificado. `Adaptive`: A orientação do vídeo de saída corresponde à do vídeo capturado. `FixedLandscape`: Orientação paisagem fixa. `FixedPortrait`: Orientação retrato fixa.
`rotationMode`	AliRtcRotationMode	Ângulo de rotação do vídeo codificado. Valores válidos: 0, 90, 180 e 270.
`codecType`	AliRtcVideoCodecType	Tipo de codec. `default`: Usa a configuração padrão do dispositivo. `software`: Usa codificação via software. `hardware`: Usa codificação via hardware. `hardwareTexture`: Usa codificação de textura via hardware.
`encodeCodecType`	AliRtcVideoEncodeCodecType	Formato de codificação de vídeo. Formatos suportados: padrão do sistema, H.264 e H.265.
`seiForceFrontIFrame`	int	Indica se deve forçar um I-frame antes de enviar uma mensagem SEI. Valores válidos: `-1` (padrão, equivalente a `1`), `0` (não forçar) e `1` (forçar).

Código de exemplo:

Android

AliRtcEngine.AliRtcVideoEncoderConfiguration aliRtcVideoEncoderConfiguration = new AliRtcEngine.AliRtcVideoEncoderConfiguration();
aliRtcVideoEncoderConfiguration.dimensions = new AliRtcEngine.AliRtcVideoDimensions(720, 1280);
aliRtcVideoEncoderConfiguration.frameRate = 20;
aliRtcVideoEncoderConfiguration.bitrate = 1200;
aliRtcVideoEncoderConfiguration.keyFrameInterval = 2000;
aliRtcVideoEncoderConfiguration.orientationMode = AliRtcVideoEncoderOrientationModeAdaptive;
mAliRtcEngine.setVideoEncoderConfiguration(aliRtcVideoEncoderConfiguration);

iOS

let config = AliRtcVideoEncoderConfiguration()
config.dimensions = CGSize(width: 720, height: 1280)
config.frameRate = 20
config.bitrate = 1200
config.keyFrameInterval = 2000
config.orientationMode = AliRtcVideoEncoderOrientationMode.adaptive
engine.setVideoEncoderConfiguration(config)

Harmony

const encoderConfig = new AliRtcVideoEncoderConfiguration();
const dimensions = new AliRtcVideoDimensions();
dimensions.width = 720;
dimensions.height = 1280;
encoderConfig.dimensions = dimensions;
encoderConfig.bitrate = 1200;
encoderConfig.frameRate = 20;
encoderConfig.orientationMode = AliRtcVideoEncoderOrientationMode.AliRtcVideoEncoderOrientationModeAdaptive;
encoderConfig.rotationMode = AliRtcRotationMode.AliRtcRotationMode_0;
// Call the RTC engine to set the configuration.
this.rtcEngine?.setVideoEncoderConfiguration(encoderConfig);

macOS

AliRtcVideoEncoderConfiguration *config = [[AliRtcVideoEncoderConfiguration alloc] init];

config.dimensions = CGSizeMake(720, 1280);
config.frameRate = 20;
config.bitrate = 1200
config.keyFrameInterval = 2000
config.orientationMode = AliRtcVideoEncoderOrientationModeAdaptive;

[self.engine setVideoEncoderConfiguration:config];

Windows

AliEngineVideoEncoderConfiguration aliRtcVideoEncoderConfiguration ;
aliRtcVideoEncoderConfiguration.dimensions = AliRtcVideoDimensions(720, 1280);
aliRtcVideoEncoderConfiguration.frameRate = AliEngineFrameRateFps20;
aliRtcVideoEncoderConfiguration.bitrate = 1200;
aliRtcVideoEncoderConfiguration.keyFrameInterval = 2000;
aliRtcVideoEncoderConfiguration.orientationMode = AliEngineVideoEncoderOrientationModeAdaptive;
mAliRtcEngine->SetVideoEncoderConfiguration(aliRtcVideoEncoderConfiguration);

3. Alternar câmeras

O SDK usa a câmera frontal por padrão. Chame setCameraCaptureConfiguration antes de iniciar a captura para especificar uma câmera diferente ou switchCamera para alternar durante a execução.

/**
 * @brief Switches between the front and rear cameras.
 * @return
 * - `0`: Success
 * - Non-zero: Failure
 * @note This API is available on iOS and Android only.
 */
public abstract int switchCamera();

Código de exemplo:

Android

mSwitchCameraBtn.setOnClickListener(v -> {
    if(mAliRtcEngine != null) {
        mAliRtcEngine.switchCamera();
    }
});

iOS

@IBAction func onCameraDirectionChanged(_ sender: UISegmentedControl) {
    rtcEngine?.switchCamera()
}

Harmony

this.rtcEngine.switchCamera();

4. Controlar a câmera

Duas APIs controlam a câmera: muteLocalCamera e enableLocalVideo.

API	`muteLocalCamera`	`enableLocalVideo`
Funcionamento	Envia quadros pretos em vez de vídeo.	Interrompe a captura da câmera e libera os recursos do dispositivo.
Comportamento	A pré-visualização local permanece ativa, mas os usuários remotos veem uma tela preta.	A pré-visualização local e o vídeo remoto congelam no último quadro.
Características	Mantém o fluxo de vídeo sem interrupção para usuários remotos. Alternância rápida com baixa latência. Ideal para alternar vídeo frequentemente.	Libera recursos da câmera. Alternância mais lenta com maior latência. Ideal para períodos prolongados com a câmera desligada, como chamadas apenas de áudio.

4,1. Silenciar ou reativar vídeo local

muteLocalCamera mantém o pipeline de captura, codificação e transmissão de vídeo ativo, mas envia quadros pretos para usuários remotos. A pré-visualização local não é afetada.

/**
 * @brief Mutes or unmutes the local video stream.
 * @param mute true: Sends black frames. false: Resumes sending normal video frames.
 * @param track The video track to mute. Only {@link AliRtcVideoTrack#AliRtcVideoTrackCamera} is supported.
 * @return
 * - 0: Success.
 * - A non-zero value: Failure.
 * @note This method sends black frames while the local preview remains unaffected. The video capture pipeline continues to run.
 */
public abstract int muteLocalCamera(boolean mute, AliRtcVideoTrack track);
/**
 * @brief Occurs when a remote user mutes or unmutes their video stream.
 * @param uid The ID of the user who called muteLocalCamera.
 * @param isMute
 * - true: The user is sending black frames.
 * - false: The user is sending normal video frames.
 */
public void onUserVideoMuted(String uid ,boolean isMute){}

Android

Silencie ou reative o fluxo de vídeo:

if(!isMutedCamera) {
    mAliRtcEngine.muteLocalCamera(true, AliRtcEngine.AliRtcVideoTrack.AliRtcVideoTrackCamera);
    mPublishVideoBtn.setText(R.string.resume_pub_video);
    isMutedCamera = true;
} else {
    mAliRtcEngine.muteLocalCamera(false, AliRtcEngine.AliRtcVideoTrack.AliRtcVideoTrackCamera);
    mPublishVideoBtn.setText(R.string.stop_pub_video);
    isMutedCamera = false;
}

Ouça o callback remoto:

@Override
public void onUserVideoMuted(String uid ,boolean isMute){
    handler.post(new Runnable() {
        @Override
        public void run() {
            ToastHelper.showToast(VideoBasicUsageActivity.this, "remote user uid:" + uid + " camera mute:" + isMute, Toast.LENGTH_SHORT);
        }
    });
}

iOS

Silencie ou reative o fluxo de vídeo:

@IBAction func onVideoMuteSwitched(_ sender: UISwitch) {
    if sender.isOn {
        // Send black frames.
        rtcEngine?.muteLocalCamera(true, for: AliRtcVideoTrack.camera)
    } else {
        // Resume sending normal video frames.
        rtcEngine?.muteLocalCamera(false, for: AliRtcVideoTrack.camera)
    }
}

Ouça o callback remoto:

extension VideoBasicUsageVC: AliRtcEngineDelegate {
    func onUserVideoMuted(_ uid: String, videoMuted isMute: Bool) {
        "onUserVideoMuted: user id \(uid) video muted: \(isMute)".printLog()
    }
}

Harmony

Silencie ou reative o fluxo de vídeo:

private toggleVideoSending(): void {
  if (this.rtcEngine) {
    if (!this.isMutedCamera) {
      this.rtcEngine.muteLocalCamera(true, AliRtcVideoTrack.AliRtcVideoTrackCamera);
      this.isMutedCamera = true;
    } else {
      this.rtcEngine.muteLocalCamera(false, AliRtcVideoTrack.AliRtcVideoTrackCamera);
      this.isMutedCamera = false;
    }
  }
}

Ouça o callback remoto:

listener.onUserVideoMuted((uid : string, isMute : boolean) => {
  console.info(`User ${uid}'s video has been ${isMute ? 'muted' : 'unmuted'}`);
});

macOS

Silencie ou reative o fluxo de vídeo:

[self.engine muteLocalCamera:self.muteLocalCamera forTrack:AliRtcVideoTrackCamera];

Ouça o callback remoto:

- (void)onUserVideoMuted:(NSString *_Nullable)uid videoMuted:(BOOL)isMute {
    NSLog(@"uid=%@ mute:%d", uid, isMute );
}

Windows

Silencie ou reative o fluxo de vídeo:

if ( mMuteLocalCamera == TRUE) {
    mAliRtcEngine->MuteLocalCamera(TRUE, AliRtcVideoTrackCamera);
} else {
    mAliRtcEngine->MuteLocalCamera(FALSE, AliRtcVideoTrackCamera); 
}

Ouça o callback remoto:

void CTutorialDlg::OnUserVideoMuted(const char* uid, bool isMute)
{
    // Find the corresponding user view to update its status.
	PartUserDlg *partUserView = mRemotePartDlgs[uid];
	if (nullptr != partUserView)
	{
		partUserView->muteStream = isMute;
		updateRemoteParticipants();
	}
}

4,2. Ative ou desative captura de vídeo

enableLocalVideo controla a câmera. Desativá-lo interrompe a captura e a transmissão, liberando o dispositivo.

/**
 * @brief Enables or disables local video capture.
 * @param enabled
 * - true: Enables local video capture.
 * - false: Disables local video capture.
 * @return
 * - 0: Success.
 * - < 0: Failure.
 * @note This feature is enabled by default. Listen for the {@link AliRtcEngineNotify#onUserVideoEnabled} callback to be notified of changes to a remote user's video capture status.
 */
public abstract int enableLocalVideo(boolean enabled);
/**
 * @brief Occurs when a remote user enables or disables their local video capture.
 * @param uid The ID of the user who called enableLocalVideo.
 * @param isEnable
 * - true: The user enabled local video capture.
 * - false: The user disabled local video capture.
 */
public void onUserVideoEnabled(String uid, boolean isEnable){}