ACB Audio Injection - Revision history

NextinHKRY: Formatting consistency changes

2025-09-06T12:21:49Z

Formatting consistency changes

← Older revision		Revision as of 12:21, 6 September 2025
Line 1:		Line 1:
	In this tutorial you will learn the basics of injecting audio (HCA, ADX) into CRIWARE's ACB files, it 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, in this tutorial we'll use [https://github.com/Thealexbarney/VGAudio VGAudioCli] and [https://notepad-plus-plus.org/ Notepad++]. You should also install [https://www.foobar2000.org/ foobar2000] with [https://vgmstream.org/ vgmstream component] for easy preview of audio, and it will also be useful to pinpoint file indices in the AWB archive.		In this tutorial you will learn the basics of injecting audio (<code>HCA</code>, <code>ADX</code>) into CRIWARE's <code>ACB</code> files, it helps to cut down the size of mods by not shipping the entire <code>ACB</code> + <code>AWB</code>. 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 <code>HCA</code> audio converter and a text editor, in this tutorial we'll use [https://github.com/Thealexbarney/VGAudio VGAudioCli] and [https://notepad-plus-plus.org/ Notepad++]. You should also install [https://www.foobar2000.org/ foobar2000] with [https://vgmstream.org/ vgmstream component] for easy preview of audio, and it will also be useful to pinpoint file indices in the <code>AWB</code> archive.

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

NextinHKRY: Wording and spacing changes

2025-09-06T12:20:42Z

Wording and spacing changes

← Older revision		Revision as of 12:20, 6 September 2025
Line 1:		Line 1:
	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.		In this tutorial you will learn the basics of injecting audio (HCA, ADX) into CRIWARE's ACB files, it 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, in this tutorial we'll use [https://github.com/Thealexbarney/VGAudio VGAudioCli] and [https://notepad-plus-plus.org/ Notepad++]. You should also install [https://www.foobar2000.org/ foobar2000] with [https://vgmstream.org/ vgmstream component] for easy preview of audio, and it will also be useful to pinpoint file indices in the AWB archive.

	~~The tutorial will be using <code>cri_utf_tool</code> from [[KwasTools (Hedgehog Engine)\|KwasTools]] for ACB conversion to and from XML.~~		For this tutorial, we will be replacing Cyber Space 1-1's music in [[Sonic Frontiers]].

	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 ACB to XML ==
	Converting the <code>ACB</code> is as easy as drag and dropping it on the <code>cri_utf_tool</code> executable.		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>.[[File:Bgm cyber acb in xml form.png\|center\|638x638px\|XML opened in a text editor\|alt=XML opened in a text editor\|thumb]]

	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 ==		== 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.		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.
			{{Notice\|type=warn\|content=Keep in mind that parameters need to match the external AWB's, otherwise the game will crash!}}<syntaxhighlight lang="xml" line="1">
	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">		<AWB version="2" offset_size="4" id_size="2" alignment="32" subkey="0">
	<entry id="0" path="audio.hca"/>		<entry id="0" path="audio.hca"/>
	</AWB>		</AWB>
	</syntaxhighlight>~~Keep in mind that parameters need to match the external AWB's. Game will crash otherwise.~~		</syntaxhighlight>

	=== Inserting the internal AWB structure ===		=== 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">		Search for <code><record value="" name="AwbFile"/></code> and you should find this:<syntaxhighlight lang="xml" line="1" start="5456">
Line 45:		Line 34:

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

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

	=== Explanation of parameters ===		=== 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.		<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:

	Streaming is more interesting, it has three available options:
	{\| class="wikitable"		{\| class="wikitable"
	\|+Streaming values		\|+Streaming values
Line 70:		Line 55:

	=== Getting AWB IDs we want to replace ===		=== 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.		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 the 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.]]		[[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.		So our IDs are <code>0</code> for main track and <code>1</code> for boost. With that we can finally proceed.
Line 106:		Line 91:

	== Converting the XML to ACB ==		== 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.		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. The <code>ACB</code> we created should be playable in foobar2000 and will only show the audio files we injected into it.[[File:ACB with injected audio.png\|center\|thumb\|660x660px\|Resulting <code>ACB</code> playing in foobar2000]]

	~~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 ==		== Result ==
	[[File:ACB Injection Result.webm\|center\|thumb\|Result of ACB Injection\|0x0px]]		[[File:ACB Injection Result.webm\|center\|thumb\|Result of ACB Injection\|0x0px]]

Kwasior: Added an image of created ACB playing in foobar2000

2025-09-02T22:07:04Z

Added an image of created ACB playing in foobar2000

← Older revision		Revision as of 22:07, 2 September 2025
Line 13:		Line 13:

	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>.		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]]		[[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 ==		== Creating an internal AWB file ==
Line 71:		Line 71:
	=== Getting AWB IDs we want to replace ===		=== 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.		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.]]		[[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.		So our IDs are <code>0</code> for main track and <code>1</code> for boost. With that we can finally proceed.

Line 107:		Line 107:
	== Converting the XML to ACB ==		== 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.		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 ==		== Result ==
	[[File:ACB Injection Result.webm\|center\|thumb\|Result of ACB Injection]]		[[File:ACB Injection Result.webm\|center\|thumb\|Result of ACB Injection\|0x0px]]

Kwasior: Created the tutorial

2025-09-02T21:56:03Z

Created the tutorial

New page

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]]