#1597
tools: write stream names and dialogue subtitles into Ogg Opus tags
Claimed in the coordination issue as: https://github.com/ItsNotRexed/Leonida/issues/1380#issuecomment-7079170297
What and why
awc_opus.py writes an empty OpusTags header, so a player shows each export only as <stream id>.ogg. The names (awc_names.py) and dialogue subtitles (text_tables.py --dialogue) are now on main, but they stay in CSVs next to the audio.
tools/opus_tags.pyfills that header in place:TITLE= the stream name.- For a dialogue wave:
LABEL,SPEAKER,SUBTITLE(English, or the first language with text) andSUBTITLE_<LANG>for each language with text. - Subtitle
~...~markup becomes a space, and empty values are left out.
- Matching: a file is matched by stream id (its file name) and bank (its folder below the Opus folder, or that path with leading folders removed). One Opus folder can therefore hold several archives' exports.
--sourcepicks one source label from the names CSV. - What it rewrites: only page 1, which holds the
OpusTagspacket alone. Audio pages, page sequence and granule positions are untouched.- A second run replaces the first run's tags, and unnamed streams are left alone.
- A tags packet larger than one page (65,024 bytes) is skipped and counted.
--dry-runcounts without writing.
- Docs: a new Tags: names and subtitles section in
docs/audio.md, plus a row in its exporter table, a pointer fromdocs/text.mdand thedocs/README.mdrow.
Tested
CPU only, Linux, Python 3.14.
python -I tests/test_opus_tags.py: 8 synthetic tests. They cover packet layout, markup removal, the page swap (other pages byte-identical, CRCs valid), the refusal cases, names plus dialogue, a second run,--dry-runand the CLI.test_awc_opus.py,test_tool_stdout_encoding.py,test_docs_links.pyandcompileallpass.- On the 1.0.2.1 package:
awc_opus.pyexport of all 638shared_minigame000.rpfbanks and the first 3,000story000.rpfbanks (83,088 Ogg Opus files), tagged with theawc_names.pyandtext_tables.pyoutputs.- 45,311 files tagged, exactly the names CSV rows for those banks. 1,980 are dialogue lines and 1,703 have a subtitle.
- A fresh export of
shared_minigame000.rpfmatches the tagged files on every page except page 1 (4,315 of 4,315). - ffprobe lists the comments, and ffmpeg decodes a sample of 8,299 tagged files with no errors.
- The whole run takes about 4 s.
Checklist
- No game data, keys or decryption (CONTRIBUTING.md), including in logs or reports quoted here.
- A new translator rule is in the contract table of
docs/design.md, with how it was confirmed. (n/a: no translator change)
🤖 Generated with Claude Code