Introduction

Material Deck is a Foundry VTT module that allows you to control certain Foundry functions using an Elgato Stream Deck. A Stream Deck is a device that has physical buttons with displays behind them. Material Deck uses this to, for example, control playlists, execute macros, display and control the combat tracker.

The module allows a high degree of customization, where each button on the Stream Deck can be assigned any desired function. Furthermore, it supports folder structures, allowing easy switching between various button configurations so you can easily switch between the combat tracker, soundboard, or any other (custom) configuration.

Material Deck is a very large module with tons of features and ways of customizing your experience. This menu will only cover the basics to get you started, the full documentation can be found on Github. Please also check the FAQ which answers some common questions, including some basic troubleshooting.

Latest Releases

Module
Stream Deck
Server
You can use the download utility in the module settings to download the Stream Deck plugin, Stream Deck profiles and Material Server.

Getting Started

Besides installing this module, you also need to install and run some other things.

Installing the Stream Deck Software and Plugin

YOu have to download and install the Stream Deck software. You then need to install the plugin. There is a delay between when the plugin get's updated and the update being pushed in the store. If you try to install the plugin right after an update, you might not have the latest version. Manual installation is better in that case.

Stream Deck Store

1. Open the Stream Deck application
2. Press 'More Actions' in the lower right
3. Search (top right) or scroll to find Material Deck
4. Press the 'Install' button

Manually

1. Download the latest plugin file using the download utility in the module settings, or download it (com.cdeenen.materialdeck.streamDeckPlugin) from here
2. Double-click the file, this should open the Stream Deck software
3. Press 'Install' in the pop-up

Installing a Stream Deck Profile (optional)

You can create your own profile, but it is recommended to start with one of the pre-made profiles. Currently, there is a profile for the normal and XL Stream Deck variants.

1. Download the latest plugin file using the download utility in the module settings, or download one (ending with .streamDeckProfile) from here
2. Double-click the file, this should load the profile into the Stream Deck software

Downloading and Starting Material Server

Material Server acts as a bridge application, bridging the communication between the Stream Deck and Material Deck.

1. Download the latest version for your operating system here
2. Download and install the prerequisites
3. Extract the archive
4. Double-click the file to start the server

You need to always have Material Server running when you want to use Material Deck

After setting up the module settings I suggest you just play around with one of the profiles to see that happens when you press buttons and do things in Foundry. Most things should be pretty self explanatory. After that you could look into customizing your experience, as you can read about below.

Module Setup

There are four buttons at the top:

• Help
• User Permission Configuration
• Download Utility
• Playlist Configuration
• Macro Configuration
• Soundboard Configuration

The help button leads you to the page you are currently reading, the other buttons will be explained below.

Below the buttons you will find the following settings:

• Enable Module - Ticking this box enabled the module for the client
• Material Server Address - Fill in the address of Material Server (usually if you run it on the same computer as you're using for Foundry, this can be localhost:3001). This is not necessarily the IP address of Foundry! It is the IP address of the computer that's running Material Server. The default value will work for 99% of people, only change it if you know what you're doing. More info on Material Server can be found here
• Image Cache Size - Sets the amount of images to store in the image cache. The image cache will locally store all images sent to the Stream Deck. This improves the update speed, but increases memory usage.
• Image Brightness - Sets the brightness of the default white images for better readibility of the text. If Image Cache Size is large, it'll take a while for the new brightness setting to be applied. A refresh will give instantaneous results.
• Number of Connection Warnings - Sets the number of times you will get a warning when Material Deck cannot connect to Material Server. Will be unlimited if set to 0.

User Permission Configuration

Using the 'User Permission Configuration' screen, the GM can configure what Material Deck functions users have access to.
Each action has various settings, and these settings can be set for each user role.

To save the settings, press the 'Save Configuration' button at the lower left, or to set the settings back to the default values, press 'Reset Defaults' in the lower right.

Download Utility

The download utility allows you to easily check the current version of the Stream Deck plugin and Material Server, and gives you the option to download the latest version.
Please note that the current version of Material Server is at the moment not supported.

At the bottom you can also download the default profiles from Github

The refresh button at the bottom refreshes the page in case there was a connection issue.

Playlist Configuration

The playlist configuration screen configures the playlists that you control using the Playlist action.
There are 2 sections: 'Settings', and 'Playlists'.

Settings

Default Play Mode

The play mode determines what to do when a track is playing, while another track is requested. By setting it to 'Unrestricted', you can play as many tracks at the same time as you want. Setting it to 'One track per playlist' will automatically stop all playing tracks in the playlist, ensuring that only one track is playing at a time. Setting 'Play Method' to 'One track in total' will limit playback to only one track in total.
This setting sets the default play mode, which can be overridden for each separate playlist, which will be discussed below.

Options:

• Unrestricted - Play as many tracks at the same time as you want
• One track per playlist - Play only one track per playlist. Trying to start a second track will stop the other tracks in the playlist
• One track in total - Play only one track in total. Trying to start a second track will stop all other tracks that are playing

Note: This play method only applies if tracks are started using the Stream Deck, you can still play more tracks using Foundry's internal audio player.

Number of Playlists

This sets the number of playlists that will be displayed. You can make this number as high or low as you want. This only changes the amount of playlists that are displayed, not the amount of playlists that can be controlled (there is no upper limit, as long as Foundry doesn't crash).

Playlists

Here you can select which playlists can be controlled with the module. You can manage as many playlists as you've set at 'Number of playlists', where the playlist number corresponds with the number you have to fill in in the property inspector (see below).
For each playlist you can set the play mode, which overrides the default play mode for that specific playlist.

Note: While you can assign the same playlist to multiple playlists in this configuration screen, only the play method of the first instance will be applied.

Macro Configuration

The Macro Configuration screen is to configure the macroboard for the Macro action.

The screen is divided into 32 boxes, each labeled 'Macro #', where each represents a single macro and its settings. This screen will be refered to as a page. By pressing the arrows at the top right and top left, you can go to the next or previous page. There is no limit to the amount of pages you can add, but if you have a lot of pages, at some point you might notice some performance issues.

For each macro there are 3 options:

• Macro Selection - Drop down menu from where you can select a macro from your macro directory
• Furnace Arguments - Allows you to use arguments if the Furnace is installed. Please read the documentation regarding advanced macros in the README of the Furnace. If, for example, you wanted to execute a macro named 'My Macro' with the arguments 'argument1 argument2 argument3', you would use for example /"My Macro" 100 50 "test" in the chat. In the macro configuration screen you would only fill in the arguments, so: 100 50 "test"
• Background - Color picker to set the background color of the Stream Deck button

At the bottom you have the following buttons:

• Clear Page - Clears all the macros on the current page. Please note that this is irreversible.
• Clear All - Clears all the macros. Please note that this is irreversible.
• Import - Import the macroboard from a file. This will override your current macroboard, and is irreversible.
• Export - Export your macroboard to a file.

When importing and exporting, you only import/export the metadata, not the actual macros. This means that you need to have the same macros in both the source and target Foundry client, or you might run into issues.

Soundboard Configuration

The Soundboard Configuration screen is used to configure the soundboard for the Soundboard action.

Similar to the Macro Configuration screen, the screen is divided into boxes, each labeled 'Sound #', where each represents a single sound and its settings. This screen will be refered to as a page. By pressing the arrows at the top right and top left, you can go to the next or previous page. There is no limit to the amount of pages you can add, but if you have a lot of pages, at some point you might notice some performance issues.

For each sound there are multiple options:

• Name - The name of the sound, this is the name that will be displayed on the SD button if 'Display Name' is selected in the property inspector. This name doesn't have to correspond with the file name of the sound, or the name that can be seen in the Foundry playlist.
• Playlist - Sets the playlist from which you want to select a sound. If you select 'File Picker', a file picker will appear instead of the sound selection drop-down menu.
• Sound - This is either a drop-down menu where you can select a sound from the selected playlist, or a file picker. When using the file picker, it is possible to use wildcard names, this means that you can randomly play a sound from a selection. To do this, navigate to the folder that contains the sounds, in the textbox append the folder name with the common part of the name of the sounds you want to play, followed by an asterisk. For example, if you have the sounds 'Thunder.wav', 'Thunder2.wav' and 'Thunder3.wav' in the folder 'Assets', you could fill in the following: 'Assets/Thunder*', which will play one of the three sounds randomly when you press the button on the Stream Deck.
• Icon - Here you can select an icon that will be displayed on the SD button if 'Display Icon' is selected in the property inspector. Please read these notes on rules regarding icon selection.
• On - Clicking the colored box you'll be presented with a color picker. This sets the color of the ring that's shown on the button when the sound is playing.
• Off - Clicking the colored box you'll be presented with a color picker. This sets the color of the ring that's shown on the button when the sound is not playing.
• Playback - This sets the playback mode, you can select from:
  • Once - Play the sound once
  • Repeat - Play the sound on repeat
  • Hold - Play the sound as long as the button is held down
• Volume - The playback volume of the sound. The final playback volume is also determined by the Interface Volume slider in Foundry's 'Audio Playlists' tab.

At the bottom you have the following buttons:

• Clear Page - Clears all the sounds on the current page. Please note that this is irreversible.
• Clear All - Clears all the sounds. Please note that this is irreversible.
• Import - Import the soundboard from a file. This will override your current soundboard, and is irreversible.
• Export - Export your soundboard to a file.

When importing and exporting, you only import/export the metadata, not the actual audio files. This means that you need to have the same audio files in the same relative location in both the source and target Foundry client, or you might run into issues.

Customization

Material Deck is extremely flexible, but most of this flexibility must be performed in the Stream Deck software.
Some basic instructions on using the software can be found here.

Some of the things you can change are:

• Button location - You can drag buttons around into any order you want
• Changing button text and icon - All the text and icons on the Stream Deck can be customized, see here
• Customize the behavior of buttons - See below

All the buttons have many settings to fine-tune your experience. Due to the large amount of things you can change, they will not be discussed here, instead you can read about it at the following links:

• Combat Tracker Action
• External Modules
• Macro Action
• Other Actions
• Playlist Action
• Scene Action
• Soundboard Action
• Token Action

Feedback

If you have any suggestions or bugs to report, feel free to create an issue, contact me on Discord (Cris#6864), or send me an email: cdeenen@outlook.com.

Credits

Author: Cristian Deenen (Cris#6864 on Discord)

Special thanks to Asmodeus#7588 who made this module possible by generously donating a Stream Deck XL
Please consider supporting me on Patreon, and feel free to join the Material Foundry Discord server.