How to troubleshoot CPIX documents using cpix_verify

Introduction

This tutorial showcases the use of our cpix_verify command-line tool to troubleshoot problems you might encounter with CPIX documents. The cpix_verify CLI tool is automatically installed when you install alongside our software. For more detail on the different options of cpix_verify, please refer to Checking CPIX documents with cpix_verify.

Using print-cpix to catch the basic errors

One of the most basic usages of the verify tool is parsing your CPIX file against syntax errors. As the CPIX files are basic XML files, changing parameters or different text editors might cause some unexpected problems. In this case, cpix_verify outputs the incorrect line from the document with an error message.

#!/bin/bash

$ cpix_verify cpixverify_tutorial1.cpix print-cpix
cpix_verify: FMP4_400: not well-formed (invalid token) @ line 13 col 0

This is the CPIX file which generates one of these errors. It's a misspelled element on line 13 which stops the verify process. This also means the verify tool stop scanning on the first detected error. For a complete scan you must correct the file and run the verify once more to continue.

<?xml version='1.0' encoding='utf-8'?>
<CPIX xmlns="urn:dashif:org:cpix" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:pskc="urn:ietf:params:xml:ns:keyprov:pskc" xsi:schemaLocation="urn:dashif:org:cpix cpix.xsd">
  <ContentKeyList>
    <ContentKey kid="0dc3ec4f-7683-548b-81e7-3c64e582e136" commonEncryptionScheme="cenc">
      <Data>
        <pskc:Secret>
          <pskc:PlainValue>WADwG2qCqkq5TVml+U5PXw==</pskc:PlainValue>
        </pskc:Secret>
      </Data>
    </ContentKey>
  </ContentKeyList>
      <cpix:URIExt
669
XKey>c2tkOi8vZmFpcnBsYXktbGljZW5zZS52dWc2UvdGVzdCpbw==</cpix:URIExtXKey>
  <DRMSystemList>
    <DRMSystem kid="0dc3ec4f-7683-548b-81e7-3c64e582e136" systemId="edef8ba9-79d6-4ace-a3c8-27dcd51d21ed">
      <PSSH>AAAAxnBzc2gBAAAA7e+LqXnWSs6jyCfc1R0h7QAAAAINw+xPdoNUi4HnPGTlguE2FEe37S9mVyu9EwbOfPNhDQAAAIISEBRHt+0vZlcrvRMGznzzYQ0SEFrGoR6qL17Vv2aMQByBNMoSEG7hNRbI51h7rp9+zT6Zom4SEPnsEqYaJl1Hj4MzTjp40scSEA3D7E92g1SLgec8ZOWC4TYaDXdpZGV2aW5lX3Rlc3QiEXVuaWZpZWQtc3RyZWFtaW5nSOPclZsG</PSSH>
    </DRMSystem>
  </DRMSystemList>
</CPIX>

Another good example would be that one of the CPIX requirements is using base64 characters. This type of errors mostly caused by an XML creator script. In this example the error also tells the process is aborted once the unencoded characters had been found.

#!/bin/bash

$ cpix_verify tutorial2.cpix print-cpix
cpix_verify: FMP4_415: Invalid base64 character. parsing aborted @ line 9 col 62

<?xml version="1.0" encoding="utf-8"?>
<CPIX xmlns="urn:dashif:org:cpix" xsi:schemaLocation="urn:dashif:org:cpix cpix.xsd"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:pskc="urn:ietf:params:xml:ns:keyprov:pskc">
    <ContentKeyList>
        <ContentKey kid="00000000-0000-0000-0000-000000000001">
            <Data>
                <pskc:Secret>
                    <pskc:PlainValue>...</pskc:PlainValue>
                </pskc:Secret>
            </Data>
        </ContentKey>
</ContentKeyUsageRuleList>
</CPIX>

Using build-evaluator for more complicated cases

Even if print-cpix is fast and successful for the basic level problems, it might not be the solution for all cases. Especially, for the big content providers use multi DRM solutions. Also, this type of content contains multi audio, video and subtitle tracks.

The next use case includes a CPIX file does not output any errors from printing command. Nevertheless, it still needs to be fixed so the content can be played by the players.

Please take a look at Trans DRM page if you want to test it all scenario on your end and then use the tutorial3.cpix file instead the given example.

#!/bin/bash

ubuntu@ip-172-31-32-140:~$ cpix_verify drm.cpix evaluate-tracks tears-of-steel.ism
enc-tears-of-steel-aac-128k.isma track id=1 timescale=48000 lang=en
soun/mp4a dref=1 bitrate=128002/0 tag=255 samplerate=48000 channels=2 sample_size=16 packet_size=4 scheme=cenc:
cpix_verify: FMP4_500: Multiple content keys (4E2D509A-753F-5E26-B253-CB7D21C3BF05 and 80964B5A-22DC-5C93-B18D-8C68B9FB8FC0) found for track id=1 timescale=48000 lang=en
soun/mp4a dref=1 bitrate=128002/0 tag=255 samplerate=48000 channels=2 sample_size=16 packet_size=4 scheme=cenc (time: 00:00:00.000000(0/1))

The error shows that the problem is related to multiple key usage for the track1. Please take a look at the DRM with multiple keys page to learn more about how to use the multiple keys. In our example ContentKeyUsageRule wasn't embedded in ContentKeyUsageRuleList. The error will be fixed as updating this relevant part of the document.

<ContentKeyUsageRuleList>
    <ContentKeyUsageRule kid="4e2d509a-753f-5e26-b253-cb7d21c3bf05">
        <VideoFilter />
    </ContentKeyUsageRule>
    <ContentKeyUsageRule kid="80964b5a-22dc-5c93-b18d-8c68b9fb8fc0">
        <AudioFilter />
    </ContentKeyUsageRule>
</ContentKeyUsageRuleList>