SDK de Transmissão do IVS: Guia de mixagem (streaming de baixa latência)

O mixer é uma unidade de processamento de áudio e vídeo que usa várias fontes de entrada e gera uma única saída. É um recurso poderoso que permite definir e gerenciar vários elementos e faixas de áudio na tela (vídeo). Você pode combinar vídeo e áudio de várias fontes, como câmeras, microfones, capturas de tela e áudio e vídeo gerados pela sua aplicação. Você pode usar transições para mover essas fontes ao redor do vídeo que você transmite para o Amazon IVS, além de adicioná-las e removê-las durante a transmissão.

Para acessar o mixer, chame:

BroadcastSession.getMixer() no Android

IVSBroadcastSession.mixer no iOS

Terminologia

Prazo	Descrição
Binding	Para associar um dispositivo de entrada a um slot, o dispositivo deve ser vinculado ao slot do mixer. Isso é feito por meio do método Mixer.bind(). Um slot pode ter uma entrada de imagem e uma entrada de áudio vinculadas a ele ao mesmo tempo. Você pode desvincular um dispositivo do slot chamando Mixer.unbind().
Tela	A extensão de exibição do vídeo definida na sua configuração da BroadcastSession. A tela tem o mesmo tamanho definido nas suas configurações de vídeo e é executada na mesma taxa de quadros especificada na sua configuração.
Dispositivo	Um componente de hardware ou software que produz entrada de áudio ou imagem para a BroadcastSession. Alguns exemplos de dispositivos são microfones, câmeras, fones de ouvido de Bluetooth e dispositivos virtuais, como capturas de tela ou entradas de imagens personalizadas. Com exceção de entradas personalizadas, você geralmente não precisa manter uma referência ao objeto do dispositivo; em vez disso, você pode manter uma cópia do descritor do dispositivo.
Descritor de dispositivo	Uma estrutura com informações sobre um dispositivo de entrada; por exemplo, seu tipo, endereço do sistema, um nome legível por humanos “amigável” e a posição física no dispositivo móvel. Tais informações possibilitam que você defina se quer usar o dispositivo referenciado e permitem que o Amazon IVS o acesse.
Slot	Um contêiner que define a posição de um elemento visual na tela e as propriedades de uma faixa de áudio na mixagem de áudio. Um mixer pode ser configurado com zero ou mais slots. Os slots recebem um nome de string, que pode ser usado para vincular dispositivos e executar transições. A imagem acima mostra quatro slots: Inferior esquerdo com entrada de câmera Superior direito com entrada de filme Inferior direito com o logo do Amazon IVS Uma imagem de plano de fundo em tela cheia Depois de configurar uma sessão, você pode adicionar e remover slots com os métodos addSlot e removeSlot do mixer.
Transição	Para mover um slot para uma nova posição ou alterar algumas de suas propriedades, use Mixer.transition(). Esse método aceita: Uma nova estrutura de slot que representa o próximo estado para o slot Uma duração que especifica quanto tempo a animação deve demorar em relação à linha do tempo do vídeo. Se a duração for definida como 0, a transição acontecerá no próximo quadro mixado. Um retorno de chamada opcional que informa quando a animação é concluída. O retorno de chamada pode ser útil para encadear animações.

Propriedades da tela

As propriedades da tela são definidas com base na BroadcastConfiguration que você fornece ao criar a BroadcastSession. Várias propriedades nas estruturas de Audio e Video afetam a tela:

Name (Nome)	Type	Descrição
Audio.channels	Inteiro	Número de canais de saída do mixer de áudio. Valores válidos: 1, 2. Em 1, o canal é áudio mono; em 2, áudio estéreo. Padrão: 2.
Audio.sampleRate	AudioSampleRate	Número de amostras de áudio por segundo do mixer de áudio. Esse valor deve ser pelo menos o dobro da frequência mais alta em seu sinal de áudio. As pessoas podem ouvir até cerca de 20 kHz; assim, 44,1 kHz e 48 kHz costumam ser suficientes. Padrão: 48 kHz.
Video.defaultAspectMode	AspectMode	Modo padrão da taxa de proporção para slots. Valores válidos: Fill: mantenha a taxa de proporção da imagem, mas preencha o slot. A imagem será cortada, se necessário. Fit: mantenha a taxa de proporção da imagem, mas enquadre a imagem inteira no slot. O slot pode ter um letterbox ou pillarbox, se necessário. O efeito letter/pillarbox será fillColor se esse valor tiver sido definido; caso contrário, será transparente (que pode parecer preto se a cor da tela atrás da imagem for preta). None: não mantém a taxa de proporção da imagem. A imagem será escalada para garantir a correspondência com as dimensões do slot.
Video.size	Vec2	Tamanho da tela de vídeo.
Video.targetFramerate	Inteiro	Número de quadros de destino por segundo para a tela. Em média, esse valor deve ser cumprido, mas o sistema pode soltar quadros em determinadas circunstâncias (por exemplo, alta carga de CPU ou congestionamento de rede).

Propriedades do slot

Os slots têm várias propriedades configuráveis que você pode usar para personalizar suas cenas e animar. Qualquer valor que seja Float ou Vector é animado usando interpolação linear para transições com uma duração superior a 0 segundos.

Name (Nome)	Type	Descrição
aspect	AspectMode	Modo de taxa de proporção para qualquer imagem renderizada no slot. Valores válidos: Fill: mantenha a taxa de proporção da imagem, mas preencha o slot. A imagem será cortada, se necessário. Fit: mantenha a taxa de proporção da imagem, mas enquadre a imagem inteira no slot. O slot pode ter um letterbox ou pillarbox, se necessário. O efeito letter/pillarbox será fillColor se esse valor tiver sido definido; caso contrário, será transparente (que pode parecer preto se a cor da tela atrás da imagem for preta). None: não mantém a taxa de proporção da imagem. A imagem será escalada para garantir a correspondência com as dimensões do slot. Padrão: o mesmo que o aspect do Canvas (Tela) se matchCanvasAspectMode for true; caso contrário, será Fill. Definir esse valor também define matchCanvasAspectMode como false.
fillColor	Vec4	Cor de preenchimento a ser usada com o Aspect Fit (Ajuste de proporção) quando as taxas de proporção do slot e da imagem não corresponderem. O formato é (vermelho, verde, azul, alfa). Valor válido (para cada canal): 0 - 1. Padrão: (0, 0, 0, 0).
gain	Float	Ganho de áudio. Este é um multiplicador. Assim, qualquer valor acima de 1 aumenta o ganho e qualquer valor abaixo de 1, diminui. Valores válidos: 0 - 2. Padrão: 1.
matchCanvasAspectMode	Booliano	Se ele estiver definido como true, use o valor do Video.defaultAspectMode da tela. Ele é definido como false se você definir a propriedade aspect do slot. Padrão: true.
matchCanvasSize	Booliano	Se estiver como true, a dimensão do slot será ajustada para corresponder à da tela e sua posição será definida como (0, 0). Ele é definido como false se você definir a propriedade size do slot. Padrão: true.
name	Segmento	Nome do slot. É usado para referenciar o slot para associações e transições. Padrão: "default".
position	Vec2	Posição do slot (em pixels) em relação ao canto superior esquerdo da tela. A origem do slot também está no canto superior esquerdo.
preferredAudioInput	DeviceType	Tipo de dispositivo de entrada de áudio preferido. Se esse slot não estiver vinculado e um dispositivo de áudio do tipo especificado estiver anexado à sessão, o dispositivo será vinculado automaticamente a esse slot. Valores válidos: Microfone: hardware de áudio, como microfone integrado, fones de ouvido conectáveis ou fones de ouvido de Bluetooth. Áudio do sistema: áudio capturado do sistema operacional, geralmente acompanhado por uma gravação de tela. Áudio do usuário: entradas de áudio personalizadas criadas por você. Desconhecido: não há definição de dispositivo preferencial; o slot sempre será vinculado manualmente.
preferredVideoInput	DeviceType	Dispositivo de entrada de vídeo preferencial. Se esse slot não estiver vinculado e um dispositivo de vídeo do tipo especificado estiver anexado à sessão, o dispositivo será vinculado automaticamente a esse slot. Valores válidos: Câmera: dispositivos de câmera integrada, como a câmera frontal, traseira ou grande angular. Tela: captura de tela do sistema operacional. Imagem do usuário: entradas de imagem e vídeo personalizadas criadas por você. Desconhecido: não há definição de dispositivo preferencial; o slot sempre será vinculado manualmente.
size	Vec2	Tamanho do slot, em pixels. Definir esse valor também define matchCanvasSize como false. Padrão: (0, 0); contudo, como os padrões de matchCanvasSize são true, a dimensão renderizada do slot será a da tela e não (0, 0).
transparency	Float	Transparência do slot. É um valor multiplicativo com quaisquer valores alfa na imagem. A opacidade é 1 - transparency. Valores válidos: 0-1, em que 0 é totalmente opaco e 1 é totalmente transparente. Padrão: 0.
zIndex	Float	Ordenação relativa de slots. Slots com valores mais altos de zIndex são desenhados por cima dos slots com valores menores de zIndex.

Configuração de uma sessão de transmissão para mixagem

Aqui, criamos uma cena semelhante à do início deste guia, com três elementos na tela:

• Slot inferior esquerdo para uma câmera.

• Slot inferior direito para uma sobreposição de logo.

• Slot superior direito para um filme.

Observe que a origem da tela é o canto superior esquerdo, e é o mesmo para os slots. Assim, posicionar um slot em (0, 0) o coloca no canto superior esquerdo com todo o slot visível.

iOS

let config = IVSBroadcastConfiguration()
try config.video.setSize(CGSize(width: 1280, height: 720))
try config.video.setTargetFramerate(60)
config.video.enableTransparency = true

// Bottom Left
var cameraSlot = IVSMixerSlotConfiguration()
cameraSlot.size = CGSize(width: 320, height: 180) 
cameraSlot.position = CGPoint(x: 20, y: 1280 - 200)
cameraSlot.preferredVideoInput = .camera
cameraSlot.preferredAudioInput = .microphone
cameraSlot.matchCanvasAspectMode = false
cameraSlot.zIndex = 2
try cameraSlot.setName("camera")

// Top Right
var streamSlot = IVSMixerSlotConfiguration()
streamSlot.size = CGSize(width: 640, height: 320) 
streamSlot.position = CGPoint(x: 1280 - 660, y: 20)
streamSlot.preferredVideoInput = .userImage
streamSlot.preferredAudioInput = .userAudio
streamSlot.matchCanvasAspectMode = false
streamSlot.zIndex = 1
try streamSlot.setName("stream")

// Bottom Right
var logoSlot = IVSMixerSlotConfiguration()
logoSlot.size = CGSize(width: 320, height: 180) 
logoSlot.position = CGPoint(x: 1280 - 340, y: 720 - 200)
logoSlot.preferredVideoInput = .userImage
logoSlot.preferredAudioInput = .unknown
logoSlot.matchCanvasAspectMode = false
logoSlot.zIndex = 3
try logoSlot.setTransparency(0.7)
try logoSlot.setName("logo")

config.mixer.slots = [ cameraSlot, streamSlot, logoSlot ]

Android

// Bottom Left
val cameraSlot = BroadcastConfiguration.Mixer.Slot.with { s ->
    s.setSize(320, 180)
    s.position = BroadcastConfiguration.Vec2(20, 1280 - 200)
    s.preferredVideoInput = Device.Descriptor.DeviceType.CAMERA
    s.preferredAudioInput = Device.Descriptor.DeviceType.MICROPHONE
    s.matchCanvasAspectMode = false
    s.zIndex = 2
    s.name = "camera"
    s
}

// Top Right
val streamSlot = BroadcastConfiguration.Mixer.Slot.with { s ->
    s.setSize(640, 320)
    s.position = BroadcastConfiguration.Vec2(1280 - 660, 20)
    s.preferredVideoInput = Device.Descriptor.DeviceType.USER_IMAGE
    s.preferredAudioInput = Device.Descriptor.DeviceType.USER_AUDIO
    s.matchCanvasAspectMode = false
    s.zIndex = 1
    s.name = "stream"
    s
}

// Bottom Right
val logoSlot = BroadcastConfiguration.Mixer.Slot.with { s ->
    s.setSize(320, 180)
    s.position = BroadcastConfiguration.Vec2(1280 - 340, 720 - 200)
    s.preferredVideoInput = Device.Descriptor.DeviceType.USER_IMAGE
    s.preferredAudioInput = Device.Descriptor.DeviceType.UNKNOWN
    s.matchCanvasAspectMode = false
    s.zIndex = 3
    s.name = "logo"
    s.transparency = 0.7
    s
}

val config = BroadcastConfiguration.with { c ->
    c.mixer.slots = listOf(cameraSlot, streamSlot, logoSlot)
    c.video.targetFramerate = 60
    c.video.setSize(1280, 720)
    c
}

Adição de slots

Assim que você criar uma BroadcastSession com a sua configuração, poderá adicionar e remover slots do mixer. Aqui, adicionamos ao mixer um grande slot de segundo plano para uma imagem.

iOS

// Background. We will use most of the defaults for this slot.
var backgroundSlot = IVSMixerSlotConfiguration()
backgroundSlot.preferredVideoInput = .userImage
backgroundSlot.preferredAudioInput = .unknown
backgroundSlot.matchCanvasAspectMode = false
try backgroundSlot.setName("background")

session.mixer.addSlot(backgroundSlot)

Android

// Background. We will use most of the defaults for this slot.
val backgroundSlot = BroadcastConfiguration.Mixer.Slot.with { s ->
    s.preferredVideoInput = Device.Descriptor.DeviceType.USER_IMAGE
    s.preferredAudioInput = Device.Descriptor.DeviceType.UNKNOWN
    s.matchCanvasAspectMode = false
    s.name = "background"
    s
}

session.mixer.addSlot(backgroundSlot)

Remoção de slots

Para remover um slot, chame BroadcastSession.Mixer.removeSlot com o nome do slot que você deseja remover. Todos os dispositivos vinculados a esse slot são automaticamente desvinculados. Assim, você deve revinculá-los a slots diferentes se quiser continuar a usá-los.

Animações com transições

O método de transição do mixer substitui a configuração de um slot por uma nova configuração. Essa substituição pode ser animada ao longo do tempo, definindo uma duração superior a 0, em segundos.

Quais propriedades podem ser animadas?

Nem todas as propriedades na estrutura do slot podem ser animadas. Todas as propriedades baseadas em tipos Float podem ser animadas; outras propriedades começam a funcionar no início ou no final da animação.

Name (Nome)	Pode ser animado(a)?	Ponto de impacto
aspect	Não	Final
fillColor	Sim	Interpolado(a)
gain	Sim	Interpolado(a)
matchCanvasAspectMode	Não	Iniciar
matchCanvasSize	Não	Iniciar
name Observações: não é possível alterar o nome do slot.	Não	N/D
position	Sim	Interpolado(a)
preferredAudioInput	Não	Final
preferredVideoInput	Não	Final
size	Sim	Interpolado(a)
transparency	Sim	Interpolado(a)
zIndex Observações: o zIndex move planos 2D através do espaço 3D. Assim, a transição acontece quando os dois planos se cruzam em algum ponto no meio da animação. Isso pode ser calculado, mas depende dos valores de início e fim do zIndex. Para obter uma transição mais suave, combine ele com a transparency.	Sim	Desconhecido

Exemplos simples

Abaixo, estão exemplos de uma aquisição de câmera em tela cheia usando a configuração definida acima em Configuring a Broadcast Session for Mixing (Configuração de uma sessão de transmissão para mixagem). Isso fica animado por 0,5 segundo.

iOS

// Bottom Left
var bigCameraSlot = cameraSlot
bigCameraSlot.size = CGSize(width: 1280, height: 720) 
bigCameraSlot.position = CGPoint(x: 0, y: 0)

session.mixer.transition("camera", bigCameraSlot, 0.5) {
    println("animation completed!")
}

Android

// Bottom Left
val bigCameraSlot = cameraSlot.changing { s ->
    s.setSize(1280, 720)
    s.position = BroadcastConfiguration.Vec2(0, 0)
    s
}

session.mixer.transition("camera", bigCameraSlot, 0.5) {
    print("animation completed!")
}

Espelhamento da transmissão

Para espelhar um dispositivo de imagem conectado na transmissão nessa direção...	Use um valor negativo para...
Horizontalmente	Largura do slot
Verticalmente	Altura do slot
Horizontalmento e verticalmente	Tanto a largura quanto a altura do slot

A posição precisará ser ajustada com base no mesmo valor para colocar o slot na posição correta quando espelhado.

Abaixo estão alguns exemplos para espelhar a transmissão horizontalmente e verticalmente.

iOS

Espelhamento horizontal:

var cameraSlot = IVSMixerSlotConfiguration
cameraSlot.size = CGSize(width: -320, height: 720)
// Add 320 to position x since our width is -320
cameraSlot.position = CGPoint(x: 320, y: 0)

Espelhamento vertical:

var cameraSlot = IVSMixerSlotConfiguration
cameraSlot.size = CGSize(width: 320, height: -720)
// Add 720 to position y since our height is -720
cameraSlot.position = CGPoint(x: 0, y: 720)

Android

Espelhamento horizontal:

cameraSlot = BroadcastConfiguration.Mixer.Slot.with {
   it.size = BroadcastConfiguration.Vec2(-320f, 180f)
   // Add 320f to position x since our width is -320f
   it.position = BroadcastConfiguration.Vec2(320f, 0f)
   return@with it
}

Espelhamento vertical:

cameraSlot = BroadcastConfiguration.Mixer.Slot.with {
   it.size = BroadcastConfiguration.Vec2(320f, -180f)
   // Add 180f to position y since our height is -180f
   it.position = BroadcastConfiguration.Vec2(0f, 180f)
   return@with it
}

Observação: esse espelhamento é diferente do método setMirrored no ImagePreviewView (Android) e IVSImagePreviewView (iOS). Esse método afeta somente a visualização local no dispositivo e não afeta a transmissão.