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
(Audio Master Controls: Added Random Single Track mode for playlists to documentation)
m
 
(18 intermediate revisions by 2 users not shown)
Line 1: Line 1:
 +
{{revdate}}
 +
{{main|API:Script Index}}
 
{{script overview
 
{{script overview
 
|name=Roll20-Audio-Master
 
|name=Roll20-Audio-Master
|author={{user profile|3135709|Victor B.}}
+
|author=[[User:3135709|Victor B.]],[[Scott C.]]
|version=2.12
+
|version=2.15
|lastmodified=2018-06-01
+
|lastmodified=2021-01
 
|dependencies=None
 
|dependencies=None
 
|conflicts=None}}
 
|conflicts=None}}
 +
'''Roll20 Audio Master''' (or '''Roll20AM''') is a script that 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 {{Text Chat}}, along with the ability to grant [[players]] selective access to the jukebox.
  
==Overview==
+
{{notebox|See Also the '''[https://app.roll20.net/forum/permalink/10593263/ Simple Sound]''' API, which is more simple to use }}
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.
+
<br>
 +
=Overview=
 +
{{#evp:youtube|V0GqlU3vrTk|Playing Music via the Roll20AM, 15min, by Nick O.|right|550}}
 +
'''Roll20 Audio Master''' (or '''Roll20AM''') is a script that 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 {{Text Chat}}, along with the ability to grant [[players]] selective access to the jukebox.
  
==The User Interface==
+
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 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===
+
The API command always starts with:
'''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.<br />
+
<pre style="overflow:auto;white-space:pre-wrap;">!roll20AM</pre>
'''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.  <br />
+
__TOC__
'''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.<br />
+
{{apiboxRec}}
'''Playlists''' - Brings up the Playlists Menu, which shows all playlists you have defined in Jukebox.  <br />
+
==Getting Started==
'''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<br />
+
By default, Roll20AM doesn't have access to any of your {{Jukebox}} tracks & playlists, so they need to be imported.
'''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<br />
+
'''Stop All Tracks''' - Stops audio for all tracks across all playlists<br />
+
'''Import Jukebox''' - 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<br />
+
'''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.<br />
+
'''Viewed By''' - Ability to assign control of Roll20AM to a single or all players.  Roll20AM menus may be viewed by: GM (Only), All (all players), Individual Player (drop list list of players to choose from).<br />
+
'''Access''' - Ability to give that person access to selective or all tracks: None (no player access to tracks or playlists), Full (full access to tracks or playlists), Limited (GM has to go through tracks and playlists and click the padlock icon in order to enable access)<br />
+
'''Menu Display''' - Ability to turn off all menu display EXCEPT for the config menu. That will always come up so you can turn back on Menu display.  This removes the requirement for the nomenu command in Macros<br />
+
  
===Audio Master Controls===
+
To import all tracks & playlist in your {{Jukebox}} to Roll20AM, do the following command once(it should update the chat to mention they are now imported):
'''Playlist or Tag Name''' - click on it to view the tracks assigned to the Playlist or Tag<br />
+
<pre style="overflow:auto;white-space:pre-wrap;">!roll20AM --config,import</pre>
'''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<br />
+
'''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 all tracks in the playlist/tag, if clicked there, or to an individual track, if clicked there.  Fade time is used to determine time it takes to fade in and fade out a track<br />
+
'''Delayed Time''' - click on the number of seconds to bring up a roll query where can enter a new delayed time (in seconds).  This is applied to all tracks in the playlist/tag, if clicked there, or to an individual track, if clicked there.  Delayed time determines the number of seconds to wait until the next Roll20AM action is taken.  <br />
+
'''Play/Stop 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.  Click on the stop button 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<br />
+
'''Fade In/Fade Out 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 and the fade out button will display.  Click the fade out button to fade out the track<br />
+
'''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<br />
+
'''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<br />
+
'''Mode''' - click on this to set the mode of the Playlist/Tag/Track<br />
+
:*'''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.  Not available for Tracks
+
:*'''Shuffled''' - Uses an method to shuffle the tracks and then will play through all songs in a shuffled order. Not available for Tracks
+
:*'''Together''' - Plays all tracks in the playlist at once. Not available for Tracks
+
:*'''Random Single Track''' - So you can use your playlist for continuous Random play or it will randomly play a single track and stop. 
+
'''Unlock Track'''- 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<br />
+
'''Remove Track''' - click on this to remove the track from Roll20AM<br />
+
'''Tags'''<br />
+
:*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
+
'''Return Button''' - This button will display the previous menu.  If you are on the Tracks View, it will return to Configuration.  If you are on Playlist/Tags View, it will return to Configuration.  If you are on Playlist or Tag Tracks View, it will return to the Playlists or Tags View.
+
  
==Using the Script==
+
The Configuration Menu is where you can change setting for Roll20AM:
 +
<pre style="overflow:auto;white-space:pre-wrap;">!roll20AM --config</pre>
  
===Basic Syntax===
+
To check if Roll20AM have access to your tracks, you can do:(or select "Tracks" from the Config Menu)
The contents of a command will change based on what you are doing, but the basic format will always look like this:<br />
+
<pre style="overflow:auto;white-space:pre-wrap;">!roll20AM --config,menu=tracks</pre>
'''!roll20AM''' - case sensitive and all commands must start with this<br />
+
'''Actions''' (must come after !roll20AM and preceeded by --, for example, --audio or --edit or --config
+
:*'''--audio''' - starts all audio related activities (play/stop, fade, etc)
+
:*'''--edit''' - starts all edit activities (changes volume, fade time, etc)
+
:*'''--config''' - displays menus or imports jukebox into Roll20AM or removes everything from Roll20AM<br />
+
'''Commands''' - play,stop,fade,in,out,increase,decrease are a small list of sample commands<br />
+
'''|''' - all commands must have a '|' character at the end.  This is required.  Everything after the '|' will be a comma delimited lists of Playlists, Tags, Tracks or any combination and must match the name of the Playlist, Tag, or Track.  You can also not provide anything after the '|' in some cases
+
  
Example:<br />
+
If you want to give players access to the api, do, then check [[#player]]-section:
*!roll20AM --audio,play|Wind
+
<pre style="overflow:auto;white-space:pre-wrap;">!roll20AM --edit,access|player</pre>
  
===Audio Commands===
 
'''play''' - starts a track using the tracks current volume<br />
 
'''stop''' - stops a track that is playing.  If no Playlists, Tags or Tracks follow the '|', then it will stop all Playlists, Tags or Tracks<br />
 
'''fade''' - this starts either a fade in or fade out<br />
 
:*'''in''' - fades in the Track from 0 to current volume level<br />
 
:*'''out''' - fades out the Track from current volume level to 0<br />
 
'''increase''' - increases both the volume of the Playlist, Tag or Track by 5% and any tracks that are currently playing<br />
 
'''decrease''' - decreases the Track from current volume level by 5% and any tracks that are currently playing<br />
 
  
Examples
+
If you have a track named "Wind", you can make it play & stop with these commands:
:*!roll20AM --audio,play|Fallout - Underground Troubles
+
<pre style="overflow:auto;white-space:pre-wrap;">!roll20AM --audio,play|Wind
:*!roll20AM --audio,stop|Fallout - Underground Troubles
+
!roll20AM --audio,stop|Wind</pre>
:*!roll20AM --audio,fade,in|Battle (fades in the playlist)
+
:*!roll20AM --audio,stop| (stops all tracks)
+
  
===Edit Commands (GM Only) ===
+
=The User Interface=
'''access'''
+
The UI is designed so once you are in it, you won't have to execute Roll20AM commands. You access it with the command:
:*'''player''' - opens the Playlist, Tag or Track for player access (they can issue roll20 commands against it)
+
<pre style="overflow:auto;white-space:pre-wrap;">!roll20AM --config</pre>'''
:*'''gm''' - locks the Playlist, Tag or Track from player access (roll20 commands will be rejected)
+
'''mode'''
+
:*'''single''' - sets the Playlist, Tag or Track mode to single.  For Playlists or Tags, it will play a singe track starting with first (open the Playlist or Tag to view current track order) and then stop.  If you start the Playlist or Tag again, it will play the next track in order.  For a track, it will play the track once and then stop. 
+
:*'''loop''' - sets the Playlist, Tag or Track mode to loop.  For Playlists or Tags, it will play each track in order (open the Playlist or Tag to view current track order) and will continue to play each tracks, starting from the beginning if all tracks have been played, until the Playlist or Tag is stopped or faded out.  For a track, it will play the track continuously until the track is stopped or faded out. 
+
:*'''random''' - sets the Playlist, Tag or Track mode to random.  For Playlists or Tags, it will play a completely random track and continue to play more random tracks until the Playlist or Tag is stopped or faded out.  This mode isn't available when setting a Track mode. 
+
:*'''shuffled''' - sets the Playlist, Tag or Track mode to shuffled. For Playlists or Tags, it will shuffle the Playlist or Tag and then play each track in shuffled order until the Playlist or Tag is stopped or faded out.  This mode isn't available when setting a Track mode. 
+
:*'''together''' - sets the Playlist, Tag or Track mode to together.  For Playlists or Tags, It will play all tracks in the Playlist or Tag at once.  Fade Out will fade out all tracks and stop will stop all tracks. This mode isn't available when setting a Track mode.
+
'''volume,level=<0-100>''' - sets the volume level for the playlist or track.  If playlist or track is not provided sets the volume level for ALL playlists and tracks<br />
+
'''fade,time=<number of seconds>''' - sets the fade time for the playlist or track.  If playlist or track is not provided sets the fade time for ALL playlists and tracks.  Fade time is used to fade in or fade out a playlist or track.<br />
+
'''delayed,time:<number of seconds>''' - sets the delay time for the playlist or track.  If playlist or track is not provided sets the delay time for ALL playlists and tracks.  Delay time is used to force a track or playlist from starting based on the delayed number of secondsk.<br />
+
'''set''' (used for tracks only)
+
:*'''tag1''' - sets a track into Tag List 1
+
:*'''tag2''' - sets a track into Tag List 2
+
:*'''tag3''' - sets a track into Tag List 3
+
:*'''tag4''' - sets a track into Tag List 4
+
'''unset''' (used for tracks only)
+
:*'''tag1''' - removes a track from Tag List 1
+
:*'''tag2''' - removes a track from Tag List 2
+
:*'''tag3''' - removes a track from Tag List 3
+
:*'''tag4''' - removes a track from Tag List 4
+
  
Examples:<br />
+
It can be handy to create a [[quickbar]] macro to quickly access the menu without having to type it out.
*!roll20AM --edit,volume,level=50| (sets all playlists and tracks to 50)<br />
+
*!roll20AM --edit,fade,time=10|11 - Drain You (sets the fade time to 10 seconds for this track)<br />
+
*!roll20AM --edit,set,tag1|Stone Temple Pilots - Atlanta (sets this track into Tag 1 List)
+
  
===Config Commands (GM Only)===
+
==Configuration Menu==
If '''menu=''' is omitted from the --config command, Roll20AM will display the setup menu<br />
+
[[File:Roll20am-api-2-15-menu.png|thumb|right|400px|Roll20AM Config 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 Jukebox''' - 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.
 +
* '''Viewed By''' - Ability to assign control of Roll20AM to a single or all players.  Roll20AM menus may be viewed by: GM (Only), All (all players), Individual Player (drop list list of players to choose from).
 +
* '''Access''' - Ability to give that person access to selective or all tracks: None (no player access to tracks or playlists), Full (full access to tracks or playlists), Limited (GM has to go through tracks and playlists and click the padlock icon in order to enable access)
 +
* '''Menu Display''' - Ability to turn off all menu display, EXCEPT for the config menu.  That will always come up so you can turn back on Menu display.  This removes the requirement for the nomenu command in Macros
  
'''menu='''
+
==Audio Master Controls==
:'''tracks''' - display the tracks menu which shows all tracks current in Roll20AM
+
[[File:Roll20am-api-2-15-player-access.png|thumb|right|400px|Two tracks shown in the menu, where the first track is unlocked(and therefore accessible to the player)]]
:'''tags''' - display the 4 tag lists
+
What each symbol or part of the menu does.
:'''playlists''' - displays all playlists currently in Roll20AM
+
:'''<playlist name>''' - displays all tracks assigned to the playlist.  The playlist name must be provided and match what is in Roll20AM
+
:'''tag1''' - displays all tracks assigned to tag1
+
:'''tag2''' - displays all tracks assigned to tag2
+
:'''tag3''' - displays all tracks assigned to tag3
+
:'''tag4''' - displays all tracks assigned to tag4
+
'''import''' - imports the Jukebox into Roll20AM.  This will do incremental additions, so as long as your playlists names don't change, additional tracks will be added from Jukebox to the correct playlist.  Tracks unassigned to playlists are brought in as well<br />
+
'''remove''' - removes everything from Jukebox. This is recommended if large changes, new playlists, changed playlists exist in Jukebox.  Run this command before running the '''import''' command<br />
+
  
Examples:
+
* '''Playlist or Tag Name''' - click on it to view the tracks assigned to the Playlist or Tag
*!roll20AM --config (displays the setup menu)
+
* '''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
*!roll20AM --config,menu=Battle (displays the tracks assigned to the Battle Playlist)
+
* '''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 all tracks in the playlist/tag, if clicked there, or to an individual track, if clicked there.  Fade time is used to determine time it takes to fade in and fade out a track
*!roll20AM --config,menu=Tracks (displays all tracks in Roll20AM)
+
* '''Delayed Time''' - click on the number of seconds to bring up a roll query where can enter a new delayed time (in seconds).  This is applied to all tracks in the playlist/tag, if clicked there, or to an individual track, if clicked there.  Delayed time determines the number of seconds to wait until the next Roll20AM action is taken. 
*!roll20AM --config,remove (removes everything from Roll20AM)
+
* '''Play/Stop 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.  Click on the stop button 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
*!roll20AM --config,import (imports everything into Roll20AM from Jukebox)
+
* '''Fade In/Fade Out 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 and the fade out button will display.  Click the fade out button to fade out the track
 +
* '''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/Tag/Track
 +
**'''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.  Not available for Tracks
 +
**'''Shuffled''' - Uses an method to shuffle the tracks and then will play through all songs in a shuffled order. Not available for Tracks
 +
**'''Together''' - Plays all tracks in the playlist at once. Not available for Tracks
 +
**'''Random Single Track''' - So you can use your playlist for continuous Random play or it will randomly play a single track and stop. 
 +
* '''Unlock Track'''- 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
 +
* '''Remove Track''' - click on this to remove the track from Roll20AM<br />
 +
* '''Tags'''<br />
 +
** ''Tag 1'' to ''Tag 4''  -- click on this to assign the track to Tag 1/2/3/4.  The icon changes to a check mark.  Click on the check mark again if you want to remove it from Tag 1/2/3/4
 +
* '''Return Button''' - This button will display the previous menu.  If you are on the Tracks View, it will return to Configuration.  If you are on Playlist/Tags View, it will return to Configuration.  If you are on Playlist or Tag Tracks View, it will return to the Playlists or Tags View.
  
===Special Commands===
+
=Using the Script=
'''delay''' - adding delay:<number of seconds> to any command will delay that command by the number of seconds.  Delay is optional.  <br />
+
'''nomenu''' - Roll20AM will often issue menu refreshes to reflect a change in a track (for example, track started or track stopped).  No menu prevents display of refresh menus.  Add it to any audio command.  It's optional
+
  
==Changelog==
+
==Basic Syntax==
'''Version 2.08'''
+
The contents of a command will change based on what you are doing, but the basic format will always look like this(case sensitive and all commands must start with this):
* Initial Deployment of new version of Roll20 Audio Master
+
<pre style="overflow:auto;white-space:pre-wrap;">!roll20AM</pre>
 +
 
 +
Actions (must come after <code>!roll20AM</code> and preceeded by <code>--</code>, for example, <code>--audio</code>, <code>--edit</code>, or <code>--config</code>
 +
* '''<code>--audio</code>''' - starts all audio related activities (play/stop, fade, etc)
 +
* '''<code>--edit</code>''' - starts all edit activities (changes volume, fade time, etc)
 +
* '''<code>--config</code>''' - displays menus or imports jukebox into Roll20AM or removes everything from Roll20AM<br />
 +
* [[#Audio Commands|Audio Commands]] - <code>play</code>,<code>stop</code>,<code>fade</code>,<code>in</code>,<code>out</code>,<code>increase</code>,<code>decrease</code> are a small list of sample commands<br />
 +
* '''<code>|</code>''' (doesn't seem true?)- all commands must have a <code>|</code> character at the end. This is required.  Everything after the <code>|</code> will be a comma delimited lists of Playlists, Tags, Tracks or any combination and must match the name of the Playlist, Tag, or Track.  You can also not provide anything after the <code>|</code> in some cases
 +
 
 +
{{ex}}
 +
* '''<code>!roll20AM --audio,play|Wind</code>''' - starts playing the "Wind"-track
 +
 
 +
==Audio Commands==
 +
* <code>play</code> - starts a track using the tracks current volume<br />
 +
* <code>stop</code> - stops a track that is playing.  If no Playlists, Tags or Tracks follow the '|', then it will stop all Playlists, Tags or Tracks<br />
 +
* <code>fade</code> - this starts either a fade in or fade out<br />
 +
** <code>in</code> - fades in the Track from 0 to current volume level<br />
 +
** <code>out</code> - fades out the Track from current volume level to 0<br />
 +
* <code>increase</code> - increases both the volume of the Playlist, Tag or Track by 5% and any tracks that are currently playing<br />
 +
* <code>decrease</code> - decreases the Track from current volume level by 5% and any tracks that are currently playing<br />
 +
 
 +
{{ex}}
 +
* '''<code>!roll20AM --audio,play|Fallout- Underground Troubles</code>'''  - starts playing the "Fallout- Underground Troubles"-track
 +
* '''<code>!roll20AM --audio,stop|Fallout - Underground Troubles</code>'''
 +
* '''<code>!roll20AM --audio,fade,in|Battle</code>''' (fades in the playlist)
 +
* '''<code>!roll20AM --audio,stop|</code>''' (stops all tracks)
 +
 
 +
==Edit Commands (GM Only) ==
 +
* '''access'''
 +
:*<code>player</code> - opens the Playlist, Tag or Track for player access (they can issue roll20 commands against it)
 +
:*<code>gm</code> - locks the Playlist, Tag or Track from player access (roll20 commands will be rejected)
 +
* '''mode'''
 +
:*<code>single</code> - sets the Playlist, Tag or Track mode to single.  For Playlists or Tags, it will play a single track starting with first (open the Playlist or Tag to view current track order) and then stop.  If you start the Playlist or Tag again, it will play the next track in order.  For a track, it will play the track once and then stop. 
 +
:*<code>loop</code> - sets the Playlist, Tag or Track mode to loop.  For Playlists or Tags, it will play each track in order (open the Playlist or Tag to view current track order) and will continue to play each tracks, starting from the beginning if all tracks have been played, until the Playlist or Tag is stopped or faded out.  For a track, it will play the track continuously until the track is stopped or faded out. 
 +
:*<code>random</code> - sets the Playlist, Tag or Track mode to random.  For Playlists or Tags, it will play a completely random track and continue to play more random tracks until the Playlist or Tag is stopped or faded out.  This mode isn't available when setting a Track mode. 
 +
:*<code>shuffled</code> - sets the Playlist, Tag or Track mode to shuffled.  For Playlists or Tags, it will shuffle the Playlist or Tag and then play each track in shuffled order until the Playlist or Tag is stopped or faded out.  This mode isn't available when setting a Track mode. 
 +
:*<code>together</code> - sets the Playlist, Tag or Track mode to together.  For Playlists or Tags, It will play all tracks in the Playlist or Tag at once.  Fade Out will fade out all tracks and stop will stop all tracks. This mode isn't available when setting a Track mode.
 +
<code>volume,level=<0-100></code> - sets the volume level for the playlist or track.  If playlist or track is not provided sets the volume level for ALL playlists and tracks<br />
 +
<code>fade,time=<number of seconds></code> - sets the fade time for the playlist or track.  If playlist or track is not provided sets the fade time for ALL playlists and tracks.  Fade time is used to fade in or fade out a playlist or track.<br />
 +
<code>delayed,time:<number of seconds></code> - sets the delay time for the playlist or track.  If playlist or track is not provided sets the delay time for ALL playlists and tracks.  Delay time is used to force a track or playlist from starting based on the delayed number of secondsk.<br />
 +
<code>set</code> / <code>unset</code>(used for tracks only)
 +
* <code>tag1</code>,<code>tag2</code>,<code>tag3</code>,<code>tag4</code> - sets / removes a track into/from Tag List 1/2/3/4
 +
 
 +
{{ex}}
 +
* '''<code>!roll20AM --edit,volume,level=50|</code>''' (sets all playlists and tracks to 50)<br />
 +
* '''<code>!roll20AM --edit,fade,time=10|11 - Drain You</code>''' (sets the fade time to 10 seconds for this track)<br />
 +
* '''<code>!roll20AM --edit,set,tag1|Stone Temple Pilots - Atlanta</code>''' (sets this track into Tag 1 List)
 +
 
 +
==Player==
 +
[[File:Roll20am-api-2-15-player-access.png|thumb|right|400px|Two tracks shown in the menu, where the first track is unlocked(and therefore accessible to the player)]]
 +
To allow [[players]] access to Audio Master, you need to first run
 +
<pre>!roll20AM --edit,access|player</pre>
 +
 
 +
Then you need to grant players access to individual tracks or playlists. Config Menu has "lock" symbol to show if track/playlist is available to player or not.
 +
 
 +
* {{forum|post/8329611/how-to-make-roll20-audio-master-accessible-to-players How to make Roll20 Audio Master accessible to players}} 
 +
<br clear=all>
 +
==Config Commands (GM Only)==
 +
If <code>menu=</code> is omitted from the <code>--config</code> command, Roll20AM will display the setup menu<br />
 +
 
 +
* '''<code>menu=</code>'''
 +
** <code>tracks</code> - display the tracks menu which shows all tracks current in Roll20AM
 +
** <code>tags</code> - display the 4 tag lists
 +
** <code>playlists</code> - displays all playlists currently in Roll20AM
 +
** <code><playlist name></code> - displays all tracks assigned to the playlist.  The playlist name must be provided and match what is in Roll20AM
 +
** <code>Tag1</code> to <code>Tag4</code> - displays all tracks assigned to that tag
 +
* <code>import</code> - imports the Jukebox into Roll20AM.  This will do incremental additions, so as long as your playlists names don't change, additional tracks will be added from Jukebox to the correct playlist.  Tracks unassigned to playlists are brought in as well<br />
 +
* <code>remove</code> - removes everything from Jukebox.  This is recommended if large changes, new playlists, changed playlists exist in Jukebox.  Run this command before running the <code>import</code> command<br />
 +
 
 +
{{ex}}
 +
* <code>!roll20AM --config</code> (displays the setup menu)
 +
* <code>!roll20AM --config,menu=Battle</code> (displays the tracks assigned to the "Battle"-Playlist)
 +
* <code>!roll20AM --config,menu=tracks</code> (displays all tracks in Roll20AM)
 +
* <code>!roll20AM --config,menu=Tag3</code> displays all tracks assigned to Tag3
 +
* <code>!roll20AM --config,remove</code> (removes tracks & playlists from Roll20AM)
 +
* <code>!roll20AM --config,import</code> (imports all tracks & playlists into Roll20AM from Jukebox)
 +
 
 +
==Special Commands==
 +
* <code>delay</code> - adding delay:<number of seconds> to any command will delay that command by the number of seconds.  Delay is optional.
 +
* <code>nomenu</code> - Roll20AM will often issue menu refreshes to reflect a change in a track (for example, track started or track stopped).  No menu prevents display of refresh menus.  Add it to any audio command.  It's optional
 +
 
 +
=More Tips=
 +
* [[Chat Menus]] -- great for making a menu for you favorite commands, without bloating your [[quickbar]]
 +
* {{forum|permalink/8934388/ Script to Create Roll20AM Inline-Link Chat Menu Macro}}
 +
* {{forum|permalink/8806020/ Adding Roll20AM call to spell description}}
 +
* {{forum|permalink/4866997/ Soundboard macro generator for [Roll20 Audio Manager}} by [[Keith]]
 +
 
 +
=Changelog=
 +
* '''Version 2.15''', update by [[Victor B.]], Jan 2021
 +
** {{fpl|9713892/ details}}
 +
* '''Version 2.12''' update, 2018
 +
* '''Version 2.08''' update, 2018
 +
* '''Version 1.0''' creation by [[Scott C.]], 2017 - {{forum|permalink/4259010/ thread}}
 +
 
 +
=See Also=
 +
* [[API:Script Index]] curated list of other APIs
 +
* '''[https://app.roll20.net/forum/permalink/10593263/ Simple Sound]''' API, which is more simple to use than Roll20AM
 +
[[Category:Featured articles]]
 +
[[Category:Audio]]
 +
[[Category:API Commands]]

Latest revision as of 10:53, 18 February 2022

Main Page: API:Script Index

API ScriptAuthor: Victor B.,Scott C.
Version: 2.15
Last Modified: 2021-01
Code: Roll20-Audio-Master
Dependencies: None
Conflicts: None

Roll20 Audio Master (or Roll20AM) is a script that allows you to replicate all of the commands in the basic u Jukebox, and then some via chat commands or a user interface that displays within q Text Chat, along with the ability to grant players selective access to the jukebox.


[edit] Overview

Playing Music via the Roll20AM, 15min, by Nick O.

Roll20 Audio Master (or Roll20AM) is a script that allows you to replicate all of the commands in the basic u Jukebox, and then some via chat commands or a user interface that displays within q Text Chat, along with the ability to grant players selective access to the jukebox.

The script allows playlist functionality by importing all tracks and playlists from u 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 API command always starts with:

!roll20AM

Contents

[edit] Getting Started

By default, Roll20AM doesn't have access to any of your u Jukebox tracks & playlists, so they need to be imported.

To import all tracks & playlist in your u Jukebox to Roll20AM, do the following command once(it should update the chat to mention they are now imported):

!roll20AM --config,import

The Configuration Menu is where you can change setting for Roll20AM:

!roll20AM --config

To check if Roll20AM have access to your tracks, you can do:(or select "Tracks" from the Config Menu)

!roll20AM --config,menu=tracks

If you want to give players access to the api, do, then check #player-section:

!roll20AM --edit,access|player


If you have a track named "Wind", you can make it play & stop with these commands:

!roll20AM --audio,play|Wind
!roll20AM --audio,stop|Wind

[edit] The User Interface

The UI is designed so once you are in it, you won't have to execute Roll20AM commands. You access it with the command:

!roll20AM --config

It can be handy to create a quickbar macro to quickly access the menu without having to type it out.

[edit] Configuration Menu

Roll20AM Config 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 Jukebox - 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.
  • Viewed By - Ability to assign control of Roll20AM to a single or all players. Roll20AM menus may be viewed by: GM (Only), All (all players), Individual Player (drop list list of players to choose from).
  • Access - Ability to give that person access to selective or all tracks: None (no player access to tracks or playlists), Full (full access to tracks or playlists), Limited (GM has to go through tracks and playlists and click the padlock icon in order to enable access)
  • Menu Display - Ability to turn off all menu display, EXCEPT for the config menu. That will always come up so you can turn back on Menu display. This removes the requirement for the nomenu command in Macros

[edit] Audio Master Controls

Two tracks shown in the menu, where the first track is unlocked(and therefore accessible to the player)

What each symbol or part of the menu does.

  • Playlist or Tag Name - click on it to view the tracks assigned to the Playlist or Tag
  • 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 all tracks in the playlist/tag, if clicked there, or to an individual track, if clicked there. Fade time is used to determine time it takes to fade in and fade out a track
  • Delayed Time - click on the number of seconds to bring up a roll query where can enter a new delayed time (in seconds). This is applied to all tracks in the playlist/tag, if clicked there, or to an individual track, if clicked there. Delayed time determines the number of seconds to wait until the next Roll20AM action is taken.
  • Play/Stop 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. Click on the stop button 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 In/Fade Out 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 and the fade out button will display. Click the fade out button to fade out the track
  • 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/Tag/Track
    • 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. Not available for Tracks
    • Shuffled - Uses an method to shuffle the tracks and then will play through all songs in a shuffled order. Not available for Tracks
    • Together - Plays all tracks in the playlist at once. Not available for Tracks
    • Random Single Track - So you can use your playlist for continuous Random play or it will randomly play a single track and stop.
  • Unlock Track- 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
  • Remove Track - click on this to remove the track from Roll20AM
  • Tags
    • Tag 1 to Tag 4 -- click on this to assign the track to Tag 1/2/3/4. The icon changes to a check mark. Click on the check mark again if you want to remove it from Tag 1/2/3/4
  • Return Button - This button will display the previous menu. If you are on the Tracks View, it will return to Configuration. If you are on Playlist/Tags View, it will return to Configuration. If you are on Playlist or Tag Tracks View, it will return to the Playlists or Tags View.

[edit] Using the Script

[edit] Basic Syntax

The contents of a command will change based on what you are doing, but the basic format will always look like this(case sensitive and all commands must start with this):

!roll20AM

Actions (must come after !roll20AM and preceeded by --, for example, --audio, --edit, or --config

  • --audio - starts all audio related activities (play/stop, fade, etc)
  • --edit - starts all edit activities (changes volume, fade time, etc)
  • --config - displays menus or imports jukebox into Roll20AM or removes everything from Roll20AM
  • Audio Commands - play,stop,fade,in,out,increase,decrease are a small list of sample commands
  • | (doesn't seem true?)- all commands must have a | character at the end. This is required. Everything after the | will be a comma delimited lists of Playlists, Tags, Tracks or any combination and must match the name of the Playlist, Tag, or Track. You can also not provide anything after the | in some cases


Example:

  • !roll20AM --audio,play|Wind - starts playing the "Wind"-track

[edit] Audio Commands

  • play - starts a track using the tracks current volume
  • stop - stops a track that is playing. If no Playlists, Tags or Tracks follow the '|', then it will stop all Playlists, Tags or Tracks
  • fade - this starts either a fade in or fade out
    • in - fades in the Track from 0 to current volume level
    • out - fades out the Track from current volume level to 0
  • increase - increases both the volume of the Playlist, Tag or Track by 5% and any tracks that are currently playing
  • decrease - decreases the Track from current volume level by 5% and any tracks that are currently playing


Example:

  • !roll20AM --audio,play|Fallout- Underground Troubles - starts playing the "Fallout- Underground Troubles"-track
  • !roll20AM --audio,stop|Fallout - Underground Troubles
  • !roll20AM --audio,fade,in|Battle (fades in the playlist)
  • !roll20AM --audio,stop| (stops all tracks)

[edit] Edit Commands (GM Only)

  • access
  • player - opens the Playlist, Tag or Track for player access (they can issue roll20 commands against it)
  • gm - locks the Playlist, Tag or Track from player access (roll20 commands will be rejected)
  • mode
  • single - sets the Playlist, Tag or Track mode to single. For Playlists or Tags, it will play a single track starting with first (open the Playlist or Tag to view current track order) and then stop. If you start the Playlist or Tag again, it will play the next track in order. For a track, it will play the track once and then stop.
  • loop - sets the Playlist, Tag or Track mode to loop. For Playlists or Tags, it will play each track in order (open the Playlist or Tag to view current track order) and will continue to play each tracks, starting from the beginning if all tracks have been played, until the Playlist or Tag is stopped or faded out. For a track, it will play the track continuously until the track is stopped or faded out.
  • random - sets the Playlist, Tag or Track mode to random. For Playlists or Tags, it will play a completely random track and continue to play more random tracks until the Playlist or Tag is stopped or faded out. This mode isn't available when setting a Track mode.
  • shuffled - sets the Playlist, Tag or Track mode to shuffled. For Playlists or Tags, it will shuffle the Playlist or Tag and then play each track in shuffled order until the Playlist or Tag is stopped or faded out. This mode isn't available when setting a Track mode.
  • together - sets the Playlist, Tag or Track mode to together. For Playlists or Tags, It will play all tracks in the Playlist or Tag at once. Fade Out will fade out all tracks and stop will stop all tracks. This mode isn't available when setting a Track mode.

volume,level=<0-100> - sets the volume level for the playlist or track. If playlist or track is not provided sets the volume level for ALL playlists and tracks
fade,time=<number of seconds> - sets the fade time for the playlist or track. If playlist or track is not provided sets the fade time for ALL playlists and tracks. Fade time is used to fade in or fade out a playlist or track.
delayed,time:<number of seconds> - sets the delay time for the playlist or track. If playlist or track is not provided sets the delay time for ALL playlists and tracks. Delay time is used to force a track or playlist from starting based on the delayed number of secondsk.
set / unset(used for tracks only)

  • tag1,tag2,tag3,tag4 - sets / removes a track into/from Tag List 1/2/3/4


Example:

  • !roll20AM --edit,volume,level=50| (sets all playlists and tracks to 50)
  • !roll20AM --edit,fade,time=10|11 - Drain You (sets the fade time to 10 seconds for this track)
  • !roll20AM --edit,set,tag1|Stone Temple Pilots - Atlanta (sets this track into Tag 1 List)

[edit] Player

Two tracks shown in the menu, where the first track is unlocked(and therefore accessible to the player)

To allow players access to Audio Master, you need to first run

!roll20AM --edit,access|player

Then you need to grant players access to individual tracks or playlists. Config Menu has "lock" symbol to show if track/playlist is available to player or not.


[edit] Config Commands (GM Only)

If menu= is omitted from the --config command, Roll20AM will display the setup menu

  • menu=
    • tracks - display the tracks menu which shows all tracks current in Roll20AM
    • tags - display the 4 tag lists
    • playlists - displays all playlists currently in Roll20AM
    • <playlist name> - displays all tracks assigned to the playlist. The playlist name must be provided and match what is in Roll20AM
    • Tag1 to Tag4 - displays all tracks assigned to that tag
  • import - imports the Jukebox into Roll20AM. This will do incremental additions, so as long as your playlists names don't change, additional tracks will be added from Jukebox to the correct playlist. Tracks unassigned to playlists are brought in as well
  • remove - removes everything from Jukebox. This is recommended if large changes, new playlists, changed playlists exist in Jukebox. Run this command before running the import command


Example:

  • !roll20AM --config (displays the setup menu)
  • !roll20AM --config,menu=Battle (displays the tracks assigned to the "Battle"-Playlist)
  • !roll20AM --config,menu=tracks (displays all tracks in Roll20AM)
  • !roll20AM --config,menu=Tag3 displays all tracks assigned to Tag3
  • !roll20AM --config,remove (removes tracks & playlists from Roll20AM)
  • !roll20AM --config,import (imports all tracks & playlists into Roll20AM from Jukebox)

[edit] Special Commands

  • delay - adding delay:<number of seconds> to any command will delay that command by the number of seconds. Delay is optional.
  • nomenu - Roll20AM will often issue menu refreshes to reflect a change in a track (for example, track started or track stopped). No menu prevents display of refresh menus. Add it to any audio command. It's optional

[edit] More Tips

[edit] Changelog

  • Version 2.15, update by Victor B., Jan 2021
  • Version 2.12 update, 2018
  • Version 2.08 update, 2018
  • Version 1.0 creation by Scott C., 2017 - thread(Forum)

[edit] See Also