Repository navigation
Conversation
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>
Goober5000
left a comment
There was a problem hiding this comment.
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.
|
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. |
|
@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. |
There was a problem hiding this comment.
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 alocalizeargument (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, throughlcl_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.
|
@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. |
|
Superseded by #8062. |
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:
-voice_language <value>on the command linesame-as-textororiginalAudio.VoiceLanguage(only when the mod enables in-game options)$Voice language:ingame_settings.tbl(the mod default)same-as-textororiginalIf none of them is set, the voice files load as named, with no extra file-system access.
lcl_get_voice_lang_index()inlocalize.cppis the one place that applies the order.lcl_get_voice_filename()makes the suffixed name, keeps a directory prefix, and searches withCF_TYPE_ANY, as the FFmpeg loader already opens every voice stream. To strip an extension it callscf_strip_extension(), a new cfile function thatcf_find_file_location_ext()now also uses, so the two cannot disagree about names such asx_1.5.audiostream_open()forASF_VOICEstreams (briefings, command briefings, debriefings, fiction, red alert, loop briefs, and LuaopenAudioStreamwithAUDIOSTREAM_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 throughaudiostream_open()with the new third parameterlocalize_voice = false, and loads a smaller file withsnd_load().debrief_choose_voice()and the convert-to-Command check count a file that exists only in the voice language as existing.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.originalorsame-as-text(the words of the command line and the table), or as{name, ext}for a language, asGame.Languageis. A stored value that the mod does not know counts as "not chosen". An unknown-voice_languagegives 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.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:For mod authors
To ship a voice pack:
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.German(gr),French(fr) andPolish(pl) again if the mod must keep them. When a table defines a language, the engine does not add the built-in languages.<name>-<lang_ext>.oggor.wav. For example,data/voice/briefing/TR1_MB_01-tw.ogggoes withTR1_MB_01.wav. A file that is not in the pack plays the original.$Voice language:in agame_settings.tblor a*-mod.tbmtable, in the#LOCALIZATION SETTINGSsection.$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.originalorsame-as-text.$Don't pre-empt training message voice: YESin#LOCALIZATION SETTINGSmakes the next message wait.Testing?
test/src/localization/test_voice_language.cpp, data intest/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.MC-01-B01, checked with strace: with nothing set and with-voice_language original, the game opensMC-01-B01.ogg; with-voice_language Chineseand a test mod that defines Chinese with the extensioncn, it opensMC-01-B01-cn.ogg.Training-1.fs2, with two test mods that defineChinese (CN)(cn) andChinese (TW)(tw), played in the game:audiostream_open()) and the instructor voices (the training voice) play in that language.Instructor HitandInstructor Attack(message_load_wave()) have no file in the voice language in these mods, and they play the original English files.Anything Else?
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.debrief_choose_voice()and the convert-to-Command check say so.originalandsame-as-textare reserved words. A language with one of these names gets a warning (Warning(), in a debug build) when the language table is read.localize.cppnow includessound/audiostr.hforaudio_ext_list.Game.Languageis. In a mod without suffixed files, choosing a language plays the original files.openAudioStreamsays so.fs2-zhare 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.LLM-authoredlabel.