MPTS Migrate Perfect Streamer Toolkit v1.0 — migração de identidade MPTS

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

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

Pré-requisitos

Antes de executar a utilidade, certifique-se de que:

  • PSS está em execução no mesmo host (ou em host acessível via --pss-base). A utilidade procura pss em /proc e lê pss.json para obter a porta de admin (padrão 43971).

  • Fonte MPTS acessível, se planejada a captura (modos 1, 2, save+apply): a URL passada como argumento posicional <input> deve entregar um fluxo MPEG-TS. Para UDP multicast — IGMP / firewall devem permitir a recepção; para arquivos — o caminho deve existir.

  • MPTS de destino já configurado no PSS: a utilidade não cria novos fluxos. Um objeto MPTS e ao menos tantos feeders SPTS quantos serviços houver no inventário devem existir previamente. Serviços sem feeder disponível são exibidos no diálogo e podem ser pulados.

  • A API HTTP admin está aberta no localhost para ler /data/stream (usado pelo verify) e gravar em /config/stream (apply).

O que é migrado

Todos os identificadores visíveis para o receptor no nível do fluxo de transporte e dos serviços:

  • Transport stream: TSID, ONID, network ID, network name, provider name (aplicado como sdt-provider-name válido para todo o mux quando todos os serviços de origem compartilham o mesmo valor), descritor de delivery (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, LCN, free-CA, EIT-present / EIT-schedule

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

  • Acesso condicional: descritores CA no nível do programa e do ES

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

O ES PID remap por serviço é construído como pares de identidade (mpegts-pid-old ≡ mpegts-pid-new) para cada PCR / video / audio / teletext / data PID, de modo que a saída multiplexada resultante mantém os PIDs originais byte-exact. Receptores legados que cacheiam o PMT após a primeira varredura continuam funcionando sem reconfiguração.

Casos de uso

  • Failover: troca dos decoders do MPTS principal para o de backup mantendo os canais no receptor

  • Migração de hardware: mudança de um multiplex ativo de um host PSS para outro sem instruções para os espectadores

  • Snapshot pré/pós atualização: capturar o multiplex antes do upgrade do PSS e reaplicá-lo após, garantindo SI/PSI bit-idênticos

  • Edição manual e reaplicação: capturar, editar migrate.json (renomear serviços, mudar LCN, ajustar service_type) e aplicar de novo

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

Início rápido

# Захват из live-потока и применение к локальному PSS за один запуск
mpts_migrate udp://239.1.1.1:1234

# Захват, сохранение в migrate.json и применение
mpts_migrate -s udp://239.1.1.1:1234

# Только захват — запись в файл, без применения
mpts_migrate -o backup.json udp://239.1.1.1:1234

# Применение ранее сохранённого JSON
mpts_migrate -i backup.json

# Без аргументов — загрузка ./migrate.json и применение
mpts_migrate

# Просмотр того, что сделает apply, без изменений
mpts_migrate -i backup.json --dry-run

Fluxo de trabalho

  1. Captura — a utilidade abre o fluxo, faz o parse de PAT / PMT / SDT / NIT / EIT por -t segundos (padrão 30) e monta o inventário; o bitrate total é medido.

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

  3. Descoberta do PSS — encontra um PSS em execução varrendo /proc e lê pss.json para obter a porta de admin (padrão 43971); --pss-base http://host:port ignora o autodescobrimento.

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

  5. Auto-despausar feeders — para cada SPTS/muxer-output mapeado, o utilitário envia {"pause":false} se estava em pausa, para que o multiplexador realmente receba dados após o apply.

  6. Ajuste automático do bitrate — se captured_bitrate × (1 + headroom%) exceder mpegts-output-bitrate do MPTS de destino, a utilidade aumenta esse limite no PSS por um único POST (arredondado para cima até o múltiplo mais próximo de 1000 kbps). Desativável por --no-bitrate-adjust.

  7. Planejamento — compara o inventário com a árvore atual de /config/stream no PSS e prepara HTTP POSTs apenas para os campos que diferem. O ES PID remap é gerado como pares de identidade (mpegts-pid-old ≡ mpegts-pid-new) para que a saída multiplexada mantenha cada PID de origem inalterado — incluindo PCR, video, audio, teletext, SCTE-35, DSM-CC.

  8. Apply — envia os POSTs planejados e em seguida alterna 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 se o plano estiver vazio) — captura o MPTS resultante por uma das saídas UDP do PSS e compara com o objetivo; divergências críticas (TSID, ONID, service_id, name, type, LCN) → exit 5.

Reexecutar todo o pipeline é idempotente: a segunda execução reporta no changes needed se o PSS já corresponde ao inventário, e o verify confirma com nova captura.

Opções CLI

Seleção de modo

Opção

Descrição

Padrão

-f, --file <path>

Caminho do JSON de migração (importação padrão sem -i e alvo de gravação com -s)

./migrate.json

-s, --save

Salvar o inventário capturado no arquivo de migração (combina com entrada por fluxo; o apply é executado mesmo assim)

—

-o, --output <file>

Apenas captura: escrever em arquivo, sem apply

—

-i, --input <file>

Apenas apply: carregar arquivo, sem captura

—

Captura

Opção

Descrição

Padrão

-t, --time <sec>

Duração máxima de captura

30

-b, --bitrate <Mbps>

Dica de bitrate TS para o pacing no modo de arquivo

38.8

Apply / Verify

Opção

Descrição

Padrão

--target-mpts <id>

Pular a seleção do MPTS; aplicar a este stream id no PSS

—

--non-interactive

Aceitar automaticamente as sugestões do diálogo; abortar em caso de conflito

—

--dry-run

Imprimir o plano de POSTs, sem enviar nada

—

--pss-base <url>

Sobrescrever o autodescobrimento do PSS (ex. http://host:43971)

auto

--no-verify

Pular a captura pós-apply e o diff

verify habilitado

--verify-time <s>

Janela de captura para verificação

10

--no-bitrate-adjust

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

ajuste habilitado

--bitrate-headroom <pct>

Margem de bitrate acima do valor medido ao ajustar

15

Outros

Opção

Descrição

-v, --verbose

Log detalhado (cada HTTP POST e ramo do diálogo)

-h, --help

Mostrar ajuda e sair

Arquivo de migração (migrate.json)

JSON legível por humanos com format_version: 1. Localização padrão ./migrate.json; substituída via -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,
      "free_ca_mode": false,
      "elementary_streams": [
        { "pid": 256, "stream_type": 27, "language": "rus" }
      ]
    }
  ]
}

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

Conexão ao PSS

  • Autodescobrimento: varrer /proc/<pid>/comm por pss, ler seu arquivo --config e usar web-server.bind-port (padrão 43971).

  • Manual: --pss-base http://host:port ignora totalmente o autodescobrimento. Útil para PSS remoto ou quando --dry-run precisa gerar um plano sem PSS ativo.

  • A API REST de admin não requer autenticação em localhost.

Verificação

Se --no-verify não for indicado (padrão), após aplicar o plano a utilidade:

  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 added by mpts_migrate for verification.

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

  3. Compara o inventário capturado com o objetivo: - Divergência crítica (TSID, ONID, service_id, name, type, LCN) → código de saída 5. - Divergência branda (PMT PID, PCR PID, ES PID) → impressa como warning, código de saída 0.

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

Dry-run

--dry-run imprime cada requisição HTTP que a utilidade enviaria (path, corpo JSON), sem enviar nenhuma. Útil para:

  • Revisão do plano com o operador antes do commit.

  • Geração de conjuntos de mudanças reproduzíveis em CI / change-management.

  • Trabalho com PSS indisponí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 mpegts-output-bitrate do MPTS de destino, a utilidade aumenta esse limite no PSS antes de aplicar as alterações de SI/PSI. Sem reserva suficiente, um MPTS sobrecarregado descarta dados de baixa prioridade — sintomas típicos: perda de áudio em serviços de rádio, erros intermitentes de CRC do EIT. Desativável por --no-bitrate-adjust; a reserva é regulada por --bitrate-headroom <pct> (padrão 15).

Códigos de saída

Código

Valor

0

Sucesso — apply e (se habilitada) verificação correram bem. Também retornado por um --dry-run bem-sucedido.

1

Erro de argumentos / arquivo / detecção

2

Nenhuma PAT encontrada na fonte — a entrada não é um MPEG-TS válido ou a janela de captura é muito curta

3

Um ou mais HTTP POSTs do apply falharam

4

Apply foi bem-sucedido, mas o MPTS de destino não voltou ao estado Running

5

Verificação falhou — o fluxo capturado difere da meta em campos críticos

Limitações e armadilhas

  • O PSS deve já hospedar o MPTS de destino e os feeders: a utilidade não cria novos fluxos. O MPTS de destino e ao menos tantos feeders SPTS quantos serviços houver no inventário devem existir previamente; serviços sem feeder disponível são pulados 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 entregar um fluxo MPEG-TS; para UDP multicast, IGMP / firewall devem permitir a recepção.

  • O ES PID remap é aplicado automaticamente: o remap de identidade por serviço (mpegts-pid-old ≡ mpegts-pid-new) é gerado para cada PCR/video/audio/teletext/data PID para que a saída multiplexada preserve os PIDs originais byte-exact. O layout PMT permanece estável entre migrações — mesmo receptores legados (STBs anteriores a 2015, Samsung anteriores à série H, LG anteriores ao WebOS 3.0) que cacheiam PIDs não exigem nova varredura.

  • O descritor de delivery deve corresponder à portadora real para receptores que se reconfiguram via NIT (DVB-T/T2/C/S). Um bloco delivery incompatível pode levar o receptor a uma frequência incorreta.

  • Consistência de LCN entre o MPTS principal e o de backup é crítica para failover — se diferirem, as posições de canais no receptor mudarão após a comutação.

  • Provider name no PSS é comum a todo o multiplex (um único sdt-provider-name no muxer-input MPTS). A utilidade o aplica automaticamente quando todos os serviços capturados compartilham o mesmo valor; se serviços diferentes tiverem valores provider_name distintos, é impresso um warning e o campo permanece intocado — a decisão fica a cargo do operador.

  • Não é uma ferramenta de configuração do PSS: mpts_migrate toca apenas nos campos de identidade SI/PSI, na flag pause em cada feeder e (opcionalmente) em mpegts-output-bitrate. Encoders, inputs, criptografia, agendamento etc. ele não configura.

Diagnóstico

Sintoma

Causa provável / solução

Error: no PAT seen in stream

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

Error: cannot reach PSS

usar --pss-base http://host:port para ignorar o autodescobrimento

Apply foi bem-sucedido, mas o MPTS permanece em pausa

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

A verificação mostra divergência crítica

comparar goal vs capture no JSON; normalmente um feeder está mapeado por engano para o serviço errado no diálogo

WARNING: target MPTS is overloaded

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