MPEGTS Reader¶

Overview¶

MPEGTS Reader is the most important module of Mcaster that allows receiving MPEG transport streams in both SPTS (Single Program Transport Stream) and MPTS (Multiple Program Transport Stream) modes. The module provides complete processing of transport streams with automatic extraction of metadata and content.

Operating Principles¶

Complete Stream Processing¶

When receiving, the stream is completely parsed down to frames, the entire transport container is unpacked. This is a fundamental difference from remultiplexers that leave MPEGTS and PES packaging with all their problems.

Automatic Metadata Extraction¶

The module automatically extracts and processes:

SDT (Service Description Table) — information about channels and providers
EPG (Electronic Program Guide) — program guide
PAT/PMT — program tables
PES packets — elementary streams

Demultiplexing¶

For MPTS streams, the module performs:

Automatic detection of programs in the stream
Extraction of selected programs by number
PID filtering for processing optimization
Preservation of synchronization between streams

Configuration¶

Basic SPTS Stream¶

The simplest configuration example for receiving SPTS:

stream s {
  input udp://239.0.0.1:1234;
}

MPTS Stream with Demultiplexing¶

For receiving MPTS, demultiplexing needs to be specifically requested:

stream s {
  input mpts-udp://239.0.0.1:1234?programs=1050;
}

Important: When using the mpts-udp protocol, the required multicast group will be received on the server only once, regardless of the number of streams using this group. This ensures efficient use of network resources and prevents traffic duplication.

Advanced Configuration¶

stream main_channel {
  input mpts-udp://239.0.0.1:1234?programs=1050,1051 pids=100,101,102;  
}

Configuration Parameters¶

Parameter	Description	Required	Example
`udp://`	UDP protocol	Yes	`udp://239.0.0.1:1234`
`mpts-udp://`	MPTS protocol	Yes	`mpts-udp://239.0.0.1:1234`
`programs`	Program numbers	No	`programs=1050,1051`
`pids`	PID filter	No	`pids=100,101,102`

Automatic Metadata Extraction¶

SDT (Service Description Table)¶

If SDT is present in the incoming stream, the following will be automatically extracted:

Channel name — display name of the program
Provider name — information about the broadcasting company
Service type — type of content (TV, radio, data)
Country and language — regional information

EPG (Electronic Program Guide)¶

If EPG is present in the stream, it will automatically:

Be parsed — extraction of structured data
Be available for further packaging on output
Be provided for reading via JSON API
Be cached for fast access

Filtering and Optimization¶

PID Filtering¶

The pids option allows filtering incoming PIDs:

# Excluding unnecessary audio tracks
stream filtered {
  input mpts-udp://239.0.0.1:1234?programs=1050 pids=100,101,102;
}

# Excluding teletext
stream no_teletext {
  input mpts-udp://239.0.0.1:1234?programs=1050 pids=100,101,102,103;
}

Filtering Benefits¶

Reduced processor load
Memory savings — processing only needed streams
Improved quality — excluding problematic PIDs
Network optimization — transmitting only necessary content

Automation¶

Minimal Configuration¶

The number of various settings is maximally reduced to relieve administrators of problems. All functionality is enabled automatically:

Auto-detection of stream type (SPTS/MPTS)
Auto-extraction of metadata
Auto-parsing of EPG data
Auto-optimization of processing

Smart Processing¶

The module automatically:

Determines structure of incoming stream
Selects optimal processing parameters
Adapts to changes in the stream
Recovers after errors

API and Interfaces¶

Monitoring and Diagnostics¶

Key Metrics¶

{
  "stats": {
    "input": {
      "pids": [
        {
          "pid": 1040,
          "pnr": 27,
          "packets": 125000,
          "frames": 5026,
          "empty_packets": 20,
          "errors_ts_scrambled": 70,
          "errors_ts_pmt": 10,
          "errors_ts_cc": 250,
          "dts_goes_backwards": 23
        }
      ]
    }
  }
}

Diagnostic Parameters¶

Basic Stream Parameters¶

packets_received — number of received packets
packets_lost — lost packets
programs_detected — detected programs
sdt_found — presence of SDT table
epg_found — presence of EPG data

Detailed PID Parameters (stats.input.pids[0])¶

Basic metrics:

pid — stream identifier
pnr — program number
packets — number of packets
frames — number of frames
empty_packets — packets without payload and adaptation field

Transport stream errors:

errors_adaptation_broken — packets with adaptation field larger than packet size
errors_ts_scrambled — amount of scrambled TS packets
errors_ts_pmt — how many times PMT was not received after 0.5 seconds
errors_ts_cc — how many MPEG-TS packets were received with non-contiguous continuity counters
errors_ts_tei — how many MPEG-TS packets with Transport Error Indicator were received
errors_ts_psi_checksum — how many times have received PSI entry with broken checksum
errors_pid_lost — how many times pid has been lost

PES packet errors:

broken_pes_count — how many PES packets were started not from startcode
broken_pes_sum — how many bytes were discarded due to lack of PES startcode

Time corrections:

time_corrections — jumps of timestamps inside a MPEG-TS stream
repeated_frames — in case of CC error last frame can be repeated. This is a count of repeated frames
corrected_backward_pts — how many times PTS was less than PCR or previous PTS
pcr_resync — if PTS is drifting away from PCR, it can be resynchronized with PCR. This is a resync count
dts_goes_backwards — time on this PID jumped back from reference PTS and it was not a roll over zero
dts_jump_forward — time on this PID jumped forward too far away from reference PTS
too_large_dts_jump — jump of the PTS was so big from previous, that had to flush all frames and restart parsing

Buffering and discarding:

discarded_buffer_count — how many times was discarded too big ES buffer without making a frame of it
discarded_buffer_sum — how many bytes were lost due to discarding ES buffer

Service data:

fillers_count — how many H264(5) NAL fillers were seen in the input
fillers_sum — how many bytes were seen in NAL fillers
padding_pes_count — how many PES packets were on the Padding streamId
padding_pes_sum — how many bytes were in PES packets on the Padding streamId

Critical errors:

crashed — unhandled crashes inside mpegts decoding process

Usage Examples¶

Simple SPTS Reception¶

stream news_channel {
  input udp://239.0.0.1:1234;
}

MPTS with Program Selection¶

stream main_program {
  input mpts-udp://239.0.0.1:1234?programs=1050;
}

stream secondary_program {
  input mpts-udp://239.0.0.1:1234?programs=1051;
}

Audio Filtering¶

stream russian_audio {
  input mpts-udp://239.0.0.1:1234?programs=1050&pids=100,101;
}

Transcoder Integration¶

stream transcoded {
  input mpts-udp://239.0.0.1:1234?programs=1050;

  transcoder {
    video {
      codec h264;
      bitrate 5000k;
    }
    audio {
      codec aac;
      bitrate 128k;
    }
  }  
}

Troubleshooting¶

Common Problems¶

Stream Not Receiving¶

Check network settings — multicast address availability
Ensure correctness of program number for MPTS
Check format of incoming stream
Monitor module logs

Missing Metadata¶

Check presence of SDT in incoming stream
Ensure correctness of EPG data
Check PID filtering settings
Wait for metadata updates

Demultiplexing Problems¶

Check program number in MPTS
Ensure stability of incoming stream
Check synchronization between streams
Monitor processing statistics

Diagnostic Commands¶

# Network traffic monitoring
tcpdump -i any -n host 239.0.0.1

# Check stream metrics
curl -sS "http://localhost:8080/streamer/api/v3/streams/stream_name"

Configuration Recommendations¶

Performance Optimization¶

Use PID filtering to reduce load
Configure buffer size for your streams
Monitor processing statistics
Plan redundancy for critical streams

Reception Quality¶

Check stability of network connection
Use quality network cables
Monitor packet loss in real-time
Configure timeouts for your network

Working with Metadata¶

Regularly check SDT relevance
Monitor EPG data updates
Use caching for fast access
Plan handling of metadata errors

Conclusion¶

MPEGTS Reader is a powerful and flexible module for receiving and processing MPEG transport streams. Automatic metadata extraction, smart filtering, and minimal configuration make it an ideal solution for professional broadcasting. Support for both SPTS and MPTS modes ensures universal application in various broadcasting scenarios.