One of the overlooked features of MapTool 1.5 is the introduction of RESTful functionality in the MapTool scripting language – MTScript. For the non-programmers, RESTful is a software architectural style that defines a set of constraints to be used for creating Web services. These take the form of an HTTP call, like when you put a web site URL into your web browser. The industry term for exposing a RESTful interface is called an Application Programming Interface or API.
But enough of the Geek Speak.
To the rest of us, pun intended, a RESTful service is just a call to a web endpoint who’s purpose is to return data, not web pages. You can test out the GitHub API for our RPTools repository by placing the following into your web browser.
https://api.github.com/users/RPTools/reposThe call returns a large JSON array detailing the contents of the RPTools repository. Simple, right?
The gist of all this is that MapTool, via macros, can communicate with other online systems. You can leverage this to bring sounds into your campaign via Syrinscape as demonstrated in the video below.
MapTool is able to utilize Syrinscape’s REST API via a macro. You simply copy the URL and auth token by clicking Show Remote Control Links from the Syrinscape Master interface. Once you have the URL, you construct a macro call to Syrinscape with something like the following:
[r: REST.get('https://www.syrinscape.com/online/frontend-api/moods/19/play/?auth_token=<insert your auth token here>')]
Once run, the macro will start playing to all the connected players.
Of course, with MapTool’s powerful scripting engine, you can do a whole lot more, like fire off one-shots when a players Initiative comes around or that awesome Heal Light Wounds (from Kyra’s sound set) every time your Channel Healing macro is used. You could also bake in some tokens on a map for quick links to selected moods for easy access.
The Path Forward
The RPTools contributors are currently in the process of adding audio streaming into MapTool. This will start with the macro calls to local or remote files and end with a GUI interface and preferences. It was made quite clear by some of our users they don’t want sound due to limited bandwidth and other considerations so you will always have the ability to keep MapTool mute. You can look for the first version of the new streaming ability in version 1.5.5.
Excited about the new functionality? Let’s discuss in the comments below or on one of our many social outlets.
You can download available versions of MapTool from GitHub.
All users running versions prior to 1.8.3 are strongly encouraged to update. See this announcement post on our forum.
A JAR file version may be downloaded as well but is only recommended for developers or other advanced users.
Mac Users are encouraged to use the PKG version of the install. Windows users are encouraged to use the MSI.
If you need interactive help, please join our Discord Server. Or visit our wiki for complete walk-throughs of how to use the tool. Our Community page has more links; see the toolbar at the top of the page.
I have tried multiple times to make the playClip and playStream functions work from both online and locally stored files but it has not worked yet.
Could you create a link with a working example?
The best advice I can give is to go over to Discord (link in sidebar) and request help from folks like Jamz and others that have integrated it into their campaigns.
I think this is a great new feature. I’ve experimented with using ambient sounds in my games and they have had a big effect on the players. I could tell they really liked it.
Integrating sound capability into MapTool was a very smart move. Other tools like microphones, Discord, etc. have built-in noise filtering features that defeat tools like Syrinscape. I’ve tried it. I turned off all the filtering on my end — buy my players still had it turned on (and might need it!).
So, having MapTool convey the ambient and other sounds is a great move! Thank you for doing this! I’m investigating the capability and plan to use it soon.
My plans to use it do not involve Syrinscape’s streaming service. I don’t want to pay for a service. Instead, I bought their sound packages outright and will figure out how to use that.
Ideally, I’d like to stream sound files from my local computer — as well as play various sound effects for spells, etc. I’ve noticed that the API supports both.
Sound adds a much needed dimension to our games. I will be integrating it into my games within this next month. Just a little busy right now making major UI changes to use frames and dialogs — and stop using input().
Either this or the next version of MapTool allows you to play sounds from a URI (typically a remote server). You can find more on the MapTool Wiki under the Audio Category.