Modding Musics/OST

Want to add your own music or any custom sound file into ZPS? This guide is especially for you!

Introduction

After ZPS version 3.0.9a, Zombie Panic! Source's audio engine is now powered by the famous middleware FMOD Studio.

FMOD Studio exists in 2 flavours: the "Studio" and "Low Level API" one. We've implemented the last one because we're still using Source's classic audio engine, however it's way more easier for you to mod the audio. No need to deal with FMOD Sound Banks (FSB) files or have FMOD Studio installed.

Keep in mind that this guide concerns ZPS's audio engine itself. This guide doesn't concern ambient sounds (for mappers: "ambient_generic") and sound scapes.

Adding/Replacing Files

The new system no longer relies on a hardcoded playlist and will scan directories each time the game is started. Making your life easier to add your custom music in Zombie Panic! Source.

Adding Custom Musics

Just copy or move your MP3 files in the "zps_custom\sound\music\<Type>" folder, where "<Type>" is one of the following:

• game = In-game music/OST (gameplay).
  
• menu = Mainmenu music.

Keep the file names simple! Don't use weird characters! Zombie Panic! Source will automatically add your music into the playlist when you start the game.


Adding a new in-game music is just that simple!

Replace an Existing Music

It's the same principle as adding it, the only difference is that the file's name matter.

Let's say you want to replace the existing Zombie Panic! Theme by something else, you would just need to rename your custom music's file to "zp_themesong.mp3".
The game will then do the rest when you start it, the custom file will take priority over the original game music.


Replacing the ZPS theme with another custom music.

OST Title and the MP3 Player HUD

Note: if the music is gonna be streamed through the Internet or used in a map (like Frozenheart's clock ticking music and Zomboeing's plane boarding music), you can skip this section.

Before Zombie Panic! Source v3.0.9a update, the music titles had to be specified in the hardcoded list. This caused huge problems when modding musics as that list had to be modified manually and could easily cause conflicts.

To fix this problem, we added ID3v1 tag parsing in the game. If you don't know what ID3 is, it's a set of norms (or standards if you prefer) for media information. Media players in PCs like Windows Media Player, VLC and even embedded media players in cars, pocket MP3 players and such parse those tags to tell you what is the music's title, artist, album, genre...


ID3 tags allow software such as Windows Media Player to show the music's title, artist, album...

If your music(s) show up as "Unknown", or as "UUUUUUUUUUUUU" or the "unknown ASCII character (interrogation mark in a diamond)". You'll need to do some changes in the ID3 tags. You can use a free program called Mp3tag[www.mp3tag.de] for this purpose.

Important notice about ID3 tags version

You must use the v1 version of the tags (ID3v1)! We haven't added ID3v2 parsing (yet). If you are using Mp3tag, go to it's settings, go to the "Tags" category and select the "Mpeg" sub-category. Make sure that only ID3v1 data is written and deletion set to everything but ID3v1.


Mp3tag's ideal configuration for ZPS

Fixing it

Open the file in Mp3tag, if there are ID3v2 tags, delete them. If you followed the notice above, it won't delete ID3v1 tags if existent.

If the "Title" field is empty on the left, then write it and press the "Save" button.


Here's an exemple of how it looks like in Mp3tag, notice the "Tag" column only has "ID3v1 (ID3v1)"

Start the game, create a local server and use the previous/next track keys until your music is playing, check if ZPS show correctly the title (the MP3 player always show up when the scoreboard is enabled).

Playing Musics from the Internet

One of the great features that we added by community request is FMOD Studio Low Level API's network streaming capability in order to play musics from Internet. This section is gonna explain everything about it.

Important

In order for this feature to work, players must enable the "Allow musics from network (HTTP/HTTPS)" option, which is disabled by default.
This option is located in "Options" -> "Zombie Panic!" -> "Custom content" tab.

If players forget and/or don't do that, then any attempt at playing a network stream will be blocked (a warning will be shown in the console).

Restrictions and How to use this feature

Playing from the Internet has more restrictions than playing from storage, here's a non-exhaustive list of them:

• Only the HTTP and HTTPS protocols are supported, other protocols such as FTP will cause a "File not found" error.
  
• Some formats might not work through network - best to use MP3 if you can (OGG seems to work as well but not tested).
  
• The stream's current position, length and title cannot be automatically detected especially in scenarios like radios/live podcasts. The MP3 player HUD's progress bar will always show empty and the server operator will have to specify the title and duration of the stream if there is one in order to have the system play the next music when the current one is done.

To use this feature, a custom Angelscript server plugin or SourceMod plugin is required.

Angelscript

You can just call the "PlayNetworkedStream" function on the "CHL2MP_Player" class. Here's how the function looks:

void PlayNetworkedStream( const string& in szURL, const string& in szTitle, int iDuration );

Parameters:

• szURL = The complete URL to the file like "http://foo.bar/file.mp3".
  
• szTitle = The title to show in the MP3 player HUD.
  
• iDuration = The duration of the stream in milliseconds if there is one, pass "0" if and only if the duration is infinite (radios for example).

SourceMod

If for some reason Angelscript is not an option, you can use the "PlayNetworkedStream" user message, the parameters and it's type are identical to Angelscript's counterpart.

Workshop Note

When making maps that rely on custom music and making "music mods" that are gonna be published in the Workshop, there is one important rule to respect when it comes to packaging/publishing:

Do not package the music in VPK files!

FMOD Studio by itself is NOT able to access VPK files. If you try to do so, you will get a "File not found" error whenever the concerned music(s) is (are) gonna be used. This is why we shipped all musics as loose files instead of inside the ZPS's sounds VPKs.

Any questions or issues, leave a comment below.

[Shepard]

It's the same principle as publishing a map to the Steam Workshop, check the appropriate section in this guide .

[Quarante-Cinq]

i know it, i make it, i test and it's work but my question is "How to publish this in the ZPS's Workshop ?"

[Shepard]

Same principle as replacing an in-game/main menu music except that the path changes, taking the exemple of "Now Boarding", it's somewhere inside the "zpo_zomboeing" folder.

[Quarante-Cinq]

How to publish in workshop a sound/music who replace officials musics like "Time coming to a crawl" or "Now boarding" ?