This guide describes 0.3.0, available as installable APKs from GitHub Releases, or as a source build.
| Device | Build |
|---|---|
| Chromecast with Google TV, including 32-bit userspace | Universal, Python 3.11 |
| Other Android 7.0+ devices with 4 KiB memory pages | Universal; check hardware capabilities after install |
| ARM64/x86_64 devices with 16 KiB pages | Modern, Python 3.13 |
If unsure, connect ADB and run adb shell getconf PAGE_SIZE (4096 or 16384) and adb shell getprop ro.product.cpu.abi. Universal and modern builds have the same package name; install one at a time. See compatibility and build commands.
Download muse-gadget-0.3.0-universal-debug.apk or muse-gadget-0.3.0-modern-debug.apk from the release above. SHA256SUMS is provided alongside the APKs. Published 0.3.0 APKs use the same development signing certificate as the published 0.2 APK.
On a phone/tablet, enable Developer options and USB debugging, connect USB and accept the Android authorization prompt. On Chromecast with Google TV, open Settings → System → About and tap the Android TV OS build entry seven times. Enable the debugging option offered by that device.
For network ADB, use the address/port shown by Android. If the device offers wireless pairing, run adb pair HOST:PAIR_PORT, then adb connect HOST:CONNECT_PORT. Older TV builds may offer debugging on port 5555 without a separate pairing-code flow. Ports and menu labels vary by Android version; do not assume the pairing port is the connection port.
adb devices
adb install -r muse-gadget-0.3.0-universal-debug.apkUse the modern filename instead if that is your selected build; source builds are at app/build/outputs/apk/debug/app-debug.apk. The -r option updates in place and preserves app data. Open the app and start the service after updating.
An incompatible signing key blocks an in-place update, including some local builds and CI artifacts. Do not uninstall reflexively: uninstalling erases pairing and local settings. Keep the original signing key for updates. Production signing is not established yet; these APKs remain development-signed.
- Open Muse Gadget Everywhere and select Start service.
- Select Try a card. The message field includes an editable example.
- Select Show card. Confirm the text appears, then choose Close.
- Optionally select Speak text. TTS needs an installed language/voice engine.
Local actions require the running service. A job being accepted does not prove playback, speech or rendering finished; use Check display, Check speech or Check playback to inspect progress.
- Get your SDK token from gadgets.muse.ai → Settings → SDK tokens. Read the SDK terms.
- Home → Pair with Muse → paste the token → Save SDK token. It stays in private app storage. Never include it in a screenshot or issue.
- Select Open setup (10 min) and allow nearby-device access when asked. Bluetooth must be on, and the hardware must support BLE peripheral mode.
- In the Muse phone app, open Settings → Devices, enable Developer mode if required, then Add Device.
- Select this device. The app shows both its Muse BLE name and the actual on-air Bluetooth name. On the tested Chromecast, the normal Chromecast name worked. If your phone app filters by name, rename the Android device to the shown
MuseGadget…name and retry. - When paired, select Start service & open controls. Wait for Connected to your Muse.
- In a Muse chat, ask: “Show a welcome message on this device.” Specify the paired device’s name if you have several. Confirm the card on its screen.
For ADB-only setup, the legacy muse_token.txt import in the app’s external files/import directory is still supported. Open Pair once to create the directory. A successful import moves the token into private storage and removes the external file; keep credentials out of shell history.
Device → Diagnostics & setup links to overlay and battery settings. Overlay access permits background screen/app launches. Battery exemption can help with vendor task killers. These settings are not required just to try a visible local card. Some TVs do not expose a battery settings page; the app reports that limitation.
Camera and microphone permission are requested in their visible flows. Capture requires a tap; speech transcripts are reviewed before sending. Home Assistant, MQTT publishing, event forwarding and the trusted developer shell are configured separately in Device → Settings. Saving settings stops the service; return Home and start it again.
| What you see | What to try |
|---|---|
| Service stopped / action asks to start service | Home → Start service; check the status line |
| No device in the pairing scan | Check Bluetooth, nearby-device permission, BLE peripheral support, proximity and the on-air name shown in Pair |
| Permission denied after declining the prompt | Tap Open setup to retry, or allow Nearby devices in Android app settings |
| Connected locally, Muse reconnecting | Check network access and saved pairing; do not reset pairing as the first troubleshooting step |
| No Cast receivers | Keep both devices on the same Wi-Fi; guest networks or multicast isolation can block discovery |
| Media URL fails | Use a direct playable media URL or workspace file, not a webpage URL; inspect Check playback |
| Background app launch blocked | Grant overlay access under Diagnostics & setup |
| Cast video is black in screenshots | Some receivers use a hardware overlay; film the physical TV for video evidence |
| Camera/voice unavailable | This hardware may not have a camera, microphone or speech recognizer. Check Device capabilities |
To intentionally remove the Muse binding: Device → Diagnostics & setup → Reset pairing, then confirm. The SDK token and device identity remain saved. Clearing app data erases more, so prefer the in-app reset when re-pairing is the intended action.
Still stuck? Ask in Discussions or report a bug. Include app version, device/Android version, exact steps and a redacted screenshot or log. See SECURITY before sharing logs.