Installation

To run Material Companion:

1. Download the latest version from the releases page:

• Windows: MaterialCompanion-win32-x64.zip
• MacOS (Intel): MaterialCompanion-macos-x64.zip or MaterialCompanion-macos-x64.dmg
• MacOS (Arm): MaterialCompanion-macos-arm64.zip or MaterialCompanion-macos-arm64.dmg

2. Extract the file (if it's a .zip)
3. Run Material Companion.exe (Windows) or Material Companion (MacOS) from within the folder, or open the .dmg file and drag Material Companion to the applications folder (MacOS)

To update the Material Plane hardware you will need to install Python v3.

Some notes for MacOS users

On MacOS you will probably get a message that it can't be opened because the developer cannot be verified. To solve this:

• Click 'Cancel'
• Open 'System Preferences'
• Navigate to 'Security & Privacy
• Unlock the page using the lock in the lower left
• There should be a message: `"Material Companion" was blocked from use because it is not from an identified developer', press 'Open Anyway' to the right of that message
• You might get another message to confirm that you want to open it: click 'Open'

Connection issues with some browsers

Some browsers, such as Brave, have a built-in adblocker that may prevent Foundry from connecting to Material Companion. If you run into connection issues, try disabling the adblocker (in brave: press the lion icon, and set the shields to 'down'), or use another browser like Chrome or Firefox.

Running/Building from the source

If you want to make modifications, or you can't get the prebuild apps to work, you can try running or building the app from the source.

Prerequisites

• Windows

  • node.js
  • Python v3
  • Microsoft Visual C++

• MacOS

  • node.js
  • Python v3
  • Xcode or Command Line Tools

• Linux

  • node.js
  • Python v3
  • A C++ compiler
  • Installed and configured ALSA
  • The libasound2-dev and build-essential packages

Running from the source

1. Download and unzip the source code
2. Open a termial window and navigate to the Material Companion folder
3. Run npm update and then npm install to update existing dependencies and install new dependencies
4. Run npm start to start the app

Building from the source

1. Make sure the app runs using the instructions above
2. Run npm run package to build the app
3. The apps should be built in /out/Material Companion-[platform]