routein

Warning

GPAC's wiki has moved to wiki.gpac.io.

This github wiki will no longer be updated.

You can contribute to GPAC's documentation here.

ROUTE input

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

This filter is a receiver for ROUTE sessions (ATSC 3.0 and generic ROUTE).

• ATSC 3.0 mode is identified by the URL atsc://.
• Generic ROUTE mode is identified by the URL route://IP:PORT.

The filter can work in cached mode, source mode or standalone mode.

Cached mode

The cached mode is the default filter behavior. It populates GPAC HTTP Cache with the received files, using http://groute/serviceN/ as service root, N being the ROUTE service ID.
In cached mode, repeated files are always pushed to cache.
The maximum number of media segment objects in cache per service is defined by nbcached; this is a safety used to force object removal in case DASH client timing is wrong and some files are never requested at cache level.

The cached MPD is assigned the following headers:

• x-route: integer value, indicates the ROUTE service ID.
• x-route-first-seg: string value, indicates the name of the first segment (completely or currently being) retrieved from the broadcast.
• x-route-ll: boolean value, if yes indicates that the indicated first segment is currently being received (low latency signaling).
• x-route-loop: boolean value, if yes indicates a loop in the service has been detected (usually pcap replay loop).

The cached files are assigned the following headers:

• x-route: boolean value, if yes indicates the file comes from an ROUTE session.

If max_segs is set, file deletion event will be triggered in the filter chain.

Source mode

In source mode, the filter outputs files on a single output PID of type file. The files are dispatched once fully received, the output PID carries a sequence of complete files. Repeated files are not sent unless requested.
If needed, one PID per TSI can be used rather than a single PID. This avoids mixing files of different mime types on the same PID (e.g. HAS manifest and ISOBMFF).
Example

gpac -i atsc://gcache=false -o $ServiceID$/$File$:dynext

This will grab the files and forward them as output PIDs, consumed by the fout filter.

If max_segs is set, file deletion event will be triggered in the filter chain.

Standalone mode

In standalone mode, the filter does not produce any output PID and writes received files to the odir directory.
Example

gpac -i atsc://:odir=output

This will grab the files and write them to output directory.

If max_segs is set, old files will be deleted.

File Repair

In case of losses or incomplete segment reception (during tune-in), the files are patched as follows:

• MPEG-2 TS: all lost ranges are adjusted to 188-bytes boundaries, and transformed into NULL TS packets.
• ISOBMFF: all top-level boxes are scanned, and incomplete boxes are transformed in free boxes, except mdat kept as is if repair is set to simple.

If kc option is set, corrupted files will be kept. If fullseg is not set and files are only partially received, they will be kept.

Interface setup

On some systems (OSX), when using VM packet replay, you may need to force multicast routing on your local interface.
For ATSC, you will have to do this for the base signaling multicast (224.0.23.60):
Example

route add -net 224.0.23.60/32 -interface vboxnet0

Then for each ROUTE service in the multicast:
Example

route add -net 239.255.1.4/32 -interface vboxnet0

Options

src (cstr): URL of source content
ifce (str): default interface to use for multicast. If NULL, the default system interface will be used
gcache (bool, default: true): indicate the files should populate GPAC HTTP cache
tunein (sint, default: -2): service ID to bootstrap on for ATSC 3.0 mode (0 means tune to no service, -1 tune all services -2 means tune on first service found)
buffer (uint, default: 0x80000): receive buffer size to use in bytes
timeout (uint, default: 5000): timeout in ms after which tunein fails
nbcached (uint, default: 8): number of segments to keep in cache per service
kc (bool, default: false): keep corrupted file
skipr (bool, default: true): skip repeated files (ignored in cache mode)
stsi (bool, default: false): define one output PID per tsi/serviceID (ignored in cache mode)
stats (uint, default: 1000): log statistics at the given rate in ms (0 disables stats)
tsidbg (uint, default: 0): gather only objects with given TSI (debug)
max_segs (uint, default: 0): maximum number of segments to keep on disk
odir (str): output directory for standalone mode
reorder (bool, default: false): ignore order flag in ROUTE/LCT packets, avoiding considering object done when TOI changes
rtimeout (uint, default: 5000): default timeout in ms to wait when gathering out-of-order packets
fullseg (bool, default: false): only dispatch full segments in cache mode (always true for other modes)
repair (enum, default: simple): repair mode for corrupted files

• no: no repair is performed
• simple: simple repair is performed (incomplete mdat boxes will be kept)
• strict: incomplete mdat boxes will be lost as well as preceding moof boxes
• full: HTTP-based repair, not yet implemented