vc2-bitstream-viewer¶
A command-line utility for displaying VC-2 bitstreams in a human readable form.
The following tutorials give a higher-level introduction to this tool.
Complete usage information can be obtained by running vc2-bitstream-viewer
--help.
Warning
This program prioritises correctness over performance. Internally the pseudocode from the VC-2 specification is used to drive the bitstream parser. As a consequence this program is relatively slow, e.g. taking many seconds per HD frame.
Basic usage¶
In its simplest form, this command can be used to create a complete textual representation of a VC-2 bitstream:
$ vc2-bitstream-viewer path/to/bitstream.vc2
+- data_units:
| +- 0:
| | +- parse_info:
000000000000: | | | +- padding: 0b
000000000000: 01000010010000100100001101000100 | | | +- parse_info_prefix: Correct (0x42424344)
000000000032: 00010000 | | | +- parse_code: end_of_sequence (0x10)
000000000040: 00000000000000000000000000000000 | | | +- next_parse_offset: 0
000000000072: 00000000000000000000000000000000 | | | +- previous_parse_offset: 0
In the printed output, each value read from the bitstream is shown on its own line:
The number at the start of the line is the offset (in bits) from the start of the file that that value begins.
The next value is the value in the bitstream expressed as a binary number. If values are being read from the bounded block in the bitstream, a (
*) indicates that any remaining bits in the value shown were read from beyond the end of the block (and read as ‘1’).The final part of the line indicates the name and decoded value of the read data. Where possible, the names used match the names of variables in the VC-2 pseudocode.
By default, every bit and every field in the bitstream will be visible, including padding bits.
Displaying an area of interest¶
It is possible to restrict the output to only parts of the bitstream
surrounding a particular offset. For example, the --offset/-o argument
can be used to restrict display to only the parts of the bitstream surrounding
a particular bit offset:
$ vc2-bitstream-viewer bitstream.vc2 --offset 40000
See the --context/-C, --context-after/-A and
--context-before/-B arguments to control the number of bits before and
after the supplied offset to be shown. Alternatively, you can also specify an
explicit range to display using the --from-offset/-f and
--to-offset/-t.
Note
Though values before the specified bit offset will not be displayed, they must still be read and parsed by the bitstream viewer in order to correctly parse what comes later in the bitstream.
Filtering displayed values¶
It is possible to filter the displayed values according to the VC-2 pseudocode function which read them. A common case might be to show only the parse_info headers from a stream:
$ vc2-bitstream-viewer bitstream.vc2 --show parse_info
Alternatively, you might wish to show everything in a bitstream except for the transform coefficients (slice data):
$ vc2-bitstream-viewer bitstream.vc2 --hide slice
For this particular action, the convenience alias -S for --hide slice
is also provided.
Showing VC-2 decoder state¶
As well as displaying a textual representation of the VC-2 bitstream, this tool
can also display (a subset of) the internal state of a VC-2 decoder based on
the pseudocode in the specification at different points during bitstream
processing. Use the --show-internal-state option to enable this. This can
be useful when debugging the encoding of transform data whose organisation
depends on various computed values earlier in the bitstream.
Malformed bitstream handling¶
The bitstream parser is as tolerant of malformed bitstreams as is practical and will accept, and blindly tolerate values which are out-of-spec so long as they do not lead to undefined behaviour. In the event that the parser encounters an anomaly that prevents it preceding further, an error will be shown and parsing will terminate.
By default, error messages show only limited information about the failure.
Adding the --verbose/-v option will cause additional details (such as
the next few bits in the bitstream and details of what was being parsed at the
time.
Arguments¶
The complete set of arguments can be listed using --help
usage: vc2-bitstream-viewer [-h] [--version] [--no-status] [--verbose]
[--show-internal-state]
[--ignore-parse-info-prefix]
[--num-trailing-bits NUM_TRAILING_BITS]
[--from-offset BIT_OFFSET]
[--to-offset BIT_OFFSET] [--offset BIT_OFFSET]
[--after-context NUM_BITS]
[--before-context NUM_BITS] [--context NUM_BITS]
[--show FUNCTION] [--hide FUNCTION] [--hide-slice]
bitstream
Display VC-2 bitstreams in a human-readable form.
positional arguments:
bitstream The filename of the bitstream to read.
optional arguments:
-h, --help show this help message and exit
--version show program's version number and exit
--no-status, --quiet, -q
Do not display a status line on stderr while reading
the bitstream.
--verbose, -v Increase the verbosity of error messages. Used once:
also show bitstream offset, bitstream target value and
next --num-trailing-bits bits in the bitstream at the
time of the error. Used twice: also show the Python
stack trace for the error.
--show-internal-state, -i
Print the internal state variable used by the VC-2
pseudo code after parsing each data unit. Parts of the
pseudocode state not directly related to bitstream
processing might or might not be included in this
printout.
--ignore-parse-info-prefix, -p
By default, parsing is halted if an invalid parse_info
prefix is encountered. Giving this option suppresses
this check and allows parsing to continue.
--num-trailing-bits NUM_TRAILING_BITS, -b NUM_TRAILING_BITS
When --verbose is used, this argument defines the
number of bits to show from the bitstream after the
point the error occurred. (Default: 128).
range options:
--from-offset BIT_OFFSET, -f BIT_OFFSET
Don't display bitstream values until the specified bit
offset. If negative, gives an offset from the end of
the file. Default: 0.
--to-offset BIT_OFFSET, -t BIT_OFFSET
Stop reading the bitstream at the specified bit
offset. If prefixed with '+', the offset will be
relative to the offset given to '--from-offset'. If
negative, gives an offset from the end of the file.
Default: the end of the file.
--offset BIT_OFFSET, -o BIT_OFFSET
Shows the parts of the bitstream surrounding the
specified bit offset. (An alternative to manually
setting '--from-offset' and '--to-offset' to values
either-side of the chosen offset). If none of '--
after-context', '--before-context' or '--context' are
given, 128 bits of context either side of this offset
will be shown.
--after-context NUM_BITS, -A NUM_BITS
Sets the number of bits after '--around-offset' to be
shown.
--before-context NUM_BITS, -B NUM_BITS
Sets the number of bits before '--around-offset' to be
shown.
--context NUM_BITS, -C NUM_BITS
Sets the number of bits before and after '--around-
offset' to be shown.
filtering options:
--show FUNCTION, -s FUNCTION
Display only parts of the bitstream which are
processed by the specified pseudo-code function as
described in the VC-2 specification. By default all
parts of the bitstream are displayed. Can be used
multiple times to show different parts of the
bitstream. Supported function names: auxiliary_data,
clean_area, color_diff_sampling_format, color_matrix,
color_primaries, color_spec,
extended_transform_parameters, fragment_data,
fragment_header, fragment_parse, frame_rate,
frame_size, hq_slice, ld_slice, padding, parse_info,
parse_parameters, parse_sequence, parse_stream,
picture_header, picture_parse, pixel_aspect_ratio,
quant_matrix, scan_format, sequence_header,
signal_range, slice, slice_parameters,
source_parameters, transfer_function, transform_data,
transform_parameters, wavelet_transform.
--hide FUNCTION, -H FUNCTION
Omit parts of the bitstream which are processed by the
specified pseudo-code function as described in the
VC-2 specification. Accepts the same values as --show.
--hide-slice, -S Alias for '--hide slice'. Suppresses the printing of
all transform coefficients, greatly reducing the
quantity of output.