Charlotte

Version: 1.1.1 (Released on: September 25th, 2026).

Charlotte is a Genshin Impact utility that losslessly decrypts .usm cutscene files into playable .mkv videos, covering all known cutscenes from versions 1.0 through 7.1. Charlotte is also able to retrieve keys directly from USM file itself, although an explicitly defined key is still preferred for processing speed.

This project is heavily inspired by GI-cutscenes. Charlotte not only rebuilds the workflow at a higher level, it also has various optimizations to the decryption algorithm to be significantly more efficient. Charlotte also add extras with tons of QoLs (see below), VapourSynth processing, and a GUI. Also credits to UsmDiviner for inspiring me with the key guessing algorithm.

Disclaimer: This tool is purely for educational purpose and aims to archive already released game content.

• Graphical User Interface
• Losslessly decrypt .usm into .mkv video
• EN, CN, JP, KR audio tracks + softsub in 15 languages
• Near perfect official subtitle styling
• Key crack for USM files without a key (pre-7.1 only)
• Subtitle fetched from Dimbreath automatically
• Font subsetting to save space (~22.5MB per .mkv) using only necessary text characters
• Automatically fetches new video keys
• Automatically fetches fonts from the game directory
• VapourSynth pipeline for post-processing quality improvements
• Bundled lightweight custom FFmpeg build at only ~15MB
• Built-in self updater

Since version 7.1, Hoyo changed the encryption format of the USM files, so cracking is no longer possible from this version onwards and only works for pre-7.1. If you have missing keys, pull requests are welcome.

• Support for Honkai: Star Rail

I should also mention that the VapourSynth filters are extremely heavy on CPU and GPU (to a lesser degree), so it's recommended to have a powerful machine for optimal performance.

Only applicable for CLI. If you use GUI (recommended), skip this section. The GUI itself should be self-explanatory.

charlotte-cli [PATHS...] [OPTIONS]

PATHS is one or more .usm files and/or directories containing .usm files.

Example:

charlotte-cli "USM\Cs_Cutscene_Something_Girl.usm" -vs -nc

This decrypts the cutscene, applies the VapourSynth filter script, and writes to output/Cs_EQHDJ005_HaiDengJie_Girl/Cs_EQHDJ005_HaiDengJie_Girl.mkv without deleting intermediate files.

Process several files and/or directories at once:

charlotte-cli "USM\Cs_A.usm" "USM\Cs_B.usm" "USM\Cs_More_Cutscenes.usm" -o output

To check what is available for your files (decryption key, local subtitles, VapourSynth script) without processing anything:

charlotte-cli "USM\Cs_Cutscene_Something_Girl.usm" --probe

To recover key straight from the USM file and report them without demuxing or converting:

charlotte-cli "USM\Cs_Cutscene_Something_Girl.usm" --crack

To check for a newer release, and install it in place after confirmation:

charlotte-cli --update

For help:

charlotte-cli --help

Tip: If you're running with -vs flag, for higher encoding speed, setting Python and FFmpeg in Task Manager to high priority can help. Alternatively, you can leave the terminal on the front so that Windows' Process Scheduling Priority will prioritize Charlotte.

When -vs or -hs is used, the following x265 params are applied automatically unless --x265-params is set:

keyint=300:min-keyint=30:no-open-gop=1:aq-mode=3:aq-strength=0.75:qcomp=0.72:cbqpoffs=-2:crqpoffs=-2:no-cutree=1:psy-rd=2.0:psy-rdoq=1.7:no-strong-intra-smoothing=1:deblock=-2,-2:no-sao=1:no-sao-non-deblock=1

With --preset slow, slower (default), veryslow or placebo, these are always applied:

ref=6:bframes=8:lookahead-slices=0:rd=4:max-merge=5:tskip=1

These options are highly optimized for video quality, I do not recommend changing it unless you have strong video encoding knowledge.

• Python 3.14 or higher
• uv
• FFmpeg (see below)

Install dependencies:

uv sync

Run the project:

uv run main.py USM/Cs_EQHDJ005_HaiDengJie_Boy.usm -vs -nc

For flag options, refer to the Parameters section.

The bundled ffmpeg.exe is a lightweight custom build. To rebuild it:

1. Set up media-autobuild_suite.
2. Copy ffmpeg_options.txt from the repo root to <suite>/build/ffmpeg_options.txt.
3. To force a rebuild after changing options, delete <suite>/local64/bin-video/ffmpeg.exe before running media-autobuild_suite.bat.
4. Copy the resulting <suite>/local64/bin-video/ffmpeg.exe to the repo root.

Setting this up takes time (a few hours), especially on the very first run. If you wish to avoid that, you can get my prebuilt from here.

uv run pyinstaller charlotte.spec

If you enjoyed using Charlotte, your support would mean so much to me. It keeps me motivated to invest more time into the project and keep it alive for as long as I can.

GitHub Sponsors