Merc Voice Control

Modify existing mercenary voice lines with full control over the frequency and style of the sound bytes used. Import custom lines and maintain settings via csv file. Supports the import of data (voice and text) for any language.

Features:
– set the frequency of each specific mercenary voice response
– import custom voice over lines via csv file (opus audio format required)
– easily update and control the voice responses for all mercs (including IMPs)
– optional "Conversation" mode dialog for custom voice over events
– multi language support (defaults to English, but supports any)

[[ Detailed Instructions ]]

:: VOICE CONFIGURATIONS ::

Once the mod is enabled, view and manage the voice configuration settings in the "Merc Voice Control" section of the mod options menu:

Main Menu -> Options -> Mod Options

Select "[Global]" to apply settings for all mercenaries or select and individual mercenary by name.

Each voice response is categorised. Select the response category first and then the voice response type.

If you have selected an individual mercenary you can also select a specific voice over line (instance).

With the selections made, adjust the voice frequency bar according to the preferred setting. Each voice instance defaults to a frequency value of 100, which represents the normal behaviour of voice lines in the base game. Setting the frequency to zero for a specific response / line will prevent it from being spoken in game. This can be useful if you are finding some of the voice acting repetitive.

Setting a voice frequency between 0 and 100 will effectively give that voice over a percentage chance of being played. When the game would normally voice that line a check will be made against the percentage. The higher the frequency value, the more likely the voice line will be used.

For example: you can mute the move order acknowledgments for all mercenaries by setting the "Mercenary" drop down to "[Global]" and then applying a frequency of 0 for the "Basic Orders" -> "Combat Move Order" reponse and the "Basic Orders" -> "Order (Out of Combat)" response (for in combat and exploration orders, respectively).

Once the settings have been applied they will be saved to the following file:

%APPDATA%Jagged Alliance 3ModsMerc Voice Controlvoice_settings.csv

:: UPDATING VOICE_SETTINGS FILE ::

The voice_settings.csv can also be manually updated (instead of via the mod options menu).

The file should be comma separated and contain the following fields (with a header line):

MercId: the name of the mercenary or IMP
ResponseId: the identifier of the response type (see all_respIds.txt for the full list)
InstanceId: the index of the voice over line (1 .. n)
Frequency: the frequency value (0 .. 100)
GlobalFlag: whether or not the voice over line should use the "[Global]" frequency setting
CustomId: the unique identifier for a custom voice over line (see below)
Params: any other additional parameters (optional, usually left blank)

:: CREATING CUSTOM AUDIO LINES ::

Custom audio lines can be added to any mercenary via the voice_settings.csv file. A new line should be added for each custom voice over.

An example of a custom audio line for Steroid can be found in the "Custom Voice Setting" archive (in the optional files section on NexusMods). This archive should be extracted to the %APPDATA%Jagged Alliance 3ModsMerc Voice Control folder:
https://www.nexusmods.com/jaggedalliance3/mods/196?tab=files&file_id=741

Each custom voice over consists of three elements:

1) an entry in the voice_settings.csv file
2) the audio file for the voice over (which should be in the opus format – see below)
3) an entry in the localisation_custom_<language> file (eg. localisation_custom_English.csv)

Audio files should be located here:
%APPDATA%Jagged Alliance 3ModsMerc Voice Control<language>Voices
Localisation files should be located here:
%APPDATA%Jagged Alliance 3ModsMerc Voice ControlLocal

:: OPUS AUDIO FILE FORMAT ::

Jagged Alliance 3 uses the opus audio format. Standard wave (.wav) files can be converted to the opus file format using the open source opus encoder tool kit available here: https://opus-codec.org/downloads/

The following command line should be used to convert .wav files in to the correct .opus file format for JA3:

opusenc.exe –bitrate 160 –serial 0 [input_filename].wav [output_filename].opus

It is also recommend to use a tool like Audacity to ensure the wave forms peak at a level of approximately 5db to normalise them at the similar volume level as the game.

**IMPORTANT** custom audio files should be named using a 12 digit id that starts with 500000 (eg. 500000000002.opus). This is a requirement for the Mercenary Voice Control mod and the filename used should also be the id reference in the localisation file, as well as the CustomId field in the voice_setting.csv file.

The Steroid example in the "Custom Voice Setting" archive (available in the optional files section on NexusMods) demonstrates the correct way the audio file should be named and referenced.

:: REPLACING VOICE OVER LINES ::

Once custom voice over lines have been added to the voice_setting.csv file, the original voice over lines (for a specific response type) can be disabled by setting their frequency values to zero. Note: it is important to retain the original indexing via the InstanceId field in the settings file. If the mercenary has 3 voice over lines for a specific response type the custom voice over line should use the next slot, that is an InstanceId (index) of 4.

:: ADDITIONAL PARAMETERS ::

The "conv" parameter can be defined in the voice_settings.csv file to enable a "Conversation" voice event (instead of the standard voice over). This will display the (custom) voice over in a "full screen" dialog (similar to those seen during standard conversations in Jagged Alliance 3). This feature was added to version 1.02 and is currently an experimental feature. All feedback welcome.

:: MULTI LANGUAGE SUPPORT ::

Localisation files should be added to the following folder:
%APPDATA%Jagged Alliance 3ModsMerc Voice ControlLocal

The file should be csv file with the following name format:
localisation_custom_<language>.csv (eg. localisation_custom_English.csv)

Audio files for each language can also be organised as follows:
%APPDATA%Jagged Alliance 3ModsMerc Voice Control<language>Voices

The language identifiers supported in Jagged Alliance 3 are:

Brazilian
Bulgarian
Czech
Danish
Dutch
English
Finnish
French
German
Hungarian
Indonesian
Italian
Japanese
Koreana
Norwegian
Polish
Russian
Schinese (simplified Chinese)
Spanish
Latam (Latin American Spanish)
Tchinese (traditional Chinese)
Thai
Turkish