MPTS Migrate Perfect Streamer Toolkit v1.1 — migração da identidade MPTS

Parte do Perfect Streamer Toolkit — https://pstreamer.tv

Captura a identidade DVB SI/PSI de um fluxo MPEG-TS multiprograma (MPTS) em operação e a reproduz em uma instância do Perfect Streamer (PSS) no mesmo host. Resultado: os receptores dos assinantes (STB / TV) continuam funcionando sem uma nova busca de canais após a migração ou a comutação para a reserva.

A ferramenta faz parte do pacote pstreamer e, após a instalação, encontra-se em /opt/pss/tools/mpts_migrate — não é necessário instalar nada separadamente.

Pré-requisitos

Antes de executar o utilitário, certifique-se de que:

  • O PSS está em execução no mesmo host (ou em um host acessível via --pss-base). O utilitário procura pss em /proc e lê pss.json para obter a porta de administração (43971, se ela não estiver na configuração).

  • A fonte MPTS está acessível, caso seja prevista uma captura (modos 1, 2, save+apply): a URL passada como argumento posicional <input> deve fornecer um fluxo MPEG-TS. Para UDP multicast, é necessário que IGMP / firewall permitam a recepção; para arquivos, o caminho deve existir.

  • O MPTS de destino já está configurado no PSS: o utilitário não cria novos fluxos. O objeto MPTS e pelo menos tantos alimentadores SPTS quantos forem os serviços do inventário devem existir previamente. Os serviços sem alimentador livre são exibidos no diálogo e podem ser ignorados.

  • A API HTTP de administração está aberta em localhost para leitura de /data/stream (usada no verify) e gravação em /config/stream (apply).

O que é migrado

Todos os identificadores visíveis ao receptor, nos níveis de fluxo de transporte e de serviço:

  • Fluxo de transporte: TSID, ONID, network ID, network name, provider name (aplicado como sdt-provider-name comum a todo o multiplex, se todos os serviços de origem tiverem o mesmo valor), descritor de entrega (parâmetros de transmissão terrestre / cabo / satélite), versões de PAT/SDT/NIT

  • Por serviço: service_id, pmt_pid, pcr_pid, service_type, nome do serviço, número lógico de canal (LCN), flag free-CA, flags EIT-present / EIT-schedule

  • Fluxos elementares: PIDs (é aplicado um identity remap — veja Limitações), tipos de fluxo, tags de idioma

  • Acesso condicional: descritores CA nos níveis de programa e de ES

Os nomes de serviços / provedores em codificações DVB diferentes de ASCII (por exemplo, ISO-8859-5 para o cirílico) são decodificados para UTF-8 automaticamente.

Para cada serviço, o remap de PID de ES é construído como pares identidade (mpegts-pid-old ≡ mpegts-pid-new) para cada PID de PCR / video / audio / teletext / data, de modo que, na saída multiplexada resultante, os PIDs originais sejam preservados byte-exact. Os receptores antigos que armazenam a PMT em cache após a primeira busca continuam funcionando sem reconfiguração.

No PSS 2.0.0.193 e posteriores, o plano habilita adicionalmente, na entrada do muxer do MPTS de destino, o modo nativo de preservação dos PIDs originais (Automatic PID mapping desativado) e define, para cada serviço, o número de ordem do programa capturado na PAT (program order) — a ordem dos programas no ar sobrevive à migração. O suporte é detectado automaticamente pela configuração do streamer de destino; em versões mais antigas essas chaves não são enviadas (o utilitário imprime um aviso) e o único mecanismo de fixação dos PIDs continua sendo os pares identidade, enquanto a ordem dos programas na PAT não é preservada.

Casos de uso

  • Failover: comutação dos decodificadores do MPTS principal para o de reserva, preservando os canais no lado do receptor

  • Migração de hardware: transferência de um multiplex em operação de um host PSS para outro sem instruções aos telespectadores

  • Instantâneo antes / depois da atualização: captura do multiplex antes da atualização do PSS e nova aplicação depois dela, para garantir um SI/PSI bit a bit idêntico

  • Edição manual e nova aplicação: captura, edição de migrate.json (renomear serviços, alterar o LCN, ajustar service_type), nova aplicação

  • Verificação em dry-run: impressão de cada HTTP POST que seria enviado, sem afetar o PSS

Início rápido

# Capture from a live stream and apply to local PSS in one run
mpts_migrate udp://239.1.1.1:1234

# Capture, save to migrate.json and apply
mpts_migrate -s udp://239.1.1.1:1234

# Capture only — write to file, do not apply
mpts_migrate -o backup.json udp://239.1.1.1:1234

# Apply a previously saved JSON
mpts_migrate -i backup.json

# No arguments — load ./migrate.json and apply
mpts_migrate

# Preview what apply would do, without changes
mpts_migrate -i backup.json --dry-run

Fluxo de trabalho

  1. Captura — o utilitário abre o fluxo, analisa PAT / PMT / SDT / NIT / EIT durante -t segundos (30 por padrão) e monta o inventário; é medida a taxa de bits total do fluxo.

  2. (Opcional) Gravação — com -s ou -o o inventário é gravado em JSON para reutilização posterior.

  3. Localização do PSS — detecta o PSS em execução por meio de uma varredura de /proc e lê pss.json para obter a porta de administração (43971, se ela não estiver na configuração); --pss-base http://host:port contorna a autodetecção.

  4. Confirmação do mapeamento — um diálogo interativo pergunta como mapear cada serviço capturado para um alimentador SPTS existente; --non-interactive aceita as sugestões e encerra a execução em caso de conflito; --target-mpts <id> ignora a solicitação de seleção do MPTS.

  5. Retirada automática da pausa dos alimentadores — para cada SPTS / muxer-output mapeado, o utilitário envia {"pause":false} se o alimentador estava pausado, para que o multiplexador realmente receba dados após o apply.

  6. Ajuste automático da taxa de bits — se captured_bitrate × (1 + headroom%) exceder o mpegts-output-bitrate do MPTS de destino, o utilitário eleva esse limite no PSS com um único POST (com arredondamento para cima até os 1000 kbps mais próximos). Desativado com --no-bitrate-adjust.

  7. Planejamento — compara o inventário com a árvore /config/stream atual no PSS e prepara requisições HTTP POST somente para os campos divergentes. O remap de PID de ES é gerado como pares identidade (mpegts-pid-old ≡ mpegts-pid-new), para que a saída multiplexada mantenha cada PID original inalterado — incluindo PCR, video, audio, teletext, SCTE-35, DSM-CC. No PSS 2.0.0.193 e posteriores, o plano habilita adicionalmente o modo de preservação dos PIDs originais na entrada do muxer de destino e define a ordem dos programas na PAT (veja O que é migrado).

  8. Aplicação — envia as requisições POST planejadas e, em seguida, alterna o pause/unpause do MPTS para que o PSS releia a configuração; com --dry-run o plano é apenas impresso.

  9. Verify (ativado por padrão, mesmo com o plano vazio) — captura o MPTS resultante por meio de uma das saídas UDP do PSS e o compara com o destino; discrepâncias críticas (TSID, ONID, service_id, name, type, LCN) → código de saída 5.

A reexecução de todo o pipeline é idempotente: a segunda execução informa no changes needed se o PSS já corresponder ao inventário, e o verify confirma isso com uma nova captura.

Opções da CLI

Seleção do modo

Opção

Descrição

Padrão

-f, --file <path>

Caminho para o JSON de migração (usado como importação padrão na ausência de -i e como destino de gravação com -s)

./migrate.json

-s, --save

Grava o inventário capturado no arquivo de migração (combina-se com uma entrada de fluxo; o apply é executado mesmo assim)

—

-o, --output <file>

Apenas captura: grava em arquivo, sem apply

—

-i, --input <file>

Apenas apply: carrega o arquivo, sem captura

—

Captura

Opção

Descrição

Padrão

-t, --time <sec>

Duração máxima da captura

30

-b, --bitrate <Mbps>

Indicação da taxa de bits do TS para o ritmo de envio no modo de arquivo

38.8

Apply / Verify

Opção

Descrição

Padrão

--target-mpts <id>

Ignora a solicitação de seleção do MPTS; aplica a este stream id no PSS

—

--non-interactive

Aceita automaticamente as sugestões do diálogo; encerra em caso de conflito

—

--dry-run

Imprime o plano de POSTs, sem enviar nada

—

--pss-base <url>

Substitui a autodetecção do PSS (por exemplo, http://host:8808)

auto

--no-verify

Ignora a captura pós-apply e o diff

verify ativado

--verify-time <s>

Janela de captura para a verificação

10

--no-bitrate-adjust

Não eleva mpegts-output-bitrate no MPTS de destino

elevação ativada

--bitrate-headroom <pct>

Margem de taxa de bits acima do valor medido durante o ajuste

15

Diversos

Opção

Descrição

-v, --verbose

Log detalhado (cada HTTP POST e ramificação do diálogo)

-h, --help

Exibe a ajuda e sai

Arquivo de migração (migrate.json)

JSON legível por humanos com format_version: 1. A localização padrão é ./migrate.json; ela é substituída por -f. Exemplo de estrutura:

{
  "format_version": 1,
  "tool": "mpts_migrate",
  "capture": {
    "source": "udp://239.1.1.1:1234",
    "captured_at_utc": "2026-04-30T08:15:00Z",
    "duration_s": 8.2,
    "packets": 109344
  },
  "transport_stream": {
    "transport_stream_id": 1234,
    "original_network_id": 8442,
    "network_name": "Operator",
    "delivery": { "type": "terrestrial", "frequency_khz": 522000 }
  },
  "services": [
    {
      "service_id": 1, "pmt_pid": 256, "pcr_pid": 256,
      "service_type": 1, "service_name": "Channel 1",
      "provider_name": "MyProvider", "logical_channel_number": 101,
      "program_order": 1,
      "free_ca_mode": false,
      "elementary_streams": [
        { "pid": 256, "stream_type": 27, "language": "rus" }
      ]
    }
  ]
}

O arquivo pode ser editado antes de um novo apply: renomear serviços, alterar o LCN, mudar service_type, ajustar network_name — mpts_migrate -i migrate.json enviará apenas os campos alterados.

Conexão com o PSS

  • Autodetecção: varredura de /proc/<pid>/comm em busca de pss, leitura do respectivo arquivo --config e obtenção de web-server.bind-port (43971, se a chave estiver ausente).

  • Manualmente: --pss-base http://host:port ignora completamente a autodetecção. Útil para um PSS remoto ou quando --dry-run deve montar o plano sem um PSS ativo.

  • A REST API de administração não exige autenticação em localhost.

Verificação

Se --no-verify não for indicado (padrão), depois de aplicar o plano o utilitário:

  1. Procura uma saída UDP em localhost no MPTS de destino ou adiciona temporariamente uma em 127.0.0.1:<auto> (com a marcação added by mpts_migrate for verification).

  2. Captura o MPTS ativo por essa saída durante --verify-time segundos (10 por padrão).

  3. Compara o inventário capturado com o destino:

    • Discrepância crítica (TSID, ONID, network name, service_id, name, type, LCN) → código de saída 5.

    • Discrepância leve (PMT PID, quantidade de ES, nome do provedor, ordem dos programas na PAT) → exibida como warning, código de saída 0.

  4. Se o MPTS de destino estiver sobrecarregado (taxa de bits da saída ≥ o mpegts-output-bitrate configurado), é impresso WARNING: target MPTS is overloaded — veja Bitrate adjust abaixo.

Dry-run

--dry-run imprime cada requisição HTTP que o utilitário enviaria (path, corpo JSON), mas não envia nenhuma. Útil para:

  • Revisar o plano com o operador antes de efetivá-lo.

  • Gerar conjuntos de alterações reproduzíveis em CI / gestão de mudanças.

  • Trabalhar com o PSS inacessível (combinar com --pss-base http://host:port).

O dry-run não executa a verificação.

Bitrate adjust

Por padrão, se captured_bitrate × (1 + headroom%) exceder o mpegts-output-bitrate do MPTS de destino, o utilitário eleva esse limite no PSS antes de aplicar as alterações de SI/PSI. Sem margem suficiente, um MPTS sobrecarregado perde os dados de baixa prioridade — os sintomas típicos são quedas de áudio nos serviços de rádio e erros intermitentes de CRC da EIT. Desativado com --no-bitrate-adjust; a margem é regulada com --bitrate-headroom <pct> (15 por padrão).

Códigos de saída

Código

Significado

0

Sucesso — o apply e (se ativada) a verificação foram concluídos sem erros. Também é retornado por um --dry-run bem-sucedido.

1

Erro de argumentos / de arquivo / de detecção

2

Nenhuma PAT encontrada na fonte — a entrada não é um MPEG-TS válido ou a janela de captura é curta demais; também é retornado quando o operador rejeitou a confirmação do mapeamento ou saiu do diálogo (apply interrompido)

3

Uma ou mais requisições HTTP POST do apply falharam

4

O apply foi concluído, mas o MPTS de destino não retornou ao estado Running

5

A verificação falhou — o fluxo capturado difere do destino em campos críticos

Limitações e armadilhas

  • O PSS deve conter previamente o MPTS de destino e os alimentadores: o utilitário não cria novos fluxos. O MPTS de destino e pelo menos tantos alimentadores SPTS quantos forem os serviços do inventário devem existir previamente; os serviços sem alimentador livre são ignorados no diálogo.

  • A fonte MPTS deve estar acessível durante a captura (modos 1, 2, save+apply): a URL passada como argumento posicional <input> deve fornecer um fluxo MPEG-TS; para UDP multicast, IGMP / firewall devem permiti-lo.

  • O remap de PID de ES é aplicado automaticamente: para cada serviço é gerado um remap identidade (mpegts-pid-old ≡ mpegts-pid-new) para cada PID de PCR/video/audio/teletext/data, para que a saída multiplexada preserve os PIDs originais byte-exact. O layout da PMT permanece estável de migração para migração — mesmo os receptores antigos (STB anteriores a 2015, Samsung anteriores à série H, LG anteriores ao WebOS 3.0) que armazenam os PIDs em cache dispensam uma nova busca.

  • O descritor de entrega deve corresponder ao meio de transmissão real para os receptores que se ressintonizam pela NIT (DVB-T/T2/C/S). Um bloco delivery incompatível pode levar o receptor a uma frequência incorreta.

  • A consistência dos LCN entre o MPTS principal e o de reserva é crítica para o failover — se forem diferentes, as posições dos canais na lista do receptor se deslocarão após a comutação.

  • O provider name no PSS é comum a todo o multiplex (um único sdt-provider-name por muxer-input do MPTS). O utilitário o aplica automaticamente se todos os serviços capturados tiverem o mesmo valor; se serviços distintos tiverem provider_name diferentes, é impresso um warning e o campo permanece intocado — a decisão cabe ao operador.

  • Não é uma ferramenta de configuração do PSS: mpts_migrate altera apenas os campos de identidade SI/PSI, o flag pause de cada alimentador, (opcionalmente) mpegts-output-bitrate e, no PSS 2.0.0.193 e posteriores, as chaves do modo de preservação de PID e da ordem dos programas. Ele não configura codificadores, entradas, criptografia, agendamentos e afins.

  • No PSS anterior à 2.0.0.193, o modo de preservação dos PIDs originais no muxer e a ordem dos programas na PAT não são suportados: o utilitário imprime um aviso, os PIDs são fixados somente por pares identidade e a ordem dos programas após a migração pode diferir da original.

Diagnóstico

Sintoma

Causa provável / solução

Error: no PAT seen in stream

a fonte não é MPEG-TS, IGMP/firewall bloqueia o multicast ou -t é curto demais

Error: cannot reach PSS

usar --pss-base http://host:port para contornar a autodetecção

O apply foi concluído, mas o MPTS permanece pausado

verificar o log do PSS; reexecutar com -v para ver o plano completo de POSTs

A verificação indica uma discrepância crítica

comparar o destino e o fluxo capturado em JSON; normalmente um alimentador foi mapeado ao serviço errado no diálogo

WARNING: target MPTS is overloaded

elevar mpegts-output-bitrate no PSS ou usar --bitrate-headroom <higher %>; sem margem, o áudio dos serviços de rádio e as tabelas PSI ficam corrompidos