View source for ACB Audio Injection

In this tutorial you will learn the basics of injecting audio (HCA, ADX) into CRIWARE's ACB files. Helps to cut down the size of mods by not shipping the entire ACB+AWB.

The tutorial will be using <code>cri_utf_tool</code> from [[KwasTools (Hedgehog Engine)|KwasTools]] for ACB conversion to and from XML.

Additional software will be required, such as the HCA audio converter and a text editor. I will be using [https://github.com/Thealexbarney/VGAudio VGAudioCli] and [https://notepad-plus-plus.org/ Notepad++]. 

I also recommend installing [https://www.foobar2000.org/ foobar2000] with [https://vgmstream.org/ vgmstream component] for easy preview of audio. Will also help with pinpointing file indices in AWB archive.

For this tutorial, I will be replacing Cyber Space 1-1 music in [[Sonic Frontiers]].

== Converting the ACB to XML ==
Converting the <code>ACB</code> is as easy as drag and dropping it on the <code>cri_utf_tool</code> executable.

If conversion was successful, it'll create an XML file in the same directory as the <code>ACB</code>. For me it created <code>bgm_cyber.acb.xml</code>.
[[File:Bgm cyber acb in xml form.png|center|638x638px|XML opened in a text editor|alt=XML opened in a text editor|thumb]]

== Creating an internal AWB file ==
Some <code>ACB</code>s do not have an internal <code>AWB</code> file, which is required to store audio we want to use. This is the case with <code>bgm_cyber</code>, it lacks one and we need to create it.

The XML structure of <code>AWB</code> file is the same as one from <code>cri_awb_tool</code>. However, I will include a minimal example for Sonic Frontiers below to keep things straightforward.<syntaxhighlight lang="xml" line="1">
<AWB version="2" offset_size="4" id_size="2" alignment="32" subkey="0">
    <entry id="0" path="audio.hca"/>
</AWB>
</syntaxhighlight>Keep in mind that parameters need to match the external AWB's. Game will crash otherwise.

=== Inserting the internal AWB structure ===
Search for <code><record value="" name="AwbFile"/></code> and you should find this:<syntaxhighlight lang="xml" line="1" start="5456">
<record value="" name="AutoModulationTable"/>
<record value="" name="StreamAwbTocWorkOld"/>
<record value="" name="AwbFile"/>
<record value="&#10;ACB Format/PC Ver.1.37.0 Build:&#10;" name="VersionString"/>
<record value="" name="CueLimitWorkTable"/>
</syntaxhighlight>We need to replace the <code>AwbFile</code> record with our own <code>AWB</code> structure. 

After changes you should get something like this:<syntaxhighlight lang="xml" line="1" start="5456">
<record value="" name="AutoModulationTable"/>
<record value="" name="StreamAwbTocWorkOld"/>
<AWB version="2" offset_size="4" id_size="2" alignment="32" subkey="0">
    <entry id="0" path="my_audio.hca"/>
    <entry id="1" path="my_audio_boost.hca"/>
</AWB>
<record value="&#10;ACB Format/PC Ver.1.37.0 Build:&#10;" name="VersionString"/>
<record value="" name="CueLimitWorkTable"/>
</syntaxhighlight>ID starts at 0 and goes up. Paths are relative to XML's location.

== Modifying Waveform data ==
Next, we need to change data in the <code>Waveform</code> table for each track we want to replace.

In short, we have to change the <code>MemoryAwbId</code> and <code>Streaming</code> values.

=== Explanation of parameters ===
<code>MemoryAwbId</code> is the index in the internal <code>AWB</code> file. In our case, index <code>0</code> is the main track and index <code>1</code> is the boost version.

Streaming is more interesting, it has three available options:
{| class="wikitable"
|+Streaming values
!Value
!Description
|-
|0
|Audio is streamed from internal <code>AWB</code> file, which resides in RAM
|-
|1
|Audio is streamed from external <code>AWB</code> file
|-
|2
|Short snippet of audio in internal <code>AWB</code> file to initialize the decoder, rest of the audio is streamed from external <code>AWB</code> file
|}
What we're looking for is the value of <code>0</code> - streaming from internal <code>AWB</code>.

=== Getting AWB IDs we want to replace ===
Cyber Space 1-1 stage name is <code>w6d01</code>. Opening <code>bgm_cyber.awb</code> in foobar2000 reveals that first two tracks are what we're looking for. However, foobar2000 lists all item indexes starting from <code>1</code>, so we need to subtract <code>1</code> from desired index.
[[File:Bgm cyber awb in foobar.png|center|thumb|642x642px|<code>bgm_cyber.awb</code> playing in foobar2000, with Cyber Space 1-1 audio tracks selected.]]
So our IDs are <code>0</code> for main track and <code>1</code> for boost. With that we can finally proceed.

=== Modifying the parameters ===
Quick and easy way of finding a correct Waveform is searching for a string <code><record value="0" name="StreamAwbId"/></code>, where <code>value</code> is the external <code>AWB</code> track ID.<syntaxhighlight lang="xml" line="1" start="812">
<row>
    <record value="65535" name="MemoryAwbId"/>
    <record value="2" name="EncodeType"/>
    <record value="1" name="Streaming"/>
    <record value="2" name="NumChannels"/>
    <record value="2" name="LoopFlag"/>
    <record value="48000" name="SamplingRate"/>
    <record value="4999086" name="NumSamples"/>
    <record value="8" name="ExtensionData"/>
    <record value="0" name="StreamAwbPortNo"/>
    <record value="0" name="StreamAwbId"/>
    <record value="65535" name="LipMorthIndex"/>
</row>
</syntaxhighlight>Waveform data for track <code>0</code>. After modifications (that is, changing <code>MemoryAwbId</code> and <code>Streaming</code> value) we get the following:<syntaxhighlight lang="xml" line="1" start="812">
<row>
    <record value="0" name="MemoryAwbId"/>
    <record value="2" name="EncodeType"/>
    <record value="0" name="Streaming"/>
    <record value="2" name="NumChannels"/>
    <record value="2" name="LoopFlag"/>
    <record value="48000" name="SamplingRate"/>
    <record value="4999086" name="NumSamples"/>
    <record value="8" name="ExtensionData"/>
    <record value="0" name="StreamAwbPortNo"/>
    <record value="0" name="StreamAwbId"/>
    <record value="65535" name="LipMorthIndex"/>
</row>
</syntaxhighlight>After repeating the process for the boost track, we can now finally convert back to <code>ACB</code> and check results ingame.

== Converting the XML to ACB ==
Same as before, drag and drop the XML on the <code>cri_utf_tool</code>. It should output a big <code>ACB</code> file that's ready to be copied into a mod.

Created <code>ACB</code> is playable in foobar2000 and will only show audio files we injected into it.
[[File:ACB with injected audio.png|center|thumb|660x660px|Resulting <code>ACB</code> playing in foobar2000]]

== Result ==
[[File:ACB Injection Result.webm|center|thumb|Result of ACB Injection|0x0px]]