Can't build .usm file

[SunRay27]

Hi! I am trying to build VP9 .usm file according to examples provided in documentation, but get different errors in the process.

OS: Windows 10
Python version: 3.13
PyCriCodecsEx version: 0.5 from pip
ffmpeg version: 2025-12-18

.usm file google drive
Encryption key: <2897314143465725881>
Video: VP9, encrypted
Audio: HCA, encrypted

Code used: code from documentation examples with insignificant changes.

Case 1:

Documentation states that .ivf container should be prepared with libvpx codec, but VP9 codec is libvpx-vp9

Case 2:

Unpacking VP9 .usm file to .mp4 and then building .usm back with it (c:v and c:a set to 'copy') fails with the following error:

  File "...\myscript.py", line 113, in pack
    f.write(builder.build())
            ~~~~~~~~~~~~~^^
  File "...\PyCriCodecsEx\usm.py", line 584, in build
    SFV_list = self.video_stream.generate_SFV(self)
  File "...\PyCriCodecsEx\usm.py", line 240, in generate_SFV
    v_framerate = int(self.framerate)
                      ^^^^^^^^^^^^^^
  File "...\Python\Python313\Lib\functools.py", line 1039, in __get__
    val = self.func(instance)
  File "...\PyCriCodecsEx\usm.py", line 203, in framerate
    return 1 / min((dt for _, _, _, dt in self.frames()))
               ~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "...\PyCriCodecsEx\usm.py", line 203, in <genexpr>
    return 1 / min((dt for _, _, _, dt in self.frames()))
                                          ~~~~~~~~~~~^^
  File "...\PyCriCodecsEx\usm.py", line 237, in frames
    yield raw_frame, frame, frame["flags"][0] == "K", float(frame["duration_time"])
                                                            ~~~~~^^^^^^^^^^^^^^^^^
KeyError: 'duration_time'

Looks like some of extracted VP9 stream packets miss "duration_time" after extracting data with ffprobe

Case 3:

Case 2 but we re-encode source VP9 stream with libvpx-vp9 before .usm building. We don't get "duration_time" error, but this error instead:

  File "...\myscript.py", line 113, in pack
    f.write(builder.build())
            ~~~~~~~~~~~~~^^
  File "...\PyCriCodecsEx\usm.py", line 584, in build
    SFV_list = self.video_stream.generate_SFV(self)
  File "...\PyCriCodecsEx\usm.py", line 268, in generate_SFV
    data = builder.VideoMask(data)
  File "...\PyCriCodecsEx\usm.py", line 116, in VideoMask
    data_view[i] ^= mask_view[mask_index]
    ~~~~~~~~~^^^
TypeError: cannot modify read-only memory

Case 4:

Unfortuantely I don't remember exact configuration for this error, but building was failing on

File "...\PyCriCodecsEx\usm.py", line 106, in VideoMask
data_view = memoryview(memObj).cast("Q")
                                     ~~~~~~~~~^^^

when I was tinkering with unpack / build configurations

Case 5:

Video players don't play audio of extracted .mp4 files unless audio stream is re-encoded from wav to another format (acc worked for me). Tried both 'copy' and re-encoding to different pcm formats to no avail. (Probably an issue with ffmpeg itself?)
Tried different video players - same result.

[mos9527]

Thanks for the sample and the detailed report. With the latest commit - https://github.com/mos9527/PyCriCodecsEx/blob/main/Tests/issue4.py should run and allow the decode-mux-rebuild-decode[rebuilt]-mux validation flow demonstrated within to operate on the sample USM you provided.

The documentation has been updated to reflect the correct codec usage as well - thanks again for catching that!

Case 5:
Video players don't play audio of extracted .mp4 files unless audio stream is re-encoded from wav to another format (acc worked for me). Tried both 'copy' and re-encoding to different pcm formats to no avail. (Probably an issue with ffmpeg itself?)
Tried different video players - same result.

This is indeed strange. However I cannot reproduce this with either ffplay/mpv - these should work with the demuxed content produced by issue4.py above.

[mos9527]

Lastly, with a key supplied - the rebuilt USM should work with offical tools as well.

[SunRay27]

Thank you so much for your immediate response and fixes!

I've tested issue4.py, and it produces valid .usm files.
However, there is still an issue: building .usm from a muxed .mp4 doesn't work without re-encoding the video stream and fails with the same frame["duration_time"] error.
This is not a problem in my case, as I intend to re-encode the video anyway.

[mos9527]

Do note that it's NOT expected to provide .mp4 files as a muxing input.
https://mos9527.com/PyCriCodecsEx/#usm-sofdec2-encode-decode explictly suggests using m1v, h264, and ivf containers and NONE the other containers like mp4, in which case it'll be undefined behaviour.

I'm not sure how duration_time is not probed (it probably should!), but using -c:v copy and generating one in ivf container (assuming it's still a VP9 stream ) should, and MUST be considered for it to function expectedly.

[SunRay27]

You are right. Sorry, I forgot to mention that I extract .wav and .ivf from .mp4 beforehand (with -c:v copy). I am not providing .mp4 file to muxing input.

[mos9527]

Hm, I can see the duration_time when probing the mp4 output with ffprobe muxed_result1.mp4 -show_entries packet=dts,pts_time,pos,flags,duration_time -of json

{
    "packets": [
        {
            "pts_time": "0.000000",
            "dts": 0,
            "duration_time": "0.033333",
            "pos": "44",
            "flags": "K__"
        },
...

Yet with c:v copy and converting it to ivf container however, it seems like the first few packets doesn't have the duration_time field returned?

        {
            "pts_time": "0.633333",
            "dts": 9728,
            "pos": "51491",
            "flags": "___"
        },
        {
            "pts_time": "0.666667",
            "dts": 10240,
            "pos": "52207",
            "flags": "___"
        },
        {
            "pts_time": "0.700000",
            "dts": 10752,
            "duration_time": "0.033333",
            "pos": "52549",
            "flags": "___"
        },
...

No clue why, but 78d318d should at least allow it to build successfully. Let me know if the USM file works as intented.

[SunRay27]

No clue why, but 78d318d should at least allow it to build successfully. Let me know if the USM file works as intented.

Resulting USM file crashes the game. The re-encoded one works.

[mos9527]

So it's requried after all. Until one can figure out why it's missing, with e4e2813 codecs should now check for duration_time, and terminate with a warning if it's not there.