Skip to content

MABR & ROUTE output

Register name used to load filter: routeout
This filter may be automatically loaded during graph resolution.

The ROUTE output filter is used to distribute a live file-based session using ROUTE or DVB-MABR.
The filter supports DASH and HLS inputs, ATSC3.0 signaling and generic ROUTE or DVB-MABR signaling.

The filter is identified using the following URL schemes:

  • atsc://: session is a full ATSC 3.0 session
  • route://IP:port: session is a ROUTE session running on given multicast IP and port
  • mabr://IP:port: session is a DVB-MABR session using FLUTE running on given multicast IP and port

The filter only accepts input PIDs of type FILE.

  • HAS Manifests files are detected by file extension and/or MIME types, and sent as part of the signaling bundle or as LCT object files for HLS child playlists.
  • HAS Media segments are detected using the OrigStreamType property, and send as LCT object files using the DASH template string.
  • A PID without OrigStreamType property set is delivered as a regular LCT object file (called raw hereafter).

For raw file PIDs, the filter will look for the following properties:

  • MCASTName: set resource name. If not found, uses basename of URL
  • MCASTCarousel: set repeat period. If not found, uses carousel. If 0, the file is only sent once
  • MCASTUpload: set resource upload time. If not found, uses carousel. If 0, the file will be sent as fast as possible.

When DASHing for ROUTE, DVB-MABR or single service ATSC, a file extension, either in dst or in ext, may be used to identify the HAS session type (DASH or HLS).
Example

"route://IP:PORT/manifest.mpd", "route://IP:PORT/:ext=mpd"

When DASHing for multi-service ATSC, forcing an extension will force all service to use the same formats.
Example

"atsc://:ext=mpd", "route://IP:PORT/manifest.mpd"

If multiple services with different formats are needed, you will need to explicit your filters:

gpac -i DASH_URL:#ServiceID=1 dashin:forward=file:FID=1 -i HLS_URL:#ServiceID=2 dashin:forward=file:FID=2 -o atsc://:SID=1,2  
gpac -i MOVIE1:#ServiceID=1 dasher:FID=1:mname=manifest.mpd -i MOVIE2:#ServiceID=2 dasher:FID=2:mname=manifest.m3u8 -o atsc://:SID=1,2

Warning: When forwarding an existing DASH/HLS session, do NOT set any extension or manifest name.

The filter will look for MCASTIP and MCASTPort properties on the incoming PID to setup multicast of each service. If not found, the default ip and port will be used, with port incremented by one for each new multicast stream.

By default, all streams in a service are assigned to a single multicast session, and differentiated by TSI (see splitlct).
TSI are assigned as follows:

  • signaling TSI is always 0 for ROUTE, 1 for DVB+Flute
  • raw files are assigned TSI 1 and increasing number of TOI
  • otherwise, the first PID found is assigned TSI 10, the second TSI 20 etc ...

When splitlct is set to mcast, the IP multicast address is computed as follows: 

- if `MCASTIP` is set on the PID and is different from the service multicast IP, it is used  
- otherwise the service multicast IP plus one is used

The multicast port used is set as follows:

  • if MCASTPort is set on the PID, it is used
  • otherwise the same port as the service one is used.

Init segments and HLS child playlists are sent before each new segment, independently of carousel.

ATSC 3.0 mode

In this mode, the filter allows multiple service multiplexing, identified through the ServiceID property.
By default (see above), a single multicast IP is used for route sessions, each service will be assigned a different port.

ATSC 3.0 attributes set by using the following PID properties:

  • ATSC3ShortServiceName: set the short service name, maxiumu of 7 characters. If not found, ServiceName is checked, otherwise default to GPAC.
  • ATSC3MajorChannel: set major channel number of service. Default to 2. This really should be set and should not use the default.
  • ATSC3MinorChannel: set minor channel number of service. Default of 1.
  • ATSC3ServiceCat: set service category, default to 1 if not found. 1=Linear a/v service. 2=Linear audio only service. 3=App-based service. 4=ESg service. 5=EA service. 6=DRM service.
  • ATSC3hidden: set if service is hidden. Boolean true or false. Default of false.
  • ATSC3hideInGuide: set if service is hidden in ESG. Boolean true or false. Default of false.
  • ATSC3configuration: set service configuration. Choices are Broadcast or Broadband. Default of Broadcast

ROUTE mode

In this mode, only a single service can be distributed by the ROUTE session.
Note: ip is ignored, and first_port is used if no port is specified in dst.
The ROUTE session will include a multi-part MIME unsigned package containing manifest and S-TSID, sent on TSI=0.

DVB-MABR mode

In this mode, the filter allows multiple service multiplexing, identified through the ServiceID and ServiceName properties.
Note: ip and first_port are used to send the multicast gateway configuration, init segments and manifests. first_port is used only if no port is specified in dst.

The session will carry DVB-MABR gateway configuration, maifests and init segments on TSI=1

The FLUTE session always uses a symbol length of mtu minus 44 bytes.

Low latency mode

When using low-latency mode (-llmode)(), the input media segments are not re-assembled in a single packet but are instead sent as they are received.
In order for the real-time scheduling of data chunks to work, each fragment of the segment should have a CTS and timestamp describing its timing.
If this is not the case (typically when used with an existing DASH session in file mode), the scheduler will estimate CTS and duration based on the stream bitrate and segment duration. The indicated bitrate is increased by brinc percent for safety.
If this fails, the filter will trigger warnings and send as fast as possible.
Note: The LCT objects are sent with no length (TOL header) assigned until the final segment size is known, potentially leading to a final 0-size LCT fragment signaling only the final size.

In this mode, init segments and manifests are sent at the frequency given by property MCASTCarousel of the source PID if set or by (-carousel)[] option.
Indicating MCASTCarousel=0 will disable mid-segment repeating of manifests and init segments.

Examples

Since the ROUTE filter only consumes files, it is required to insert:

  • the dash demultiplexer in file forwarding mode when loading a DASH session
  • the dash multiplexer when creating a DASH session

Multiplexing an existing DASH session in route:

gpac -i source.mpd dashin:forward=file -o route://225.1.1.0:6000/

Multiplexing an existing DASH session in atsc:

gpac -i source.mpd dashin:forward=file -o atsc://

Dashing and multiplexing in route:

gpac -i source.mp4 dasher:profile=live -o route://225.1.1.0:6000/manifest.mpd

Dashing and multiplexing in route Low Latency:

gpac -i source.mp4 dasher -o route://225.1.1.0:6000/manifest.mpd:profile=live:cdur=0.2:llmode

Sending a single file in ROUTE using half a second upload time, 2 seconds carousel:

gpac -i URL:#MCASTUpload=0.5:#MCASTCarousel=2 -o route://225.1.1.0:6000/

Common mistakes:

gpac -i source.mpd -o route://225.1.1.0:6000/

This will only send the manifest file as a regular object and will not load the dash session.
Example

gpac -i source.mpd dashin:forward=file -o route://225.1.1.0:6000/manifest.mpd

This will force the ROUTE multiplexer to only accept .mpd files, and will drop all segment files (same if ext is used).
Example

gpac -i source.mpd dasher -o route://225.1.1.0:6000/  
gpac -i source.mpd dasher -o route://225.1.1.0:6000/manifest.mpd

These will demultiplex the input, re-dash it and send the output of the dasher to ROUTE

Error simulation

It is possible to simulate errors with (-errsim)(). In this mode the LCT network sender implements a 2-state Markov chain:

gpac -i source.mpd dasher -o route://225.1.1.0:6000/:errsim=1.0x98.0

This will set a 1.0 percent chance to transition to error (not sending data over the network) and 98.0 percent chance to transition from error back to OK.

Options

dst (cstr): destination URL

ext (cstr): set extension for graph resolution, regardless of file extension

mime (cstr): set mime type for graph resolution

ifce (str): default interface to use for multicast. If NULL, the default system interface will be used

carousel (uint, default: 1000): carousel period in ms for repeating signaling and raw file data

first_port (uint, default: 6000): port number of first ROUTE session in ATSC mode

ip (str, default: 225.1.1.0): multicast IP address for ROUTE session in ATSC mode

ttl (uint, default: 0): time-to-live for multicast packets

bsid (uint, default: 800): ID for ATSC broadcast stream

mtu (uint, default: 1472): size of LCT MTU in bytes

splitlct (enum, default: off): split mode for LCT channels

  • off: all streams are in the same LCT channel
  • type: each new stream type results in a new LCT channel
  • all: all streams are in dedicated LCT channel, the first stream being used for STSID signaling
  • mcast: all streams are in dedicated multicast groups

korean (bool, default: false): use Korean version of ATSC 3.0 spec instead of US

llmode (bool, default: false): use low-latency mode

brinc (uint, default: 10): bitrate increase in percent when estimating timing in low latency mode

noreg (bool, default: false): disable rate regulation for media segments, pushing them as fast as received

runfor (uint, default: 0): run for the given time in ms

nozip (bool, default: false): do not zip signaling package (STSID+manifest)

furl (bool, default: false): inject full URLs of source service in the signaling instead of stripped server path

flute (bool, default: true): use flute for DVB-MABR object delivery

csum (enum, default: meta): send MD5 checksum for DVB flute

  • no: do not send checksum
  • meta: only send checksum for configuration files, manifests and init segments
  • all: send checksum for everything

recv_obj_timeout (uint, default: 50): set timeout period in ms before client resorts to unicast repair

errsim (v2d, default: 0.0x100.0): simulate errors using a 2-state Markov chain. Value are percentages

use_inband (bool, default: false): DVB mabr option: If true send the mani and init segment in content transport sessions instead of configuration transport session

ssm (bool, default: false): indicate source-specific multicast for DVB-MABR, requires ifce to be set

Was this page helpful?