Nikita488's ZSND script Tutorial

[Generic Unit]

Hey there. I thought I'd write a tutorial for using nikita's ZSND script since there isn't one out yet. I haven't fully utilized most of it's features so I can only give somewhat of a small run down of what I know so far. Hopefully this guide will give newer folks an understanding how to use this tool. And it's pretty easy!

What you will be using in this tutorial:

ZSND Tool - By nikita488 - Also comes with his adpcm.py script to extract PC sounds.
Sample Sounds - Contains clean versions of Wolverine's sounds from X-Men Legends 2 that we'll be working with.
Notepad++ Recommended to have the latest version as it can open json, py and any texting-based files. But mainly .json as the file we're extracting is in that format.
ZSM Editor v2.3 by Winstrol - You can scroll down the resource page to find it. You'll need it for converting sound commands to hashes in order for it to be read through the game,
Audacity: To edit many types of sound files
Command Prompt: located on your desktop's system files.
Python - You might need install this FIRST to get Nikita's ZSND script working in command prompt. I forgot to mention this! :runaway: - Edited 2/24/2022

Extract the files you downloaded above. With everything in place, let's begin.

Section1: Setting up your command prompt

Spoiler

When running nikita's ZSND using command prompt, it can be annoying for having to set up the desire location on where command prompt can locate the ZSND.py script to run it (at least for me it was). So if you're having trouble, here's what I did to run the program easier, and save you some time:

Step 1: In your windows tab at the bottom left of your desktop search for "command prompt" in your search bar (I use windows 10 so it may be different for others). Right-click on command prompt and open it's file location.

Step 2: Your desktop window will open. If the window opens up and it gives you a shortcut version of command prompt right-click on the shortcut and open it's file location again, and it should directly lead you to the system files where command prompt's main application is located and the cursor will immediately highlight it.

Step 3: Now copy THAT cmd and paste it in the same folder where you extracted your ZSND files. It should look like this:

With ZSND set-up, you're ready to move on to the next section

Section 2: Commands

Spoiler

Here's an important set of commands you'll need to know when decompiling or compiling a sound file whether its in zss or zsm format (.ens and .enm for ps2). All you have to do is copy a line below in red (with your appropriate name of sound file you're decompiling/compiling) and paste it in cmd and hit enter it will perform its script.

Decompiling powersounds, environmental sounds, etc.:
zsnd.py -d soundname_m.zsm out_file.json
Decompiling character voices:
zsnd.py -d soundname_v.zss out_file.json
Decompiling ambient sounds:
zsnd.py -d soundname_a.zss out_file.json
Decompiling BGM:
zsnd.py -d soundname_c.zss out_file.json

Compiling powersounds:
zsnd.py out_file.json NewSoundName_m.zsm
Compiling character voices:
zsnd.py out_file.json NewSoundName_v.zss
Compiling ambient sounds:
zsnd.py out_file.json NewSoundName_a.zss
Compiling BGM:
zsnd.py out_file.json NewSoundName_c.zss

With that covered, let's move on.

Section 2a: Extracting the sound file

Spoiler

Step 1:
We'll be working with XML 2 Wolverine's clean power sounds in this tutorial. If you downloaded the Sample Sounds.zip from the link above, open the .zip file with your desired file extractor program and grab your sound file from the appropriate game platform, and extract it into the same folder as your ZSND tool. Also extract the Wolverine_MvC3_sample_grunt.wav

Step 2:
In your ZSND tool folder, run cmd and the window will open. Remember the command lines from above? Open notepad++ and create a new text file in there. Copy the appropriate line from above (since we're working with powersounds, you'll want the one that has .zsm extension), and paste it into notepad++.

Step 3:
Rename the line into zsnd.py -d wolv_m.zsm out_file.json. Copy the text and paste it into cmd, hit enter. ZSND.py will now work it's magic in decompiling the .zsm file. Remember, if you're working with PS2 version of the sound, the line should be zsnd.py -d wolv_m.enm out_file.json. Close cmd and inside your zsnd folder, you'll now have a few new things created: A "__pycache__" folder, "out_file" folder, and "out_file.json" file. You don't need to worry about the "__pycache__" folder. It's there after decoding PC sounds and be able to edit them on a simple sound program like Audacity.

And with that, moving on to Section 3.

Section 3: The out_file's structure.

Spoiler

The out_file.json that was extracted is like a configurator. It's what holds the information that's needed for command prompt to use it with ZSND.py and compile the necessary files back into the desired sound file. With notepad++ installed, let's open it shall we?

This is how the out_file maintains the .zsm. The entire structure lists what platform the sound operates on, it's hashes, and samples. The images below are example of wolverine's PC sounds we just decompiled.

Top section (Hashes):
Below is the section that lists the set of hashes directing to the samples in the .zsm. Since we're working with power sounds, the structure isn't as large as if we were working with something like the X_Voice. If you scroll down some more in the out_file, you'll eventually find the sample section

Click to enlarge


Bottom section (Samples in the .zsm):
This part of the out_file is what records the sample files that exists in the .zsm. The sections may appear different depending on the platform the sound operates for. In order for you to tell the out_file to include a new .wav file into your .zsm when compiling, you'll need to set up a new entry in the "Sample" section and it's .wav name. We'll cover that in the Section 4: Setting Up Your Sounds

Click to enlarge


The images below will serve as a reference table on how each line is set up.

Sounds Section (Hashes):

So, what does the sample_index mean? Notice how it refers to "0" for Wolverine's CLAW_IN hash? Sample_Index refers how sounds are arranged in the "out_file" folder. For example, if you go inside the out_file and set view the folder in "details", your samples will be arranged in a list. The link below will provide better explanation:

https://i.imgur.com/8SFnc9W.png

Sample Section:

Sample Section (Consoles):
Consoles slightly differ compared to PC and X-Box's. You'll notice when decompiling GCN/Wii, and PS2 sounds, samples appear as numbers in the "out_file" folder. This isn't an error with the script, it's how consoles reference their sound samples within every .zss and zsm file. So it's harder to tell which sample plays what appropriate sound you're looking for. But, a nice trick to it is if you happen to have the ZSM editor program, and a PC or X-box version of a sound file you're working with, you can easily import the non-console .zsm / .zss into that program and find your reference there since all XML, XML2. and MUA have their samples organized in the same manner.

However, this doesn't quite mean there's an advantage with PC sounds being named. When ZSND decompiles PC / X-box sounds, your desktop may organize everything in the out_file in alphabetical order. So it might mess up your sample_indexes to play the wrong file if you are attempting to work with large file like the X_Voice. I highly recommend sticking to ZSM Editor for doing Non-Console sounds and only use ZSND for compiling new samples into a .zsm / .zss and then injecting them over through ZSM Editor.

Entries
See the highlight area in the image below? That's how an entry is constructed. And notice how the entry below the highlighted one doesn't have a comma after the end bracket? That's to define it is last entry in the section because you're not adding anymore to the list. When placing in new sounds, if you accidentally leave a comma on the last entry, there's no need to worry because the nikita's zsnd.py script will will tell you there's an error and the exact line it is at when compiling the .zsm file in cmd.

Hopefully this helped! It's time to move on to modding in your sound.

Section 4 is found in the next post

[Generic Unit]

Section 4: Setting Up Your Sounds

From here on, we'll be branching out based which platform you're working with. Each tutorial is written in the same manner, but have little differences because of having to use the appropriate sound program to edit the samples, and setting them up in the out_file. View any of the spoilers below for your preferred platform.

PC and X-Box

Spoiler

Step 1:
We're going to be adding in one of Wolverine's grunts from Marvel Vs. Capcom 3 and setting it as one of his samples when he jumps. Place the Wolverine_MvC_sample_grunt into the "out_file" folder and rename it into a name that will make it appear at the bottom of the list. z.wav for example

Step 2:

Open the z.wav in audacity. When the wav loads, and you'll see that the track is in stereo. We want to make sure that it's in mono, otherwise, the sound will not play properly if you simply add it into the game in stereo. Now on the top of the window, go to tracks > mix > mix stereo down to mono and click it.



Your track should merge into one. If the sample rate at the bottom left is not 22050, make sure to change it to that. Then File > Export Audio and export it as .wav format. (Or overwrite the z.wav in the out_file.)

Step 3:
Open up your out_file.json text with notepad++ (if you accidentally closed it) and scroll down to the bottom of the hash section make an empty space after the last entry. (I would move my cursor to the beginning of Line 149 and hit enter. If the box bracket "]" at the end moves forward, just go to edit --> undo, and it would move the "]" back into position.)


Step 4:
Highlight the entry above the space you just made from lines 144 to 148, and copy it. Paste it into beginning of the empty space you just made. Back in entry 28, place a comma at the end of that entry's bracket.

Step 5:
Rename the new sample_index to 29, and then go into ZSM editor and head to "Tools > Text To Hash". We're going to now set up a hash for wolverine's jump so it can be played. Since he has many hashes that directs to his jump, the new grunt noise we're adding will be played randomly. The hash set to play a sound randomly would be: CHAR/WOLV_M/JUMP/***RANDOM***/3 because it would be the 4th random grunt in the that set. The image below will show you an example on how it decodes words into hashes.

Once your hash has been decoded, copy the entire number set and head back to sample_index 29's entry and replace the hash 189597991 with 89576867



Alternatively, Nikita's ZSND script also accepts the exact hash coding inside the out_file. So you can simply place in CHAR/WOLV_M/JUMP/***RANDOM***/3 into the "hash": section of the entry, and when it compiles, it automatically decodes it to proper numbers. But if you do that, you'll have to make sure to include the quotation marks before and after so it should like look like this: "hash": "CHAR/WOLV_M/JUMP/***RANDOM***/3".

Step 6:
Go down to the Sample Section and do the exact same thing you did in step 4 by making an additional empty space after the throw.wav's entry. Again, if the end "]" moves forward when you make an empty space, just go "edit > undo" and it should revert its position. Don't forget to place a comma at the end of the throw.wav's bracket.

Step 7:
Copy the entire throw.wav's entry and paste it into the empty space. Rename the second "throw.wav" into "z.wav". The reason we must to do this is because if we don't include another entry that directs to our new sample we placed in the folder, ZSND will not compile our new file into the .zsm


Step 8:
Save the out_file.json. Run "cmd" and wait for it to open. Remember the commands for compiling power sounds in section 2a? Copy zsnd.py out_file.json wolv_m_NEW.zsm and paste it into cmd and hit enter. We're naming it wolv_m_NEW.zsm because when it ZSND compiles the files, it doesn't overwrite the clean one we're working with, but rather, creates a new .zsm file.

Step 9:
In ZSM Editor, open the new wolv_m.zsm we just compiled. When the files load, scroll down to the z.wav in the "files"  tab (and not "file"). Rename z.wav into jump4.wav just so you know what it is. You can arrange it in the list as well so your .zsm file is organized, but this is optional because it will take some time having to set all your samples in order. Save it and select the format as PC.

Step 10:
Place rename the new file into wolv_m.zsm and place it inside the proper directory where wolverine's sounds are stored. Make sure you back up the clean existing one in there because we're just testing this new one. With everything done, boot up your X-Men Legends PC with Wolverine deployed to the team

Step 11:
Go to a map that allows you to jump. If the correct sound plays, then you've successfully modded in a sound using nikita's ZSND script! It will play quietly because we didn't amplify the volume of it in Audacity to play louder. But keep in mind to make sure your sample has an appropriate volume so it can be heard in game. Good luck modding!

X-Box sounds:

If you're an X-Box user, all you should need to do is open the completed .zsm file you compiled with ZSM Editor, and File > Save it in X-Box format, and vise-versa to PC.

One last reminder:
I highly recommend remaining with ZSM Editor for doing PC and X-Box sounds. Only use ZSND for compiling new samples into a .zsm / .zss file and then injecting them over through ZSM Editor to keep your hashes and samples organized.

For PS2 and PSP

Spoiler

You've chosen the PS2 route, so you'll need to install this program to open .vag files that the PS2 files run on. According to nikita on one of his Discord posts, it was recommended not to share the encoders outside of discord. I've only uploaded a portion for PS2 purposes so you can edit .vag samples, and save files in that format.

Step 1:
We're going to be adding in one of Wolverine's grunts from Marvel Vs. Capcom 3 and setting it as one of his samples when he jumps. Open the Wolverine_MvC_sample_grunt in audacity. When the wav loads, and you'll see that the track is in stereo. We want to make sure that it's in mono, otherwise, the sound will not play properly if you simply add it into the game in stereo. Now on the top of the window, go to tracks > mix > mix stereo down to mono and click it.



Your track should merge into one. If the sample rate at the bottom left is not 11025, make sure to change it to that because that's what PS2 sounds run on (as according in the out_file.json). Then File > Export Audio and export it as .wav format. You can overwrite the grunt.wav you edited or you can save a new file. Now you're finished with Audacity here. You can exit the program. 

Step 2:
Inside the FPacker.zip you downloaded from the mini link before step 1, extract the files onto where you can find it on your desktop. When done, navigate through its folders and inside GUI folder, you'll find the FPacker application. Click it to run it.

Step 3:
You'll be in a program with not many features. But this is what we'll be using to export sound files into .vag files. Go to File > Open > Audio File. When searching for the .wav file you made in audacity, click on the drop tab and set it the Files of Type to .wav. Wolverine's grunt .wav should appear. Open it and the features will appear like an old sound editor.



Then all you gotta do is File > Save As, Set the file type to save as PS2 .VAG file (.VAG). and save it inside the out_file. Depending on the amount of samples that exists in the out_file, the name of your new sample will be given the next number in the list. So, Wolverine has 28.vag samples in his default sound set. You'll be saving it as 29.vag .
Remember: If you forgot to change the sound's sample rate to 11025, you should be able to do that by going to VAG options > set sample rate > enter 11025 in the box and hit enter. It will change the it and you can save it again.
And you're done on this part.

Step 4:
Open up your out_file.json text with notepad++ (if you accidentally closed it) and scroll down to the bottom of the hash section make an empty space after the last entry. (I would move my cursor to the beginning of Line 149 and hit enter. If the box bracket "]" at the end moves forward, just go to edit --> undo, and it would move the "]" back into position.)


Step 5:
Highlight the entry above the space you just made from lines 144 to 148, and copy it. Paste it into beginning of the empty space you just made. Back in entry 28, place a comma at the end of that entry's bracket.

Step 6:
Rename the new sample_index to 29, and then go into ZSM editor and head to "Tools > Text To Hash". We're going to now set up a hash for wolverine's jump so it can be played. Since he has many hashes that directs to his jump, the new grunt noise we're adding will be played randomly. The hash set to play a sound randomly would be: CHAR/WOLV_M/JUMP/***RANDOM***/3 because it would be the 4th random grunt in the that set. The image below will show you an example on how it decodes words into hashes.

Once your hash has been decoded, copy the entire number set and head back to sample_index 29's entry and replace the hash 189597991 with 89576867



Alternatively, Nikita's ZSND script also accepts the exact hash coding inside the out_file. So you can simply place in CHAR/WOLV_M/JUMP/***RANDOM***/3 into the "hash": section of the entry, and when it compiles, it automatically decodes it to proper numbers. But if you do that, you'll have to make sure to include the quotation marks before and after so it should like look like this: "hash": "CHAR/WOLV_M/JUMP/***RANDOM***/3".

Step 7:
Go down to the Sample Section and do the exact same thing you did in step 4 by making an additional empty space after the throw.wav's entry. Again, if the end "]" moves forward when you make an empty space, just go "edit > undo" and it should revert its position. Don't forget to place a comma at the end of the throw.wav's bracket.

Step 8:
Copy the entire 28.vag entry and paste it into the empty space. Rename the second "28.vag" into "29.vag". The reason we must to do this is because if we don't include another entry that directs to our new sample we placed in the folder, ZSND will not compile our new file into the .enm.



Step 9:
Save the out_file.json. Run "cmd" and wait for it to open. Remember the commands for compiling power sounds in section 2a? Copy zsnd.py out_file.json wolv_m_NEW.enm and paste it into cmd and hit enter. We're naming it wolv_m_NEW.enm because when it ZSND compiles the files, it doesn't overwrite the clean one we're working with, but rather, creates a new .enm file.

Step 11:
If you already have an extracted a PS2 iso where its directories are somewhere on your desktop, you can drop the wolv_m_NEW into sounds > eng > w> o and place it in there. Back up the current wolv_m.enm because you don't to overwrite that and rename the wolv_m_new.enm into the CURRENT wolv_m.enm. If you haven't extracted your PS2 iso of XML II, there should be tutorials around here on how to do that.

Step 12:
Once you've got everything set up and your new sound placed in, rebuild your ps2 ISO with your preferred program. Ex: like ImgBurn. When your new iso has been created, test it with your PS2 emulator.

Step 13:
Go to a map that allows your character to jump. If the correct sound plays, then you've successfully modded in a sound using nikita's ZSND script! It will play quietly because we didn't amplify the volume of it in Audacity to play louder. But keep in mind to make sure your sample has an appropriate volume so it can be heard in game. Good luck with modding!

For Gamecube & Wii

Spoiler

Both Wii and gamecube run their sound files on .DSP formats. Thankfully, a somone on GBAtemp made a modified version of Audacity that's able to edit .DSP files You can get the program at the bottom of the post on his thread here: Once you've downloaded it, we'll begin the tutorial.

This program is a bit buggy too and will often close itself entirely if you are closing multiple windows of this Audacity when they're all running. So be very cautious and save your work frequently!

Step 0:
Before you proceed to editing sounds, you want to run the audacity you just downloaded. In the program, we're going to set some default preferences so this makes it easier to optimize the sounds for the gamecube and Wii's quality.. Go under edit > preferences and make sure your default set up looks like the image below:



22050hz and 16 bit rate pcm are what game cube and wii run on. It will help making the quality play appropriate for their platforms. With that taken care of, the next time you open any .wav file, it should automatically optimize them so the work is taken care of for you.

Step 1:
We're going to be adding in one of Wolverine's grunts from Marvel Vs. Capcom 3 and setting it as one of his samples when he jumps. Open the Wolverine_MvC_sample_grunt When the wav loads, and you'll see that the track is in stereo. We want to make sure that it's in mono, otherwise, the sound will not play properly if you simply add it into the game in stereo. Now on the top of the window, go to tracks > mix > mix stereo down to mono and click it.



Your track should merge into one. If the sample rate at the bottom left is not 22050, make sure to change it to that. Then File > Export Audio and set the file type as .dsp format (Nintendo Gamecube DSPADPCM (.dsp). Save it inside the out_file folder where the rest of Wolverine's sound samples are. Depending on the amount of samples that exists in the out_file, the name of your new sample will be given the next number on the list. So, Wolverine has 28.dsp samples in his default sound set. You'll be saving it as 29.dsp .

Step 4:
Open up your out_file.json text with notepad++ (if you accidentally closed it) and scroll down to the bottom of the hash section make an empty space after the last entry. (I would move my cursor to the beginning of Line 149 and hit enter. If the box bracket "]" at the end moves forward, just go to edit --> undo, and it would move the "]" back into position.)


Step 5:
Highlight the entry above the space you just made from lines 144 to 148, and copy it. Paste it into beginning of the empty space you just made. Back in entry 28, place a comma at the end of that entry's bracket.

Step 6:
Rename the new sample_index to 29, and then go into ZSM editor and head to "Tools > Text To Hash". We're going to now set up a hash for wolverine's jump so it can be played. Since he has many hashes that directs to his jump, the new grunt noise we're adding will be played randomly. The hash set to play a sound randomly would be: CHAR/WOLV_M/JUMP/***RANDOM***/3 because it would be the 4th random grunt in the that set. The image below will show you an example on how it decodes words into hashes.

Once your hash has been decoded, copy the entire number set and head back to sample_index 29's entry and replace the hash 189597991 with 89576867



Alternatively, Nikita's ZSND script also accepts the exact hash coding inside the out_file. So you can simply place in CHAR/WOLV_M/JUMP/***RANDOM***/3 into the "hash": section of the entry, and when it compiles, it automatically decodes it to proper numbers. But if you do that, you'll have to make sure to include the quotation marks before and after so it should like look like this: "hash": "CHAR/WOLV_M/JUMP/***RANDOM***/3".

Step 7:
Go down to the Sample Section and do the exact same thing you did in step 4 by making an additional empty space after the throw.wav's entry. Again, if the end "]" moves forward when you make an empty space, just go "edit > undo" and it should revert its position. Don't forget to place a comma at the end of the throw.wav's bracket.

Step 8:
Copy the entire 28.dsp entry and paste it into the empty space. Rename the second "28.dsp" into "29.dsp". The reason we must to do this is because if we don't include another entry that directs to our new sample we placed in the folder, ZSND will not compile our new file into the .zsm



Step 9:
Save the out_file.json. Run "cmd" and wait for it to open. Remember the commands for compiling power sounds in section 2a? Copy zsnd.py out_file.json wolv_m_NEW.zsm and paste it into cmd and hit enter. We're naming it wolv_m_NEW.zsm because when it ZSND compiles the files, it doesn't overwrite the clean one we're working with, but rather, creates a new .zsm file.

Step 11:
If you already extracted your gamecube iso from one of my tutorials, you can drop the wolv_m_NEW.zsm into sounds > eng > w> o. Back up the current wolv_m.zsm because you don't to overwrite that and rename the wolv_m_new.zsm into the CURRENT one. If you haven't extracted your gamecube iso of XML II, follow section 1 of my guide here: To rebuild, scroll down to Section 2 for Installing Character Mods and jump to Step 14: It will give you a run down on how to rebuild your Gamecube ISO.

Step 12:
Once you've got everything set up and your new sound placed in, rebuild your Gamecube ISO with GC Rebuilder, and boot up XML 2 in Dolphin Emulator.

Step 13:
Go to a map that allows your character to jump. If the correct sound plays, then you've successfully modded in a sound using nikita's ZSND script! It will play quietly because we didn't amplify the volume of it in Audacity to play louder. But keep in mind to make sure your sample has an appropriate volume so it can be heard in game. Good luck modding!

[Nicaras]

That's amazing, Lags! Just about what we needed, a guide on this new software!

I'll point to your tutorial at the beginning of mine as an alternative (and probably a preferable one, due to the quality results) so people can choose the method and the software that suit them best. I hope I can learn from it soon!