Repository files navigation

A command line program playing with the cutscene files (USM) from Genshin Impact, reimplemented in Rust.

Much like itsoriginal C# implementation by ToaHartor, it is able to demux USM files, decrypt video and audio tracks, convert HCA files to WAV, convert SRT subtitles into ASS and merge all of these files into a single MKV file.

(note: the subtitle system is not ready yet)

In order to translate cutscenes of 2.7 check outtheversions.json file provided by ToaHartor.

This implementation depends onffmpeg being installed on the system (for now). We are working on being able to merge the different formats ourselves, but this is not yet operational.

Commits are typically verified with GPG keyE30568E404157F2A932071532C5FA04C19678729.You can get it with

curl -L https://vulpinecitrus.info/Lymkwi.gpg.txt| gpg --import -

You can then verify release signatures using that key :

gpg --verify<release-file><release-sig>.asc

You can simply call the program and provide it top-level arguments, a subcommand, and sub-command arguments.

TL;DR at the bottom.

The available top-level arguments are :

• -o/--output : Outfile file or folder
• -V/--version : Print version information
• -h/--help : Print help information
• --no-cleanup : Do not remove the extracted files after conversion/merging

The subcommands are :

• demuxUsm : Demux a single USM file. Its arguments are :
  • -a/--key1 : the 4 lower bytes of the decryption key (hexadecimal)
  • -b/--key2 : the 4 higher bytes of the encryption key (hexadecimal)
  • -f/--demux-file : Path to the file to be demuxed
  • -k/--version-keys : Path to theversions.json file (defaults to./versions.json)
  • -m/--merge : Flag to indicate we wish to merge the output IVF, WAV and ASS into a MKV container
  • -p/--merge-program : Path to the FFMpeg merge program (defaults toffmpeg)
  • -s/--subtitles : Flag to indicate we want to add the subtitles to the MKV file
• batchDemux : Demux a whole folder of USM files. Arguments are :
  • -u/--usm-folder : Path to the folder containing USM files
  • -k/--version-keys : Path to theversions.json file (defaults to./versions.json)
  • -m/--merge : Flag to indicate we wish to merge the output IVF, WAV and ASS into a MKV container
  • -p/--merge-program : Path to the FFMpeg merge program (defaults toffmpeg)
  • -s/--subtitles : Flag to indicate we want to add the subtitles to the MKV file
• convertHca : Convert a HCA file to WAV
  • -i/--hca-input : Path to the input HCA file
  • -a/--key1 : the 4 lower bytes of the decryption key (hexadecimal)
  • -b/--key2 : the 4 higher bytes of the encryption key (hexadecimal)
  • -k/--version-keys : Path to theversions.json file (defaults to./versions.json)
  • -n/--base-name : Base name to look for in theversions.json file to find keys

Here are the most common commands :

Demux a given cutscene

./gi-cutscenes-rs -o battlePass.mkv demuxUsm -m -f battlePass.usm -k ./versions.json

Demux a batch of cutscenes

./gi-cutscenes-rs -o cutscene-output batchDemux -m -u usm-files/ -k versions.json

Convert a HCA file to WAV

./gi-cutscenes-rs -o battlePass_0.wav convertHca -n battlePass -i battlePass_0.hca

This implementation is written in Rust for speed and efficiency. It can be built withcargo using :

cargo build --release

And installed in your cargo folder using :

cargo install --path .

While we aim to be able to only depend on the standard Rust library, and a crate here and there (notablyclap),there is no crate suitable to let us manually merge the IVF, WAV and ASS files into a MKV. As such, we depend onffmpeg for this.

While the original C# implementation of this tool relied onMKVMerge from the MKVToolNix suite, we figuredffmpeg would be better suited and more flexible.

It can be installed on

• Windows using GyanDev's builds
• Linux using your favourite package manager
• MacOS
• just about anything where you cancompile the source code (I've heard people put it on embedded hardware, it's notthat hard)

As soon as it is built, either the path to its binary is added in your path variable, or you can supply it using the-p/--merge-programargument described above.

• Full pipeline of USM to (HCA + IVF) to (WAV + IVF) to MKV
• Batch demux
• Single HCA to WAV file
• Merging of sub files (obtainable inDimbreath's repository)

Just as the original, this is released under GPL 3.0.

I would like to thankToaHartor for his commitment to understanding the encryption system used in Genshin Impact's USM files, as well as the code this implementation is based on.