Character Vault
Any Concept / Any System
Your System Come To Life
Roll20 for Android
Streamlined for your Tablet
Roll20 for iPad
Streamlined for your Tablet

Personal tools

Script:Roll20 Audio Master

From Roll20 Wiki

Revision as of 23:11, 2 July 2018 by Victor B. (Talk | contribs)

Jump to: navigation, search
API ScriptAuthor: Scott C.
Version: 1.01
Last Modified: 2016-11-22
Code: Roll20-Audio-Master
Dependencies: None
Conflicts: None



I felt there needed to be a comprehensive jukebox control script. This script allows you to replicate all of the commands in the basic jukebox and then some via chat commands or a user interface that displays within chat. The script allows playlist functionality by importing all tracks and playlists from Jukebox into Roll20AM. There's an ability to create up to 4 dynamic playlists (called Tags) from individual tracks so you don't have to go back and manipulate Jukebox and import again into Roll20AM. The in-game help has been disabled for the time being because of the new User Interface, which makes building help around the UI a challenge.

Using the Script

Basic Syntax

All Roll20AM commands use the same basic syntax. The contents of a command will change based on what you are doing, but the basic format will always look like this: !roll20AM --action,action settings, or options|track name to act on|or playlist name to act on

  • Action keywords are preceded by a space followed by a double dash " --". The action keywords are: play, stop, listCreate, listEdit, vcontrol, delayCancel, and config.
  • Action keywords and settings/options are separted by a comma. The option keywords will be described below in their associated action keyword section.
  • For most actions, the settings/options are optional.
  • Track/playlist names are always separated by a bar "|".
  • Commands can be chained together by making a second (third, fourth, etc) action group. Action groups are acted on sequentially.

Player Accessible Action Keywords

Commands are shown with all possible settings. If a setting is optional, it will be enclosed in brackets. If only one of a series of settings will be accepted, they are separated by a slash "/". The order of options does not matter as long as the action keyword begins the action group and the list of tracks ends the action group.

--play,[swap],[loop],[mode:shuffle/trueRandom/together/single],[delay:seconds]|track/list to play|track/list to play|... Plays the indicated track(s) or playlist(s). When sent by a player, only those tracks/playlists that are tagged as player accessible will be played.

  • swap - All other tracks will be stopped when the indicated tracks/lists begin playing.
  • loop - The indicated tracks will loop. When playlists are specified, only applies when the together option is indicated and then all tracks in the list will loop.
  • shuffle - No effect on individual tracks. Will cause the indicated playlists to shuffle when played.
  • trueRandom - As shuffle, but the same track may be played repeatedly.
  • together - Plays all tracks in the indicated playlist(s) at once.
  • delay:seconds - Delays the execution of the action group by this many seconds.

--stop,[soft],[ignore],[delay:seconds]|track/list to stop|track/list to stop|... Stops the indicated track(s) or playlist(s). When sent by a player, only those tracks/playlists that are tagged as player accessible will be stopped.

  • soft - Allows the indicated track(s)/playlist(s) to finish their current playthrough before stopping them.
  • ignore - Inverts the command, stopping all tracks/playlists except those listed. If no track or playlist is listed, stops all tracks/playlists (respects player restrictions).
  • delay:seconds - Delays the execution of the action group by this many seconds.

GM Only Features

--vcontrol,volume:value,[ignore],[fade/mute/unmute,[tickTime:seconds],[volTick:number],[stop]],[delay:seconds]|track to change|track to change|... Adjusts the volume of the indicated tracks. Has no effect on playlists. Players can be given access to volume control by turning access restriction off in the config menu.

  • volume - What to set the volume to. This can be a number, or an expression. Valid expressions are -X,+X,/X,and *X.
  • ignore - Inverts the command, adjusting the volume of all tracks/playlists except those listed. If no track or playlist is listed, adjusts the master volume.
  • mute/unmute - Sets the jukebox volume of the indicated track(s) to 0, but does not affect the saved track volume/restores the volume of the indicated track(s) to their saved volume.
  • fade - Allows you to adjust the volume of the indicated track(s) gradually over time. The volume is adjusted to the value passed in volume as with a normal vcontrol command. Has three optional settings.
  • tickTime - How frequently the volume should be adjusted during the fade
  • volTick - How much to adjust the volume by each tick. Will be modified on the last tick if this change would bypass the target volume.
  • stop - Stops the track(s) once they reach the target volume.
  • delay:seconds - Delays the execution of the action group by this many seconds.

--listCreate,listName:name,[access:gm/player][mode:shuffle/trueRandom/together/single]|track to add|track to add|... Creates a new script defined playlist. Note: These are different from the jukebox playlists, and have no relation to those as they are not API accessible.

  • listName - The name of the new playlist. Must be unique among playlist and track names.
  • mode:shuffle - Sets the default playlist behavior to shuffle.
  • mode:trueRandom - Sets the default playlist behavior to trueRandom
  • mode:together - Sets the default playlist behavior to together
  • mode:single - Sets the default playlist behavior to single. Will play a random single track. If no behavior is specified, will default to single.
  • access:gm/player - Sets the access for this playlist to be player accessible or gm only. Default is gm only.

--listEdit,listName:name,[add/remove],[mode:shuffle/trueRandom/single/together],[access:gm/player]|track to add|track to add|... Edits the indicated playlist.

  • add - Adds the track(s) to the playlist
  • remove - Removes the tracks from the playlist. If no tracks are specified, deletes the playlist.

--cancelDelay Cancels all delays except for the fading of volumes. There is not currently a more specific cancellation of delays.

--config,[menu:Which Menu] Brings up the chat based menu interface for the script

  • menu:Which Menu - Specifies one of the config menus to send to chat. Possibilities are:
  • playlists - Brings up the list of created playlists and their current play state and player access state and the controls to play/stop them, add more playlists, toggle player access and see the details of an individual playlist.
  • tracks - Brings up the list of all tracks and their current volume and play state and controls to change these.
  • restrict - Brings up the menu to set how the script reacts to player and API messages and what denotes a player accessible track.
  • playlist name - Providing the name of a playlist will bring up the details menu for that playlist.

--listImport,[listName:name] Imports playlists from the jukebox into the script. If the named playlist already exists, it will update that playlist with any missing tracks.

  • listName:name - Will only import or update the designated playlist.


Version 1.01

  • Fixed a crash that would result from improper action keyword usage
  • Added Playlist import/update from jukebox functionality

Version 1.0

  • Release