MPTS Migrate Perfect Streamer Toolkit v1.0 — MPTS identity migration

Part of the Perfect Streamer Toolkit — https://pstreamer.tv

Capture the DVB SI/PSI identity of a live MPEG-TS multiprogram stream (MPTS) and reproduce it on a Perfect Streamer (PSS) instance running on the same host. The result: consumer receivers (STB / TV) keep working without a channel re-scan after a migration or failover.

Pre-conditions

Before running the utility verify that:

  • PSS is running on the same host (or a host reachable via --pss-base). The utility queries /proc for pss and reads pss.json for the admin port (default 43971).

  • Source MPTS is reachable if you intend to capture (modes 1, 2, save+apply): the URL passed as the positional <input> argument must deliver an MPEG-TS stream. For UDP multicast — IGMP / firewall must allow it; for files — the path must exist.

  • Target MPTS is configured in PSS: the utility never creates new streams. An MPTS object plus at least as many SPTS feeders as the inventory has services must already exist. Services without an available feeder are surfaced in the dialog and can be skipped.

  • HTTP admin API is open on localhost for reading /data/stream (used by verify) and writing /config/stream (apply).

What gets migrated

Every receiver-visible identifier on the transport-stream and per-service level:

  • Transport stream: TSID, ONID, network ID, network name, provider name (auto-applied as mux-wide sdt-provider-name when all source services share one), delivery descriptor (terrestrial / cable / satellite parameters), PAT/SDT/NIT versions

  • Per service: service_id, pmt_pid, pcr_pid, service_type, service name, logical channel number (LCN), free-CA mode, EIT-present/EIT-schedule flags

  • Elementary streams: PIDs (identity remap applied — see Limitations), stream types, language tags

  • Conditional access: program-level and ES-level CA descriptors

Service / provider names in non-ASCII DVB character sets (e.g. ISO-8859-5 Cyrillic) are decoded into UTF-8 automatically.

Per-service ES PID remap is built as identity pairs (mpegts-pid-old ≡ mpegts-pid-new) for every PCR / video / audio / teletext / data PID, so the resulting muxed output keeps source PIDs byte-exact. Legacy receivers that cache PMT after first scan continue to work without re-tune.

Use cases

  • Failover: switch decoders from primary to backup MPTS, keeping every receiver locked on the same channel numbers

  • Hardware migration: move a working mux from one PSS host to another without operator instructions to viewers

  • Pre-/post-update snapshot: capture the mux before a PSS upgrade, re-apply after to guarantee bit-identical SI/PSI

  • Manual edit & re-apply: capture, edit migrate.json (rename services, change LCN, fix service_type), re-apply

  • Dry-run review: print every HTTP POST that would be sent, without touching PSS

Quick start

# 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, no apply
mpts_migrate -o backup.json udp://239.1.1.1:1234

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

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

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

Workflow

  1. Capture — utility opens the stream, parses PAT / PMT / SDT / NIT / EIT for up to -t seconds (default 30) and builds an inventory; total stream bitrate is measured.

  2. (Optional) Save — with -s or -o writes the inventory to JSON for later reuse.

  3. Discover PSS — locates the running PSS instance via /proc scan, reads pss.json to find its admin port (default 43971); --pss-base http://host:port overrides discovery.

  4. Confirm mapping — interactive dialog asks how to map each captured service to an existing SPTS feeder; --non-interactive accepts suggestions and aborts on conflict; --target-mpts <id> skips the MPTS-choice prompt.

  5. Auto-unpause feeders — for each mapped SPTS / muxer-output the utility issues {"pause":false} if it was paused, so the muxer actually receives data after apply.

  6. Auto-adjust bitrate — if captured_bitrate × (1 + headroom%) exceeds the target MPTS mpegts-output-bitrate, the utility raises that limit on PSS in a single POST (rounded up to the nearest 1000 kbps). Disable with --no-bitrate-adjust.

  7. Plan — diffs the inventory against PSS’s current /config/stream tree, prepares HTTP POSTs only for fields that differ. ES PID remap is generated as identity pairs (mpegts-pid-old ≡ mpegts-pid-new) so the muxed output keeps every source PID exactly — including PCR, video, audio, teletext, SCTE-35, DSM-CC.

  8. Apply — sends the planned POSTs, then triggers a pause/unpause of the MPTS so PSS reloads config; with --dry-run only prints the plan.

  9. Verify (default on, even when the plan is empty) — captures the resulting MPTS through one of the PSS UDP outputs and diffs against the goal; critical mismatches (TSID, ONID, service_id, name, type, LCN) → exit 5.

Re-running the whole pipeline is idempotent: a second run reports no changes needed if PSS already matches the inventory, and verify still confirms via a fresh capture.

CLI options

Mode selection

Option

Description

Default

-f, --file <path>

Migration JSON path (used as default import without -i, and as save target with -s)

./migrate.json

-s, --save

Save captured inventory to migration file (combines with stream input; still applies)

—

-o, --output <file>

Capture-only: write to file, do not apply

—

-i, --input <file>

Apply-only: load file, do not capture

—

Capture

Option

Description

Default

-t, --time <sec>

Maximum capture duration

30

-b, --bitrate <Mbps>

TS bitrate hint for file-mode pacing

38.8

Apply / Verify

Option

Description

Default

--target-mpts <id>

Skip MPTS choice prompt; apply to this PSS stream id

—

--non-interactive

Auto-accept dialog suggestions; abort on conflict

—

--dry-run

Print planned POSTs, send nothing

—

--pss-base <url>

Override PSS discovery (e.g. http://host:43971)

auto-discovered

--no-verify

Skip post-apply self-capture and diff

verify on

--verify-time <s>

Verification capture window

10

--no-bitrate-adjust

Do not auto-raise mpegts-output-bitrate on the target MPTS

adjust on

--bitrate-headroom <pct>

Safety headroom above measured bitrate when adjusting

15

Misc

Option

Description

-v, --verbose

Verbose log (every HTTP POST and dialog branch)

-h, --help

Show usage and exit

Migration file (migrate.json)

Human-readable JSON with format_version: 1. Default location ./migrate.json; override with -f. Example shape:

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

Edit it before re-apply: rename services, change LCN, flip service_type, adjust network_name — mpts_migrate -i migrate.json will push only the changed fields.

PSS connection

  • Auto-discovery: scans /proc/<pid>/comm for pss, reads its --config file, picks web-server.bind-port (default 43971).

  • Manual: --pss-base http://host:port skips discovery entirely. Useful for remote PSS or when --dry-run should produce a plan without a live PSS.

  • The admin REST API requires no authentication on localhost.

Verification

When --no-verify is not specified (default), after applying the plan the utility:

  1. Looks for a localhost UDP output of the target MPTS, or temporarily adds one on 127.0.0.1:<auto> (annotated added by mpts_migrate for verification).

  2. Captures the live MPTS through that output for --verify-time seconds (default 10).

  3. Diffs the captured inventory against the goal: - Critical mismatch (TSID, ONID, service_id, name, type, LCN) → exit code 5. - Soft mismatch (PMT PID, PCR PID, ES PID) → printed as warning, exit code 0.

  4. If the target MPTS is overloaded (output bitrate ≥ configured mpegts-output-bitrate), prints WARNING: target MPTS is overloaded — see Bitrate adjust below.

Dry-run

--dry-run prints every HTTP request the utility would send (path, JSON body) but issues none. Useful for:

  • Reviewing the plan with the operator before commit.

  • Generating reproducible change-sets in a CI / change-management workflow.

  • Working when PSS is offline (combine with --pss-base http://host:port).

Dry-run does not run verification.

Bitrate adjust

By default, if captured_bitrate × (1 + headroom%) exceeds the target MPTS mpegts-output-bitrate, the utility raises that limit on PSS before applying SI/PSI changes. Without enough headroom an overloaded MPTS drops low-priority data — typical symptoms: missing audio on radio services, intermittent EIT CRC errors. Disable with --no-bitrate-adjust, tune the safety margin with --bitrate-headroom <pct> (default 15).

Exit codes

Code

Meaning

0

Success — apply and (if enabled) verification both clean. Also returned by successful --dry-run.

1

Argument / file / discovery error

2

No PAT seen in source — input is not a valid MPEG-TS, or capture window too short

3

One or more apply HTTP POSTs failed

4

Apply succeeded but the target MPTS did not return to Running state

5

Verification failed — captured stream differs from the goal in critical fields

Limitations & gotchas

  • PSS must already host the target MPTS and feeders: the utility does not create new streams. The target MPTS plus at least as many SPTS feeders as the inventory has services must already exist; services that have no available feeder are skipped in the dialog.

  • Source MPTS must be reachable when capturing (modes 1, 2, save+apply): the URL passed as the positional <input> argument has to deliver an MPEG-TS stream; for UDP multicast IGMP / firewall must allow it.

  • ES PID remap is applied automatically: per-service identity remap (mpegts-pid-old ≡ mpegts-pid-new) is generated for every PCR/video/audio/teletext/data PID so the muxed output keeps source PIDs byte-exact. PMT layout stays stable across migration — even legacy receivers (pre-2015 STBs, Samsung pre-H, LG pre-WebOS 3.0) that cache PIDs do not need re-scan.

  • Delivery descriptors must match the real carrier for receivers that re-tune via NIT (DVB-T/T2/C/S). A mismatched delivery block can send the receiver to a wrong frequency.

  • LCN consistency between primary and backup MPTS is essential for failover — if they differ, channel positions move in the receiver’s list after the switch.

  • Provider name is mux-wide on PSS (single sdt-provider-name on the MPTS muxer-input). The utility applies it automatically when all captured services share one provider; if different services have different provider_name values, a warning is printed and the field is left untouched — the operator must decide which one wins.

  • Not a configuration tool for PSS itself: mpts_migrate only touches SI/PSI identity fields, the per-feeder pause flag, and (optionally) mpegts-output-bitrate. It does not configure encoders, inputs, encryption, scheduling, etc.

Troubleshooting

Symptom

Likely cause / fix

Error: no PAT seen in stream

source is not MPEG-TS, IGMP/firewall blocks the multicast, or -t is too short

Error: cannot reach PSS

use --pss-base http://host:port to bypass auto-discovery

Apply succeeds but MPTS stays paused

check PSS log; re-run with -v to see the full POST plan

Verification reports critical diff

compare goal vs capture in JSON; usually a feeder is mistakenly mapped to the wrong service in the dialog

WARNING: target MPTS is overloaded

raise mpegts-output-bitrate on PSS or --bitrate-headroom <higher %>; without headroom radio audio and PSI tables corrupt