Skip to content

Add opt-in mono AWC compaction and loading geometry inspection - #304

Open
ThomasTrovon wants to merge 1 commit into
Hancapo:mainfrom
ThomasTrovon:feat/awc-loading-geometry
Open

ThomasTrovon wants to merge 1 commit into
Hancapo:mainfrom
ThomasTrovon:feat/awc-loading-geometry

Conversation

@ThomasTrovon

Copy link
Copy Markdown
Contributor

Summary

This adds opt-in mono AWC compaction and a loading-geometry inspector. It does not change the default writer or impose a universal buffer limit.

  • build_awc_bytes(awc, compact_streams=True) keeps each mono stream's chunks together while preserving logical table order and payloads. Multichannel banks are rejected by this option.
  • inspect_loading_geometry(header, file_size, alignment=..., budget_bytes=...) reports stream spans and the explicit aligned_header + stream_span model. The caller must qualify the alignment, capacity and loading model. Missing budgets remain unknown; multichannel banks do not receive mono-budget verdicts.
  • compact_mono_payloads(data) relocates opaque mono chunks without decoding or recoding their contents. It checks table bounds but does not certify codec validity.
  • Synthetic tests cover preservation, idempotence, endian variants, already-compact encrypted mono banks, budget boundaries and invalid/truncated input.

Why

During investigation of a modified GTA V Enhanced dialogue bank, we needed to distinguish payload size from the physical span a loader reads. A compact bank plus selective recoding of two oversized entries passed the reported in-game dialogue test without stuttering or crashing.

Importantly, the default FiveFury writer already reproduces that successful artifact for this bank's encrypted mono layout. This is not evidence that the default FiveFury writer caused the crash. The new explicit option covers other mono layouts, while the inspector lets consumers validate the final artifact, including after incremental replacement.

The observed budget is not a universal AWC limit. Game-specific allocation policies and automatic recoding are intentionally outside this PR. No game audio, binaries, dumps or newly extracted keys are included.

Validation

  • Based on upstream b3e5c3b.
  • python -m pytest tests/audio/awc -q: 112 passed, 5 integration tests deselected on Windows/Python 3.12.
  • Native source is unchanged between the production 0.5.1 base and this upstream revision; the existing native extension was reused for these tests.
  • The production fork separately passed 167 AWC tests plus 87 audio-authoring/serialization tests. Its project-specific compatibility changes are not part of this PR.

Detailed evidence, limitations and Portuguese documentation are in AWC_LOADING_GEOMETRY.md. The manual game result qualifies the reported dialogue only, not every AWC bank or game version.

Estende build_awc_bytes com compact_streams sem alterar o comportamento padrão e rejeita o uso desse modo em bancos multicanal.

Inclui inspeção de spans físicos com alinhamento e orçamento explícitos e compactação de chunks opacos sem recodificar áudio. Orçamentos desconhecidos não são aprovados automaticamente.

Documenta evidências, limites e responsabilidade do consumidor; adiciona fixtures sintéticas para preservação, idempotência, endianness, limites de orçamento e tabelas inválidas. Validação na base oficial: 112 testes AWC aprovados e 5 testes de integração não selecionados.
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.

1 participant