Checking CPIX documents with cpix_verify
¶
Introduction¶
The cpix_verify
command-line tool can be used to verify CPIX
documents and check the results of content key [1] selection (see
Content key selection algorithm) for a particular presentation. On
success, it will print a human-readable representation of the
results and return a zero exit status. Otherwise, it will print
an error message and return a non-zero exit status.
Note
The human-readable representation of the results that is printed
by cpix_verify
is not part of its documented interface and subject to
change without notice.
Getting help¶
Typing cpix_verify --help
on the command-line will print a brief
summary of its commands and options:
usage: cpix_verify [<option> ...] <cpix URL> <command>
options are:
--allow-unencrypted allow (partially) unencrypted playout
commands are:
build-evaluator build CPIX evaluator
evaluate-tracks <input URL> ...
build CPIX evaluator and evaluate tracks
evaluate-tracks-for-timespan <start> <end> <input URL> ...
build CPIX evaluator and evaluate tracks
for timespan
print-cpix print internal CPIX structure
The print-cpix
command¶
cpix_verify <cpix URL> print-cpix
The print-cpix
command loads a CPIX document from <cpix URL>
and attempts to parse it. This is useful for checking for basic errors
in the CPIX document, such as syntax errors, forbidden elements and
attributes, etc.
The build-evaluator
command¶
cpix_verify <cpix URL> build-evaluator
The build-evaluator
command loads a CPIX document from <cpix
URL>
and attempts to parse it and build a track evaluator. The
checking performed by build-evaluator
is more extensive and
includes some referential integrity constraints.
The evaluate-tracks
command¶
cpix_verify [--allow-unencrypted] <cpix URL> evaluate-tracks <input URL> ...
The evaluate-tracks
command loads a CPIX document from <cpix
URL>
, builds an evaluator from it, and applies the
Content key selection algorithm to the audio and video tracks found in its
<input URL>
arguments. For each track, it prints the content keys
and signaling data found.
The --allow-unencrypted
option controls whether unencrypted
content is allowed. If it is not, a track for which no content key
is found will result in an error.
The evaluate-tracks-for-timespan
command¶
cpix_verify [--allow-unencrypted] <cpix URL> evaluate-tracks-for-timespan <start> <end> <input URL> ...
The evaluate-tracks-for-timespan
command loads a CPIX document from
<cpix URL>
, builds an evaluator from it, and applies the
Content key selection algorithm to the audio and video tracks found in its
<input URL>
arguments, limited to the timespan denoted by
<start>
and <end>
(both in ISO8601 format). This is useful for
testing key rotation scenarios. For each track, it prints a series of
zero or more timespans with the corresponding content keys and
signaling data.
Please note that the CPIX origin server may be instructed to limit the
CPIX's document time range by adding the start=
and end=
query
parameters to the <cpix URL>
; see CPIX origin.
The --allow-unencrypted
option controls whether unencrypted
content is allowed. If it is not, a track for which no content key is
found for (part of) the specified time range, will result in an error.
Footnotes
[1] | A content key in a CPIX document is identified by a Key ID (KID) and usually contains a content encryption key (CEK). In some cases, a Key IV is also specified as part of the content key. |