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

Personal tools

Difference between revisions of "Script:Roll20 Audio Master"

From Roll20 Wiki

Jump to: navigation, search
(Configuration Menu)
(Playlist Menu)
Line 24: Line 24:
 
*Remove All - Cleans out Roll20AM by removing all playlists and tracks from Roll20AM.  This does not affect Jukebox.  Use this when you make a lot of changes to your Jukebox Playlists.  This is also needed when there is a schema change in Roll20AM.  Check Schema version at the top of the script.
 
*Remove All - Cleans out Roll20AM by removing all playlists and tracks from Roll20AM.  This does not affect Jukebox.  Use this when you make a lot of changes to your Jukebox Playlists.  This is also needed when there is a schema change in Roll20AM.  Check Schema version at the top of the script.
 
===Playlist Menu===
 
===Playlist Menu===
 +
*Playlist Name - Clicking on the Playlist Name takes you to the Playlist Tracks Menu where you can see the tracks assigned into the Playlist
 +
*Volume - clicking on the current volume level brings up a roll query where you can enter a new volume.  This volume will be applied to the playlist and all tracks in the playlist.  It does not change the volume of tracks that are playing
 +
*Fade Time - click on the number of seconds brings up a roll query where you can enter a new fade time (in seconds).  This is applied to the playlist and and all tracks in the playlist.  Fade time is used to determine time it takes to fade in and fade out a track
 +
*Play Button - click on play to start the track.  The playlist will turn green to show it's running and a stop button will appear to stop the playlist whenever you wish
 +
*Stop Button - click on stop to stop the track.  The playlist will turn back to red to show it's stopped and the play button will appear to start it again
 +
*Fade Out Button - click on this to fade out the playlist.  The sound will gradually reduce based on fade time until the track volume is 0 at which point the track is stopped.  The playlist will go from green to red. 
 +
*Fade In Button - click on this to fade in the track.  The sound will gradually increase from 0 to the current track volume based on the Fade Time.  The playlist will turn from red to green to show it's running
 +
*Decrease Volume - click on this once or multiple times to reduce the volume of the track.  If the track is playing, it will reduce the volume of the playing track
 +
*Increase Volume - click on this once or multiple times to increase the volume of the track.  If the track is playing, it will increase the volume of the playing track
 +
*Mode - click on this to set the mode of the playlist
 +
:*Single - Plays a single track and stops
 +
:*Loop - Plays through all songs in order and will start again with first song when it has played all songs
 +
:*Random - Randomly chooses a song to play and will continue to randomly choose other songs until the playlist is stopped or faded out
 +
:*Shuffled - Uses an method to shuffle the tracks and then will play through all songs in a shuffled order
 +
:*Together - Plays all tracks in the playlist at once
 +
*Tag 1 - click on this to assign the track to Tag 1.  The icon changes to a check mark.  Click on the check mark again if you want to remove it from Tag 1
 +
*Tag 2 - click on this to assign the track to Tag 2.  The icon changes to a check mark.  Click on the check mark again if you want to remove it from Tag 2
 +
*Tag 3 - click on this to assign the track to Tag 3.  The icon changes to a check mark.  Click on the check mark again if you want to remove it from Tag 3
 +
*Tag 4 - click on this to assign the track to Tag 4.  The icon changes to a check mark.  Click on the check mark again if you want to remove it from Tag 4
 +
*Unlock playlist - click on this to enable player access to the playlist.  Players can't see the Roll20AM menus, but they can issue macro commands against the playlist.  The icon changes from locked to unlocked.  Click on the unlock icon to lock the playlist again
 +
*
  
 
==Using the Script==
 
==Using the Script==

Revision as of 19:42, 3 July 2018

API ScriptAuthor: Scott C.
Version: 1.01
Last Modified: 2016-11-22
Code: Roll20-Audio-Master GitHubLogo.png
Dependencies: None
Conflicts: None

Contents

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.

The User Interface

The UI is designed so once you are in it, you won't have to execute Roll20AM commands. However, because dice rolls and player chats can fill up the chat window it's always handy to have a macro with !roll20AM --config ready to go to bring it back up.

Configuration Menu

  • Master Volume - Click on the volume level to set another default volume. This updates all playlists and tracks. Master volume is the loudness (0-100) that a track will start playing at.
  • Fade Time - Click on the seconds to set another default. This updates all playlists and tracks to the new fade time. Fade time is the number of seconds to fade in or fade out tracks.
  • Delayed - Click on the seconds to set another Delayed time. This updates all playlists and tracks. Delayed is the number of seconds to wait before anything is done with a track.
  • Playlists - Brings up the Playlists Menu, which shows all playlists you have defined in Jukebox.
  • Tracks - Brings up the Tracks Menu, which shows all tracks you have in Jukebox. If you have a lot of tracks, this menu can be a challenge to use
  • Tags - Brings up the Tags Menu, which shows 4 Tags (Tag 1 through Tag 4). Tags are "dynamic" playlists that enable you to assign any number of tracks into one of the 4 tags
  • Stop All Tracks - Stops audio for all tracks across all playlists
  • Import Playlist - Brings in all Playlists from Jukebox, assigns all tracks in those Jukebox playlists to the Playlists in Roll20AM and brings in all other tracks that may not be assigned to Jukebox Playlists
  • Remove All - Cleans out Roll20AM by removing all playlists and tracks from Roll20AM. This does not affect Jukebox. Use this when you make a lot of changes to your Jukebox Playlists. This is also needed when there is a schema change in Roll20AM. Check Schema version at the top of the script.

Playlist Menu

  • Playlist Name - Clicking on the Playlist Name takes you to the Playlist Tracks Menu where you can see the tracks assigned into the Playlist
  • Volume - clicking on the current volume level brings up a roll query where you can enter a new volume. This volume will be applied to the playlist and all tracks in the playlist. It does not change the volume of tracks that are playing
  • Fade Time - click on the number of seconds brings up a roll query where you can enter a new fade time (in seconds). This is applied to the playlist and and all tracks in the playlist. Fade time is used to determine time it takes to fade in and fade out a track
  • Play Button - click on play to start the track. The playlist will turn green to show it's running and a stop button will appear to stop the playlist whenever you wish
  • Stop Button - click on stop to stop the track. The playlist will turn back to red to show it's stopped and the play button will appear to start it again
  • Fade Out Button - click on this to fade out the playlist. The sound will gradually reduce based on fade time until the track volume is 0 at which point the track is stopped. The playlist will go from green to red.
  • Fade In Button - click on this to fade in the track. The sound will gradually increase from 0 to the current track volume based on the Fade Time. The playlist will turn from red to green to show it's running
  • Decrease Volume - click on this once or multiple times to reduce the volume of the track. If the track is playing, it will reduce the volume of the playing track
  • Increase Volume - click on this once or multiple times to increase the volume of the track. If the track is playing, it will increase the volume of the playing track
  • Mode - click on this to set the mode of the playlist
  • Single - Plays a single track and stops
  • Loop - Plays through all songs in order and will start again with first song when it has played all songs
  • Random - Randomly chooses a song to play and will continue to randomly choose other songs until the playlist is stopped or faded out
  • Shuffled - Uses an method to shuffle the tracks and then will play through all songs in a shuffled order
  • Together - Plays all tracks in the playlist at once
  • Tag 1 - click on this to assign the track to Tag 1. The icon changes to a check mark. Click on the check mark again if you want to remove it from Tag 1
  • Tag 2 - click on this to assign the track to Tag 2. The icon changes to a check mark. Click on the check mark again if you want to remove it from Tag 2
  • Tag 3 - click on this to assign the track to Tag 3. The icon changes to a check mark. Click on the check mark again if you want to remove it from Tag 3
  • Tag 4 - click on this to assign the track to Tag 4. The icon changes to a check mark. Click on the check mark again if you want to remove it from Tag 4
  • Unlock playlist - click on this to enable player access to the playlist. Players can't see the Roll20AM menus, but they can issue macro commands against the playlist. The icon changes from locked to unlocked. Click on the unlock icon to lock the playlist again

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