[Script] Roll20 Audio Master -- Hear the dice, Hear the action!

1479418958

Edited 1491353234
Scott C.
Pro
API Scripter
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. The script also allows playlist functionality via script defined playlists; these have no relation to the playlists in the jukebox as the API does not have access to any of the folder structure (which unfortunately includes playlists). The help document is created in game as an archived handout and can be accessed via a link output to chat if you type an invalid command or just !roll20AM into chat. Most up to date version is always available from  my fork of the repository . Current one-click Version: 1.04 Newest Version: 1.05 Command Details below: 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 -Note the fade feature is not currently working due to the asynch nature of setting attributes- --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,  an expression, or mute/unmute. 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. • 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. Let me know if this is actually useful for anyone, and if anything needs work, Scott And because I'm a horrible person I almost forgot to thank the people who helped make this script what it is: Aaron and Stephen S. For code review and helping me implement some of the more complicated parts. William B for alpha testing and  DulfiJavadMalik at plainicon.com for all of the button icons for the chat menus. ChangeLog: v1.05 Fade functionality is working now tickTime is now actually in seconds Several erroneous pieces of the fade code have been fixed The script now whispers directly to the person who sent the command requiring chat output (help, errors, or menus). If the command is sent by an API script, the script will still whisper "gm" instead of a specific player Script messages are now noarchive, so they won't pollute your chat archive. v1.04: Script now trims hanging spaces from the start/end of track and playlist names in commands. Fix for  this issue . v1.03: Fixed player restriction handling so that it properly handles turning player restrictions off v1.02: Fixed an erroneous state.Roll20AM.{} variable definition that was assuming state.Roll20AM had been created when it hadn't, causing the API to not compile. v1.01: Fixed a crash that could occur when improper action keywords were used Added playlist import/update from jukebox functionality V1.0 Release
1479419856
Ah, perfect! I've been waiting for a script like this for a while!
1479420427
Scott C.
Pro
API Scripter
Heh, just discovered (thanks to The Aaron) in another thread, that the playlists may not be inaccessible after all. I'll play around with that and see if I can't more smoothly incorporate the script and the jukebox, I'm thinking even if I can do it, I may not as the standard jukebox only allows a track to be in a single playlist.
Would this allow you to include a short sound effect (assuming that it was in your Jukebox library) and activate it with a macro? So that a melee attack might play a sword sound, for instance?
1479437838
Scott C.
Pro
API Scripter
Yep, !roll20AM --play|track name would be your basic syntax.
Much evil grinning and furious soundbite searching must now ensue...
1479846596
Scott C.
Pro
API Scripter
Minor update: Fixed a crash that could occur if you did not use the correct action group keywords (e.g. play, config, etc) Added playlist import functionality (thanks to Aaron for showing me I could get info out of the playlist hierarchy) Syntax: !roll20AM --listImport,[listName:name] See the help handout in game after updating or in the OP for full details.
1479929656

Edited 1479929725
Charly Bellavance
Pro
Marketplace Creator
I tried to make sense of the actual line to type in your script, to make anything play but I could not find anything, Could you give me an exemple of an actual command I could type to test it? I got something weird like : !roll20AM --play,[swap],[loop],[mode:single],[delay:0]|Creepy ship| But nothing happens
1479931705

Edited 1480345274
Scott C.
Pro
API Scripter
Sure thing, I may need to make the help menu more clear, I'll think of how to better relay the syntax information. In the mean time; The single brackets denote options that are optional (the brackets aren't actually part of the syntax). Similarly, the forward slashes between options mean that the script only accepts one of those arguments at a time (usually in the order that they are listed). I'm not sure if your Creepy ship is a track or a playlist. If it's a track: !roll20AM --play,swap,loop|Creepy ship will play the Creepy ship track looped and will stop all other tracks/playlists when it starts playing the first time. If it's a playlist (first make sure you've created the playlist in the script, or imported it from your jukebox to the script using the new feature in v1.01): !roll20AM --play,swap,mode:single|Creepy ship will play a random track from the Creepy ship playlist one time and will stop all other tracks/playlists when it starts. The delay argument is never needed, unless you want to delay the command by some time frame. !roll20AM --play,swap,loop,delay:5|Creepy ship 5 seconds after the command is sent, the script will loop the track Creepy ship and stop all other tracks/playlists. You can chain multiple tracks/playlists (and mix tracks and playlists by separating each one with a |) together, and can chain multiple commands together in a single message. !roll20AM --play,swap,loop,mode:shuffle|Track Name|List Name|Track 2 Name|Track 3 Name|List 2 Name --vcontrol,volume:40,delay:10|Track Name|List Name|Track 2 Name|Track 3 Name|List 2 Name This command will play all the tracks and playlists (Track Name,List Name,Track 2 Name,Track 3 Name,and List 2 Name) immediately. The individually named tracks will be looped, and the playlists will shuffle. All tracks/playlists will be stopped before the listed tracks/playlists play for the first time. In addition, 10 seconds later, the volume of all the specified tracks will be set to 40% volume. Currently the volume controls do not act on playlists, so the playlist names are ignored in this second action group. Hope that helps explain it a little better.
1479998497

Edited 1479998556
Charly Bellavance
Pro
Marketplace Creator
Weridly enough, It started to send me errors such as this : TypeError: Cannot set property 'version' of undefined TypeError: Cannot set property 'version' of undefined at Object.checkInstall (apiscript.js:2453:36) at apiscript.js:3483:14 at eval (eval at <anonymous> (/home/node/d20-api-server/api.js:144:34), <anonymous>:65:16) at Object.publish (eval at <anonymous> (/home/node/d20-api-server/api.js:144:34), <anonymous>:70:8) at checkForReady (/home/node/d20-api-server/api.js:1205:12) at /home/node/d20-api-server/api.js:1284:9 at c (/home/node/d20-api-server/node_modules/firebase/lib/firebase-node.js:14:64) at /home/node/d20-api-server/node_modules/firebase/lib/firebase-node.js:93:560 at hc (/home/node/d20-api-server/node_modules/firebase/lib/firebase-node.js:39:147) at Kd (/home/node/d20-api-server/node_modules/firebase/lib/firebase-node.js:93:546) And I did not change anything inside of the script, I just tested your command line. Not sure if the erre was there before or after the command was input however.
1480000626
Scott C.
Pro
API Scripter
Ok, that is very weird. Somehow the Roll20AM object in the state has apparently been deleted (assuming that it is Roll20AM's checkInstall function that is throwing this error). Out of curiosity, do you have a lot of scripts installed and/or several scripts that make extensive use of the state (e.g. Page Navigator, Torch, or other scripts that have behavior that is remembered from session to session)? I definitely don't get this error in my script development game. Would you be willing to let me poke around in your game sometime this weekend (not today, because Thanksgiving)?
1480000831

Edited 1480000850
Charly Bellavance
Pro
Marketplace Creator
Well I got torch, and I quick added Map changer like... 10 minutes after retrying the music script. The scripts I do not use are still ''there'' but disabled, I do not know if it does bad things
1480001195
Scott C.
Pro
API Scripter
Hmm, ok, just to make sure this is Roll20AM throwing the error, could you disable everything else and then try running it again?
1480004642
Charly Bellavance
Pro
Marketplace Creator
Well still the same thing. Too bad, I shall switch musics and SFX myself. Thx for the help you provided.
1480004772
Scott C.
Pro
API Scripter
Hmm, ok, I'd be happy to come and debug in your game, but I think that's the only way I'm going to figure this out.
1480408487

Edited 1480408935
Gold
Pro
ETA on One-Click? Thanks for preparing this Scott. Waiting patiently for one-clickiness. I've got the idea to add a Fatality sound effect on my game's existing death macro (currently sets 0 HP, big red X status, and announces who died in text chat). !roll20AM --play|Fatality To play the short vocal sound effect Fatality without stopping any potential background battle-music, will that work?
1480426315

Edited 1480426377
Scott C.
Pro
API Scripter
Yep, that'll do it One-click is just waiting on a merge (hopefully today).
1480444225

Edited 1480445117
Scott C.
Pro
API Scripter
Well, script is merged, but apparently taking some delay to actually get to the one-click dropdown. Also gold, you could get fancy and do the following: !roll20AM --play|Fatality --vcontrol,volume:mute,ignore|Fatality --vcontrol,volume:unmute,ignore,delay:3|Fatality To play your fatality vocal, mute everything but fatality and then unmute everything 3 seconds later(adjust for your fatality length). Could give a nice pop of "SOMETHING DIED!!!!" to the vocal sound effect. And, I also just realized that the help menu has some incorrect info. Mute/unmute is now done via volume:mute/unmute rather than a separate option.
1480948789

Edited 1480948806
Scott C.
Pro
API Scripter
Fixed a compile error that went unnoticed in my test games (because they had all been created with an earlier, pre-release version of the script where state.Roll20AM had been created previously. The script should now compile and run just fine for everyone. I apologize for any inconvenience this may have caused.
1481155536
Hey Scott, this is a really awesome script, and I've been playing around with it and had the following questions/issues: I can get the script to run as the GM (e.g. using a !roll20AM --play|Shortbow) , but when I try to do it as a player it doesn't work.  How does the Jukebox work for players?  I noticed that they don't have an "Add" button and the Track list (e.g. Shortbow) isn't show anywhere.  My goal is to allow players to use marcros to make attack/melee effects When I try to run a macro with "GM only" commands (e.g. -volume controls), as a player it crashes the script Nice work!  Really excited to get this to work
1481156288
Scott C.
Pro
API Scripter
Jack V. said: Hey Scott, this is a really awesome script, and I've been playing around with it and had the following questions/issues: I can get the script to run as the GM (e.g. using a !roll20AM --play|Shortbow) , but when I try to do it as a player it doesn't work.  How does the Jukebox work for players?  I noticed that they don't have an "Add" button and the Track list (e.g. Shortbow) isn't show anywhere.  My goal is to allow players to use marcros to make attack/melee effects That's certainly one of the things that this script was made to do. If this is a track, you'll need to append "-players-" to the end of the track name in the jukebox. Don't include this tag when you send commands via the script to play a track. If this is a playlist, you can set the list to be player accessible via the playlist config menu: Red box denotes a GM only playlist, green box is player accessible. When I try to run a macro with "GM only" commands (e.g. -volume controls), as a player it crashes the script Hmm, that definitely shouldn't be happening. I'll try to get the logic that's just supposed to gate players out of those areas before the next merge.
1481167900

Edited 1481169738
Works like a boss!  Thanks Scott.  COuple of follow up questions: Is the -players- thing part of the roll20 documentation (I couldn't see it) or is it in your script For the playlist, If I make playlist with all sound fx's that I want to expose to my players, do I have to still individual append the -players- tag on each track, or can I just give the access to the play list?  (i.e. can it be inherited) Stupid question:  how do you get to the playlist config menu? This is really sweet
1481171512
Scott C.
Pro
API Scripter
The player accessibility tag is a script thing; and I just realized it is not actually mentioned in the help menu (doh). The tracks should inherit (for practical purposes) the access of the playlist, but I haven't actually tested this. Based on how I coded it though, this is how it should work. See the help menu section on !roll20AM --config for all the details. You can access it either via the button in the base config menu accessible via !roll20AM --config or directly via chat command, !roll20AM --config,menu:playlists
1481173254
Scott C.
Pro
API Scripter
Figured out why the script was crashing when trying to use vcontrol as a player. Is now fixed on the repository.
1481174417
OK cool.  I've got it working nicely now.    For the "GM only options", does that mean that your example macro above that allows the GM to mute the background music, play another track, then resume the background music wouldn't be possible for a player to use because it uses GM options? Not a big deal, but it is a nice feature to make the weapon attacks stand out more
1481179437
Scott C.
Pro
API Scripter
You can enable player access to volume control in the config menu.
1481555372
Any word on the one-click availability?  Seems that it has been about a week since the merge.
1481557303

Edited 1481562348
Scott C.
Pro
API Scripter
Hmm, that is odd. It's in the approved.yaml. I'll pester the devs. Although the version that is currently merged has an error due to an incorrect definition in the state (see my post a little bit above about the fix). The fix is still waiting on merge. EDIT: If I had to guess, I would guess that the problem with getting it into the one-click drop-down is that Steve assigned the script to a new category, "jukebox", which has not previously existed. This may not be populated in the drop-down.
1481751726

Edited 1481752058
Scott C.
Pro
API Scripter
Steve figured out the issue (which was an error on my part) and the script is now live on the one-click install, all updates as of today (12/14/16, version 1.02) have been merged.
1483135878
Michael R.
Sheet Author
Hi, I've tried unrestricted for my players and/or using the -players- code in the track names but nothing works, the audio macro I have set up runs from me as a GM but not when my players try it. What must I be doing wrong?
1483136646

Edited 1483137785
Scott C.
Pro
API Scripter
Sorry for the inconvenience Michael, I'll try to get you and your party up and running as soon as possible. Can you post the macro you are using? EDIT: Still not sure why your players can't play tracks tagged as player accessible as that works fine in my test game (although as previous bug hunts have shown this is no guarantee the problem isn't with the code), but I did figure out why they couldn't play things when access restriction was turned off; hadn't changed an if statement to check for the new value of the restrict variable correctly and so it was always returning true. I'll get that fix pushed to the repository sometime this weekend along with some other updates I've had percolating in the back of my brain. Anyways, if you can still post up the macro/command that your players were trying to play tracks tagged as player accessible that would help a lot.
1483384527
Scott C.
Pro
API Scripter
Player restriction handling should now be fixed. Still waiting on more info about the potential bug with players accessing player tagged tracks/lists.
Hey, with your brand new update, sometimes I get an error that stops the APIs altogether. It looks like this... ReferenceError: playerid is not defined ReferenceError: playerid is not defined at _.each._.each._.some (apiscript.js:4539:22) at _.each._.each.ops.*./.+.ops.*./._.each.state.Roll20AM.playLists.(anonymous function).currentTrack._.some._.some._.each._.each (apiscript.js:4882:25) at ontimeout [as _onTimeout] (timers.js:209:34) at Timer.listOnTimeout (timers.js:92:15) It's always after I try to create a new playlist with the API tools themselves. Just wanted to let you know. Restarting the API Sandbox fixes it, it's just a bit annoying at the moment.
1483452199
Scott C.
Pro
API Scripter
Hmm, that is odd. I'll look into it. Thanks for the report.
1483459787

Edited 1483460067
Scott C.
Pro
API Scripter
V1.04 pull request sent. Just missed the last merge day, so could be a couple weeks before it comes to one-click. Only fix/new feature here is that the command parser now trims hanging spaces from the start/end of a track/playlist string to avoid the issue reported by  TheProtoBabe in  this thread (thanks for the report). I've been unable to replicate the intermittent crash that TheProtoBabe reported. If anyone has some additional replication steps, that would help me track down the issue.
1483878657
Michael R.
Sheet Author
Hi Scott, not sure how but now the macros I set up are working perfectly, thanks!
1483886624
Scott C.
Pro
API Scripter
Good to hear.
1484441104
BK
Pro
Chris - I've got the syntax working and its great.... but every so often it looks like the API is breaking (no tokens buttons or macros work)... but if I SAVE the AM API, it goes back to working.   Any ideas why this is happening?   Script from my API page attached
1484443631

Edited 1485215829
Scott C.
Pro
API Scripter
BK, had you just deleted a jukebox track when this crash occurred? It looks like a typo was introduced to the destroyHandler function during one of my updates. Easy fix, but annoyed with myself that that slipped in. EDIT: This has been fixed in the most recent version (1.04) that is waiting on merge day. The problem with not working with spaces between the track name and the "-players-" tag has also been fixed. The most recent version can be found in my  fork of the repository if you want to grab the changes prior to merge day. EDIT the Second: v1.04 has been merged with one-click installer as of 1/23/17
1485877514
This is a great script, that said, I've got a question about the playback delay function. Would it be possible to include delays of less than a second? 0.5 secs, 0.75, etc?
1485882797
Scott C.
Pro
API Scripter
Is it not working with those? It should work just fine with fractional seconds. If it's not, then I'll have to go in and edit the command extractor a little, otherwise, I'll edit the help menu to be more clear that it accepts decimals.
1485996032

Edited 1485996052
It didn't work when I tried them the first few times, but when I tested it today it worked perfectly. Random stuff like that tends to happens with scripts I'm just testing out so I'll chalk it up to beginner mishaps. Thanks for the response.
1485996087
Scott C.
Pro
API Scripter
Np, lad it's working as expected, let me know if it stops at some point.
1489291919

Edited 1489291942
Minor annoyance. Whenever I get this thing to play a random track from my Victory Music playlist like this. !roll20AM --play,swap,mode:single,delay:2|Victory Music| it turns off the "loop" for every other track in my Jukebox. I've tried adding the loop to the command, tried using a mode other than single... nope.
1489296654

Edited 1489296792
Scott C.
Pro
API Scripter
Remove the swap keyword. This keyword tells the script that you want to stop all other tracks and start the tracks you've listed. Try this: !roll20AM --play,mode:single,delay:2|Victory Music you also do the need to end with a bar, shouldn't be a problem either way tho. Edit:also, did you mean to have a 2 second delay on the playing of your victory music?
1490662493
Hey Scott, AWESOME script!  Im just a little confused on how to use the fade option... I have a heavy breathing sound for when my Barbarian exits rage, but the track is rather long, and gets kinda akwards after a moment lol. I was thinking about having it run for 10 seconds with a fade starting at 5 seconds?
I've also had problems with the fade feature.
1490715384
Scott C.
Pro
API Scripter
Yeah, I'm currently working on chasing down why the fade feature doesn't work as intended. Hopefully I'll have some time this weekend to do so.
1490924056
Attempting to add a playlist and im getting this Error. ReferenceError: playerid is not defined ReferenceError: playerid is not defined at createList (apiscript.js:21039:22) at Timeout.delayHandler [as _onTimeout] (apiscript.js:21377:25) at ontimeout (timers.js:393:18) at tryOnTimeout (timers.js:244:5) at Timer.listOnTimeout (timers.js:214:5) this is the command im adding !roll20AM --listCreate,listName:Swoosh,access:player mode:trueRandom|Swoosh|Swoosh2|Swoosh3|Swoosh4|Swoosh5 Could this be the trueRandom causing this?
1490925948
Scott C.
Pro
API Scripter
shouldn't be the trueRandom, but I do notice one thing. Not sure if it's a copy/paste error or if it would cause the crash, but you're missing a comma between access:player and mode:trueRandom.
1491335877
Scott C.
Pro
API Scripter
@Dustin C. I realized what was going on while chasing down another bug. I had some old Help menu syntax in the script that was looking for a no longer used variable, so it was undefined which would crash the script. I'll get a fix out for that pronto. @Keith C. & Dustin C. So, I've tracked the problem with fade down. First of all, I apparently had some bad code in the fadeTracks function. Fixed that only to find the true problem. The problem is that the volume processor for tracks appears to not work until the volume slider stops moving, so the fade command's volume changes (while properly fading the volume if you watch the volume slider on the jukebox) are not implemented until all of them are completed. I'm working on trying to figure out a fix, but at this time, I'm not sure what that might be.