Sound Framework – Custom Sounds and Voices v1.4.0
Required mods:
- Kingdom Come Script Extender (KCSE) (For the (KCSE) Sound Framework)
- Ultimate ASI Loader (For the (ASI) Sound Framework)
Sound Framework gives Kingdom Come: Deliverance II mods a way to use custom sounds and voices with lip sync. Mods can add voice lines and sounds without code by placing their settings in an INI file inside the mod’s SoundFramework folder.
Features
- Sounds: A pack can play its files through the game’s world, voice or music buses. It can also use the game’s own sound events with changed pitch and volume, in either 3D or flat playback. Volume and pitch variation, loops, cooldowns and instance limits are supported.
- Sound replacement: A pack sound may replace a game sound event or play over it. The replacement can apply everywhere or only to selected characters and animals, and it can begin with the event or later, such as when a bow is released.
- Voice lines: NPCs use the game’s speech system to deliver lines from a pack. The result can include a bottom subtitle and speaker name, a chat bubble, or both.
- Voice replacement: Pack lines can take the place of game voice lines, either through an exact key or through a pattern.
- Volume: Conversation, bark and cutscene voices have separate volume controls. Packs can also make selected game sounds quieter or louder.
- Lip sync: Pack voice lines animate the speaker’s mouth. A small model learned from the game’s own animation or from voice loudness supplies the movement. Mouth animation is also added to lines that lack it, whether they come from mods or the game, as well as to speakers in cutscenes made by mods and every line in a voice dub that has no mouth animation of its own.
- Moods: Facial expressions remain active while a line plays. There are eleven default moods, and packs may alter them or add more.
- Live reload: Saving a pack or the settings INI applies the changes during play.
- Pack problems are logged together with the relevant file and line. Debug options can additionally record the game’s sound events and voice lines.
- The project is open-source and uses the DetourModKit modding framework.
Specifications
- The target is Kingdom Come: Deliverance II on PC, built around Steam 1.5.6.
- Advanced lip sync relies on a small neural network containing about 680,000 parameters.
- The advanced lip-sync model was trained using Kingdom Come: Deliverance II’s own voice lines and facial animation.
- strength sets the mood scale from 0 to 2, and its default value is 1.
Requirements
- Kingdom Come: Deliverance II on PC, built around Steam 1.5.6.
- For the ASI build: an ASI loader, not included.
- For the KCSE build: Kingdom Come Script Extender (KCSE).
Installation
Two builds are available in the Files tab. Install one of them, not both. When both are present, the one loaded second remains disabled and reports this in its log.
Option A: ASI build
First locate the KC:D 2 installation folder, then open the Bin/Win64MasterMaster… subfolder containing WHGame.dll. For Steam, the path is:
<KC:D 2 installation folder>/Bin/Win64MasterMasterSteamPGO/
Each other store has its own Bin/Win64MasterMaster… folder. Identify the right folder by finding WHGame.dll in it.
Step 1: Install an ASI loader. You can skip this step if KC:D 2 already has a working ASI loader. Download one x64 variant of Ultimate ASI Loader by ThirteenAG, then extract its DLL next to WHGame.dll:
- Use this as the usual choice when dinput8.dll is not in use.
- Choose the alternative when dinput8.dll is already being used.
- Use the other alternative when version.dll is also in use or fails to load.
KCSE loads .asi files from beside its dinput8.dll as well, meaning KCSE users do not need another loader. Never overwrite a DLL that belongs to a different mod.
Step 2: Install the mod. Extract the archive directly beside WHGame.dll in the same folder. Do not create an additional subfolder named after the archive:
Bin/Win64MasterMasterSteamPGO/
|-- WHGame.dll (game file, already present) |-- dinput8.dll (ASI loader) |-- KCD2_SoundFramework.asi (this mod) |-- KCD2_SoundFramework.ini (settings) |-- KCD2_SoundFramework_moods.ini (default facial moods) |-- KCD2_SoundFramework_lipmodel.bin (advanced lip sync model) -- KCD2_SoundFramework.log (created when the mod loads)
For Wine/Proton, place an override for the loader in Steam’s Properties -> Launch Options:
WINEDLLOVERRIDES="dinput8=n,b" %command%
If the loader uses another name, use version=n,b or winmm=n,b instead.
Option B: KCSE build
Begin by installing KCSE. Then install the KCSE archive with a mod manager, or unpack it into your Mods folder. Create that folder if it does not exist:
Mods/ -- soundframework/ |-- mod.manifest -- KCSE/ -- Plugins/ |-- KCD2_SoundFramework.dll |-- KCD2_SoundFramework.ini |-- KCD2_SoundFramework_moods.ini -- KCD2_SoundFramework_lipmodel.bin
Optional: Sound Framework Fixes
The Files tab also contains Sound Framework Fixes, which corrects bugs in the game’s own sounds. It can be used independently or together with the framework. Install it through your mod manager, or unpack it into the Mods folder.
- After a fight with an NPC using a wooden or blunt weapon, longsword draw and sheathe sounds no longer become silent.
Verification and updates
After loading a save, open KCD2_SoundFramework.log beside the mod’s DLL or ASI. The file names every sound pack discovered by the framework and records any problems found in them.
Before updating, make a backup of your customized INI. Extract the new archive and then apply your settings again to the supplied INI.
Configuration
Use a text editor such as Notepad to open KCD2_SoundFramework.ini beside the mod. Saving the file applies changes while you play, although a restart is required only for Enabled.
- LogLevel – Select TRACE, DEBUG, INFO, WARNING or ERROR.
- Enabled – Provides lip movement for voice lines that do not have the game’s own lip-sync animation, including custom and replaced lines.
- Mode = ADVANCED (default) – A small machine-learned model animates the entire lower face, including the jaw, lips, mouth corners and smile lines. The file
KCD2_SoundFramework_lipmodel.binmust be beside the INI. - Mode = BASIC – Uses the voice’s loudness and spectrum to create jaw and lip shapes. It also serves as the fallback if the model file is absent.
- OffsetMs – Shifts mouth movement earlier with a positive value or later with a negative value compared with the sound. Test values during play with
sfw_lipsync_offset <ms>in the console. - DubbedVoices = AUTO (default) – For voice dubs, the game displays English mouth animation when a voice language has none of its own. The lips then follow each line’s own voice, including in cutscenes, while smiles and frowns from the animation remain. ON always enables this behavior, and OFF always disables it.
- DialogueVoices / BarkVoices / CutsceneVoices – These settings control the loudness of conversations, barks, including calls, mutters, shouts and Henry’s thoughts, and cutscene lines in addition to the game’s sliders: 1 leaves them unchanged, 0.5 makes them half as loud, 0 silences them, and values can reach 4. Mod lines of each corresponding kind are affected as well. Pre-rendered cutscenes are videos with their own sound, so they are not affected.
- EventLog / SpeakLog – Mod authors can use these to log the game’s sound events and voice lines when looking for items to replace or reuse.
The default moods are stored in KCD2_SoundFramework_moods.ini. Updates replace this file, so change a mood by defining it again inside your own pack.
Console commands
Press ~ to open the console.
sfw_play <sound> [x y z]– Plays a pack sound at the supplied world position, or at the camera when no position is supplied.sfw_stop <sound>/sfw_stop_all– Stops one sound / stops every sound from the framework.sfw_say <entity> <line or voice path>– Makes an NPC speak a pack voice line, or play a recording.sfw_lipsync_offset <ms>– Shifts the mouth movement earlier or later.sfw_mood_override <mood> [pose:weight ...]/sfw_mood_dump <mood>– Tests mood values live / writes a mood to the log.sfw_reload/sfw_list– Reloads every pack / writes the catalog into the log.
Quick test
A pack is not needed for this test. Load a save, open the console, and have Henry speak lines belonging to other characters while using different moods:
sfw_say Dude Localization/dialog/trosecko/konecZabomysichValek/jmil_comb_bojovnici_ty_odporny_RkVq mood:angry strength:2 You disgusting, slimy, rotten piece of shit! sfw_say Dude Localization/dialog/open_world/lazne_a_lazebnice/aals_obje_lazebnice_sss__jeste_AjPM mood:happy Wonderful! You'll see, you'll be happy to come back here. sfw_say Dude Localization/dialog/open_world/crime_reaction_barks/mrtvola/mbis_npc__npc_vidi__promin_str_0DUg mood:sad I'm sorry, but I can't stand to be here any longer. sfw_say Dude Localization/dialog/kutnohorsko/pogrom/tsho_zena_pogrom_ob_na_pomoc_S0g7 mood:scared Somebody help us! sfw_say Dude Localization/dialog/open_world/lazne_a_lazebnice/aals_obje_lazebnice_ale_ty_uz__wAcW mood:surprised You're already undressed? That's a new one! sfw_say Dude Localization/dialog/trosecko/konecZabomysichValek/jmil_comb_bojovnici_olbramovi__xiB6 mood:disgusted Olbram's breath smells like a bull's arse! sfw_say Dude Localization/dialog/utils/roomrenting/lcar_zena_hospodska_to_pujde_z_8Lbz mood:smug Very well, but you'll have to pay in advance.
- Dude represents Henry. His face can be seen with a third-person camera mod.
- strength scales the mood from 0 to 2, with a default of 1. The words at the end provide the subtitle.
- None of the recordings includes the game’s lip-sync animation, and all of the voices belong to other characters. The framework therefore supplies the mouth movement, while the mood animates the whole face.
For mod authors
To create a sound pack, use a normal mod folder containing a SoundFramework folder. Every .ini file inside that folder is treated as a pack:
[mymod_bell] Files = bell_1.ogg, bell_2.ogg Bus = world Replaces = event:/animals/dog/dog_bark [mymod_guard_hello] Voice = Localization/dialog/mymod/mymd_hello_01 TextKey = mymd_hello_01 Speaker = soul_ui_name_guard Display = subtitle Mood = angry ReplacesVoice = zaty_strazny_z_*
The modding guide explains every key, the bus names, voice recordings and text tables, moods, and the process for locating the game’s event paths and line keys. Stop Right There, Criminal Scum provides a complete example pack.
Please mark Sound Framework as a requirement on your mod page.
Known limitations
- Voice recordings and text are stored in the mod’s paks, which the game reads only at startup, so changing them requires a restart. Pack INIs and loose sound files can reload while playing.
- Lines with Warhorse’s own lip-sync animation retain that animation. A mood then affects only the upper face.
- A game update may require a framework update if the framework can no longer locate the game code it hooks.
Troubleshooting
- Under , set LogLevel = DEBUG, save the INI, and reproduce the problem.
- Look beside the mod for
KCD2_SoundFramework.log. Problems in packs are recorded with their file and line. - When a mod’s sounds do not play, verify that it contains a SoundFramework folder with its INI, and confirm that the log lists the pack.
When reporting an issue, include the log, INI, game/mod versions and reproduction steps.
Advanced lip sync
Machine learning drives advanced lip sync. While you play, a small neural network with about 680,000 parameters, trained on Kingdom Come: Deliverance II’s own voice lines and facial animation, converts each voice line into mouth movement. It creates facial animation only, not audio, text or images. Choose Mode = BASIC to animate the mouth without machine learning.
The code uses the MIT license. KCD2_SoundFramework_lipmodel.bin derives from Kingdom Come: Deliverance II game data owned by Warhorse Studios and PLAION. That MIT license does not cover the file: use it only with KC:D 2 through this mod, and not in other games, other products or commercially.
