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)
Custom sounds and voices with lip sync for Kingdom Come: Deliverance II mods. Sound Framework lets mods add sounds and voice lines without writing code, using an INI file in the mod’s SoundFramework folder.
Features
- Sounds: Play a pack’s files on the game’s buses, including world, voice and music, or the game’s own sound events at a new pitch and volume, in 3D or flat, with volume and pitch variation, loops, cooldowns and instance limits.
- Sound replacement: Play a pack sound in place of a game sound event or on top of it, everywhere or for chosen characters and animals, at its start or at a later moment such as a bow’s release.
- Voice lines: NPCs speak a pack’s lines through the game’s own speech system, with a bottom subtitle and speaker name, a chat bubble, or both.
- Voice replacement: Play a pack line instead of a game voice line, by exact key or by pattern.
- Volume: Separate volume settings for conversation, bark and cutscene voices, and packs that make chosen game sounds quieter or louder.
- Lip sync: A pack’s lines move the speaker’s mouth, with a small model that learned from the game’s own animation or from the loudness of the voice. Any line without mouth animation gets it too, from mods or the game, and so do the speakers in mods’ own cutscenes and every game line of a voice dub without mouth animation of its own.
- Moods: Facial expressions held while a line plays, with eleven defaults that packs can change or add to.
- Live reload: Saving a pack or the settings INI applies it while you play.
- Every problem in a pack is logged with its file and line. Debug options log the game’s sound events and voice lines.
- Open-source, built on the DetourModKit modding framework.
Specifications
- Kingdom Come: Deliverance II on PC, built around Steam 1.5.6.
- Advanced lip sync uses a small neural network with about 680,000 parameters.
- Advanced lip sync is trained on Kingdom Come: Deliverance II’s own voice lines and facial animation.
- strength scales the mood from 0 to 2, with a default of 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
The framework comes in two builds in the Files tab. Install one of them, not both. If both are installed, the second one to load stays off and says so in its log.
Option A: ASI build
Open your KC:D 2 installation folder, then open the Bin/Win64MasterMaster… subfolder that contains WHGame.dll. On Steam this is:
<KC:D 2 installation folder>/Bin/Win64MasterMasterSteamPGO/
Other stores use their own Bin/Win64MasterMaster… folder; use WHGame.dll to identify the correct one.
Step 1: Install an ASI loader. If you already have a working ASI loader for KC:D 2, skip this step. Download one x64 variant of Ultimate ASI Loader by ThirteenAG and extract its DLL beside WHGame.dll:
- Usual choice if dinput8.dll is unused.
- Alternative when dinput8.dll is already used.
- Another alternative if version.dll is also used or does not load.
KCSE also loads .asi files beside its dinput8.dll, so KCSE users need no separate loader. Do not overwrite a DLL belonging to another mod.
Step 2: Install the mod. Extract the archive directly into the same folder, beside WHGame.dll, without an extra archive-named subfolder:
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)
On Wine/Proton, add an override for your loader in Steam’s Properties -> Launch Options:
WINEDLLOVERRIDES="dinput8=n,b" %command%
Use version=n,b or winmm=n,b instead when using that loader name.
Option B: KCSE build
Install KCSE, then install the KCSE archive with your mod manager, or extract it into your Mods folder, creating it if it is missing:
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 Sound Framework Fixes file in the Files tab fixes the game’s own sound bugs. It works with or without the framework: install it with your mod manager, or extract it into your Mods folder.
- Longsword draw and sheathe sounds no longer go silent after a fight with an NPC that uses a wooden or blunt weapon.
Verification and updates
Load a save, then open KCD2_SoundFramework.log beside the mod’s DLL or ASI. It lists every sound pack the framework found and any problem in them.
When updating, back up your customized INI before extracting the new archive, then reapply your settings to the supplied INI.
Configuration
Open KCD2_SoundFramework.ini beside the mod with a text editor such as Notepad. Save the file to apply changes while playing; only Enabled needs a restart.
- LogLevel – TRACE, DEBUG, INFO, WARNING or ERROR.
- Enabled – Lip movement for voice lines without the game’s own lip-sync animation, such as custom and replaced lines.
- Mode = ADVANCED (default) – A small machine-learned model moves the whole lower face: jaw, lips, mouth corners and smile lines. It needs
KCD2_SoundFramework_lipmodel.binbeside the INI. - Mode = BASIC – Jaw and lip shapes from the voice’s loudness and spectrum. This mode is also the fallback when the model file is missing.
- OffsetMs – Moves the mouth earlier (positive) or later (negative) than the sound. Try values live with
sfw_lipsync_offset <ms>in the console. - DubbedVoices = AUTO (default) – Voice dubs: the game shows English mouth animation for a voice language without its own. The lips then follow each line’s own voice, in cutscenes too, and the animation’s smiles and frowns stay. ON always does this, OFF never.
- DialogueVoices / BarkVoices / CutsceneVoices – How loud conversations, barks, including calls, mutters, shouts and Henry’s thoughts, and cutscene lines play, on top of the game’s sliders: 1 unchanged, 0.5 half, 0 silent, up to 4. Mods’ lines of each kind follow too. Pre-rendered cutscenes are videos with their own sound and are not affected.
- EventLog / SpeakLog – For mod authors: log the game’s sound events and voice lines, to find what to replace or reuse.
KCD2_SoundFramework_moods.ini holds the default moods. It is replaced on update; change a mood by defining it again in your own pack.
Console commands
Open the console with ~.
sfw_play <sound> [x y z]– Plays a pack sound at a world position, or at the camera.sfw_stop <sound>/sfw_stop_all– Stops a sound / every framework sound.sfw_say <entity> <line or voice path>– An NPC says a pack voice line, or speaks a recording.sfw_lipsync_offset <ms>– Moves the mouth earlier or later.sfw_mood_override <mood> [pose:weight ...]/sfw_mood_dump <mood>– Tries mood values live / writes a mood to the log.sfw_reload/sfw_list– Reads every pack again / writes the catalog to the log.
Quick test
No pack needed. Load a save, open the console and make Henry say other characters’ lines in 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 is Henry. A third-person camera mod shows his face.
- strength scales the mood from 0 to 2, with a default of 1. The text at the end is the subtitle.
- None of these recordings has the game’s lip-sync animation, and the voices are other characters’, so the mouth movement is the framework’s lip sync and the mood moves the whole face.
For mod authors
A sound pack is an ordinary mod folder with a SoundFramework folder inside; every .ini file in it is 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 covers every key, the bus names, voice recordings and text tables, moods, and how to find the game’s event paths and line keys. Stop Right There, Criminal Scum is a complete example pack.
Please list Sound Framework as a requirement on your mod page.
Known limitations
- Voice recordings and text live in the mod’s paks, which the game reads only at startup; changing them needs a restart. Pack INIs and loose sound files reload live.
- Game lines that have Warhorse’s own lip-sync animation keep it: a mood then moves only the upper face.
- Game updates may require a mod update if the framework stops finding the game code it hooks.
Troubleshooting
- Set LogLevel = DEBUG under , save the INI and reproduce the problem.
- Check
KCD2_SoundFramework.logbeside the mod. Pack problems are listed with their file and line. - If a mod’s sounds don’t play, check that the mod has a SoundFramework folder with its INI and that the log lists the pack.
Report issues with the log, INI, game/mod versions and reproduction steps.
Advanced lip sync
Advanced lip sync is machine-learned. A small neural network, with about 680,000 parameters, trained on Kingdom Come: Deliverance II’s own voice lines and facial animation, turns each voice line into mouth movement while you play. It generates facial animation only: no audio, text or images. Set Mode = BASIC for the mouth without machine learning.
The code is MIT licensed. KCD2_SoundFramework_lipmodel.bin is derived from Kingdom Come: Deliverance II game data owned by Warhorse Studios and PLAION. The MIT license does not cover it: use it only with KC:D 2 through this mod, and not in other games, other products or commercially.
