MPTS Migrate Perfect Streamer Toolkit v1.0 — MPTS-Identitätsmigration

Teil des Perfect Streamer Toolkit — https://pstreamer.tv

Erfasst die DVB-SI/PSI-Identität eines laufenden Multi-Programm-MPEG-TS-Streams (MPTS) und reproduziert sie auf einer Perfect-Streamer-Instanz (PSS) auf demselben Host. Ergebnis: Endkunden-Empfänger (STB / TV) arbeiten ohne erneuten Sender-Suchlauf nach der Migration oder dem Failover weiter.

Voraussetzungen

Stellen Sie vor dem Start des Tools sicher, dass:

  • PSS läuft auf demselben Host (oder auf einem über --pss-base erreichbaren Host). Das Tool sucht pss in /proc und liest pss.json, um den Admin-Port (Standard 43971) zu ermitteln.

  • MPTS-Quelle erreichbar, falls eine Erfassung geplant ist (Modi 1, 2, save+apply): die als Positionsargument <input> übergebene URL muss einen MPEG-TS-Stream liefern. Für UDP multicast — IGMP / Firewall müssen den Empfang erlauben; bei Dateien — der Pfad muss existieren.

  • Ziel-MPTS bereits im PSS konfiguriert: das Tool legt keine neuen Streams an. Ein MPTS-Objekt sowie mindestens so viele SPTS-Feeder, wie das Inventar Services hat, müssen vorab existieren. Services ohne verfügbaren Feeder erscheinen im Dialog und können übersprungen werden.

  • Die HTTP-Admin-API ist auf localhost offen — fürs Lesen von /data/stream (verify) und Schreiben in /config/stream (apply).

Was wird migriert

Alle vom Empfänger sichtbaren Identifikatoren auf Transportstream- und Service-Ebene:

  • Transport-Stream: TSID, ONID, network ID, network name, provider name (wird mux-weit als sdt-provider-name angewendet, wenn alle Quell-Services denselben Wert haben), Delivery-Descriptor (Parameter terrestrischer/Kabel-/Satelliten-Übertragung), PAT/SDT/NIT-Versionen

  • Pro Service: service_id, pmt_pid, pcr_pid, service_type, Servicename, logische Kanalnummer (LCN), free-CA-Flag, EIT-present-/EIT-schedule-Flags

  • Elementarstreams: PIDs (Identity-Remap angewandt — siehe Einschränkungen), Streamtypen, Sprachtags

  • Conditional Access: CA-Deskriptoren auf Programm- und ES-Ebene

Service- und Provider-Namen in nicht-ASCII-DVB-Kodierungen (z. B. ISO-8859-5 für Kyrillisch) werden automatisch nach UTF-8 dekodiert.

Per-Service-ES-PID-Remap wird als Identity-Paare (mpegts-pid-old ≡ mpegts-pid-new) für jedes PCR/video/audio/teletext/data PID gebildet, sodass die resultierende multiplexte Ausgabe die Quell-PIDs byte-exact beibehält. Legacy-Empfänger, die das PMT nach dem ersten Suchlauf cachen, arbeiten ohne Neukonfiguration weiter.

Anwendungsfälle

  • Failover: Umschalten der Decoder vom primären auf den Backup-MPTS bei gleichbleibenden Kanälen am Empfänger

  • Hardware-Migration: Verlagerung eines laufenden Multiplexes von einem PSS-Host auf einen anderen ohne Instruktionen für Zuschauer

  • Snapshot vor/nach Update: Multiplex vor dem PSS-Upgrade erfassen und danach erneut anwenden, um bit-identische SI/PSI zu garantieren

  • Manuelle Bearbeitung und erneutes Anwenden: Erfassen, migrate.json bearbeiten (Services umbenennen, LCN ändern, service_type korrigieren) und erneut anwenden

  • Dry-Run-Review: jeder HTTP-POST, der gesendet würde, wird ausgegeben, ohne PSS zu beeinflussen

Schnellstart

# Захват из 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

Arbeitsablauf

  1. Erfassung — das Tool öffnet den Stream, parst PAT / PMT / SDT / NIT / EIT für -t Sekunden (Standard 30) und erstellt das Inventar; die Gesamtbitrate wird gemessen.

  2. (Optional) Speichern — mit -s oder -o wird das Inventar zur späteren Wiederverwendung als JSON gespeichert.

  3. PSS-Suche — findet ein laufendes PSS per /proc-Scan und liest pss.json zur Ermittlung des Admin-Ports (Standard 43971); --pss-base http://host:port umgeht die Auto-Discovery.

  4. Mapping-Bestätigung — ein interaktiver Dialog fragt, wie jeder erfasste Service einem vorhandenen SPTS-Feeder zuzuordnen ist; --non-interactive akzeptiert die Vorschläge und bricht bei Konflikt ab; --target-mpts <id> überspringt die MPTS-Auswahl.

  5. Auto-Unpause der Feeder — für jeden zugeordneten SPTS/muxer-output sendet das Tool {"pause":false}, falls der Feeder pausiert war, damit der Multiplexer nach dem Apply tatsächlich Daten empfängt.

  6. Auto-Bitrate-Anpassung — wenn captured_bitrate × (1 + headroom%) mpegts-output-bitrate des Ziel-MPTS übersteigt, hebt das Tool diese Grenze auf dem PSS per einzelnem POST an (aufgerundet auf das nächste Vielfache von 1000 kbps). Deaktivierbar über --no-bitrate-adjust.

  7. Planung — vergleicht das Inventar mit dem aktuellen Baum /config/stream auf dem PSS und bereitet HTTP-POSTs nur für die abweichenden Felder vor. Das ES-PID-Remap wird als Identity-Paare (mpegts-pid-old ≡ mpegts-pid-new) erzeugt, sodass die multiplexte Ausgabe jedes Quell-PID unverändert beibehält — einschließlich PCR, video, audio, teletext, SCTE-35, DSM-CC.

  8. Apply — sendet die geplanten POSTs und schaltet anschließend MPTS pause/unpause um, damit PSS die Konfiguration neu liest; bei --dry-run wird der Plan nur gedruckt.

  9. Verify (standardmäßig aktiv, auch wenn der Plan leer ist) — erfasst das resultierende MPTS über einen der UDP-Outputs des PSS und vergleicht mit dem Ziel; kritische Abweichungen (TSID, ONID, service_id, name, type, LCN) → exit 5.

Eine erneute Ausführung der gesamten Pipeline ist idempotent: Beim zweiten Lauf wird no changes needed gemeldet, wenn PSS dem Inventar bereits entspricht; verify bestätigt das durch erneute Erfassung.

CLI-Optionen

Modusauswahl

Option

Beschreibung

Standard

-f, --file <path>

Pfad zur Migrations-JSON (Standardimport ohne -i und Speicherziel mit -s)

./migrate.json

-s, --save

Erfasstes Inventar in eine Migrations-Datei speichern (kombinierbar mit Stream-Input; Apply wird trotzdem ausgeführt)

—

-o, --output <file>

Nur Erfassung: in Datei schreiben, ohne Apply

—

-i, --input <file>

Nur Apply: Datei laden, ohne Erfassung

—

Erfassung

Option

Beschreibung

Standard

-t, --time <sec>

Maximale Erfassungsdauer

30

-b, --bitrate <Mbps>

TS-Bitrate-Hinweis für das Pacing im Dateimodus

38.8

Apply / Verify

Option

Beschreibung

Standard

--target-mpts <id>

MPTS-Auswahl überspringen; auf diese Stream-ID am PSS anwenden

—

--non-interactive

Dialogvorschläge automatisch akzeptieren; bei Konflikt abbrechen

—

--dry-run

POST-Plan ausgeben, nichts senden

—

--pss-base <url>

PSS-Auto-Discovery überschreiben (z. B. http://host:43971)

automatisch

--no-verify

Post-Apply-Erfassung und Diff überspringen

verify aktiviert

--verify-time <s>

Erfassungsfenster für die Verifikation

10

--no-bitrate-adjust

mpegts-output-bitrate am Ziel-MPTS nicht anheben

Anhebung aktiviert

--bitrate-headroom <pct>

Bitrate-Sicherheitsreserve über dem gemessenen Wert beim Anpassen

15

Sonstiges

Option

Beschreibung

-v, --verbose

Detailliertes Log (jeder HTTP-POST und Dialogzweig)

-h, --help

Hilfe anzeigen und beenden

Migrations-Datei (migrate.json)

Menschenlesbares JSON mit format_version: 1. Standardpfad ./migrate.json; mit -f überschreibbar. Beispielstruktur:

{
  "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" }
      ]
    }
  ]
}

Die Datei lässt sich vor einem erneuten Apply bearbeiten: Services umbenennen, LCN ändern, service_type umschalten, network_name anpassen — mpts_migrate -i migrate.json sendet nur die geänderten Felder.

Verbindung zu PSS

  • Auto-Discovery: /proc/<pid>/comm nach pss durchsuchen, dessen --config-Datei lesen und web-server.bind-port (Standard 43971) übernehmen.

  • Manuell: --pss-base http://host:port umgeht die Auto-Discovery vollständig. Nützlich für ein entferntes PSS oder wenn --dry-run ohne lebendes PSS einen Plan erstellen soll.

  • Die Admin-REST-API erfordert keine Authentifizierung auf localhost.

Verifikation

Wenn --no-verify nicht gesetzt ist (Standard), führt die Utility nach Anwendung des Plans Folgendes aus:

  1. Sucht einen UDP-Localhost-Ausgang am Ziel-MPTS oder fügt vorübergehend einen unter 127.0.0.1:<auto> mit Marker added by mpts_migrate for verification hinzu.

  2. Erfasst den Live-MPTS über diesen Ausgang für --verify-time Sekunden (Standard 10).

  3. Vergleicht das erfasste Inventar mit dem Ziel: - Kritische Abweichung (TSID, ONID, service_id, name, type, LCN) → Exit-Code 5. - Weiche Abweichung (PMT PID, PCR PID, ES PID) → wird als Warning ausgegeben, Exit-Code 0.

  4. Wenn der Ziel-MPTS überlastet ist (Output-Bitrate ≥ konfigurierter mpegts-output-bitrate), wird WARNING: target MPTS is overloaded ausgegeben — siehe Bitrate adjust unten.

Dry-run

--dry-run gibt jede HTTP-Anfrage aus, die das Tool senden würde (Pfad, JSON-Body), schickt aber keine. Nützlich für:

  • Plan-Review mit dem Bediener vor dem Commit.

  • Erzeugung reproduzierbarer Änderungsmengen in CI / Change-Management.

  • Arbeit bei nicht erreichbarem PSS (mit --pss-base http://host:port kombinieren).

Dry-Run führt keine Verifikation aus.

Bitrate adjust

Wenn captured_bitrate × (1 + headroom%) mpegts-output-bitrate des Ziel-MPTS übersteigt, hebt das Tool standardmäßig diese Grenze auf dem PSS an, bevor SI/PSI-Änderungen angewendet werden. Ohne ausreichende Reserve verliert ein überlasteter MPTS Daten niedriger Priorität — typische Symptome: Audio-Verlust bei Radio-Services, gelegentliche EIT-CRC-Fehler. Deaktivierbar über --no-bitrate-adjust; die Reserve wird über --bitrate-headroom <pct> gesteuert (Standard 15).

Exit-Codes

Code

Wert

0

Erfolg — Apply und (falls aktiviert) Verifikation liefen sauber durch. Auch ein erfolgreicher --dry-run liefert diesen Code.

1

Argument-, Datei- oder Erkennungsfehler

2

In der Quelle wurde keine PAT gefunden — Eingabe ist kein gültiger MPEG-TS oder das Erfassungsfenster ist zu kurz

3

Ein oder mehrere HTTP-POSTs des Apply schlugen fehl

4

Apply lief, aber der Ziel-MPTS ist nicht in den Zustand Running zurückgekehrt

5

Verifikation fehlgeschlagen — der erfasste Stream weicht in kritischen Feldern vom Ziel ab

Einschränkungen und Stolperfallen

  • Das PSS muss das Ziel-MPTS und die Feeder bereits halten: das Tool legt keine neuen Streams an. Das Ziel-MPTS sowie mindestens so viele SPTS-Feeder, wie das Inventar Services hat, müssen vorab existieren; Services ohne verfügbaren Feeder werden im Dialog übersprungen.

  • Die MPTS-Quelle muss bei der Erfassung erreichbar sein (Modi 1, 2, save+apply): die als Positionsargument <input> übergebene URL muss einen MPEG-TS-Stream liefern; bei UDP multicast müssen IGMP / Firewall den Empfang erlauben.

  • Das ES-PID-Remap wird automatisch angewendet: das Per-Service-Identity-Remap (mpegts-pid-old ≡ mpegts-pid-new) wird für jedes PCR/video/audio/teletext/data PID erzeugt, damit die multiplexte Ausgabe die Quell-PIDs byte-exact beibehält. Das PMT-Layout bleibt über Migrationen hinweg stabil — selbst Legacy-Empfänger (STBs vor 2015, Samsung vor H-Serie, LG vor WebOS 3.0), die PIDs cachen, brauchen keinen erneuten Suchlauf.

  • Der Delivery-Descriptor muss zur tatsächlichen Trägerstrecke passen für Empfänger, die sich über NIT (DVB-T/T2/C/S) neu abstimmen. Ein nicht passender delivery-Block kann den Empfänger auf eine falsche Frequenz leiten.

  • LCN-Konsistenz zwischen Haupt- und Backup-MPTS ist beim Failover entscheidend — bei Abweichungen verschieben sich Kanalpositionen in der Empfängerliste nach dem Umschalten.

  • Provider name am PSS — mux-weit gemeinsam (ein einziger sdt-provider-name am muxer-input MPTS). Das Tool wendet ihn automatisch an, wenn alle erfassten Services denselben Wert haben; haben verschiedene Services unterschiedliche provider_name-Werte, wird ein Warning ausgegeben und das Feld bleibt unverändert — die Entscheidung trifft der Operator.

  • Kein Konfigurationstool für PSS selbst: mpts_migrate berührt nur die SI/PSI-Identitätsfelder, das pause-Flag pro Feeder und (optional) mpegts-output-bitrate. Encoder, Inputs, Verschlüsselung, Scheduling etc. konfiguriert es nicht.

Diagnose

Symptom

Wahrscheinliche Ursache / Lösung

Error: no PAT seen in stream

Quelle ist kein MPEG-TS, IGMP/Firewall blockiert Multicast oder -t ist zu kurz

Error: cannot reach PSS

--pss-base http://host:port verwenden, um die Auto-Discovery zu umgehen

Apply lief, aber das MPTS bleibt pausiert

PSS-Log prüfen; mit -v neu starten, um den vollständigen POST-Plan zu sehen

Verifikation meldet kritische Abweichung

goal mit capture im JSON vergleichen; meist ist ein Feeder im Dialog versehentlich dem falschen Service zugeordnet

WARNING: target MPTS is overloaded

mpegts-output-bitrate am PSS erhöhen oder --bitrate-headroom <higher %> setzen; ohne Reserve werden Radio-Audio und PSI-Tabellen beschädigt