dashin

HOME » Filters » MPEG-DASH and HLS client

MPEG-DASH and HLS client

Register name used to load filter: dashin
This filter may be automatically loaded during graph resolution.
This filter requires the graph resolver to be activated.

This filter reads MPEG-DASH, HLS and MS Smooth manifests and produce media output according to its mode.

Regular mode

This is the default mode, in which the filter produces media PIDs and frames from sources indicated in the manifest.
The default behaviour is to perform adaptation according to algo, but the filter can:

• run with no adaptation, to grab maximum quality.
  Example

gpac -i MANIFEST_URL:algo=none:start_with=max_bw -o dest.mp4

• run with no adaptation, fetching all qualities.
  Example

gpac -i MANIFEST_URL:split_as fout:dst=$File$.mp4:clone

File mode

When forward is set to file, the client forwards media files without demultiplexing them.
This is mostly used to expose the DASH session to a file server such as ROUTE or HTTP.
In this mode, the manifest is forwarded as an output PID.

Warning: This mode cannot be set through inheritance as it changes the link capabilities of the filter. The filter MUST be explicitely declared.

To expose a live DASH session to route:
Example

gpac -i MANIFEST_URL dashin:forward=file @ -o route://225.0.0.1:8000/

Note: This mode used to be trigger by filemode option, still recognized.

If the source has dependent media streams (scability) and all qualities and initialization segments need to be forwarded, add split_as.

Segment bound modes

When forward is set to segs or mani, the client forwards media frames (after demux) together with segment and fragment boundaries of source files.

This mode can be used to process media data and regenerating the same manifest/segmentation.

Example

gpac -i MANIFEST_URL:forward=mani cecrypt:cfile=DRM.xml @ -o encrypted/live.mpd:pssh=mv

This will encrypt an existing DASH session, inject PSSH in manifest and segments.

Example

gpac -i MANIFEST_URL:forward=segb cecrypt:cfile=DRM.xml @ -o encrypted/live.m3u8

This will encrypt an existing DASH session and republish it as HLS, using same segment names and boundaries.

This mode will force noseek to true to ensure the first segment fetched is complete, and split_as to true to fetch all qualities.

Each first packet of a segment will have the following properties attached:

• CueStart: to indicate this is a segment start (set by demuxer if it offers sigfrag option)
• FileNumber: current segment number
• FileName: current segment file name without manifest base url

If forward is set to mani, the first packet of a segment dispatched after a manifest update will also carry the manifest payload as a property:

• DFManifest: contains main manifest (MPD, M3U8 master)
• DFVariant: contains list of HLS child playlists as strings for the given quality
• DFVariantName: contains list of associated HLS child playlists name

Each output PID will have the following properties assigned:

• DFMode: set to 1 for segb or 2 for mani
• DCue: set to inband
• DFPStart: set to current period start value
• FileName: set to associated init segment if any
• Representation: set to the associated representation ID in the manifest
• DashDur: set to the average segment duration as advertized in the manifest

When the dasher is used together with this mode, this will force all generated segments to have the same name, duration and fragmentation properties as the input ones.
It is therefore not recommended for sessions stored/generated on local storage to generate the output in the same directory.

Options

auto_switch (uint, default: 0): switch quality every N segments, disabled if 0
segstore (enum, default: mem): enable file caching

• mem: all files are stored in memory, no disk IO
• file: files are stored to disk but discarded once played
• cache: all files are stored to disk and kept

algo (str, default: gbuf, minmax: none|grate|gbuf|bba0|bolaf|bolab|bolau|bolao|JS): adaptation algorithm to use

• none: no adaptation logic
• grate: GPAC legacy algo based on available rate
• gbuf: GPAC legacy algo based on buffer occupancy
• bba0: BBA-0
• bolaf: BOLA Finite
• bolab: BOLA Basic
• bolau: BOLA-U
• bolao: BOLA-O
• JS: use file JS (either with specified path or in $GSHARE/scripts/) for algo (.js extension may be omitted)

start_with (enum, default: max_bw): initial selection criteria

• min_q: start with lowest quality
• max_q: start with highest quality
• min_bw: start with lowest bitrate
• max_bw: start with highest bitrate; for tiles are used, all low priority tiles will have the lower (below max) bandwidth selected
• max_bw_tiles: start with highest bitrate; for tiles all low priority tiles will have their lowest bandwidth selected

max_res (bool, default: true): use max media resolution to configure display
immediate (bool, default: false): when interactive switching is requested and immediate is set, the buffer segments are trashed
abort (bool, default: false): allow abort during a segment download
use_bmin (bool, default: false): use the indicated min buffer time of the MPD if true, otherwise uses default player settings
shift_utc (sint, default: 0): shift DASH UTC clock in ms
route_shift (sint, default: 0): shift ROUTE requests time by given ms
server_utc (bool, default: yes): use ServerUTC: or Date: http headers instead of local UTC
screen_res (bool, default: yes): use screen resolution in selection phase
init_timeshift (sint, default: 0): set initial timshift in ms (if >0) or in per-cent of timeshift buffer (if <0)
tile_mode (enum, default: none): tile adaptation mode

• none: bitrate is shared equaly accross all tiles
• rows: bitrate decreases for each row of tiles starting from the top, same rate for each tile on the row
• rrows: bitrate decreases for each row of tiles starting from the bottom, same rate for each tile on the row
• mrows: bitrate decreased for top and bottom rows only, same rate for each tile on the row
• cols: bitrate decreases for each columns of tiles starting from the left, same rate for each tile on the columns
• rcols: bitrate decreases for each columns of tiles starting from the right, same rate for each tile on the columns
• mcols: bitrate decreased for left and right columns only, same rate for each tile on the columns
• center: bitrate decreased for all tiles on the edge of the picture
• edges: bitrate decreased for all tiles on the center of the picture

tiles_rate (uint, default: 100): indicate the amount of bandwidth to use at each quality level. The rate is recursively applied at each level, e.g. if 50%, Level1 gets 50%, level2 gets 25%, ... If 100, automatic rate allocation will be done by maximizing the quality in order of priority. If 0, bitstream will not be smoothed across tiles/qualities, and concurrency may happen between different media
delay40X (uint, default: 500): delay in millisconds to wait between two 40X on the same segment
exp_threshold (uint, default: 100): delay in millisconds to wait after the segment AvailabilityEndDate before considering the segment lost
switch_count (uint, default: 1): indicate how many segments the client shall wait before switching up bandwidth. If 0, switch will happen as soon as the bandwidth is enough, but this is more prone to network variations
aggressive (bool, default: no): if enabled, switching algo targets the closest bandwidth fitting the available download rate. If no, switching algo targets the lowest bitrate representation that is above the currently played (eg does not try to switch to max bandwidth)
debug_as (uintl): play only the adaptation sets indicated by their indices (0-based) in the MPD
speedadapt (bool, default: no): enable adaptation based on playback speed
noxlink (bool, default: no): disable xlink if period has both xlink and adaptation sets
query (str): set query string (without initial '?') to append to xlink of periods
split_as (bool, default: no): separate all qualities into different adaptation sets and stream all qualities. Dependent representations (scalable) are treated as independent
noseek (bool, default: no): disable seeking of initial segment(s) in dynamic mode (useful when UTC clocks do not match)
bwcheck (uint, default: 5): minimum time in milliseconds between two bandwidth checks when allowing segment download abort
lowlat (enum, default: early): segment scheduling policy in low latency mode

• no: disable low latency
• strict: strict respect of AST offset in low latency
• early: allow fetching segments earlier than their AST in low latency when input demux is empty

forward (enum, default: none): segment forwarding mode -see filter help

• none: regular DASH read
• file: do not demux files and forward them as file pids (imply segstore=mem)
• segb: turn on split_as, segment and fragment bounds signaling and DASH cue insertion
• mani: same as segb and also forward manifests

fmodefwd (bool, default: yes): forward packet rather than copy them in file forward mode. Packet copy might improve performances in low latency mode
skip_lqt (bool, default: no): disable decoding of tiles with highest degradation hints (not visible, not gazed at) for debug purposes
llhls_merge (bool, default: yes): merge LL-HLS byte range parts into a single open byte range request
groupsel (bool, default: no): select groups based on language (by default all playable groups are exposed)