v20.1 Marin's Enhanced Jukebox 2022-05-22

Please note: this plugin was commissioned by @DerxwnaKapsyla. As such, I will likely not provide any support or updates in the future.

Enhanced Jukebox

This plugin re-imagines the Jukebox in a way that gives players access to all the Ogg Vorbis audio files used by the game, at least as long as the developer chooses to expose those files to the player. Furthermore, it lets the developers specify where the track is used, where it came from, who made it, what it's used for, and even write a description about the track in general. All this information is stored in the metadata of the Ogg Vorbis file, so you keep all the information in one place.

Note that this jukebox only supports the Ogg Vorbis format as per the conditions of the original commission.

Here are some screenshots to show you how it looks:






Oh yeah, and a bunch of the text can scroll horizontally too. That's pretty cool.

Usage

The jukebox integrates seamlessly into your project by overwriting the jukebox that is called from the pokegear, so no additional setup or modification is required there.

This plugin requires my Scripting Utilities to function.

Install the following script:
v19: Marin's Enhanced Jukebox
v20: Marin's Enhanced Jukebox

There are several constants at the top of the EnhancedJukebox.rb file that can be used to tweak how the system works or looks.

As mentioned, all the information on tracks is stored in the metadata of the Ogg Vorbis files. Below is a quick definition of all the available metadata tags, their format, and what they do. Please note that all these metadata tags are optional, only intended to enrich the user experience of the jukebox. You do not need to include all of these tags, although when using this resource this does make your jukebox feel more personal, unique and special.

• DONOTSHOW: If this tag is set to TRUE, then this file will be completely hidden from view.
• SONGTYPE: This is the category of the track. If left blank, the file will appear above all other categories. When this field is not blank, a new category will be shown in the list of audio with this track and all other tracks with the same SONGTYPE value.
• TITLE: This value represents the name of the track. If not set, the filename will be shown instead.
• ARTIST: This value represents the artists who worked on this track. Multiple ARTIST entries can exist in the metadata, and each entry will be shown with a separate bullet point if this is the case.
• ALBUM: This value represents the album this track is a part of.
• SOURCE: This value represents the origin of this track, e.g. the game or show it came from. Multiple SOURCE entries can exist in the metadata, and each entry will be shown with a separate bullet point if this is the case.
• COMMENTS: This value represents any developer notes that you may want to leave on a track, such as a fun fact or reasoning for why this particular track or usage.
• LOCATIONS: This value is a list of locations separated with commas, where each location is shown with a separate bullet point. This list of comma-separated locations can be very simple (e.g. LOCATIONS=Map One,Map Two,Map Three, but it is also possible to specify simple conditions that must be true for one of these locations to be shown. For instance, if I only want to display that this track is used on Map Three if switch 100 is ON, I would change the format to LOCATIONS=Map One,Map Two,Map Three|SWITCH|100|TRUE. Aside from this Map Name|SWITCH|SwitchId|Value condition, you can also use Map Name|VARIABLE|VariableId|Value where the variable must be greater than or equal to the given value, or you can use Map Name|AREA|MapId where you must have visited the map with the id specified for the map name to show up in the list of locations.

Furthermore, this jukebox also entertains a concept of a "spoiler". As you could see in the second screenshot above, one of the tracks is named "??????". This jukebox system contains 3 different metadata tags which allow you to set under which conditions a track would be considered a spoiler, and when it is fine to show it to the user. This way, you can warn the user in advance if they are about to play a track that would spoil something or someone later in the game. The metadata tags that facilitate this behaviour are:

• SHOWIFSWITCH: This tag contains a list of comma-separated switch conditions in the format SHOWIFSWITCH=1|TRUE,2|TRUE,3|TRUE. As a shortcut for X|TRUE, you may also write simply "X", which will check that the switch is true automatically. As such, we can rewrite our condition to SHOWIFSWITCH=1,2,3.
  Now, a track will be considered a spoiler if this tag exists but none of the conditions are met. That is, if you include this tag with this particular value in a track, it will be treated as a spoiler unless switch 1, 2, or 3 is ON. As long as at least one of the conditions in this list is met, the track will not be seen as a spoiler.
• SHOWIFVARIABLE: This tag contains a list of comma-separated variable conditions in the format SHOWIFVARIABLE=1|30,2|50,3|70. This means that global variable 1 must be >= 30, OR global variable 2 must be >= 50, OR global variable 3 must be >= 70 for this track not to be seen as a spoiler. Other than that, it works the same as SHOWIFSWITCH.
• SHOWIFLOCATION: This tag contains a list of comma-separated map ids. Each entry in this list represents a map id, and if one of these maps has been visited at one point during regular gameplay, this track will not be considered a spoiler. This is an excellent way to prevent spoiling of location-specific tracks, for instance.

Editing Metadata

One of the easiest ways to set metadata in an Ogg Vorbis file is through Audacity. If you open the Ogg file, go to Edit > Metadata you will see a screen that looks a little bit like this:


Audacity sets a few tags by itself. These won't show up (other than Artist Name which is ARTIST, TRACK Title which is TITLE, and Album Title which is ALBUM), so you needn't fill these out. Notice that Comments is also one of Audacity's default metadata tags. This is the same as the aforementioned COMMENTS tag, as these metadata keys are case-insensitive, meaning the capitalization does not matter.