How to use Online player with MapTool

Do you use the best free VTT ever, Maptool?
Do you use the best sound sound design app evar?

Would you like to integrate the two? Look no further :smiley:

MapTool 1.5.x introduce full RESTful functionality, and Syrinscape has a REST API, see where this is going? So, inside MapTool, simply create a macro with this one line like this:

[r: REST.get('')]

And bam, it’ll start playing to all the connected players just as if you used the master interface! Be sure to open your Master interface and click Show Remote Control Links from the menu to get the direct URL you need (along with your personal auth token built in)

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 soundset) everytime 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. In fact, here’s a video from @dorpond doing just this!


Excellent! thanks for sharing this with everyone @jamz! :slight_smile:

It was fun making the macros and framework, to see what I could pull off in Maptool! This video was fun to make and enlightening!

A quick question for Developers; besides on and off, is there other data that can be received/sent? I’d love to delve further into the possibilities here. Perhaps you discuss this somewhere? And if questions like this should go elsewhere, please let me know.

What would really help, are two things (@jamz, you may already know the answer to these?) :

  • Real time playback data. In other words, when the sounds stop on your end, they send that information back to Maptool, so that we can reflect that with our buttons. Right now, when your sounds stop playing, my buttons have no idea, so they still show as playing - could cause some headaches with many sounds playing at once.

  • Retrieving tagging/naming information on the soundset, mood, element, etc, so that I can pull that in automatically, instead of having to type it all in for each sound playing macro that I make. I’d like to eliminate typing this stuff in below.

Thanks, and great job making an awesome app!

    <b>This sound is playing on Syrinscape!</b> <br>

    <b>Sound Set:</b> 	<!-- Name of the Sound Set -->

    <b>Mood:</b>   		<!-- Name of the Mood, if applicable -->        
    Height of the storm  				
    <b>Element:</b>  	<!-- Name of the Element, if applicable -->      

@dorpond @jamz Somebody could create a websocket client (the master interface is an example of this) that is able to receive realtime information about the state of the GM’s online player (e.g. sample X is playing, at 65% volume, with 3 seconds until it stops and the next sample begins).

Such a websocket client could be built into a 3rd party app that wants access to the data.

Or if such an app already has an existing API that can receive data, the websocket client could transform the incoming data from Syrinscape and send it to the 3rd party app.

If you want to have a go at building a basic websocket client, have a look at your network tab in the Chrome developer tools (filter by WS requests) when you load the master interface. It will:

  • establish a sockjs connection to
  • send a register message with a user_session_key (you can send token instead, which you can get from the remote control links)
  • receive state messages up to 5 times per second which include is_playing, amp (amplitude) and wait (time to stop or next sample) for each element and sample
  • receive reconnect_to_new_backend messages with a subdomain param indicating to which subdomain (of the client should reconnect to

You can also filter by XHR requests to see how we get a list of soundsets and list of moods and elements within a soundset via the REST API. You’ll need to match up the ID numbers in state messages with the ID numbers in the REST API data to get soundset, mood and element names.

UPDATE: Note that this API is not yet stable, and so I would not recommend building official support for a Syrinscape websocket client directly into a 3rd party app at this time. But if any developers of 3rd party apps want better Syrinscape integration, let us know and we’ll work something out.


Are there any swagger it swagger like docs for the REST API yet or are things still in flux?

@benjamin is there any issue using your logo (unmodified) in promotion (WordPress/Twitter) and such?

I created a MapTool token lib as well using the logo. (Basically a collection of scripts that make calling your API more automated in MapTool)

I’m guessing it’s fine but always good to ask. :smile:

Hey @jamz, you can use any of the logos from HERE or if you need anything making up specifically then drop me an email at and I can get it sorted for you :slight_smile:

Thanks, now I remember seeing that, should have searched. :slight_smile:

1 Like