#1597

tools: write stream names and dialogue subtitles into Ogg Opus tags

Opennikolas-sturmwants to merge intofrom

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.py fills that header in place:
    • TITLE = the stream name.
    • For a dialogue wave: LABEL, SPEAKER, SUBTITLE (English, or the first language with text) and SUBTITLE_<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. --source picks one source label from the names CSV.
  • What it rewrites: only page 1, which holds the OpusTags packet 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-run counts without writing.
  • Docs: a new Tags: names and subtitles section in docs/audio.md, plus a row in its exporter table, a pointer from docs/text.md and the docs/README.md row.

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-run and the CLI. test_awc_opus.py, test_tool_stdout_encoding.py, test_docs_links.py and compileall pass.
  • On the 1.0.2.1 package: awc_opus.py export of all 638 shared_minigame000.rpf banks and the first 3,000 story000.rpf banks (83,088 Ogg Opus files), tagged with the awc_names.py and text_tables.py outputs.
    • 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.rpf matches 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