Skip to content

Add a voice language, separate from the text language - #8054

Closed
caasi wants to merge 5 commits into
scp-fs2open:masterfrom
caasi:spike/zh-i18n
Closed

caasi wants to merge 5 commits into
scp-fs2open:masterfrom
caasi:spike/zh-i18n

Conversation

@caasi

@caasi caasi commented Nov 16, 2026

Copy link
Copy Markdown

Written by Claude Opus 5.5, with the implementation by Claude Fable 5.1 and Claude Opus 5.5. Claude Opus 5.5, Claude Sonnet 5.5 and Codex (gpt-6) reviewed the code. Claude Sonnet 5.5 checked this description against the diff. The project owner did the in-game tests.

What?

A voice language that is separate from the text language. A mod can ship voice files in more languages as <name>-<lang_ext>.<ogg|wav> next to <name>.<ogg|wav>, the naming that movie subtitles and fiction files already use. The player picks the voice language in the in-game options (Audio, Voice Language), and a mod can set a default. If the suffixed file does not exist, the game plays the original file. With nothing set, nothing changes.

Why?

Players do not all read and listen in the same language. The author of this PR wants to play with a Chinese voice. Other players read English or Chinese text and listen to a Japanese voice in other games. Today the voice follows the files as named, whatever the text language is, so the voice cannot be chosen apart from the text.

This PR comes from a Chinese voice mod in progress: Simplified and Traditional Chinese voices and translations for FreeSpace 2 (https://github.com/caasi/fs2-zh). With a voice language, those packs can ship next to each other. The author hopes that other packs follow: a Cantonese voice, a Japanese voice, or a voice pack that voice actors record in Chinese.

How?

Three sources set the voice language, in this order:

Source Values
-voice_language <value> on the command line a language name, same-as-text or original
The in-game option Audio.VoiceLanguage (only when the mod enables in-game options) Original voice, Same as text language, or a language
$Voice language: in game_settings.tbl (the mod default) a language name, same-as-text or original

If none of them is set, the voice files load as named, with no extra file-system access.

  • lcl_get_voice_lang_index() in localize.cpp is the one place that applies the order. lcl_get_voice_filename() makes the suffixed name, keeps a directory prefix, and searches with CF_TYPE_ANY, as the FFmpeg loader already opens every voice stream. To strip an extension it calls cf_strip_extension(), a new cfile function that cf_find_file_location_ext() now also uses, so the two cannot disagree about names such as x_1.5.
  • The load paths that use it: audiostream_open() for ASF_VOICE streams (briefings, command briefings, debriefings, fiction, red alert, loop briefs, and Lua openAudioStream with AUDIOSTREAM_VOICE), message_load_wave() for mission messages, and the training voice. The training voice resolves its file once. It streams a file of more than 100000 bytes through audiostream_open() with the new third parameter localize_voice = false, and loads a smaller file with snd_load().
  • debrief_choose_voice() and the convert-to-Command check count a file that exists only in the voice language as existing.
  • The option is the last one in the Audio category (importance(-1)), so it does not mix with the speech (TTS) options. With a valid -voice_language, the menu shows the flag value and disables the control.
  • A change in the menu applies to voice files that load after the change. Files that are already loaded keep their language. The option description says so. No restart is needed.
  • The player's choice is stored as the string original or same-as-text (the words of the command line and the table), or as {name, ext} for a language, as Game.Language is. A stored value that the mod does not know counts as "not chosen". An unknown -voice_language gives a warning in a debug build (Warning(), as for an unknown -lang), and the next source applies. An unknown $Voice language: is written to the log.
  • Four new XSTR ids, 1942 to 1945.

A mod can ship several languages of one family side by side, each with its own short extension, as the built-in German (gr), French (fr) and Polish (pl) do:

$Language: Chinese (TW)
+Extension: tw
+Special Character Index: 0

For mod authors

To ship a voice pack:

  1. Add the language in a language table with a file name of its own, for example data/tables/zh-tw-lcl.tbm. If two mods use the same table file name, the game reads only one of them, so only one of the languages appears.
  2. In the same table, list German (gr), French (fr) and Polish (pl) again if the mod must keep them. When a table defines a language, the engine does not add the built-in languages.
  3. Put each voice file next to the original, in the same voice folder, as <name>-<lang_ext>.ogg or .wav. For example, data/voice/briefing/TR1_MB_01-tw.ogg goes with TR1_MB_01.wav. A file that is not in the pack plays the original.
  4. Optional: set a mod default with $Voice language: in a game_settings.tbl or a *-mod.tbm table, in the #LOCALIZATION SETTINGS section.
  5. Optional: set $Enable in-game options: YES, so that players can choose the voice language in the options menu.

Limits:

  • <name>-<lang_ext>.ogg, with any directory part, must be at most 31 characters.
  • Supply every persona and Command variant that the original has. A variant file as named wins over the base file in the voice language.
  • Do not name a language original or same-as-text.
  • A voice line that is longer than the original can be cut by the next training message. $Don't pre-empt training message voice: YES in #LOCALIZATION SETTINGS makes the next message wait.

Testing?

  • 26 unit tests in test/src/localization/test_voice_language.cpp, data in test/test_data/voice_language/. They cover the order of the sources, the stored values, the fallback, the extension rule, the directory prefix and the name length limit. They test the helper functions, not the load paths, because the unit tests run with sound off. Full suite on Linux (Release, no Vulkan, no OpenXR): 375 tests, 374 passed, 1 skipped; the skipped test also skipped before this change.
  • Beyond the Red Line, mission MC-01, briefing voice MC-01-B01, checked with strace: with nothing set and with -voice_language original, the game opens MC-01-B01.ogg; with -voice_language Chinese and a test mod that defines Chinese with the extension cn, it opens MC-01-B01-cn.ogg.
  • Retail FreeSpace 2 (GOG) from Knossos.NET, mission Training-1.fs2, with two test mods that define Chinese (CN) (cn) and Chinese (TW) (tw), played in the game:
    • With both mods on, the Audio category lists both languages.
    • With either language, the command briefing and briefing voices (audiostream_open()) and the instructor voices (the training voice) play in that language.
    • The built-in messages Instructor Hit and Instructor Attack (message_load_wave()) have no file in the voice language in these mods, and they play the original English files.
    • A change of the voice language during the mission does not change the voice files that are already loaded.
  • Not tested in game: which branch of the training voice (stream a file of more than 100000 bytes, or load it) each instructor file used; a mission message with a file in the voice language; debriefing voices, persona voices and the convert-to-Command case.

Anything Else?

  • File name length: the sound code copies file names into char[MAX_FILENAME_LEN] buffers (32). So <name>-<lang_ext>.ogg, with any directory part, must be at most 31 characters: a base name of at most 24 characters with a two-letter extension. A longer name plays the original file and writes a line to the log.
  • A persona or Command file as named wins over the base file in the voice language. A voice pack therefore needs every persona and Command file that the original has. Comments in debrief_choose_voice() and the convert-to-Command check say so.
  • original and same-as-text are reserved words. A language with one of these names gets a warning (Warning(), in a debug build) when the language table is read.
  • localize.cpp now includes sound/audiostr.h for audio_ext_list.
  • The option is visible in every mod, as Game.Language is. In a mod without suffixed files, choosing a language plays the original files.
  • A Lua script that opens a voice stream gets the file of the voice language. The doc string of openAudioStream says so.
  • How the test voice packs were made: the Chinese voice files of fs2-zh are synthetic. The Simplified Chinese (cn) pack uses IndexTTS-2.5 with the retail lines as the reference. The Traditional Chinese (tw) pack uses BreezyVoice with Taiwan Mandarin reference voices from Mozilla Common Voice 27.0 zh-TW (CC0). The packs contain no retail files; the scripts read the retail data from the player's own copy.
  • This PR is mainly written by LLMs (see the note at the top), so please add the LLM-authored label.

caasi and others added 5 commits November 16, 2026 18:53
Players can now hear voice files in a language other than the text
language, for example Chinese text with English voice. A mod ships a
voice in another language as "<name>-<lang_ext>.<ogg|wav>" next to
"<name>", the same naming that movie subtitles and fiction files use.

The voice language comes from, in this order: the -voice_language flag,
the player's stored choice of the in-game option Audio.VoiceLanguage
(only when in-game options are on), $Voice language: in
game_settings.tbl, and else the original voice. Each source takes a
language name, "same-as-text" or "original". With nothing set, voice
files load as named, with no extra file-system access, for every text
language, so existing installs do not change. A stored player choice,
including "Same as text language" and "Original voice", wins over the
mod default; while the player has not chosen, the menu shows the mod
default. A stored value that the mod does not know counts as not
chosen.

lcl_get_voice_filename() resolves a name: it follows the cfile
extension rule (a dot starts an extension only when at least two
characters follow it, and only after the last directory separator),
keeps the directory prefix, falls back to the name as given when the
suffixed file does not exist or the name would not fit in
MAX_FILENAME_LEN, and leaves the name alone before lcl_init().
lcl_voice_file_exists() is the same check for a given folder type.

An unknown -voice_language value is reported by a Warning; an unknown
$Voice language: value is logged and gives the original voice.

The tests save and restore the global language list, so they do not
depend on the order in which tests run.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The voice load paths now ask the localization code which file to use:
audiostream_open() for ASF_VOICE streams (briefings, command briefings,
debriefings, fiction, red alert, loop briefs and Lua voice streams),
message_load_wave() for mission messages, and the training voice.

The training voice resolves its file once, so the size check and the
opened stream use the same file; it passes localize_voice = false to
audiostream_open() for the name it already resolved. The "none.wav"
sentinel is not localized, so a "none-<ext>" file can never play.

debrief_choose_voice() and the convert-to-Command check count a file
that exists only in the voice language as existing, so a mod can ship
voice files in one language only.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
cf_strip_extension() strips an extension the way
cf_find_file_location_ext() always did: after the last directory
separator, a dot starts an extension only when at least two characters
follow it, so that "x_1.5" keeps its ".5". cf_find_file_location_ext()
now calls it, and so does lcl_get_voice_filename(), which had a copy of
the rule. The cfile caller strips the directory first, so its result
does not change.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- The option is the last one in the Audio category (importance -1), so
  it does not mix with the speech (TTS) options, which share importance
  0. Its description says that voice files that are already loaded keep
  their language: a message wave loads the first time it plays, so a
  change during a mission applies to the messages that did not play yet.
- The stored value is "same-as-text", the word of -voice_language and
  $Voice language:, not "text".
- "original" and "same-as-text" are reserved: a language with one of
  these names gets a warning when the language table is read.
- A voice file name that is too long for MAX_FILENAME_LEN is logged
  before the fallback, and a failed message wave logs the name that was
  tried.
- The strings move to XSTR 1942-1945, because upstream master now uses
  1940 and 1941 (the Frame Profiler Overlay option).
- Comments say that a persona or Command file as named wins over the
  voice language, so a voice pack needs every variant file, and the Lua
  doc of openAudioStream says that voice streams use the voice language.
- Shorter comments, as upstream reviewers ask.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Six tests had their own game_settings.tbl only to set
$Voice language:. They now set Default_voice_language in the test.
ModDefault keeps its table, so that the parse of $Voice language:
stays covered. The stored value in the tests is now "same-as-text".

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@caasi caasi closed this Nov 16, 2026
@caasi
caasi deleted the spike/zh-i18n branch November 16, 2026 11:32
@caasi
caasi restored the spike/zh-i18n branch November 16, 2026 11:32
@caasi caasi reopened this Nov 16, 2026

@Goober5000 Goober5000 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This PR adds a lot of code to duplicate a feature that mostly already exists. Although the existing feature has a bug in it, which may be why your Claude didn't pick it up -- my Claude ignored it too until I told it specifically.

I'll patch the hole, check the design, and get back to you.

@NovachenFS2

Copy link
Copy Markdown
Contributor

That's interesting! I'm currently working on additional localization features for the next version of my translation library, with the goal of moving away from having to maintain several separate language packs.

Audio localization is definitely part of that. I've actually been considering a somewhat different approach, though: allowing the original voice VP files from the German, French, and Polish retail releases to be used as essentially drag-and-drop language packs, without having to rename any of the original files.

My idea is based on language-specific subfolders. When looking for a voice file, the engine would first check the corresponding language directory and fall back to the default language if the file isn't available there.

I vaguely remember something along these lines being discussed about 20 years ago, and I believe some of the groundwork might already exist in the code, although I haven't verified that yet.

I think this approach could also be useful for language-specific graphics. Instead of having to rename assets such as nameplates, the engine could simply load the appropriate localized version when available.

Of course, I haven't investigated the technical details too deeply yet. I originally planned to tackle this at a later stage, since there are still some more pressing issues with my translation library that need attention first. 😂

I thought I'd bring this up as a possible alternative to the proposed filename suffix approach, especially since it could provide a more general solution for localized assets beyond just voice files.

@caasi

caasi commented Nov 17, 2026

Copy link
Copy Markdown
Author

@Goober5000 Thank you. Let me check again. Maybe this PR is not needed at all.

@NovachenFS2 It will be awesome. Then I don't have to list German, French, and Polish in all voice mods.

@dustinspace217 dustinspace217 left a comment •

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I looked into the premise, since Goober's review says most of this already exists. This is from reading the code at af4c1a3 and master; I did not build or run it.

What the engine already has

  • A language-folder lookup. cfopen() still takes a localize argument (cfile.h:181). Until #4771 (November 2022) that argument made the file lookup try <folder>/<language ext>/<file> first and fall back to the plain file, through lcl_add_dir_to_path_with_filename() (localize.cpp:949). #4771 removed the lookup and left the argument ignored (cfile.cpp:640, bool /* localize */). I think that is the hole Goober means. The comments it left behind are still in cfilesystem.cpp (1404 and 1634).
  • Today only the font loader uses the folder helper, by calling it directly (FontManager.cpp:163).
  • Fiction files and movie subtitles use the <name>-<ext> suffix with a fallback, as the description says.

So the "find a file for a language, else fall back" half of this PR is a third copy of something the engine has in two forms, and the folder idea in NovachenFS2's comment is the old localize behavior.

What is new here

  • Choosing the voice language apart from the text language. The old lookup followed the text language, so by itself it cannot do that. That part of the premise holds.

A smaller shape, once the lookup is restored: keep the selector (the flag, the option and the table default) and have the voice load paths ask the folder lookup for the chosen language. That would drop the suffix scheme, lcl_get_voice_filename() and the new cf_strip_extension().

One code point if the suffix design stays (also from reading): a voice file with a dot in its name loses its voice. For x_1.5, the lookup returns x_1.5-tw.ogg; audiostream_open() strips .ogg (audiostr.cpp:1041), and the wave loader then calls cf_find_file_location_ext(), whose extension strip takes .5-tw as the extension and searches for x_1. The DottedNameKeepsAShortTail test covers the helper, not this path.

@Goober5000

Copy link
Copy Markdown
Contributor

@NovachenFS2 Yes, what you describe is what already exists. It was already implemented for fonts, and it is very simple to extend it to audio files. No mod reconfiguration needed; it follows the existing language settings.

The bug is that, subsequent to the feature to allow mod files to be stored in subfolders (#4771), language folders began to overlap each other. The fix keeps them distinct.

@Goober5000

Copy link
Copy Markdown
Contributor

Superseded by #8062.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants