Todos os produtos
Search
Central de documentação

ApsaraVideo Live:Uso dos recursos

Última atualização: Jul 04, 2026

Este tópico descreve as interfaces e o fluxo de trabalho básico do Push SDK para iOS e fornece exemplos de uso dos principais recursos.

Recursos

  • Suporta ingestão de stream via Real-Time Messaging Protocol (RTMP).

  • Permite ingestão e pull de streams RTS com base em Real-Time Communication (RTC).

  • Compatível com co-streaming e batalhas.

  • Utiliza H.264 para codificação de vídeo e AAC para codificação de áudio.

  • Oferece configurações personalizadas para recursos como controle de taxa de bits, resolução e modo de exibição.

  • Suporta diversas operações de câmera.

  • Disponibiliza retoque em tempo real e efeitos de retoque personalizados.

  • Permite adicionar e remover stickers animados como marcas d'água.

  • Possibilita a transmissão de gravações de tela.

  • Aceita entradas externas de áudio e vídeo em diferentes formatos, como YUV e pulse-code modulation (PCM).

  • Suporta mixagem de múltiplos streams.

  • Permite ingestão de streams apenas de áudio ou apenas de vídeo, além de ingestão em segundo plano.

  • Inclui suporte a música de fundo.

  • Captura snapshots de vídeo.

  • Conta com reconexão automática e tratamento de erros.

  • Implementa algoritmos de Automatic Gain Control (AGC), Automatic Noise Reduction (ANR) e Acoustic Echo Cancellation (AEC).

  • Permite alternar entre os modos de codificação por software e hardware para arquivos de vídeo, aumentando a estabilidade do módulo de codificação.

Limitações

Observe os limites a seguir antes de usar o Push SDK para iOS:

  • Configure a orientação da tela antes da ingestão de stream. Não é possível girar a tela durante a transmissão ao vivo.

  • Desative a rotação automática de tela para ingestão no modo paisagem.

  • No modo de codificação por hardware, o valor da resolução de saída deve ser um múltiplo de 16 para garantir compatibilidade com o codificador. Por exemplo, se você definir a resolução como 540p, a resolução de saída será 544 × 960. Ajuste o tamanho da tela do player com base na resolução de saída para evitar barras pretas.

Referência da API

Referência da API para Basic Edition

Fluxo de trabalho

O fluxo de trabalho básico é o seguinte:

  1. Registre o SDK

  2. Configure os parâmetros de ingestão de stream

  3. Inicie a ingestão de stream

Uso dos recursos

Registre o SDK

Para solicitar e configurar uma licença, consulte Integrar uma licença do Push SDK.

Nota

É obrigatório registrar o SDK antes de utilizar o recurso de ingestão de stream. Caso contrário, o Push SDK não funcionará.

Chame a interface de registro de licença em uma etapa early (antes de usar o Push SDK).

[AlivcLiveBase registerSDK];
  • A classe AlivcLiveBase permite definir níveis de log, especificar um caminho de log local e obter a versão do SDK.

  • O método onLicenceCheck da interface AlivcLiveBase#setObserver possibilita verificar assincronamente se a licença foi configurada com sucesso.

Configure os parâmetros de stream

No ViewController onde você planeja usar o pusher, importe o arquivo de cabeçalho: #import <AlivcLivePusher/AlivcLivePusher.h>.

Os parâmetros básicos de ingestão de stream possuem valores padrão recomendados, permitindo uma inicialização simples sem necessidade de configurações adicionais.

AlivcLivePushConfig *config = [[AlivcLivePushConfig alloc] init];// Initialize the stream ingest configuration class. You can also use initWithResolution.
config.resolution = AlivcLivePushResolution540P;// The default resolution is 540p. The maximum is 720p.
config.fps = AlivcLivePushFPS20; // We recommend a frame rate of 20 fps.
config.enableAutoBitrate = true; // Enable bitrate control. The default value is true.
config.videoEncodeGop = AlivcLivePushVideoEncodeGOP_2;// The default value is 2. A larger keyframe interval results in higher latency. We recommend a value of 1 or 2.
config.connectRetryInterval = 2000; // The reconnection interval in milliseconds. The default is 2000 ms (2s). The interval must be at least 1s. We recommend using the default value.
config.previewMirror = false; // The default value is false. In normal cases, this should be false.
config.orientation = AlivcLivePushOrientationPortrait; // The default orientation is portrait. You can set it to landscape with the home button to the left or right.
Importante
  • Considerando o desempenho de dispositivos móveis e a largura de banda da rede, recomendamos definir a resolução como 540p. A maioria dos aplicativos de transmissão ao vivo utiliza 540p.

  • Se você desativar o controle de taxa de bits, ela ficará fixa na taxa inicial e não se adaptará entre as taxas alvo e mínima definidas. Isso pode causar travamentos na reprodução em condições de rede instáveis. Use essa configuração com cautela.

Ingira um stream de câmera

  1. Inicialize o SDK.

    Após configurar os parâmetros de ingestão de stream, chame o método initWithConfig para inicializar o SDK. Código de exemplo:

    self.livePusher = [[AlivcLivePusher alloc] initWithConfig:config];
    Nota

    AlivcLivePusher não suporta múltiplas instâncias. Portanto, cada chamada init deve ter uma chamada destroy correspondente.

  2. Registre os callbacks de ingestão de stream.

    Os seguintes callbacks de ingestão de stream são suportados:

    • Info: callbacks usados para notificações e detecção de status.

    • Error: callbacks retornados quando ocorrem erros.

    • Network: callbacks relacionados à rede.

    Registre os delegates para receber seus respectivos callbacks. Código de exemplo:

    [self.livePusher setInfoDelegate:self];
    [self.livePusher setErrorDelegate:self];
    [self.livePusher setNetworkDelegate:self];
  3. Inicie a pré-visualização.

    Depois que o objeto livePusher for inicializado, inicie a pré-visualização. É necessário passar a view de exibição, que deve ser uma subclasse de UIView, para a pré-visualização da câmera. Código de exemplo:

    [self.livePusher startPreview:self.view];
  4. Inicie a ingestão de stream.

    A ingestão de stream só pode ser iniciada após o sucesso da pré-visualização. Para isso, escute o callback onPreviewStarted de AlivcLivePusherInfoDelegate e adicione o seguinte código dentro do callback.

    [self.livePusher startPushWithURL:@"Test ingest URL (rtmp://......)"];
    Nota
    • A url de ingestão suporta os protocolos RTMP e RTS (artc://). Para obter uma url, consulte Gerar URLs de ingestão e streaming.

    • O ApsaraVideo Live não suporta a ingestão de múltiplos streams simultâneos para a mesma url. A segunda solicitação de ingestão será rejeitada.

Controles da câmera

Métodos relacionados à câmera só podem ser chamados após o início da pré-visualização, como durante a ingestão de stream, em estado de pausa ou durante a reconexão. Esses métodos permitem trocar de câmera, controlar o flash, ajustar foco, zoom e configurar espelhamento. Chamá-los antes do início da pré-visualização não terá efeito.

/* Switch between the front and rear cameras. */
[self.livePusher switchCamera];
/* Turn the flash on or off. The flash is not available on the front camera. */
[self.livePusher setFlash:false]; 
/* Adjust the focal length to zoom the captured image. A positive value zooms in, and a negative value zooms out. */
CGFloat max = [_livePusher getMaxZoom];
[self.livePusher setZoom:MIN(1.0, max)]; 
/* Manually set focus. You must pass two parameters: 1. point: the coordinates of the focus point; 2. autoFocus: whether to enable autofocus for this specific action. Subsequent auto-focus behavior follows the previously set value. */
[self.livePusher focusCameraAtAdjustedPoint:CGPointMake(50, 50) autoFocus:true];
/* Enable or disable autofocus. */
[self.livePusher setAutoFocus:false];
/* Configure mirroring. There are two mirroring interfaces: PushMirror for the ingested stream and PreviewMirror for the preview. PushMirror only affects the playback display, while PreviewMirror only affects the preview display. The two are independent. */
[self.livePusher setPushMirror:false];
[self.livePusher setPreviewMirror:false];

Controles de ingestão

Os controles de ingestão de stream incluem iniciar, parar, pausar, retomar, reiniciar e destruir. Adicione botões à sua UI para acionar essas operações conforme as necessidades do seu aplicativo. Código de exemplo:

/* Set a pauseImage and then call pause to switch from camera streaming to static image streaming. Audio ingest continues. */
[self.livePusher pause];
/* Switch from static image streaming back to camera streaming. Audio ingest continues. */
[self.livePusher resume];
/* Stop the current stream ingest. This can only be called while a stream is active. */
[self.livePusher stopPush];
/* Stop the preview. This can only be called while in the previewing state, not during an active stream ingest. After stopping, the preview display freezes on the last frame. */
[self.livePusher stopPreview];
/* Restart the stream. This can be called during an active stream ingest or in an error state. In an error state, you can only call this method, reconnectPushAsync, or destroy. This restarts all internal AlivcLivePusher resources, including preview and stream ingest. */
[self.livePusher restartPush];
/* Asynchronously reconnect the stream. This can be called during an active stream or in a network-related error state from AlivcLivePusherNetworkDelegate. In an error state, you can also call restartPush or destroy. This action attempts to re-establish the RTMP connection. */
[self.livePusher reconnectPushAsync];
/* Destroy the stream ingest instance. This stops the stream ingest and preview, and removes the preview display. All resources related to AlivcLivePusher are released. */
[self.livePusher destory];
self.livePusher = nil;
/* Get the current stream ingest status. */
AlivcLivePushStatus status = [self.livePusher getLiveStatus];

Ingestão de compartilhamento de tela

O ReplayKit, introduzido no iOS 9, suporta gravação de tela. O iOS 10 permitiu que o ReplayKit transmitisse o conteúdo da tela ao vivo por meio de extensões de aplicativos de terceiros. No iOS 10 e versões posteriores, use o Push SDK com uma extensão de aplicativo para implementar a transmissão ao vivo da tela.

Para garantir o desempenho do sistema, o iOS aloca recursos limitados para extensões de gravação de tela. Se uma extensão usar muita memória, o sistema a encerra. Para contornar essa limitação de memória, o Push SDK divide o processo de compartilhamento de tela entre um Extension App e um Host App. O Extension App captura o conteúdo da tela e o envia ao Host App via comunicação entre processos. O Host App cria o mecanismo AlivcLivePusher e ingere os dados da tela no servidor. Como todo o processo de ingestão de stream é tratado no Host App, a captura e transmissão do microfone também podem ser gerenciadas pelo Host App, deixando o Extension App responsável apenas pela captura de tela.

Importante

A demo do Push SDK usa um App Group para comunicação entre processos entre o Extension App e o Host App. Essa lógica está encapsulada no AlivcLibReplayKitExt.framework.

Para implementar o compartilhamento de tela no iOS, crie uma extensão de gravação de tela. O sistema instancia essa extensão quando necessário para receber as imagens capturadas da tela.

  1. Crie um App Group.

    Faça login no Apple Developer e conclua as etapas a seguir:

    1. Na página Certificates, IDs & Profiles, registre um App Group. Para mais informações, consulte Register an App Group.

    2. Retorne à página Identifier, selecione App IDs e clique em seu App ID para ativar a capacidade App Group. Execute a mesma configuração tanto para os IDs do Host App quanto do Extension App. Para mais informações, consulte Enable App Group.

    3. Após concluir a configuração, baixe os Provisioning Profiles atualizados e instale-os no Xcode.

    Após a conclusão correta dessas etapas, o Extension App e o Host App poderão se comunicar.

    Nota

    Após criar o App Group, salve o App Group Identifier. Você precisará dele em uma etapa posterior.

  2. Crie a extensão de gravação de tela.

    A demo do Push SDK para iOS inclui as extensões AlivcLiveBroadcast e AlivcLiveBroadcastSetupUI para compartilhamento de tela. Para criar a extensão de gravação de tela no seu aplicativo, siga estas etapas:

    1. No seu projeto existente, escolha New > Target… e selecione Broadcast Upload Extension.

    2. Altere o Product Name, marque a caixa de seleção Include UI Extension e clique em Finish para criar as extensões de broadcast e UI. Por exemplo, defina o Product Name como AlivcLiveBroadcast.

    3. Configure o arquivo Info.plist para a extensão de broadcast. No novo target, o Xcode cria automaticamente um arquivo de cabeçalho e um arquivo source chamado SampleHandler. Este diretório do target chama-se AlivcLiveBroadcast.

      Arraste o AlivcLibReplayKitExt.framework para o seu projeto e vincule-o como dependência para o target da extensão.1 Substitua o código em SampleHandler.m pelo código a seguir. Substitua kAPPGROUP no código pelo App Group Identifier criado na Etapa 1. Código de exemplo:

      
      #import "SampleHandler.h"
      #import <AlivcLibReplayKitExt/AlivcLibReplayKitExt.h>
      
      @implementation SampleHandler
      
      - (void)broadcastStartedWithSetupInfo:(NSDictionary<NSString *,NSObject *>
      *)setupInfo {
      
       // User has requested to start the broadcast. Setup info from the UI extension can
      be supplied but is optional.
       [[AlivcReplayKitExt sharedInstance] setAppGroup:kAPPGROUP];
      }
      
      - (void)processSampleBuffer:(CMSampleBufferRef)sampleBuffer withType:(RPSampleBufferType)sampleBufferType {
       if (sampleBufferType != RPSampleBufferTypeAudioMic) {
       // Audio is captured and sent by the Host App.
       [[AlivcReplayKitExt sharedInstance] sendSampleBuffer:sampleBuffer withType:sampleBufferType];
       }
      }
      
      - (void)broadcastFinished {
      
       [[AlivcReplayKitExt sharedInstance] finishBroadcast];
      }
      @end
      

    No seu projeto, crie um target para o Broadcast Upload Extension e integre o AlivcLibReplayKitExt.framework, que é personalizado para o módulo de extensão de gravação de tela, nesse target.

  3. Integre o SDK de transmissão ao vivo no Host App.

    No Host App, crie objetos AlivcLivePushConfig e AlivcLivePusher. Defina ExternMainStream como true e AudioFromExternal como false. Essa configuração significa que o áudio ainda é capturado pelo SDK. Chame startScreenCapture para começar a receber dados de tela do Extension App e, em seguida, inicie e pare a ingestão de stream. Siga estas etapas específicas:

    1. Adicione dependências de AlivcLivePusher.framework, AlivcLibRtmp.framework, RtsSDK.framework e AlivcLibReplayKitExt.framework ao processo do Host App.

    2. Inicialize o Push SDK e configure-o para usar uma fonte de vídeo externa.

      Defina ExternMainStream como true e ExternVideoFormat como AlivcLivePushVideoFormatYUV420P. Para usar o SDK interno para captura de áudio, defina AudioFromExternal como false. Configure outros parâmetros de ingestão de stream conforme mostrado no código de exemplo a seguir:

       self.pushConfig.externMainStream = true;
       self.pushConfig.externVideoFormat = AlivcLivePushVideoFormatYUV420P;
       self.pushConfig.audioSampleRate = 44100;
       self.pushConfig.audioChannel = 2;
       self.pushConfig.audioFromExternal = false;
       self.pushConfig.videoEncoderMode = AlivcLivePushVideoEncoderModeSoft;
       self.pushConfig.qualityMode = AlivcLivePushQualityModeCustom;
       self.pushConfig.targetVideoBitrate = 2500;
       self.pushConfig.minVideoBitrate = 2000;
       self.pushConfig.initialVideoBitrate = 2000;
       self.livePusher = [[AlivcLivePusher alloc] initWithConfig:self.pushConfig];
      
                                      
    3. Use o AlivcLivePusher para gerenciar funções de transmissão ao vivo chamando os seguintes métodos:

      • Comece a receber dados de gravação de tela.

        Substitua kAPPGroup no código pelo App Group Identifier criado anteriormente. Código de exemplo:

        [self.livePusher startScreenCapture:kAPPGROUP];
      • Inicie a ingestão de stream.

        Código de exemplo:

        [self.livePusher startPushWithURL:self.pushUrl]
      • Pare a ingestão de stream.

        Código de exemplo:

        [self.livePusher stopPush];
        [self.livePusher destory];
        self.livePusher = nil;

Modos de exibição de pré-visualização

O Push SDK suporta três modos de pré-visualização. O modo de exibição da pré-visualização não afeta o stream ingerido.

  • ALIVC_LIVE_PUSHER_PREVIEW_SCALE_FILL: A pré-visualização preenche a janela. Se as proporções do vídeo e da janela forem diferentes, a pré-visualização ficará distorcida.

  • ALIVC_LIVE_PUSHER_PREVIEW_ASPECT_FIT: (Padrão) A pré-visualização mantém a proporção do vídeo. Se as proporções do vídeo e da janela forem diferentes, a pré-visualização terá barras pretas.

  • ALIVC_LIVE_PUSHER_PREVIEW_ASPECT_FILL: A pré-visualização corta o vídeo para caber na proporção da janela. Se as proporções do vídeo e da janela forem diferentes, o vídeo será cortado.

    Código de exemplo:

mAlivcLivePushConfig.setPreviewDisplayMode(AlivcPreviewDisplayMode.ALIVC_LIVE_PUSHER_PREVIEW_ASPECT_FIT);
Nota
  • Defina o modo em AlivcLivePushConfig ou dinamicamente usando a API setpreviewDisplayMode durante a pré-visualização ou ingestão de stream.

  • Essa configuração afeta apenas a pré-visualização. A resolução do stream de vídeo ingerido é determinada por AlivcLivePushConfig e não é afetada pelo modo de pré-visualização. Os modos de exibição de pré-visualização foram projetados para se adaptar a diferentes tamanhos de tela de telefone, permitindo que você escolha o melhor efeito de pré-visualização.

Ingestão de imagem

O SDK pode ingerir uma imagem estática quando o aplicativo está em segundo plano ou quando a taxa de bits está muito baixa. Quando o aplicativo está em segundo plano, a ingestão de vídeo é pausada por padrão e apenas o áudio é ingerido. Nesse momento, defina uma imagem para ser transmitida. Por exemplo, exiba uma imagem com uma mensagem como O apresentador voltará em breve. Código de exemplo:

config.pauseImg = [UIImage imageNamed:@"image.png"];// Set the image for background stream ingest.

Além disso, configure uma imagem estática para ser ingerida quando a conexão de rede estiver ruim. Após definir a imagem, o SDK detecta quando a taxa de bits atual está baixa e ingere essa imagem para evitar travamentos no vídeo. Código de exemplo:

config.networkPoorImg = [UIImage imageNamed:@"image.png"];// Set the image to ingest during poor network conditions.

Ingestão externa de áudio e vídeo

O Push SDK suporta a ingestão de áudio e vídeo de fontes externas, como um arquivo de áudio ou vídeo.

  1. Configure a entrada externa de áudio e vídeo na configuração de ingestão de stream.

  2. Código de exemplo:

    config.externMainStream = true;// Enable external stream input.
    config.externVideoFormat = AlivcLivePushVideoFormatYUVNV21;// Set the video data color format. Here, it is set to YUVNV21. You can set it to other formats as needed.
    config.externAudioFormat = AlivcLivePushAudioFormatS16;// Set the audio data bit depth format. Here, it is set to S16. You can set it to other formats as needed.
  3. Insira dados de vídeo externos.

  4. Código de exemplo:

    /* The sendVideoData interface only supports continuous buffer data in external video formats like YUV and RGB. You can use it to send the video data buffer, length, width, height, timestamp, and rotation angle. */
    [self.livePusher sendVideoData:yuvData width:720 height:1280 size:dataSize pts:nowTime rotation:0];
    /* If the external video data is in CMSampleBufferRef format, you can use the sendVideoSampleBuffer interface. */
    [self.livePusher sendVideoSampleBuffer:sampleBuffer]
    /* You can also convert the CMSampleBufferRef format to a continuous buffer and then pass it to the sendVideoData interface. The following is reference code for the conversion. */
    // Get the sample buffer size.
    - (int) getVideoSampleBufferSize:(CMSampleBufferRef)sampleBuffer {
    if(!sampleBuffer) {
     return 0;
    }
    int size = 0;
    CVPixelBufferRef pixelBuffer = CMSampleBufferGetImageBuffer(sampleBuffer);
    CVPixelBufferLockBaseAddress(pixelBuffer, 0);
    if(CVPixelBufferIsPlanar(pixelBuffer)) {
     int count = (int)CVPixelBufferGetPlaneCount(pixelBuffer);
     for(int i=0; i<count; i++) {
     int height = (int)CVPixelBufferGetHeightOfPlane(pixelBuffer,i);
     int stride = (int)CVPixelBufferGetBytesPerRowOfPlane(pixelBuffer,i);
     size += stride*height;
     }
    }else {
     int height = (int)CVPixelBufferGetHeight(pixelBuffer);
     int stride = (int)CVPixelBufferGetBytesPerRow(pixelBuffer);
     size += stride*height;
    }
    CVPixelBufferUnlockBaseAddress(pixelBuffer, 0);
    return size;
    }
    // Convert a sample buffer to a continuous buffer.
    - (int) convertVideoSampleBuffer:(CMSampleBufferRef)sampleBuffer toNativeBuffer:(void*)nativeBuffer
    {
    if(!sampleBuffer || !nativeBuffer) {
     return -1;
    }
    CVPixelBufferRef pixelBuffer = CMSampleBufferGetImageBuffer(sampleBuffer);
    CVPixelBufferLockBaseAddress(pixelBuffer, 0);
    int size = 0;
    if(CVPixelBufferIsPlanar(pixelBuffer)) {
     int count = (int)CVPixelBufferGetPlaneCount(pixelBuffer);
     for(int i=0; i<count; i++) {
     int height = (int)CVPixelBufferGetHeightOfPlane(pixelBuffer,i);
     int stride = (int)CVPixelBufferGetBytesPerRowOfPlane(pixelBuffer,i);
     void *buffer = CVPixelBufferGetBaseAddressOfPlane(pixelBuffer, i);
     int8_t *dstPos = (int8_t*)nativeBuffer + size;
     memcpy(dstPos, buffer, stride*height);
     size += stride*height;
     }
    }else {
     int height = (int)CVPixelBufferGetHeight(pixelBuffer);
     int stride = (int)CVPixelBufferGetBytesPerRow(pixelBuffer);
     void *buffer = CVPixelBufferGetBaseAddress(pixelBuffer);
     size += stride*height;
     memcpy(nativeBuffer, buffer, size);
    }
    CVPixelBufferUnlockBaseAddress(pixelBuffer, 0);
    return 0;
    }
  5. Insira dados de áudio.

  6. Código de exemplo:

    /* Only continuous buffer data in PCM format is supported. Use sendPCMData to send the audio data buffer, size, and timestamp. */
    [self.livePusher sendPCMData:pcmData size:size pts:nowTime];

Configure marcas d'água

O Push SDK permite adicionar múltiplas marcas d'água. As imagens das marcas d'água devem estar no formato PNG. Código de exemplo:

NSString *watermarkBundlePath = [[NSBundle mainBundle] pathForResource:
[NSString stringWithFormat:@"watermark"] ofType:@"png"];// Set the path of the watermark image.
[config addWatermarkWithPath: watermarkBundlePath
 watermarkCoordX:0.1
 watermarkCoordY:0.1
 watermarkWidth:0.3];// Add a watermark.
Nota
  • Os parâmetros coordX, coordY e width são valores relativos. Por exemplo, watermarkCoordX:0.1 posiciona a marca d'água em 10% da largura total do stream. Se a resolução do stream for 540×960, a posição x da marca d'água será 54.

  • A altura da imagem da marca d'água é escalada proporcionalmente com base em sua proporção original e no valor width especificado.

  • Para implementar uma marca d'água de texto, primeiro converta o texto em uma imagem e depois use esta interface para adicionar a imagem como marca d'água.

  • Para garantir clareza e bordas suaves na marca d'água, use uma imagem de origem que tenha as mesmas dimensões do tamanho final de saída da marca d'água. Por exemplo, se a resolução do vídeo de saída for 544×940 e a largura relativa da marca d'água for 0.1f, a largura ideal da imagem de origem deve ser cerca de 54,4 pixels (544 * 0,1).

Configure a qualidade do vídeo

Três modos de qualidade de vídeo são suportados: modo de prioridade de resolução, modo de prioridade de fluidez e modo personalizado.

Importante

Para configurar a qualidade do vídeo, ative o controle de taxa de bits: config.enableAutoBitrate = true;

Modo de prioridade de resolução (padrão)

No modo de prioridade de resolução, o SDK configura internamente os parâmetros de taxa de bits para priorizar a clareza do stream de vídeo ingerido.

config.qualityMode = AlivcLivePushQualityModeResolutionFirst; // Resolution priority mode

Modo de prioridade de fluidez

No modo de prioridade de fluidez, o SDK configura internamente os parâmetros de taxa de bits para priorizar a suavidade do stream de vídeo ingerido.

config.qualityMode = AlivcLivePushQualityModeFluencyFirst; // Fluency priority mode

Modo personalizado

No modo personalizado, o SDK configura o stream com base na taxa de bits definida por você. Ao usar o modo personalizado, defina as taxas de bits inicial, mínima e alvo.

  • Taxa de bits inicial: A taxa de bits no início da transmissão ao vivo.

  • Taxa de bits mínima: Quando a conexão de rede está ruim, a taxa de bits diminui gradualmente até atingir a taxa mínima para reduzir travamentos no vídeo.

  • Taxa de bits alvo: Quando a conexão de rede está boa, a taxa de bits aumenta gradualmente até atingir a taxa alvo para melhorar a clareza do vídeo.

config.qualityMode = AlivcLivePushQualityModeCustom // Set to custom mode.
config.targetVideoBitrate = 1400; // Target bitrate: 1400 Kbps
config.minVideoBitrate = 600; // Minimum bitrate: 600 Kbps
config.initialVideoBitrate = 1000; // Initial bitrate: 1000 Kbps

Ao definir uma taxa de bits personalizada, consulte as configurações recomendadas pela Alibaba Cloud. As configurações recomendadas são fornecidas nas tabelas a seguir:

Tabela 1. Configurações recomendadas para o modo de Prioridade de Resolução

Resolução

initialVideoBitrate

minVideoBitrate

targetVideoBitrate

360p

600

300

1000

480p

800

300

1200

540p

1000

600

1400

720p

1500

600

2000

1080p

1800

1200

2500

Tabela 1. Configurações recomendadas para o modo de Prioridade de Resolução

Resolução

initialVideoBitrate

minVideoBitrate

targetVideoBitrate

360p

400

200

600

480p

600

300

800

540p

800

300

1000

720p

1000

300

1200

1080p

1500

1200

2200

Resolução adaptativa

Quando a resolução adaptativa está ativada, o SDK reduz automaticamente a resolução durante condições de rede ruins para melhorar a suavidade do vídeo.

config.enableAutoResolution = YES; // Enable adaptive resolution. This is disabled by default (NO).
Importante
  • A resolução adaptativa é eficaz apenas quando o modo de Qualidade de vídeo está definido como Clarity First ou Fluency First, mas não no modo personalizado.

  • Alguns players podem não suportar alterações dinâmicas de resolução. Se precisar usar o recurso de resolução adaptativa, recomendamos o uso do ApsaraVideo Player.

Música de fundo

O Push SDK suporta reprodução de música de fundo, mixagem de áudio, redução de ruído, monitoramento in-ear e silenciamento. Interfaces relacionadas à música de fundo só podem ser chamadas após o início da pré-visualização. Código de exemplo:

/* Start playing background music. */
[self.livePusher startBGMWithMusicPathAsync:musicPath];
/* Stop playing background music. If background music is already playing and you need to switch songs, you only need to call the start playing interface again. You do not need to stop the current background music first. */
[self.livePusher stopBGMAsync];
/* Pause background music. This can only be called after background music has started playing. */
[self.livePusher pauseBGM];
/* Resume playing background music. This can only be called when the background music is paused. */
[self.livePusher resumeBGM];
/* Enable looping for the music. */
[self.livePusher setBGMLoop:true];
/* Set the denoising switch. When enabled, non-human sounds in the captured audio are filtered. This might slightly suppress human voices. We recommend letting users choose whether to enable this feature. It is disabled by default. */
[self.livePusher setAudioDenoise:true];
/* Set the in-ear monitoring switch. This feature is mainly used in karaoke scenarios. When enabled, the host's voice is audible in the headphones. When disabled, the voice is not audible. In-ear monitoring does not work if no headphones are connected. */
[self.livePusher setBGMEarsBack:true];
/* Configure audio mixing to adjust the volume of the background music and captured voice. */
[self.livePusher setBGMVolume:50];// Set the background music volume.
[self.livePusher setCaptureVolume:50];// Set the captured voice volume.
/* Set mute. When muted, both music and voice input are silenced. To mute only the music or voice, use the audio mixing volume settings. */
[self.livePusher setMute:isMute?true:false];

Snapshots de stream

O Push SDK fornece um recurso para capturar snapshots do stream de vídeo local. Código de exemplo:

/* Set the snapshot callback. */
[self.livePushersetSnapshotDelegate:self];
/* Call the snapshot API. */
[self.livePushersnapshot:1interval:1];

Configure retoques

O ApsaraVideo Live Push SDK oferece dois modos de retoque: básico e avançado. O retoque básico inclui clareamento de pele, suavização e adição de um tom rosado. O retoque avançado suporta clareamento baseado em reconhecimento facial, suavização, tom rosado, aumento dos olhos e afinamento do rosto. Este recurso é fornecido pelo Queen SDK. Código de exemplo:

#pragma mark - "APIs for Retouching Types and Parameters"/**
* @brief Enables or disables a specific retouching type.
* @param type A value from QueenBeautyType.
* @param isOpen YES: enable, NO: disable.
*
*/
- (void)setQueenBeautyType:(kQueenBeautyType)type enable:(BOOL)isOpen;
/**
* @brief Sets a retouching parameter.
* @param param The retouching parameter type, one from QueenBeautyParams.
* @param value The value to set, ranging from [0,1]. Values less than 0 are set to 0, and values greater than 1 are set to 1.
*/
- (void)setQueenBeautyParams:(kQueenBeautyParams)param
value:(float)value;
#pragma mark - "APIs for Filters"
/**
* @brief Sets a filter image. kQueenBeautyTypeLUT must be enabled before setting a filter image.
* @param imagePath The path to the filter image to be set.
*/
- (void)setLutImagePath:(NSString *)imagePath;
#pragma mark - "APIs for Face Shaping"
/**
*@brief Sets the face shaping type. kQueenBeautyTypeFaceShape must be enabled before setting.
*@param faceShapeType The type of face shaping to set, see QueenBeautyFaceShapeType.
*@param value The value to set.
*/
- (void)setFaceShape:(kQueenBeautyFaceShapeType)faceShapeType
value:(float)value;
#pragma mark - "APIs for Makeup"
/**
* @brief Sets the makeup type and material asset path. kQueenBeautyTypeMakeup must be enabled before setting makeup.
* @param makeupType The makeup type.
* @param imagePaths A collection of paths to makeup material assets.
* @param blend The blend type.
*/
- (void)setMakeupWithType:(kQueenBeautyMakeupType)makeupType
paths:(NSArray<NSString *> *)imagePaths
blendType:(kQueenBeautyBlend)blend;
/**
* @brief Sets the makeup type and material asset path.
* @param makeupType The makeup type.
* @param imagePaths A collection of paths to makeup material assets.
* @param blend The blend type.
* @param fps The corresponding frame rate.
*/
- (void)setMakeupWithType:(kQueenBeautyMakeupType)makeupType
paths:(NSArray<NSString *> *)imagePaths
blendType:(kQueenBeautyBlend)blend fps:(int)fps;
/**
* @brief Sets the makeup transparency, with an option to specify gender.
* @param makeupType The makeup type.
* @param isFeMale Whether the user is female. YES for female, NO for male.
* @param alpha The transparency of the makeup.
*/
- (void)setMakeupAlphaWithType:(kQueenBeautyMakeupType)makeupType
female:(BOOL)isFeMale alpha:(float)alpha;
/**
* @brief Sets the blend type for a makeup type.
* @param makeupType The makeup type.
* @param blend The blend type.
*/
- (void)setMakeupBlendWithType:(kQueenBeautyMakeupType)makeupType
blendType:(kQueenBeautyBlend)blend;
/**
* @brief Clears all makeup effects.
*/
- (void)resetAllMakeupType;

Ajuste de parâmetros em tempo real

O Push SDK suporta ajuste em tempo real dos parâmetros de retoque durante a ingestão de stream. Ative o interruptor de retoque e ajuste os valores dos parâmetros correspondentes. Código de exemplo:

[_queenEngine setQueenBeautyType:kQueenBeautyTypeSkinBuffing enable:YES];
[_queenEngine setQueenBeautyType:kQueenBeautyTypeSkinWhiting enable:YES];
[_queenEngine setQueenBeautyParams:kQueenBeautyParamsWhitening value:0.8f];
[_queenEngine setQueenBeautyParams:kQueenBeautyParamsSharpen value:0.6f];
[_queenEngine setQueenBeautyParams:kQueenBeautyParamsSkinBuffing value:0.6];

Configure quiz ao vivo

O recurso de quiz ao vivo funciona inserindo mensagens SEI no stream ao vivo para que o player as interprete. O Push SDK fornece uma interface para inserir SEI. Essa interface só pode ser chamada enquanto uma ingestão de stream estiver ativa. Código de exemplo:

/*
msg: The SEI message body to insert into the stream. We recommend using JSON format. The ApsaraVideo Player SDK can receive this SEI message, parse it, and display the content.
repeatCount: The number of frames to send. To ensure that SEI messages are not dropped, you must set the number of repetitions. For example, a value of 100 inserts this SEI message into the next 100 frames. The player will deduplicate identical SEI messages.
delayTime: The delay in milliseconds before sending.
KeyFrameOnly: Whether to send only on keyframes.
*/
[self.livePusher sendMessage:@"Question Information" repeatCount:100 delayTime:0 KeyFrameOnly:false];

Adaptação para iPhone X

Na maioria dos cenários, definir o frame da view de pré-visualização como tela cheia funciona corretamente. No entanto, em um iPhone X, uma pré-visualização em tela cheia pode parecer esticada devido à proporção única do dispositivo. Recomendamos evitar uma view em tela cheia para pré-visualizações no iPhone X.

Redimensione a view durante a ingestão

Itere pela UIView atribuída ao chamar a interface startPreview ou startPreviewAsync. Altere o frame para todas as subviews da view de pré-visualização. Por exemplo:

[self.livePusher startPreviewAsync:self.previewView];
for (UIView *subView in [self.previewView subviews]) {
 // ...
}

Efeitos sonoros externos

Se precisar reproduzir efeitos sonoros ou música na página de ingestão de stream, recomendamos usar AVAudioPlayer, pois o SDK atualmente conflita com AudioServicesPlaySystemSound. Após a reprodução, atualize as configurações do AVAudioSession. Abaixo está um código de exemplo para reproduzir efeitos sonoros com AVAudioPlayer:

- (void)setupAudioPlayer {
 NSString *filePath = [[NSBundle
mainBundle] pathForResource:@"sound" ofType:@"wav"];
 NSURL *fileUrl = [NSURL URLWithString:filePath];
 self.player = [[AVAudioPlayer alloc] initWithContentsOfURL:fileUrl error:nil];
 self.player.volume = 1.0;
 [self.player prepareToPlay];
}
 - (void)playAudio {
 self.player.volume = 1.0;
 [self.player play];
 // Configure AVAudioSession
 AVAudioSession *session = [AVAudioSession sharedInstance];
 [session setMode:AVAudioSessionModeVideoChat error:nil];
 [session overrideOutputAudioPort:AVAudioSessionPortOverrideSpeaker error:nil];
 [session setCategory:AVAudioSessionCategoryPlayAndRecord withOptions:AVAudioSessionCategoryOptionDefaultToSpeaker|AVAudioSessionCategoryOptionAllowBluetooth
| AVAudioSessionCategoryOptionMixWithOthers error:nil];
 [session setActive:YES error:nil];
}

Modo em segundo plano e chamadas telefônicas

O SDK lida com o modo em segundo plano internamente, portanto, nenhuma ação é necessária de sua parte. Por padrão, quando o aplicativo entra em segundo plano, o SDK continua a ingerir áudio enquanto o stream de vídeo pausa no último quadro. Ative a capacidade Background Modes no seu aplicativo e selecione Audio, AirPlay and Picture in Picture. Isso garante que seu aplicativo possa capturar áudio em segundo plano.

Se quiser parar a ingestão de áudio enquanto o aplicativo está em segundo plano, destrua o mecanismo de ingestão de stream quando o aplicativo entrar em segundo plano e recrie-o quando o aplicativo se tornar ativo novamente.

Nota

Se usar este método, escute UIApplicationWillResignActiveNotification e UIApplicationDidBecomeActiveNotification. O uso de outros métodos pode levar a riscos.

Callbacks

O Push SDK inclui os seguintes callbacks principais:

Tipo de callback

Nome da classe

Callbacks de ingestão de stream

AlivcLivePusherInfoDelegate

Callbacks relacionados à rede

AlivcLivePusherNetworkDelegate

Callbacks de erro

AlivcLivePusherErrorDelegate

Callbacks de música de fundo

AlivcLivePusherBGMDelegate

Callbacks para retoque externo e processamento de filtro

AlivcLivePusherCustomFilterDelegate

Callbacks de ingestão

Os callbacks de ingestão de stream relatam o status do SDK, como quando a pré-visualização começa, o primeiro quadro de vídeo é renderizado, o primeiro quadro de áudio ou vídeo é enviado e quando a ingestão de stream inicia e para.

  • onPushStarted: Indica uma conexão bem-sucedida com o servidor.

  • onFirstFramePushed: Indica que o primeiro quadro de áudio ou vídeo foi enviado com sucesso.

  • onPushStarted e onFirstFramePushed: Indicam que o SDK iniciou a ingestão de stream com sucesso.

Callbacks de rede

Callbacks relacionados à rede notificam o aplicativo sobre o status da rede e da conexão. Para breves flutuações ou trocas de rede que estejam dentro do tempo limite de reconexão e da contagem de tentativas definidos em AlivcLivePushConfig, o SDK tenta se reconectar automaticamente. Se a reconexão for bem-sucedida, a ingestão de stream continua.

  • onConnectFail: Indica que a ingestão de stream falhou. Verifique se a url de ingestão é inválida, contém caracteres ilegais, tem problemas de autenticação, excede o limite máximo de streams simultâneos ou está em uma lista de bloqueios. Garanta que a url de ingestão seja válida e esteja disponível antes de tentar novamente. Códigos de erro específicos estão nos intervalos de 0x30020901 a 0x30020905 e 0x30010900 a 0x30010901.

  • onConnectionLost: Acionado quando a conexão é perdida. O SDK tenta se reconectar automaticamente e aciona onReconnectStart. Se a conexão não puder ser restaurada após o número máximo de tentativas (config.connectRetryCount), onReconnectError será acionado.

  • onNetworkPoor: Acionado durante condições de rede lenta. Isso indica que a rede é insuficiente para streaming estável, mas a ingestão ainda está ativa. Trate sua lógica de negócios aqui, como exibir uma notificação na UI para o usuário.

  • onNetworkRecovery: Acionado quando a conexão de rede é restaurada.

  • onReconnectError: Um callback para falha de reconexão. Isso indica que a tentativa de reconexão falhou. Recomendamos verificar a rede atual e reiniciar o stream quando a rede se recuperar.

  • onSendDataTimeout: Um callback para tempo limite de envio de dados. Recomendamos verificar a rede atual, parar o stream e reiniciá-lo quando a rede se recuperar.

  • onPushURLAuthenticationOverdue: Um callback indicando que a autenticação para a url de ingestão atual expirou. Forneça uma nova url ao SDK.

Callbacks de erro

  • onSystemError: Um callback para exceções de dispositivos do sistema. Destrua o mecanismo e tente novamente.

  • onSDKError: Um callback para erros do SDK. Trate diferentes erros com base em seus códigos:

    • Se o código de erro for 805438211, indica baixo desempenho do dispositivo e uma taxa de quadros de codificação e renderização baixa. Notifique o apresentador e pare qualquer lógica de negócios intensiva em recursos na camada do aplicativo, como retoques avançados ou animações.

    • Trate os callbacks para permissões ausentes de microfone e câmera. O código de erro para permissão de microfone ausente é 268455940, e o código de erro para permissão de câmera ausente é 268455939.

    • Por enquanto, todos os outros erros devem ser apenas registrados em log, sem exigir ações adicionais.

Callbacks de música de fundo

  • onOpenFailed: A música de fundo falhou ao iniciar. Verifique se o arquivo de música e seu caminho passados para a interface startBGMWithMusicPathAsync estão corretos. Chame startBGMWithMusicPathAsync para tentar novamente.

  • onDownloadTimeout: A reprodução da música de fundo atingiu o tempo limite. Isso ocorre frequentemente ao reproduzir música de uma url de rede. Solicite ao apresentador que verifique o status atual da rede. Chame startBGMWithMusicPathAsync para tentar novamente.

Callbacks de filtro personalizado

Use o callback AlivcLivePusherCustomFilterDelegate para integrar com SDKs de retoque de terceiros e implementar recursos de retoque básicos e avançados. O objetivo principal de AlivcLivePusherCustomFilterDelegate é fornecer a textura interna ou CVPixelBuffer do SDK para o SDK de retoque processar e, em seguida, retornar a textura ou CVPixelBuffer processado ao nosso SDK para aplicar os efeitos de retoque.

Se o interruptor livePushMode em AlivcLivePushConfig estiver definido como AlivcLivePushBasicMode, o SDK fornece o ID da textura através do callback AlivcLivePusherCustomFilterDelegate, e não o CVPixelBuffer. Os callbacks principais são:

  • onCreate: Um callback para quando o contexto OpenGL é criado. Geralmente usado para inicializar o mecanismo de retoque.

  • onProcess: Um callback para quando a textura OpenGL é atualizada. Este método fornece o ID da textura interna original do SDK. Neste callback, chame seu método de processamento de retoque e retorne o ID da textura processada.

  • onDestory: Um callback para quando o contexto OpenGL é destruído. Geralmente usado para destruir o mecanismo de retoque.

APIs comuns

/* In custom mode, you can adjust the minimum and target bitrates in real time. */
[self.livePusher setTargetVideoBitrate:800];
[self.livePusher setMinVideoBitrate:200]
/* Get the current stream ingest status. */
BOOL isPushing = [self.livePusher isPushing]; 
/* Get the ingest URL. */
NSString *pushURLString = [self.livePusher getPushURL];
/* Get performance debugging information for stream ingest. For specific parameters and descriptions, refer to the API documentation or interface comments. */
AlivcLivePushStatsInfo *info = [self.livePusher getLivePushStatusInfo];
/* Get the SDK version number. */
NSString *sdkVersion = [self.livePusher getSDKVersion];
/* Set the log level to filter debugging information as needed. */
[self.livePusher setLogLevel:(AlivcLivePushLogLevelDebug)];

Ferramenta de depuração

O SDK fornece uma ferramenta de depuração de UI chamada DebugView. DebugView é uma janela flutuante global móvel que sempre permanece no topo da hierarquia de views. Ela inclui recursos de depuração como visualização de logs de ingestão de stream, monitoramento em tempo real de parâmetros de desempenho e gráficos de linhas para métricas-chave de desempenho.

Nota

Não chame a interface para adicionar DebugView na sua build de release.

Código de exemplo:

[AlivcLivePusher showDebugView];// Open the debugging tool.

Referência da API

Referência da API para Basic Edition

FAQ

Falha na ingestão de stream

Use a ferramenta de solução de problemas para verificar se a url de ingestão é válida.

Como obtenho informações sobre streams de áudio e vídeo ingeridos?

Acesse a página Stream Management. Na seção Active Streams, visualize e gerencie seus streams de áudio e vídeo ingeridos.

Como reproduzo o stream?

Após iniciar a ingestão de stream, use um player como ApsaraVideo Player, FFplay ou VLC para testar o pull do stream. Para obter uma url de reprodução, consulte Gerar URLs de ingestão e streaming.

Rejeição de envio para a App Store

O RtsSDK é um binário fat que inclui arquiteturas tanto para dispositivos físicos quanto para o simulador. Para enviar seu aplicativo à App Store, remova a arquitetura do simulador. Use lipo -remove para remover a fatia x86_64 do binário.