Media Reframer

Register name used to load filter: reframer
This filter is not checked during graph resolution and needs explicit loading.
Filters of this class can connect to each-other.

This filter provides various tools on inputs:

• ensure reframing (1 packet = 1 Access Unit)
• optionally force decoding
• real-time regulation
• packet filtering based on SAP types or frame numbers
• time-range extraction and splitting

This filter forces input PIDs to be properly framed (1 packet = 1 Access Unit).
It is typically needed to force remultiplexing in file to file operations when source and destination files use the same format.

SAP filtering

The filter can remove packets based on their SAP types using saps option.
For example, this can be used to extract only the key frame (SAP 1,2,3) of a video to create a trick mode version.

Frame filtering

This filter can keep only specific Access Units of the source using frames option.
For example, this can be used to extract only specific key pictures of a video to create a HEIF collection.

Frame decoding

This filter can force input media streams to be decoded using the raw option.
Example

gpac -i m.mp4 reframer:raw=av [dst]

Real-time Regulation

The filter can perform real-time regulation of input packets, based on their timescale and timestamps.
For example to simulate a live DASH:
Example

gpac -i m.mp4 reframer:rt=on -o live.mpd:dynamic

Range extraction

The filter can perform time range extraction of the source using xs and xe options.
The formats allowed for times specifiers are:

• 'T'H:M:S, 'T'M:S: specify time in hours, minutes, seconds
• 'T'H:M:S.MS, 'T'M:S.MS, 'T'S.MS: specify time in hours, minutes, seconds and milliseconds
• INT, FLOAT, NUM/DEN: specify time in seconds (number or fraction)
• 'D'INT, 'D'FLOAT, 'D'NUM/DEN: specify end time as offset to start time in seconds (number or fraction) - only valid for xe
• 'F'NUM: specify time as frame number, 1 being first
• XML DateTime: specify absolute UTC time

In this mode, the timestamps are rewritten to form a continuous timeline, unless xots is set.
When multiple ranges are given, the filter will try to seek if needed and supported by source.

Example

gpac -i m.mp4 reframer:xs=T00:00:10,T00:01:10,T00:02:00:xe=T00:00:20,T00:01:20 [dst]

This will extract the time ranges [10s,20s], [1m10s,1m20s] and all media starting from 2m

If no end range is found for a given start range:

• if a following start range is set, the end range is set to this next start
• otherwise, the end range is open

Example

gpac -i m.mp4 reframer:xs=0,10,25:xe=5,20 [dst]

This will extract the time ranges [0s,5s], [10s,20s] and all media starting from 25s
Example

gpac -i m.mp4 reframer:xs=0,10,25 [dst]

This will extract the time ranges [0s,10s], [10s,25s] and all media starting from 25s

It is possible to signal range boundaries in output packets using splitrange.
This will expose on the first packet of each range in each PID the following properties:

• FileNumber: starting at 1 for the first range, to be used as replacement for $num$ in templates
• FileSuffix: corresponding to StartRange_EndRange or StartRange for open ranges, to be used as replacement for $FS$ in templates

Example

gpac -i m.mp4 reframer:xs=T00:00:10,T00:01:10:xe=T00:00:20:splitrange -o dump_$FS$.264 [dst]

This will create two output files dump_T00.00.10_T00.02.00.264 and dump_T00.01.10.264.
Note: The : and / characters are replaced by . in FileSuffix property.

It is possible to modify PID properties per range using props. Each set of property must be specified using the active separator set.

Warning: The option must be escaped using double separators in order to be parsed properly.

Example

gpac -i m.mp4 reframer:xs=0,30::props=#Period=P1,#Period=P2:#foo=bar [dst]

This will assign to output PIDs

• during the range [0,30]: property Period to P1
• during the range [30, end]: properties Period to P2 and property foo to bar

For uncompressed audio PIDs, input frame will be split to closest audio sample number.

When xround is set to seek, the following applies:

• a single range shall be specified
• the first I-frame preceding or matching the range start is used as split point
• all packets before range start are marked as seek points
• packets overlapping range start are forwarded with a SkipBegin property set to the amount of media to skip
• packets overlapping range end are forwarded with an adjusted duration to match the range end

This mode is typically used to extract a range in a frame/sample accurate way, rather than a GOP-aligned way.

When xround is not set to seek, compressed audio streams will still use seek mode.
Consequently, these streams will have modified edit lists in ISOBMFF which might not be properly handled by players.
This can be avoided using no_audio_seek, but this will introduce audio delay.

UTC-based range extraction

The filter can perform range extraction based on UTC time rather than media time. In this mode, the end time must be:

• a UTC date: range extraction will stop after this date
• a time in second: range extraction will stop after the specified duration

The UTC reference is specified using utc_ref.
If UTC signal from media source is used, the filter will probe for utc_probe before considering the source has no UTC signal.

The properties SenderNTP and, if absent, UTC of source packets are checked for establishing the UTC reference.

Other split actions

The filter can perform splitting of the source using xs option.
The additional formats allowed for xs option are:

• SAP: split source at each SAP/RAP
• DVAL: split source by chunks of VAL seconds
• DNUM/DEN: split source by chunks of NUM/DEN seconds
• SVAL: split source by chunks of estimated size VAL bytes (can use property multipliers, e.g. m)

Note: In these modes, splitrange and xadjust are implicitly set.

Options

exporter (bool, default: false): compatibility with old exporter, displays export results

rt (enum, default: off, updatable): real-time regulation mode of input

• off: disables real-time regulation
• on: enables real-time regulation, one clock per PID
• sync: enables real-time regulation one clock for all PIDs

saps (uintl, Enum: 0|1|2|3|4, updatable): list of SAP types (0,1,2,3,4) to forward, other packets are dropped (forwarding only sap 0 will break the decoding)

refs (bool, default: false, updatable): forward only frames used as reference frames, if indicated in the input stream

speed (dbl, default: 0.0, updatable): speed for real-time regulation mode, a value of 0 uses speed from play commands

raw (enum, default: no): force input AV streams to be in raw format

• no: do not force decoding of inputs
• av: force decoding of audio and video inputs
• a: force decoding of audio inputs
• v: force decoding of video inputs

frames (sintl, updatable): drop all except listed frames (first being 1). A negative value -V keeps only first frame every V frames

xs (strl): extraction start time(s)

xe (strl): extraction end time(s). If less values than start times, the last time interval extracted is an open range

xround (enum, default: before): adjust start time of extraction range to I-frame

• before: use first I-frame preceding or matching range start
• seek: see filter help
• after: use first I-frame (if any) following or matching range start
• closest: use I-frame closest to range start

xadjust (bool, default: false): adjust end time of extraction range to be before next I-frame

xots (bool, default: false): keep original timestamps after extraction

nosap (bool, default: false): do not cut at SAP when extracting range (may result in broken streams)

splitrange (bool, default: false): signal file boundary at each extraction first packet for template-base file generation

seeksafe (dbl, default: 10.0): rewind play requests by given seconds (to make sure the I-frame preceding start is catched)

tcmdrw (bool, default: true): rewrite TCMD samples when splitting

props (strl): extra output PID properties per extraction range

no_audio_seek (bool, default: false): disable seek mode on audio streams (no change of priming duration)

probe_ref (bool, default: false): allow extracted range to be longer in case of B-frames with reference frames presented outside of range

utc_ref (enum, default: any): set reference mode for UTC range extraction

• local: use UTC of local host
• any: use UTC of media, or UTC of local host if not found in media after probing time
• media: use UTC of media (abort if none found)

utc_probe (uint, default: 5000): timeout in milliseconds to try to acquire UTC reference from media

copy (bool, default: false, updatable): try copying frame interface into packets

cues (enum, default: no, updatable): cue filtering mode

• no: do no filter frames based on cue info
• segs: only forward frames marked as segment start
• frags: only forward frames marked as fragment start

rmseek (bool, default: false, updatable): remove seek flag of all sent packets