Publicação e assinatura com o SDK de Transmissão para iOS do IVS | Streaming em tempo real

Este documento descreve as etapas envolvidas na publicação e assinatura de um estágio usando o SDK de Transmissão para iOS para streaming em tempo real do IVS.

Conceitos

Existem três conceitos principais que fundamentam a funcionalidade em tempo real: palco, estratégia e renderizador. O objetivo do projeto é minimizar a quantidade de lógica do lado do cliente que é necessária para desenvolver um produto funcional.

Estágio

A classe IVSStage corresponde ao principal ponto de interação entre a aplicação de host e o SDK. A classe representa o próprio palco e é usada para entrar e sair do palco. Criar ou entrar em um palco requer uma string de token válida e não expirada do ambiente de gerenciamento (representada como token). Entrar e sair de um palco é simples.

let stage = try IVSStage(token: token, strategy: self)

try stage.join()

stage.leave()

Na classe IVSStage, também é possível anexar IVSStageRenderer e IVSErrorDelegate:

let stage = try IVSStage(token: token, strategy: self)
stage.errorDelegate = self
stage.addRenderer(self) // multiple renderers can be added

Strategy

O protocolo IVSStageStrategy fornece uma maneira para a aplicação de host comunicar o estado desejado do palco ao SDK. Três funções precisam ser implementadas: shouldSubscribeToParticipant, shouldPublishParticipant e streamsToPublishForParticipant. Todas serão discutidas abaixo.

Como se inscrever como participante

func stage(_ stage: IVSStage, shouldSubscribeToParticipant participant: IVSParticipantInfo) -> IVSStageSubscribeType

Quando um participante remoto entra em um palco, o SDK consulta a aplicação de host sobre o estado de inscrição desejado para esse participante. As opções são .none, .audioOnly e .audioVideo. Ao retornar um valor para essa função, a aplicação de host não precisa se preocupar com o estado de publicação, o estado atual da inscrição ou o estado da conexão do palco. Se .audioVideo for retornado, o SDK aguardará até que o participante remoto esteja publicando antes de inscrever e atualizará a aplicação de host por meio do renderizador durante todo o processo.

Veja a seguir uma amostra de implementação:

func stage(_ stage: IVSStage, shouldSubscribeToParticipant participant: IVSParticipantInfo) -> IVSStageSubscribeType {
    return .audioVideo
}

Esta é a implementação completa desta função para uma aplicação de host que sempre deseja que todos os participantes se vejam, por exemplo, uma aplicação de bate-papo por vídeo.

Implementações mais avançadas também são possíveis. Use a propriedade attributes em IVSParticipantInfo para se inscrever, de forma seletiva, como participante com base nos recursos fornecidos pelo servidor:

func stage(_ stage: IVSStage, shouldSubscribeToParticipant participant: IVSParticipantInfo) -> IVSStageSubscribeType {
    switch participant.attributes["role"] {
    case "moderator": return .none
    case "guest": return .audioVideo
    default: return .none
    }
}

Isso pode ser usado para criar um palco no qual os moderadores podem monitorar todos os convidados sem serem vistos ou ouvidos. A aplicação de host pode usar uma lógica de negócios adicional para permitir que os moderadores se vejam, mas permaneçam invisíveis para os convidados.

Configuração da assinatura de participantes

func stage(_ stage: IVSStage, subscribeConfigurationForParticipant participant: IVSParticipantInfo) -> IVSSubscribeConfiguration

Se um participante remoto estiver fazendo uma assinatura (consulte Assinatura de participantes), o SDK consultará a aplicação host sobre uma configuração de assinatura personalizada para esse participante. Essa configuração é opcional e permite que a aplicação host controle certos aspectos do comportamento do assinante. Para obter informações sobre o que pode ser configurado, consulte SubscribeConfiguration na documentação de referência do SDK.

Veja a seguir uma amostra de implementação:

func stage(_ stage: IVSStage, subscribeConfigurationForParticipant participant: IVSParticipantInfo) -> IVSSubscribeConfiguration {
    let config = IVSSubscribeConfiguration()

    try! config.jitterBuffer.setMinDelay(.medium())

    return config
}

Essa implementação atualiza o atraso mínimo do buffer de instabilidade para todos os participantes assinantes para uma predefinição de MEDIUM.

Como com shouldSubscribeToParticipant, implementações mais avançadas são possíveis. As ParticipantInfo fornecidas podem ser usadas para atualizar seletivamente a configuração de assinatura para participantes específicos.

Recomendamos usar os valores padrão. Especifique a configuração personalizada somente se houver um comportamento específico que você queira alterar.

Publicação

func stage(_ stage: IVSStage, shouldPublishParticipant participant: IVSParticipantInfo) -> Bool

Uma vez conectado ao palco, o SDK consulta a aplicação de host para visualizar se um determinado participante deve realizar uma publicação. Isso é invocado somente para participantes locais que têm permissão para realizar publicações com base no token fornecido.

Veja a seguir uma amostra de implementação:

func stage(_ stage: IVSStage, shouldPublishParticipant participant: IVSParticipantInfo) -> Bool {
    return true
}

Isso é para uma aplicação de bate-papo por vídeo padrão na qual os usuários sempre desejam realizar publicações. Eles podem ativar e desativar o áudio e o vídeo para serem ocultados ou vistos/ouvidos instantaneamente. (Também é possível usar publicar/cancelar a publicação, mas isso é muito mais lento. Ativar/Desativar o áudio é preferível para casos de uso em que é desejável alterar a visibilidade com frequência.)

Como escolher streams para realizar publicações

func stage(_ stage: IVSStage, streamsToPublishForParticipant participant: IVSParticipantInfo) -> [IVSLocalStageStream]

Ao realizar publicações, isso é usado para determinar quais streams de áudio e de vídeo devem ser publicados. Isso será abordado com mais detalhes posteriormente em Publish a Media Stream.

Como atualizar a estratégia

A estratégia pretende ser dinâmica, ou seja, os valores retornados de qualquer uma das funções acima podem ser alterados a qualquer momento. Por exemplo, se a aplicação de host não desejar realizar publicações até que o usuário final toque em um botão, você poderá retornar uma variável de shouldPublishParticipant (algo como hasUserTappedPublishButton). Quando essa variável for alterada com base em uma interação do usuário final, chame stage.refreshStrategy() para sinalizar ao SDK que ele deve consultar a estratégia para obter os valores mais recentes, aplicando somente o que sofreu alterações. Se o SDK observar que o valor shouldPublishParticipant foi alterado, ele iniciará o processo de publicação. Se as consultas do SDK e todas as funções retornarem o mesmo valor anterior, a chamada refreshStrategy não fará nenhuma modificação no palco.

Se o valor de retorno de shouldSubscribeToParticipant for alterado de .audioVideo para .audioOnly, a transmissão de vídeo será removida para todos os participantes com os valores retornados alterados, caso uma transmissão de vídeo tenha existido anteriormente.

Geralmente, o palco usa a estratégia para aplicar com mais eficiência a diferença entre as estratégias anteriores e atuais, sem que a aplicação de host precise se preocupar com todo o estado necessário para realizar o gerenciamento adequado. Por causa disso, pense na chamada stage.refreshStrategy() como uma operação barata, porque ela não faz nada a menos que a estratégia seja alterada.

Renderizador

O protocolo IVSStageRenderer comunica o estado do palco à aplicação de host. Geralmente, as atualizações na interface do usuário da aplicação de host podem ser baseadas inteiramente nos eventos fornecidos pelo renderizador. O renderizador fornece as seguintes funções:

func stage(_ stage: IVSStage, participantDidJoin participant: IVSParticipantInfo)

func stage(_ stage: IVSStage, participantDidLeave participant: IVSParticipantInfo)

func stage(_ stage: IVSStage, participant: IVSParticipantInfo, didChange publishState: IVSParticipantPublishState)

func stage(_ stage: IVSStage, participant: IVSParticipantInfo, didChange subscribeState: IVSParticipantSubscribeState)

func stage(_ stage: IVSStage, participant: IVSParticipantInfo, didAdd streams: [IVSStageStream])

func stage(_ stage: IVSStage, participant: IVSParticipantInfo, didRemove streams: [IVSStageStream])

func stage(_ stage: IVSStage, participant: IVSParticipantInfo, didChangeMutedStreams streams: [IVSStageStream])

func stage(_ stage: IVSStage, didChange connectionState: IVSStageConnectionState, withError error: Error?)

Não é esperado que as informações fornecidas pelo renderizador impactem os valores de retorno da estratégia. Por exemplo, não se espera que o valor de retorno de shouldSubscribeToParticipant seja alterado quando participant:didChangePublishState for chamado. Se a aplicação de host desejar inscrever um determinado participante, ele deverá retornar o tipo de inscrição desejado, independentemente do estado de publicação desse participante. O SDK é responsável por garantir que o estado desejado da estratégia seja acionado no momento correto com base no estado do palco.

Observe que somente a publicação de participantes aciona participantDidJoin e, sempre que um participante interrompe as publicações ou sai da sessão de palco, participantDidLeave é acionado.

Publicação de uma transmissão de mídia

Dispositivos locais, como microfones e câmeras integrados, são descobertos por meio de IVSDeviceDiscovery. Veja a seguir um exemplo de como selecionar a câmera frontal e o microfone padrão e, em seguida, retorná-los como IVSLocalStageStreams para serem publicados pelo SDK:

let devices = IVSDeviceDiscovery().listLocalDevices()

// Find the camera virtual device, choose the front source, and create a stream
let camera = devices.compactMap({ $0 as? IVSCamera }).first!
let frontSource = camera.listAvailableInputSources().first(where: { $0.position == .front })!
camera.setPreferredInputSource(frontSource)
let cameraStream = IVSLocalStageStream(device: camera)

// Find the microphone virtual device and create a stream
let microphone = devices.compactMap({ $0 as? IVSMicrophone }).first!
let microphoneStream = IVSLocalStageStream(device: microphone)

// Configure the audio manager to use the videoChat preset, which is optimized for bi-directional communication, including echo cancellation.
IVSStageAudioManager.sharedInstance().setPreset(.videoChat)

// This is a function on IVSStageStrategy
func stage(_ stage: IVSStage, streamsToPublishForParticipant participant: IVSParticipantInfo) -> [IVSLocalStageStream] {
    return [cameraStream, microphoneStream]
}

Exibição e remoção de participantes

Após a conclusão da inscrição, você receberá uma matriz de objetos IVSStageStream por meio da função didAddStreams do renderizador. Para visualizar previamente ou receber estatísticas de nível de áudio sobre este participante, é possível acessar o objeto IVSDevice subjacente da transmissão:

if let imageDevice = stream.device as? IVSImageDevice {
    let preview = imageDevice.previewView()
    /* attach this UIView subclass to your view */
} else if let audioDevice = stream.device as? IVSAudioDevice {
    audioDevice.setStatsCallback( { stats in
        /* process stats.peak and stats.rms */
    })
}

Quando um participante interrompe as publicações ou cancela a inscrição, a função didRemoveStreams é chamada com as transmissões que foram removidas. As aplicações de host devem usar isso como um sinal para remover a transmissão de vídeo do participante da hierarquia de visualização.

didRemoveStreams é invocada para todos os cenários em que uma transmissão pode ser removida, incluindo:

Como didRemoveStreams é invocada para todos os cenários, nenhuma lógica de negócios personalizada é necessária para remover participantes da IU durante operações de saída remotas ou locais.

Ativação ou desativação do áudio para transmissões de mídia

Os objetos IVSLocalStageStream têm uma função setMuted que controla se a transmissão é silenciada. Essa função pode ser chamada na transmissão antes ou depois de ser retornada da função de estratégia streamsToPublishForParticipant.

Importante: se uma nova instância de objeto IVSLocalStageStream for retornada por streamsToPublishForParticipant após uma chamada para refreshStrategy, o estado mudo do novo objeto de transmissão será aplicado ao palco. Tenha cuidado ao criar novas instâncias IVSLocalStageStream para garantir que o estado mudo esperado seja mantido.

Monitoramento do estado mudo da mídia do participante remoto

Quando um participante altera o estado mudo de sua transmissão de vídeo ou áudio, a função didChangeMutedStreams do renderizador é invocada com uma matriz de transmissões que foram alteradas. Use a propriedade isMuted na IVSStageStream para atualizar a IU adequadamente:

func stage(_ stage: IVSStage, participant: IVSParticipantInfo, didChangeMutedStreams streams: [IVSStageStream]) {
    streams.forEach { stream in 
        /* stream.isMuted */
    }
}

Criação de uma configuração de palco

Para personalizar os valores da configuração de vídeo de um palco, use IVSLocalStageStreamVideoConfiguration:

let config = IVSLocalStageStreamVideoConfiguration()
try config.setMaxBitrate(900_000)
try config.setMinBitrate(100_000)
try config.setTargetFramerate(30)
try config.setSize(CGSize(width: 360, height: 640))
config.degradationPreference = .balanced

Obtenção de estatísticas WebRTC

Para obter as estatísticas WebRTC mais recentes para uma transmissão de publicação ou uma transmissão de inscrição, use requestRTCStats em IVSStageStream. Quando uma coleta for concluída, você receberá as estatísticas por meio do IVSStageStreamDelegate, que pode ser definido em IVSStageStream. Para coletar estatísticas WebRTC de forma contínua, chame esta função em um Timer.

func stream(_ stream: IVSStageStream, didGenerateRTCStats stats: [String : [String : String]]) {
    for stat in stats {
      for member in stat.value {
         print("stat \(stat.key) has member \(member.key) with value \(member.value)")
      }
   }
}

Obtenção de atributos do participante

Se você especificar atributos na solicitação de endpoint CreateParticipantToken, poderá visualizar os atributos nas propriedades IVSParticipantInfo:

func stage(_ stage: IVSStage, participantDidJoin participant: IVSParticipantInfo) {
    print("ID: \(participant.participantId)")
    for attribute in participant.attributes {
        print("attribute: \(attribute.key)=\(attribute.value)")
    }
}

Continuação da sessão em segundo plano

Quando a aplicação entra em segundo plano, é possível continuar no palco enquanto ouve o áudio remoto, embora não seja possível continuar enviando a própria imagem e áudio. Você precisará atualizar a implementação de sua IVSStrategy para interromper as publicações e se inscrever como .audioOnly (ou .none, se aplicável):

func stage(_ stage: IVSStage, shouldPublishParticipant participant: IVSParticipantInfo) -> Bool {
    return false
}
func stage(_ stage: IVSStage, shouldSubscribeToParticipant participant: IVSParticipantInfo) -> IVSStageSubscribeType {
    return .audioOnly
}

Em seguida, realize uma chamada para stage.refreshStrategy().

Habilitação ou desabilitação da codificação em camadas com a transmissão simultânea

Ao publicar um stream de mídia, o SDK transmite streams de vídeo de alta e de baixa qualidade, para que os participantes remotos possam se inscrever no streaming, mesmo que tenham largura de banda de downlink limitada. Por padrão, a codificação em camadas com a transmissão simultânea está ativada. É possível desabilitá-la com IVSSimulcastConfiguration:

// Disable Simulcast
let config = IVSLocalStageStreamVideoConfiguration()
config.simulcast.enabled = false

let cameraStream = IVSLocalStageStream(device: camera, configuration: config)

// Other Stage implementation code

Transmissão do palco para um canal do IVS

Para transmitir um palco, crie uma IVSBroadcastSession separada e, em seguida, siga as instruções usuais para uma transmissão com o SDK, descritas acima. A propriedade device na IVSStageStream será um IVSImageDevice ou um IVSAudioDevice, conforme mostrado no trecho de código acima. Eles podem ser conectados ao IVSBroadcastSession.mixer para transmitir todo o palco em um layout personalizável.

Você também pode compor um palco e transmiti-lo para um canal de baixa latência do IVS para alcançar um público maior. Consulte Enabling Multiple Hosts on an Amazon IVS Stream no Guia do usuário do streaming de baixa latência do IVS.