Packet inspector

Packet inspector¶

Register name used to load filter: inspect
This filter is not checked during graph resolution and needs explicit loading.

The inspect filter can be used to dump PID and packets. It may also be used to check parts of payload of the packets.

The default options inspect only PID changes.
If full is not set, mode is forced to frame and PID properties are formatted in human-readable form, one PID per line.
Otherwise, all properties are dumped.
Note: specifying xml, analyze, fmt or using -for-test will force full to true.

Custom property dumping¶

The packet inspector can be configured to dump specific properties of packets using fmt.
When the option is not present, all properties are dumped. Otherwise, only properties identified by $TOKEN$ are printed. You may use '$', '@' or '%' for TOKEN separator. TOKEN can be:

pn: packet (frame in framed mode) number
dts: decoding time stamp in stream timescale, N/A if not available
ddts: difference between current and previous packets decoding time stamp in stream timescale, N/A if not available
cts: composition time stamp in stream timescale, N/A if not available
dcts: difference between current and previous packets composition time stamp in stream timescale, N/A if not available
ctso: difference between composition time stamp and decoding time stamp in stream timescale, N/A if not available
tmcd: timecode as provided in SEI, N/A if not available (requires reframer)
dur: duration in stream timescale
frame: framing status
- interface: complete AU, interface object (no size info). Typically a GL texture
- frame_full: complete AU
- frame_start: beginning of frame
- frame_end: end of frame
- frame_cont: frame continuation (not beginning, not end)
sap or rap: SAP type of the frame
ilace: interlacing flag (0: progressive, 1: top field, 2: bottom field)
corr: corrupted packet flag
seek: seek flag
bo: byte offset in source, N/A if not available
roll: roll info
crypt: crypt flag
vers: carousel version number
size: size of packet
csize: total size of packets received so far
crc: 32 bit CRC of packet
lf or n: insert new line
t: insert tab
data: hex dump of packet (big output!) or as string if legal UTF-8
lp: leading picture flag
depo: depends on other packet flag
depf: is depended on other packet flag
red: redundant coding flag
start: packet composition time as HH:MM:SS.ms
startc: packet composition time as HH:MM:SS,ms
end: packet end time as HH:MM:SS.ms
endc: packet end time as HH:MM:SS,ms
ck: clock type used for PCR discontinuities
pcr: MPEG-2 TS last PCR, n/a if not available
pcrd: difference between last PCR and decoding time, n/a if no PCR available
pcrc: difference between last PCR and composition time, n/a if no PCR available
P4CC: 4CC of packet property
PropName: Name of packet property
pid.P4CC: 4CC of PID property
pid.PropName: Name of PID property
fn: Filter name

Example

fmt="PID $pid.ID$ packet $pn$ DTS $dts$ CTS $cts$ $lf$"

This dumps packet number, cts and dts as follows: PID 1 packet 10 DTS 100 CTS 108 \n

An unrecognized keyword or missing property will resolve to an empty string.

Note: when dumping in interleaved mode, there is no guarantee that the packets will be dumped in their original sequence order since the inspector fetches one packet at a time on each PID.

Note on playback¶

Buffering can be enabled to check the input filter chain behaviour, e.g. check HAS adaptation logic.
The various buffering options control when packets are consumed. Buffering events are logged using media@info for state changes and media@debug for media filling events.
The speed option is only used to configure the filter chain but is ignored by the filter when consuming packets.
If real-time consumption is required, a reframer filter must be setup before the inspect filter.
Example

gpac -i SRC reframer:rt=on inspect:buffer=10000:rbuffer=1000:mbuffer=30000:speed=2

This will play the session at 2x speed, using 30s of maximum buffering, consuming packets after 10s of media are ready and rebuffering if less than 1s of media.

Options¶

_any: target file path and name
stderr: dump to stderr
stdout: dump to stdout
GLOG: use GPAC logs app@info
TL: use GPAC log tool TL at level info
null: silent mode

mode (enum, default: pck): dump mode

pck: dump full packet
blk: dump packets before reconstruction
frame: force reframer
raw: dump source packets without demultiplexing

interleave (bool, default: true): dump packets as they are received on each PID. If false, logs are reported for each PID at end of session

deep (bool, default: false, updatable): dump packets along with PID state change, implied when fmt is set

props (bool, default: true, updatable): dump packet properties, ignored when fmt is set

dump_data (bool, default: false, updatable): enable full data dump (very large output), ignored when fmt is set

fmt (str, updatable): set packet dump format

hdr (bool, default: true): print a header corresponding to fmt string without '$' or "pid"

allp (bool, default: false): analyse for the entire duration, rather than stopping when all PIDs are found

info (bool, default: false, updatable): monitor PID info changes

full (bool, default: false, updatable): full dump of PID properties (always on if XML)

pcr (bool, default: false, updatable): dump M2TS PCR info

speed (dbl, default: 1.0): set playback command speed. If negative and start is 0, start is set to -1

start (dbl, default: 0.0): set playback start offset. A negative value means percent of media duration with -1 equal to duration

dur (frac, default: 0/0): set inspect duration

analyze (enum, default: off, updatable): analyze sample content (NALU, OBU), similar to -bsdbg option of reframer filters

off: no analyzing
on: simple analyzing
bs: log bitstream syntax (all elements read from bitstream)
full: log bitstream syntax and bit sizes signaled as (N) after field value, except 1-bit fields (omitted)

xml (bool, default: false, updatable): use xml formatting (implied if (-analyze]() is set) and disable fmt

crc (bool, default: false, updatable): dump crc of samples of subsamples (NALU or OBU) when analyzing

fftmcd (bool, default: false, updatable): consider timecodes use ffmpeg-compatible signaling rather than QT compliant one

dtype (bool, default: false, updatable): dump property type

buffer (uint, default: 0): set playback buffer in ms

mbuffer (uint, default: 0): set max buffer occupancy in ms. If less than buffer, use buffer

rbuffer (uint, default: 0, updatable): rebuffer trigger in ms. If 0 or more than buffer, disable rebuffering

stats (bool, default: false): compute statistics for PIDs

timeout (uint, default: 5000): timeout in ms when doing simple inspection in case no packets are received on some PIDs

test (enum, default: no, updatable): skip predefined set of properties, used for test mode

no: no properties skipped
noprop: all properties/info changes on PID are skipped, only packets are dumped
network: URL/path dump, cache state, file size properties skipped (used for hashing network results)
netx: same as network but skip track duration and templates (used for hashing progressive load of fmp4)
encode: same as network plus skip decoder config (used for hashing encoding results)
encx: same as encode and skip bitrates, media data size and co
nocrc: disable packet CRC dump
nobr: skip bitrate

ENCRYPT