HedgeDocs - User contributions [en]

ACB Audio Injection

2025-09-02T22:07:04Z

Kwasior: Added an image of created ACB playing in foobar2000

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="
ACB Format/PC Ver.1.37.0 Build:
" 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="
ACB Format/PC Ver.1.37.0 Build:
" 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]]

File:ACB with injected audio.png

2025-09-02T22:04:41Z

Kwasior:

Modified ACB showing injected audio for Cyber Space 1-1

ACB Audio Injection

2025-09-02T21:56:03Z

Kwasior: Created the tutorial

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|515x515px|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="
ACB Format/PC Ver.1.37.0 Build:
" 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="
ACB Format/PC Ver.1.37.0 Build:
" 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|557x557px|<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.

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

File:ACB Injection Result.webm

2025-09-02T21:52:34Z

Kwasior:

Ingame footage of Cyber Space 1-1 with music changed thanks to ACB Injection

File:Bgm cyber awb in foobar.png

2025-09-02T21:15:44Z

Kwasior:

Cyber Space music archive playing in foobar2000

File:Bgm cyber acb in xml form.png

2025-09-02T20:32:55Z

Kwasior:

bgm_cyber.acb converted with cri_utf_tool and opened for viewing in notepad++

Creating custom uv-anims with KwasTools

2025-08-03T16:15:41Z

Kwasior: Added example XML files for both HE1 and HE2

{{Notice|type=info|content=This guide uses <i><b>he_anim_tool</b></i> from [https://hedgedocs.com/index.php/KwasTools_(Hedgehog_Engine) KwasTools] package.}}

== Brief description of the format ==
'''Uv-anims''' are used to animate textures inside of material files. The most common usage would be the animation of eyes in cutscenes.
{| class="wikitable"
|+Types of transformations
!Type
!Value
!HE1
!HE2
|-
|Position X
|0
|✔️
|✔️
|-
|Position Y
|1
|✔️
|✔️
|-
|Rotation
|2
|❌
|✔️
|-
|Scale X
|3
|❌
|✔️
|-
|Scale Y
|4
|❌
|✔️
|}
{| class="wikitable"
|+Types of interpolation
!Type
!Value
|-
|Linear
|0
|-
|Constant
|1
|}

== Differences between HE versions ==

=== Hedgehog Engine 1 ===

* Data version in the mirage header is set to <code>2</code>
* One uv-anim can animate only one texture in the material
* Only position animation is possible (types <code>0</code> and <code>1</code>)

=== Hedgehog Engine 2 ===

* Data version in the mirage header is set to 3
* Multiple textures animated in one uv-anim
* All transformation types available
* Assignment of one animation to multiple textures

== Example XML for HE1 ==
<syntaxhighlight lang="xml" line="1">
<UVAnimation data_version="2" material_name="sonic_example_mat" texture_name="sonic_example_mat-0000">
<Animation name="default" frame_rate="60" start_frame="0" end_frame="60">
<KeyframeSet type="0" flag2="0" interpolation="0" flag4="0">
<Keyframe index="0" value="0"/>
<Keyframe index="61" value="1"/>
</KeyframeSet>
</Animation>
</UVAnimation>
</syntaxhighlight>

== Example XML for HE2 ==
<syntaxhighlight lang="xml" line="1">
<UVAnimation data_version="3" material_name="sonic_example_mat" texture_name="none">
<Animation name="sonic_example_mat-0000/sonic_example_mat-0001" frame_rate="60" start_frame="0" end_frame="60">
<KeyframeSet type="0" flag2="0" interpolation="0" flag4="0">
<Keyframe index="0" value="0"/>
<Keyframe index="61" value="1"/>
</KeyframeSet>
</Animation>
</UVAnimation>
</syntaxhighlight>

Creating custom uv-anims with KwasTools

2025-08-03T15:51:47Z

Kwasior: Created the page and saved because my internet malfunctioned and I dont want to write it all over again

KwasTools (Hedgehog Engine)

2025-05-10T19:25:36Z

Kwasior: Wrote more so that the page isn't a stub. Also added informations related to recent development of KwasTools.

{{ToolInfobox|title=KwasTools|author=Kwasior|website=https://github.com/ThisKwasior/KwasTools}}
'''KwasTools''' is a set of utilities for several games. Notably it contains tools to view and edit Hedgehog Engine <code>*-anim</code> family of formats and CRIWARE formats. A [[wikipedia:Blender_(software)|Blender]] addon called '''[https://github.com/ThisKwasior/KwasTools/tree/master/addons/blender/io_kwastools io_kwastools]''' also exists for real-time preview and editing <code>.cam-anim</code> and <code>.uv-anim</code> files.

Entire suite of tools supports Windows and GNU/Linux operating systems.

== Software ==

=== he_anim_tool ===
[[File:KwasTools he anim tool usage.png|alt=he_anim_tool running without any arguments given to the program. By default, it prints supported file formats and how to use the software.|thumb|366x366px|Usage of <code>he_anim_tool</code>]] <code>he_anim_tool</code> is a tool for modifying animation files native to the Hedgehog Engine 1 and 2.

Any given <code>*-anim</code> will be converted to its XML representation. Same goes for XML files - tool will know the output format thanks to root element's name (XML identifier).

{| class="wikitable"
|+
Supported formats
!Format
!Description
!XML identifier
|-
|<code>.uv-anim</code>
|Translation (v2), rotation and scaling (v3) of a texture in the material
|<code>UVAnimation</code>
|-
|<code>.cam-anim</code>
|Full control of in-game camera during events
|<code>CAMAnimation</code>
|-
|<code>.vis-anim</code>
|Visibility of the mesh
|<code>VISAnimation</code>
|-
|<code>.morph-anim</code>
|Animation of shape keys (Sonic's mouth in Unleashed/Generations uses this to speak)
|<code>MORPHAnimation</code>
|-
|<code>.pt-anim</code>
|Texture swapping (Tokyo DLC in Shadow Generations uses this for the billboard)
|<code>PTAnimation</code>
|-
|<code>.mat-anim</code>
|Transformation of a material (like swapping Sonic's mouth left-to-right)
|<code>MATAnimation</code>
|-
|<code>.lit-anim</code>
|Companion to <code>.light</code> files. Can animate its fields.
|<code>LITAnimation</code>
|}

=== cri_awb_tool ===
Unpacker and packer for AWB audio archives. Does not support decrypting data (will extract contents as-is).

Extracts an AWB to a folder and writes an XML file with its metadata.

Creates an AWB from a folder of files (with default values) or from an XML descriptor.

=== cri_utf_tool ===
[[File:Example XML created by cri utf tool.png|alt=Converted bgm_miller.acb displayed in Notepad++ as an XML|left|thumb|385x385px|<code>bgm_miller.acb</code> converted to XML]]
Multi-purpose tool for editing CRIWARE <code>@UTF</code> tables. Created for modification of <code>.acb</code> files, but will work fine with tables from other formats, such as <code>.acf</code>, <code>.cpk</code>, <code>.aax</code>, <code>.usm</code> or <code>.csb</code>.

In addition to <code>@UTF</code>, program will also parse '''ACB commands''' (used for example for looping of '''Sonic Frontiers'''<nowiki/>' Titan songs) and embedded '''AWB files''' (which allows for modding music and sounds without shipping entire corresponding AWB file).

File:Example XML created by cri utf tool.png

2025-05-10T19:19:57Z

Kwasior:

Converted bgm_miller.acb being displayed in Notepad++ as an XML file

File:KwasTools he anim tool usage.png

2025-05-10T18:24:18Z

Kwasior:

Default output of he_anim_tool with no arguments given