DASH and HLS segmenter
Register name used to load filter: dasher
GPAC DASH and HLS segmenter
This filter provides segmentation and manifest generation for MPEG-DASH and HLS formats.
The segmenter currently supports:
- MPD and m3u8 generation (potentially in parallel)
- ISOBMFF, MPEG-2 TS, MKV and raw bitstream segment formats
- override of profiles and levels in manifest for common codecs (aac, hevc, vp9, av1, aac)
- most MPEG-DASH profiles
- static and dynamic (live) manifest offering
- context store and reload for batch processing of live/dynamic sessions
The segmenter uses templates to derive output file names, regardless of the DASH mode (even when templates are not used). The default one is
$File$_dash for ondemand and single file modes, and
$File$_$Number$ for seperate segment files
If input is foo.mp4 with 640x360 video, this will resolve in Great_foo_640_$Number$ for the DASH template.
If input is foo.mp4 with 640x360 video, this will resolve in Great_foo_640.mp4 for onDemand case.
Standard DASH replacement strings:
- $Number[%%0Nd]$: replaced by the segment number, possibly prefixed with 0
- $RepresentationID$: replaced by representation name
- $Time$: replaced by segment start time
- $Bandwidth$: replaced by representation bandwidth.
Note: these strings are not replaced in the manifest templates elements.
Additionnal replacement strings (not DASH, not generic GPAC replacements but may occur multiple times in template):
- $Init=NAME$: replaced by NAME for init segment, ignored otherwise
- $Index=NAME$: replaced by NAME for index segments, ignored otherwise
- $Path=PATH$: replaced by PATH when creating segments, ignored otherwise
- $Segment=NAME$: replaced by NAME for media segments, ignored for init segments
- $DS$ (Dash Suffix): replaced by
_trackNin case the input is an AV multiplex, or kept empty otherwise
Note: these strings are replaced in the manifest templates elements.
To assign PIDs into periods and adaptation sets and configure the session, the segmenter looks for the following properties on each input pid:
- Representation: assigns representation ID to input pid. If not set, the default behaviour is to have each media component in different adaptation sets. Setting the RepresentationID allows explicit multiplexing of the source(s)
- Period: assigns period ID to input pid. If not set, the default behaviour is to have all media in the same period with the same start time
- PStart: assigns period start. If not set, 0 is assumed, and periods appear in the Period ID declaration order. If negative, this gives the period order (-1 first, then -2 ...). If positive, this gives the true start time and will abort DASHing at period end
Note: When both positive and negative values are found, the by-order periods (negative) will be inserted AFTER the timed period (positive)
- ASID: assigns parent adaptation set ID. If not 0, only sources with same AS ID will be in the same adaptation set
Note: If multiple streams in source, only the first stream will have an AS ID assigned
- xlink: for remote periods, only checked for null pid
- Role, PDesc, ASDesc, ASCDesc, RDesc: various descriptors to set for period, AS or representation
- BUrl: overrides segmenter [-base] with a set of BaseURLs to use for the pid (per representation)
- Template: overrides segmenter template for this PID
- DashDur: overrides segmenter segment duration for this PID
- StartNumber: sets the start number for the first segment in the PID, default is 1
- Non-dash properties: Bitrate, SAR, Language, Width, Height, SampleRate, NumChannels, Language, ID, DependencyID, FPS, Interlaced. These properties are used to setup each representation and can be overriden on input PIDs using the general PID property settings (cf global help).
This will force declaring a bitrate of 1M for the representation, regardless of actual input bitrate.
This will create unmuxed DASH segments.
This will create muxed DASH segments.
src=m1.mp4 src=m2.mp4:#Period=Yep dst=test.mpd
This will put src m1.mp4 in first period, m2.mp4 in second period.
This will assign a baseURL to src m1.mp4.
src=m1.mp4:#ASCDesc=<ElemName val="attval">text</ElemName> dst=test.mpd
This will assign the specified XML descriptor to the adaptation set.
Note: this can be used to inject most DASH descriptors not natively handled by the segmenter.
The segmenter handles the XML descriptor as a string and does not attempt to validate it. Descriptors, as well as some segmenter filter arguments, are string lists (comma-separated by default), so that multiple descriptors can be added:
src=m1.mp4:#RDesc=<Elem attribute="1"/>,<Elem2>text</Elem2> dst=test.mpd
This will insert two descriptors in the representation(s) of m1.mp4.
src=video.mp4:#Template=foo$Number$ src=audio.mp4:#Template=bar$Number$ dst=test.mpd
This will assign different templates to the audio and video sources.
This will insert an create an MPD with first a remote period then a regular one.
This will create an MPD with first a regular period, dashing ony 6s of content, then a remote one.
The segmenter will create muxing filter chains for each representation and will reassign PID IDs so that each media component (video, audio, ...) in an adaptation set has the same ID.
For HLS, the output pid will deliver the master playlist and the variant playlists.
The default variant playlist are $NAME_$N.m3u8, where $NAME is the radical of the output file name and $N is the 1-based index of the variant.
The default behavior of the segmenter is to estimate the theoretical start time of each segment based on target segment duration, and start a new segment when a packet with SAP type 1,2,3 or 4 with time greater than the theoretical time is found.
This behavior can be changed to find the best SAP packet around a segment theoretical boundary using sbound:
- closest mode: the segment will start at the closest SAP of the theoretical boundary
- in mode: the segment will start at or before the theoretical boundary
Warning: These modes will introduce delay in the segmenter (typically buffering of one GOP) and should not be used for low-latency modes.
The segmenter can also be configured to:
- completely ignore SAP when segmenting using sap.
- ignore SAP on non-video streams when segmenting using strict_sap.
The segmenter can take a list of instructions, or Cues, to use for the segmentation process, in which case only these are used to derive segment boundaries.
Cue files can be specified for the entire segmenter, or per PID using DashCue property.
Cues are given in an XML file with a root element called <DASHCues>, with currently no attribute specified. The children are <Stream> elements, with attributes:
- id: integer for stream/track/pid ID
- timescale: integer giving the units of following timestamps
- mode: if present and value is
edit, the timestamp are in presentation time (edit list applied). Otherwise they are in media time
The children of <Stream> are <Cue> elements, with attributes:
- sample: integer giving the sample/frame number of a sample at which spliting shall happen
- dts: long integer giving the decoding time stamp of a sample at which spliting shall happen
- cts: long integer giving the composition / presentation time stamp of a sample at which spliting shall happen
Warning: Cues shall be listed in decoding order.
Manifest Generation only mode
The segmenter can try to generate manifests from already fragmented ISOBMFF inputs using sigfrag.
In this case, segment boundaries are attached to each packet starting a segment and used to drive the segmentation.
This should only be used with single-track ISOBMFF sources. If onDemand profile is requested, sources have to be formatted as a DASH self-initializing media segment with the proper sidx.
This mode automatically disables templates and forces sseg for all profiles except onDemand ones.
The manifest generation-only mode supports both MPD and HLS generation.
Muxer development considerations
Output muxers allowing segmented output must obey the following:
- inspect packet properties
- FileNumber: if set, indicate the start of a new DASH segment
- FileName: if set, indicate the file name. If not present, output shall be a single file. This is only set for packet carrying the
FileNumberproperty, and only on one PID (usually the first) for multiplexed outputs
- IDXName: gives the optional index name (if not present, index shall be in the same file as dash segment). Only used for MPEG-2 TS for now
- EODS: property is set on packets with no payload and no timestamp to signal the end of a DASH segment. This is only used when stoping/resuming the segmentation process, in order to flush segments without dispatching an EOS (see subdur )
- for each segment done, send a downstream event on the first connected PID signaling the size of the segment and the size of its index if any
- for muxers with init data, send a downstream event signaling the size of the init and the size of the global index if any
- the following filter options are passed to muxers, which should declare them as arguments:
- noinit: disables output of init segment for the muxer (used to handle bitstream switching with single init in DASH)
- frag: indicates muxer shall used fragmented format (used for ISOBMFF mostly)
- subs_sidx=0: indicates an SIDX shall be generated - only added if not already specified by user
- xps_inband=all|no: indicates AVC/HEVC/... parameter sets shall be sent inband or out of band
- nofragdef: indicates fragment defaults should be set in each segment rather than in init segment
The segmenter will add the following properties to the output PIDs:
- DashMode: identifies VoD (single file with global index) or regular DASH mode used by segmenter
- DashDur: identifies target DASH segment duration - this can be used to estimate the SIDX size for example
dur (number, default: 1.0): target segment duration in seconds
tpl (boolean, default: true): use template mode (multiple segment, template URLs)
stl (boolean, default: false): use segment timeline (ignored in on_demand mode)
dmode (enum, default: static, updatable): dash content mode
- static: static content
- dynamic: live generation
- dynlast: last call for live, will turn the MPD into static
sseg (boolean, default: false): single segment is used
sfile (boolean, default: false): use a single file for all segments (default in on_demand)
align (boolean, default: true): enable segment time alignment between representations
sap (boolean, default: true): enable spliting segments at SAP boundaries
mix_codecs (boolean, default: false): enable mixing different codecs in an adaptation set
ntp (enum, default: rem): insert/override NTP clock at the begining of each segment
- rem: removes NTP from all input packets
- yes: inserts NTP at each segment start
- keep: leaves input packet NTP untouched.
no_sar (boolean, default: false): do not check for identical sample aspect ratio for adaptation sets
m2ts (boolean, default: false): generate MPEG-2 TS output
forcep (boolean, default: false): force profile string for avc/hevc/aac
bs_switch (enum, default: def): bitstream switching mode (single init segment)
- def: resolves to off for onDemand and inband for live
- off: disables BS switching
- on: enables it if same decoder configuration is possible
- inband: moves decoder config inband if possible
- force: enables it even if only one representation
- multi: uses multiple stsd entries in ISOBMFF
avcp (string): profile to use for AVC|H264 if no profile could be found. If forcep is set, enforces this profile
hvcp (string): profile to use for HEVC if no profile could be found. If forcep is set, enforces this profile
aacp (string): profile to use for AAC if no profile could be found. If forcep is set, enforces this profile
av1p (string): profile to use for AV1 if no profile could be found. If forcep is set, enforces this profile
vpxp (string): profile to use for VP8/9 if no profile could be found. If forcep is set, enforces this profile
template (string): template string to use to generate segment name - see filter help
segext (string): file extension to use for segments
initext (string): file extension to use for the init segment
muxtype (enum, default: auto): muxtype to use for the segments
- mp4: uses ISOBMFF format
- ts: uses MPEG-2 TS format
- mkv: uses Matroska format
- webm: uses WebM format
- raw: uses raw media format (disables muxed representations)
- auto: guess format based on extension, default to mp4 if no extension
asto (int, default: 0): availabilityStartTimeOffset to use. A negative value simply increases the AST, a positive value sets the ASToffset to representations
profile (enum, default: auto): target DASH profile. This will set default option values to ensure conformance to the desired profile. For MPEG-2 TS, only main and live are used, others default to main.
- auto: turns profile to live for dynamic and full for non-dynamic
- live: DASH live profile, using segment template
- onDemand: MPEG-DASH live profile
- main: MPEG-DASH main profile, using segment list
- full: MPEG-DASH full profile
- hbbtv1.5.live: HBBTV 1.5 DASH profile
- dashavc264.live: DASH-IF live profile
- dashavc264.onDemand: DASH-IF onDemand profile
- set: in adaptation set element
- rep: in representation element
- both: in both adaptation set and representation elements
pssh (enum, default: v): storage mode for PSSH box
- f: stores in movie fragment only
- v: stores in movie only
- m: stores in mpd only
- mf: stores in mpd and movie fragment
- mv: stores in mpd and movie
- n: discard pssh from mpd and segments
buf (int, default: -100): min buffer duration in ms. negative value means percent of segment duration (eg -150 = 1.5*seg_dur)
timescale (int, default: 0): set timescale for timeline and segment list/template. A value of 0 picks up the first timescale of the first stream in an adaptation set. A negative value forces using stream timescales for each timed element (multiplication of segment list/template/timelines). A positive value enforces the MPD timescale
check_dur (boolean, default: true): check duration of sources in period, trying to have roughly equal duration. Enforced whenever period start times are used
skip_seg (boolean, default: false): increment segment number whenever an empty segment would be produced - NOT DASH COMPLIANT
title (string): MPD title
source (string): MPD Source
info (string): MPD info url
cprt (string): MPD copyright string
lang (string): language of MPD Info
location (string list): set MPD locations to given URL
base (string list): set base URLs of MPD
refresh (number, default: 0): refresh rate for dynamic manifests, in seconds. A negative value sets the MPD duration. If 0, uses dash duration
tsb (number, default: 30): time-shift buffer depth in seconds. A negative value means infinity
subdur (number, default: 0): maximum duration of the input file to be segmentated. This does not change the segment duration, segmentation stops once segments produced exceeded the duration.
ast (string): set start date (as xs:date, eg YYYY-MM-DDTHH:MM:SSZ) for live mode. Default is now. !! Do not use with multiple periods, nor when DASH duration is not a multiple of GOP size !!
state (string): path to file used to store/reload state info when simulating live. This is stored as a valid MPD with GPAC XML extensions
loop (boolean, default: false): loop sources when dashing with subdur and state. If not set, a new period is created once the sources are over
split (boolean, default: true): enable cloning samples for text/metadata/scene description streams, marking further clones as redundant
hlsc (boolean, default: false): insert clock reference in variant playlist in live HLS
cues (string): set cue file - see filter help
strict_cues (boolean, default: false): strict mode for cues, complains if spliting is not on SAP type 1/2/3 or if unused cue is found
strict_sap (enum, default: off): strict mode for sap
- off: ignore SAP types for PID other than video, enforcing startsWithSAP=1
- sig: same as off but keep startsWithSAP to the true SAP value
- on: warn if any PID uses SAP 3 or 4 and switch to FULL profile
subs_sidx (int, default: -1): number of subsegments per sidx. negative value disables sidx. Only used to inherit sidx option of destination
cmpd (boolean, default: false): skip line feed and spaces in MPD XML for more compacity
styp (string): indicate the 4CC to use for styp boxes when using ISOBMFF output
dual (boolean): indicate to produce both MPD and M3U files
sigfrag (boolean): use manifest generation only mode - see filter help
sbound (enum, default: out): indicate how the theoretical segment start
TSS (= segment_number * duration) should be handled
- out: segment split as soon as
TSSis exceeded (
- closest: segment split at closest SAP to theoretical bound
TSSis always in segment (
reschedule (boolean): reschedule sources with no period ID assigned once done (dynamic mode only)