Fontes de live stream e LSI¶

media.live.inputs

O LSI (Live Source Input) gerencia as entradas de um live stream. Ele recebe mídia da fonte selecionada, acompanha seu estado e organiza a recuperação em caso de problemas. Se o stream tiver entradas de reserva configuradas, o LSI avalia sua disponibilidade e escolhe de onde continuar a captura.

Para uma transmissão contínua, não basta abrir o endereço de entrada uma única vez. A fonte pode manter a conexão, mas deixar de fornecer vídeo. O caminho principal pode se recuperar por apenas alguns segundos. A reserva pode estar indisponível justamente quando for necessária. O LSI acompanha as fontes durante toda a operação do stream e toma decisões com base nos dados de mídia.

O gerenciamento de fontes faz parte do pipeline do Sapsan:

• Controle da captura identifica a ausência de quadros e problemas em faixas individuais.
• Avaliação da qualidade permite detectar danos no fluxo antes da interrupção completa da captura.
• Verificação das reservas fornece informações sobre seu funcionamento antes de uma falha da entrada principal.
• Comutação coordenada prepara a nova fonte e encaminha sua mídia pelo pipeline.
• Observabilidade mostra a entrada selecionada e os motivos das decisões, além de permitir medir o tempo de operação na reserva.

O que significa uma fonte estar funcionando¶

Uma conexão de rede bem-sucedida ainda não significa que a fonte esteja pronta para transmissão. O LSI considera a chegada de dados de mídia e a existência de um ponto a partir do qual seja possível começar seu processamento. Para uma entrada de vídeo baseada em quadros, esse ponto é um quadro-chave; para uma fonte apenas de áudio, um quadro de áudio. Na captura com preservação de fragmentos prontos, utiliza-se o limite de um fragmento.

O estado da fonte depende das observações disponíveis para seu protocolo e das regras configuradas:

O LSI distingue falha de degradação da qualidade. Em uma falha, não é possível continuar a captura da entrada: por exemplo, o tempo limite sem quadros ou o tempo limite de vídeo configurado foi atingido. Essa entrada é fechada e começa a busca por uma alternativa.

Na degradação da qualidade, a mídia continua chegando. Por exemplo, o áudio desapareceu ou o número de erros de continuidade ultrapassou o limite permitido. O LSI procura uma fonte mais adequada, mantendo a captura atual. Se não houver uma fonte reserva em boas condições, ele continua usando a fonte degradada: a transmissão parcialmente preservada permanece disponível.

Esse controle avalia o estado técnico da mídia. Quadros que chegam no horário com uma imagem estática não significam, por si só, um timeout de vídeo. As regras de degradação são descritas no controle de qualidade das fontes.

Como o LSI escolhe a fonte¶

Várias entradas em inputs descrevem fontes alternativas de um mesmo stream. Na operação normal, a mídia da entrada selecionada é encaminhada pelo pipeline. A prioridade padrão segue a ordem da lista; a definição explícita de source_options.priority permite alterá-la. Um número menor significa prioridade mais alta.

A janela limpa é um intervalo sem violações das regras de qualidade. Sua duração é definida por return_alive_secs, com padrão de 15 segundos. No retorno a uma fonte de maior prioridade, uma conexão bem-sucedida não basta: o LSI precisa observar uma captura estável. Isso protege a transmissão contra comutações repetidas para uma fonte que se recupera por pouco tempo.

A comutação de emergência após a falha da entrada atual não espera essa janela completa: a captura é retomada assim que o candidato estiver pronto. Se ainda for necessário abrir a reserva, o tempo de recuperação inclui o estabelecimento da conexão e a espera por um ponto inicial adequado.

Conexões malsucedidas são repetidas com pausas crescentes. Assim, um endereço indisponível não provoca um ciclo contínuo de tentativas imediatas. Os parâmetros detalhados estão em comutação de fontes.

Como a reserva é verificada¶

O LSI pode verificar a reserva enquanto a fonte principal continua funcionando. A verificação recebe dados reais de mídia e avalia sua qualidade. O resultado contém o estado da fonte e o horário da observação; ele fica disponível pela API junto com as informações das faixas.

A verificação periódica é definida por recheck_secondary_inputs_interval: o padrão é 900 segundos e o valor 0 a desativa. Esse é um intervalo de agendamento das verificações em segundo plano, não uma garantia de abrir cada reserva exatamente a cada 900 segundos. A operação atual do LSI e as pausas de reconexão influenciam o momento da verificação.

Uma verificação bem-sucedida em segundo plano termina com o fechamento da entrada de reserva. Portanto, o estado working de uma fonte não selecionada significa que ela estava funcionando na última observação. Avalie a atualidade do resultado por checked_at. Isso não implica captura paralela e permanente de todas as reservas.

O método de verificação depende da entrada. Uma fonte à qual o Sapsan se conecta pode ser aberta temporariamente. Na publicação, o remetente inicia a conexão: o LSI observa a publicação recebida, mas não pode abri-la no lugar do remetente. A janela limpa de retorno descrita se aplica às entradas verificáveis; uma publicação recebida e admitida pode ser selecionada já no primeiro quadro inicial adequado.

Comutação e continuidade da transmissão¶

Em uma comutação preparada, o LSI mantém a captura atual até que a substituta esteja pronta. Por exemplo, o stream está usando a entrada de reserva e a principal se recuperou:

1. O LSI abre a entrada principal; a mídia da reserva continua chegando aos consumidores.
2. A principal passa pela janela limpa.
3. Em um quadro-chave adequado ou no limite de um fragmento, o LSI seleciona a entrada principal.
4. O pipeline recebe a notificação de mudança de fonte e os novos parâmetros de mídia antes dos quadros da nova entrada.

Assim, a espera pela verificação da fonte principal não se transforma em uma pausa na transmissão. A comutação ocorre dentro do mesmo stream nomeado; o operador não precisa pará-lo e criá-lo novamente.

O tratamento do tempo também considera a mudança de fonte. Para entradas que exigem associação ao horário do servidor, o componente correspondente do pipeline restabelece essa associação. Para protocolos com uma escala de tempo de calendário confiável e modos de preservação de fragmentos, aplicam-se suas próprias regras de preservação dos timestamps.

Esses mecanismos permitem organizar uma comutação sem interrupções com fontes compatíveis e preparadas. O resultado para o espectador depende de toda a cadeia:

• Compatibilidade da mídia. Alinhe os codecs e a composição das faixas. Verifique também os parâmetros de vídeo e áudio: uma mudança de formato pode exigir a reconfiguração do decodificador.
• Sincronização do conteúdo. Duas fontes do mesmo canal de televisão podem ter atrasos diferentes. Sem alinhar o conteúdo, a comutação pode repetir ou pular um trecho da programação.
• Disponibilidade do ponto inicial. Um GOP longo aumenta a espera pelo quadro-chave. Entradas com fragmentos prontos comutam no limite de um fragmento.
• Tipo de falha. Se a fonte atual desaparecer repentinamente, a comutação por si só não recupera os quadros já perdidos. A pausa depende do timeout de detecção e da prontidão da reserva.
• Cadeia de saída. Verifique a comutação com os protocolos de entrega e reprodutores reais e, ao transcodificar, com a configuração escolhida do transcodificador.

O LSI não verifica a equivalência completa dos parâmetros de codificação antes de cada comutação. A simples presença de dois endereços em inputs não garante uma transição imperceptível. Ao projetar o sistema, prepare as fontes e verifique a reprodução final. Se todas as entradas estiverem indisponíveis, a função separada de vinheta permite fornecer um arquivo preparado.

Exemplo de configuração¶

O Sapsan recebe a configuração pela API do central. Abaixo está um fragmento YAML com duas fontes UDP alternativas. As configurações de lsi definem a política comum do stream, enquanto source_options especifica os parâmetros compatíveis de uma entrada individual.

streams:
  - name: tv1
    inputs:
      - udp:
          host: 239.0.0.1
          port: 5000
        source_options:
          priority: 1
      - udp:
          host: 239.0.0.2
          port: 5000
        source_options:
          priority: 2
    lsi:
      source_timeout: 5
      video_timeout: 3
      audio_timeout: 3
      cc_errors_limit: 10
      return_alive_secs: 15
      recheck_secondary_inputs_interval: 900
      reconnect_initial_delay: 1500
      reconnect_delay_step: 5000
      reconnect_max_delay: 60000

Neste exemplo, a ausência de qualquer quadro por 5 segundos ou de vídeo por 3 segundos significa falha da entrada. A ausência de áudio por 3 segundos significa degradação da qualidade. O limite de erros de continuidade é 10 por janela de avaliação; ultrapassá-lo degrada o estado da fonte. A verificação de retorno à principal exige uma janela limpa de 15 segundos.

Os tempos limite e intervalos de observação do exemplo estão em segundos. Os parâmetros reconnect_* estão em milissegundos: pausa inicial de 1500 ms, incremento de 5000 ms e limite de 60000 ms. Esses parâmetros de reconexão são definidos em lsi.

Os valores dos tempos limite foram escolhidos para o exemplo. Ajuste-os ao comportamento da fonte e à interrupção de transmissão aceitável. Por padrão, source_timeout é de 60 segundos, e os tempos limite individuais de vídeo e áudio não estão ativados.

O que monitorar¶

A API do central permite consultar o estado das entradas do stream:

curl -fsS -u "$ADMIN_USER:$ADMIN_PASSWORD" \
  http://central:8080/central/api-v4/streams/stats/tv1 \
  | jq '{name, inputs: [.inputs[] | {
      url, current, status,
      problems: (.problems // []),
      checked_at, error, failure_cause
    }]}'

O campo current mostra a entrada selecionada, e status, seu estado. Esses atributos são independentes: a entrada atual pode estar degraded, e a reserva, working. Durante a busca de emergência, current ainda não confirma a retomada da captura: considere status e a reprodução real.

• unchecked — ainda não há resultado de observação.
• starting — a entrada está aberta, mas ainda não foi recebido um ponto inicial adequado.
• working — pelas observações disponíveis, a fonte está funcionando.
• degraded — a mídia chega com violações das regras de qualidade.
• dead — a fonte está indisponível ou foi considerada em falha.

problems informa as violações detectadas, enquanto error e failure_cause ajudam a investigar o erro. checked_at contém o horário da observação em UTC, no formato RFC 3339; ele pode estar ausente em uma fonte ainda não verificada. A consulta de estatísticas, por si só, não inicia uma verificação da reserva.

Os seguintes sinais são úteis para o monitoramento operacional:

• Degradação da entrada atual — current: true junto com degraded ou uma falha.
• Perda da reserva — a entrada de reserva falhou ou está há muito tempo sem confirmação recente de funcionamento, embora a entrega atual continue funcionando.
• Comutações frequentes — input_switches aumenta; verifique a estabilidade das fontes e as configurações de retorno.
• Operação prolongada na reserva — num_sec_on_secondary_input aumenta; a recuperação da principal exige atenção.
• Ausência de mídia — num_sec_no_data aumenta.

Os contadores detalhados de .input estão disponíveis na consulta de estatísticas de um único stream ao streamer que realiza a captura: /streamer/api-v4/streams/stats/tv1. O estado compacto no central não substitui essa seção. O exemplo de consulta e as regras de cálculo dos intervalos estão em medição do tempo nas entradas.

input_switches conta as transições entre entradas configuradas diferentes; reconectar à mesma entrada, por si só, não é uma comutação. Os contadores de tempo distinguem a primeira entrada da lista das demais, mesmo quando as prioridades são redefinidas. São valores acumulados: para avaliar um período, compare observações consecutivas e considere a reinicialização das estatísticas após um reinício.

Como verificar a redundância antes de entrar em operação¶

1. Confirme que a entrada principal esperada está selecionada. Obtenha um resultado recente da verificação da reserva e compare inputs[].media_info: os parâmetros das entradas devem corresponder ao projeto do sistema.
2. Interrompa a fonte principal de forma controlada. Verifique a mudança de current e o aumento de input_switches, acompanhando simultaneamente a reprodução real.
3. Restaure a fonte principal. Para entradas às quais o Sapsan se conecta, confirme que a reserva continua funcionando durante a verificação e que o retorno ocorre após a janela limpa.
4. Verifique separadamente a degradação da qualidade sem interromper a conexão, por exemplo, a perda da faixa de áudio com audio_timeout ativado.
5. Verifique a falha da reserva com a principal funcionando: o monitoramento deve detectar a perda de redundância antes de uma falha da entrada principal.

O que o LSI oferece ao serviço de transmissão¶

O FFmpeg fornece ferramentas de processamento de mídia e consegue restabelecer conexões — por exemplo, o HTTP dispõe de parâmetros de reconexão. Ao construir um serviço em torno de um comando FFmpeg, o gerenciamento do ciclo de vida de várias fontes exige uma solução separada.

No Sapsan, esse trabalho é integrado ao LSI. O operador define as fontes e a política; o streamer observa a qualidade e prepara as comutações, enquanto a API fornece o estado para monitoramento. Assim, a redundância se torna uma parte gerenciável da transmissão contínua: é possível verificar antecipadamente o caminho de reserva, explicar o motivo da mudança de fonte e confirmar que a principal se recuperou de forma estável.