Take Control of Your Campaign Audio

Roll20 Mod Scripts (formerly known as API Scripts) are powerful tools that allow Pro subscribers to do amazing things in their games using the power of Javascript. For example, you can run advanced calculations, unlock a huge library of chat commands and macros to manage tokens, and even build entire knowledge bases with map markers that link game handouts together. Learn more about Mods in our Help Center, and check out our Masterclass Video!

This blog features a new script from Keith Curtis that provides a powerful and streamlined upgrade to Roll20’s built-in Jukebox system. Read on to learn more.

---

Keith Curtis is a professional RPG illustrator and cartographer with an extensive range of publishing credits. He has played and worked with many systems, starting with the earliest days of the hobby. Formerly a Roll20 forum moderator, he now supports the community as a Forum Champion and Marketplace Creator, works as a Conversion Contractor for Roll20, and continues to freelance in the RPG industry.

---

Upgrading the Roll20 Jukebox

Jukebox Plus is designed to give GMs complete, intuitive control over in-game audio. This video demonstrates the core features of the script, including playlist and album (tags) organization, playback controls, looping, visual previews, and chat-based feedback. It supports both Light and Dark mode.

Tracks can be sorted into user-defined albums and playlists for quick access, and the visual interface makes it easy to preview, tag, and play sounds without hunting through menus. Looping, isolate-play, and bulk commands like “Play All” and “Stop All” are all just a click away. Each track can include a description and an optional image, making it ideal for ambient scenes, cues, or musical motifs.

Tracks can send styled “Now Playing” messages, including descriptions and images, to keep players immersed and informed. The system is easy to maintain and transfer to new games, with backup handouts that hold all of your customized data.

Key Features

• Support for custom albums (tags) and playlists for sorting and organizing tracks
• Editable track descriptions and optional image previews
• A clean sidebar and track interface with light and dark mode options
• Easy controls for play, stop, loop, isolate, and bulk actions like “Play All” and “Stop All”
• Announce function to send styled “Now Playing” messages to the chat, including image and text
• A Find command to search track names and descriptions, grouping results in a temporary “Found” album
• Identifies duplicate tracks
• Backup and restore tools to preserve playlists, tags, and track metadata between games (moderate fidelity, use with this in mind)

The script is designed to be easy to use and maintain, making it ideal for games where music and atmosphere play an important role.

Getting Started

Jukebox Plus lets you organize and control music tracks by albums or playlists. Use the toggle buttons in the sidebar to switch between views. Tracks are displayed on the right, and control buttons appear for each one.

Header Buttons

Found at the top right of the interface:

• Play All — Plays all visible tracks simultaneously. Limited to the first five visible.
• Stop All Audio — Stops all currently playing tracks
• Loop All — Sets loop mode for all visible tracks
• Unloop All — Disables loop mode for all tracks
• Find Tracks — Search all track names and descriptions for the keyword. All matching tracks will be assigned to a temporary album called Found.
  • You can then switch to the Found album to quickly view the results. To clear the results, simply delete the Found album using the utility panel.
  • If you input “d” as the search term it will create a temporary play list of any duplicate tracks, grouped by name.
• Help — Displays a full help page. Click Return to Player to return.

Sidebar: Navigation & Now Playing

View Mode Toggle

The left sidebar lists all albums or playlists, depending on the current view mode. Clicking a name switches the view.

These buttons let you switch between organizing by Album tags or by manual Playlists. Albums are groupings of tracks that you define through Jukebox Plus. You can make as many of these as you like, and any track may belong to multiple Albums. Playlists are managed by the Roll20 Jukebox interface. You can view and play them here, but you cannot move them about.

At the bottom of the list is:

• Now Playing: filters the list to show only tracks currently playing.
• Track Controls: Each track shows these control buttons:
  • Play: Start the track.
  • Loop: Toggle loop mode for the track.
  • Isolate: Stops all others and plays only this one.
  • Stop: Stops this track.
• Announce: Sends the track name and description to the chat window.

Example:

Track Info and Management

Click the track description “edit” link to create a description. You can use “//” to insert a line break.

Each track has a Playlist tag, and the ability to add album tags. Playlist tags are in blue, and Album tags are in red. Click + Add to add a track to an Album. Click a Playlist or Album tag to jump immediately to that Playlist or Album. Click the “x” in an Album tag to remove the track from that Album: Album name | x

Click the image area to submit a valid image URL. This will be used as the image for that track. It will be cropped to fit a 100px square. The URL can come from your Roll20 image library or any valid image host.

Utility Panel

Click Settings ▾ to expand the utility tools. Includes:

These buttons change the name of an album, add a new album, or remove the currently selected album. There is no verification, so use with care.

These buttons switch between light and dark mode.

Rebuilds the interface if something breaks.

These buttons create a backup handout of the custom data you have entered: playlists, descriptions, and images. Higher-numbered handouts are later backups. You can restore from a backup if your data gets screwed up, or you can transmogrify the handout, or copy it to a new game, and restore from there. This is a useful way to move your customizations from game to game. Use with caution. Roll20 stores tracks by ID number, which are different in every game, and the script tries hard to match the title to ID. If you have multiple tracks with the same name or have renamed a track, this may not perform as expected.

Useful Macros

Here are some chat commands that can be used in macros:

!jb — Puts a link to this handout in chat

!jb play TrackName — play the named track

!jb stopall — stops all audio

!jb loopall — sets loop mode on all visible tracks

!jb unloopall — disables loop mode on all tracks

!jb jump album AlbumName — switch to a specific album

!jb help — open this help screen

!jb find keyword — command to search all track names and descriptions for the keyword. All matching tracks will be assigned to a temporary album called Found. You can then switch to the Found album to quickly view the results. To clear the results, simply delete the Found album using the utility panel.

!jb find d — command to search all track names duplicate tracks. All duplicate tracks will be assigned to a temporary album called Duplicates. You can then switch to the Duplicates album to quickly view the results. To clear the results, simply delete the Duplicates album using the utility panel.

You can also discover commands by pressing a button, clicking in the chat window, and pressing the up arrow to see what was sent.

Help

Click the “Help” button in upper right-hand corner of the Jukebox Plus handout on the header buttons to display the in-game help menu, which includes all the commands and their meanings.

One-Click Installation

---

Let Keith know what you think about Jukebox Plus here!

Tell Us What You Need

Our Suggestions & Ideas forum is the best place to request and vote for tools and features that would improve your Roll20 experience. If you have ideas about how to make the tabletop better for your games, let us know by posting, commenting, and voting. Feel free to also join us on Discord, where you can hang out with other community members and connect directly with staff for brainstorming, troubleshooting, and announcements.