index muse gadget
Turn an ESP32 board into a Muse gadget in a few minutes. No coding, no ESP-IDF, no command line. Plug the board into a Windows PC, paste your Muse SDK token, press INSTALL, and Muse Companion does the rest.
Meta open-sourced the Muse Gadget SDK, so anyone can build a Muse-powered device on ESP32 hardware. The SDK is flexible, but setting a board up by hand means installing ESP-IDF, configuring the SDK, building firmware, finding the serial port, flashing, and pairing.
ESP-IDF → configure → build → serial port → flash → monitor → pair
connect → token → install
Muse Companion is a small Windows app that does all of it for the boards below. It also stays in the tray afterwards: it gives your gadget a voice (Muse sends gadgets text; Companion turns it into speech on the board) and, on the touchscreen board, shows what your computer is playing.
Two boards are supported. Others won't work: the firmware is built for these two.
recommended · most compatible
A desktop Muse with a big touchscreen for the character, captions and the music page. Everything Muse Companion does works on this board. Connect the speaker to it before you start.
on Amazonsmall · battery powered
A pocket-sized Muse with a built-in battery, so it works away from the USB cable. The screen is small (135×240) and not a touchscreen, there's no music page, and the character is always Muse.
on Amazon| Hosyond 3.5″ | M5StickS3 | |
|---|---|---|
| Screen | 3.5″ | small, 135×240 |
| Touchscreen | ● | — |
| Music page (now playing, cover, controls) | ● | — |
| Choice of character | ● | — Muse only |
| "Hey Muse" and voice input | ● | ● |
| Speaks Muse's replies | ● with the speaker connected | ● |
| Built-in battery | — USB powered | ● |
| Compatibility | full | core features |
step 01
Every Muse gadget needs an official SDK token. Sign in at gadgets.muse.ai with your Muse account, open Account → SDK tokens, create a token and copy it. It starts with mgst_.
step 02
Download the installer (2.4 MB) and run it. It fetches the app (about 24 MB), installs it, and opens it. No Python or ESP-IDF needed. It asks for administrator rights to install into Program Files.
The installer isn't code-signed yet. If SmartScreen warns, choose More info → Run anyway. On PCs with Smart App Control turned on, Windows blocks unsigned installers outright.
step 03
In the SETUP tab, paste your token into SDK TOKEN. It's saved on this computer.
Hosyond: connect the speaker to the board first, then the board to the PC. M5StickS3: connect it directly.
After a few seconds BOARD changes from PLUG IN YOUR BOARD to READY · COM5 (any port number). Companion finds the port and checks it really is a supported ESP32-S3 by itself.
step 04
On the Hosyond, pick the character its screen will show (you can change it later). The M5StickS3 always uses Muse, so there's nothing to choose.
step 05
Companion writes the firmware and your token to the board. It takes a minute or two. Don't unplug the board while it runs.
When it's done it says Installed … and the name your gadget will have in the Muse app, like MuseGadget-3F9A21. (The Hosyond shows up as ES3C35P, the board's own model name.)
step 06
On your iPhone or Android phone, open the Muse app and go to Settings → Devices. Turn on Developer mode: it lets the app find gadgets built with the Gadget SDK.
step 07
Still in Settings → Devices, tap + (top right). Your board appears as MuseGadget-XXXXXX. Select it and follow the app: it may ask you to confirm on the board with its button, then pick a 2.4 GHz Wi-Fi network.
Once it's on Wi-Fi, Companion finds it and the pill at the top says ONLINE. You're done: say "Hey Muse".
Leave Muse Companion running (it sits in the tray and starts with Windows): it's what speaks Muse's replies on the board, so the PC and the gadget need to be on the same network.
Muse sends gadgets text. Companion reads it aloud on the board, in one of 25 voices: natural ones, accents, and silly ones (Movie Trailer, Evil Overlord, Chipmunk…). Every voice reads Chinese too. Set the speed, choose online (natural, streaming) or Windows offline speech, change the wake word, and use TEST BOARD SPEAKER to check the sound. Speaker and volume are set on the board, in its SYS menu.
The board's MUSIC page shows what this computer is playing, cover included, with play, pause, skip and seek on its touchscreen. Turn it on or off in the MUSIC tab. The M5StickS3 has no music page.
Pick a different face for your gadget in SETUP and press UPDATE. An update keeps the pairing and Wi-Fi, so there's nothing to redo in the Muse app.
Companion checks for a new version when it starts and every six hours (or press CHECK FOR UPDATES). Updating the app never touches the board. To put new firmware on the board, press UPDATE.
Unplug the board, plug it back in, and press INSTALL again. If it still fails, put the board in download mode first:
Check that Settings → Devices → Developer mode is on, then tap + and look for a device starting with MuseGadget-.
Paste the right one in SETUP and press UPDATE (or INSTALL). If a token has been exposed, revoke it in your Muse account and create a new one.
Your SDK token is used on your computer only. Companion writes it into the board's firmware settings. It isn't uploaded to our server or stored in any cloud of ours. Still, treat it like a password; if it's exposed, revoke it and make a new one.
The finished gadget talks to Muse over your Wi-Fi like any Muse device. With the online speech engine, the text of Muse's replies is turned into speech by Microsoft's online voices; choose Windows · offline in the VOICE tab to keep that on your PC.
Muse Companion is open source and built on Meta's open-source Muse Gadget SDK, released under the Apache License 2.0 (some included third-party components keep their own licenses; Meta's license excludes the Jollybot avatar). You're welcome to read the code, add boards, make characters, or build your own version: github.com/huismaxx/companion.
Muse Companion is an independent community project for personal, non-commercial use. It isn't an official Meta product and isn't affiliated with or endorsed by Meta. Muse, the Muse Gadget SDK and Meta are trademarks of their owners. Flashing firmware changes your board and is done at your own risk; only flash firmware meant for your board.
Pick a board, get your token, plug it in, press INSTALL. Your Muse gadget is a few minutes away.