Revision as of 23:11, 2 July 2018

Overview

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.

Changelog

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