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.

Regular mode

This is the default mode, in which the filter produces media PIDs and frames from sources indicated in the manifest.
The default behavior 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 -o 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 explicitly 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 (scalability) and all qualities and initialization segments need to be forwarded, add split_as.

Segment bound modes

When forward is set to segb 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 regenerate 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=true to ensure the first segment fetched is complete, and split_as=true to fetch all qualities.

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

• CueStart: indicate this is a segment start
• FileNumber: current segment number
• FileName: current segment file name without manifest base url
• DFPStart: set with value 0 if this is the first packet in the period, absent otherwise

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, in same order as manifests in DFVariant

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 indicated in the manifest
• source_template: set to true to indicate the source template is known
• stl_timescale: timescale used by SegmentTimeline, or 0 if no SegmentTimeline
• init_url: unresolved intialization URL (as it appears in the manifest)
• manifest_url: manifest URL

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 (sint, default: 0): switch quality every N segments

• positive: go to higher quality or loop to lowest
• negative: go to lower quality or loop to highest
• 0: disabled

segstore (enum, default: mem): enable file caching

• mem: all files are stored in memory, no disk IO
• disk: 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; if tiles are used, all low priority tiles will have the lower (below max) bandwidth selected
• max_bw_tiles: start with highest bitrate; if tiles are used, all low priority tiles will have their lowest bandwidth selected

max_res (bool, default: true): use max media resolution to configure display
abort (bool, default: false): allow abort during a segment download
use_bmin (enum, default: auto): playout buffer handling

• no: use default player settings
• auto: notify player of segment duration if not low latency
• mpd: use the indicated min buffer time of the MPD

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 timeshift 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 equally across 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 milliseconds to wait between two 40X on the same segment
exp_threshold (uint, default: 100): delay in milliseconds 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 (e.g. 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

• 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 (sigfrag) in sources 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)
chain_mode (enum, default: on): MPD chaining mode

• off: do not use MPD chaining
• on: use MPD chaining once over, fallback if MPD load failure
• error: use MPD chaining once over or if error (MPD or segment download)

asloop (bool, default: false): when auto switch is enabled, iterates back and forth from highest to lowest qualities