How to install and sideload using CastMLT screencasting commands

Updated 2026-10-28

Android TV devices rarely ship with CastMLT built in, which means you usually have to load its configuration and commands over a cast session before the TV picks them up. This guide walks through installing the CastMLT payload and running the screencasting commands from a host machine without touching the Google Play Store.

What CastMLT is and why sideloading still matters

CastMLT is a screencasting control profile that lets you push UI events, app launches, and media playback instructions to an Android TV from an external client. On supported Nvidia Shield Pro and some custom Android TV boxes, CastMLT is not part of the default app bundle, so you load it yourself. Sideloading is the only way to get it onto TVs that run a locked store image or a regional build that omits the CastMLT package.

The main reason to prefer a cast-triggered install over a direct APK flash is that the TV itself applies signature checks on sideloaded packages. By embedding the payload in a cast session you keep the file in transit and let the TV update its app cache only after you confirm the payload ran cleanly.

Preparing the host machine for CastMLT push

Set up one Linux workstation on the same network as the TV. The host needs Java 17, the CastMLT SDK tarball, and a small Python helper script for JSON-to-radio conversion.

1. Install jdk-17-jdk on the host and verify java -version returns 17 or higher.
2. Download the latest CastMLT SDK release from the vendor. Verify the checksum against the published SHA-256 hash.
3. Create a radio-config.json that maps each target TV IP to its CastMLT audio channel:

[
  {"ip": "192.168.1.42", "id": "tv-living-room"},
  {"ip": "192.168.1.43", "id": "tv-kitchen"}
]

The TV must be on the same subnet and have the CastMLT receiver service running on port 5000. If it is not, start it with sudo systemctl start castmlt-receiver and confirm it responds to a quick TCP ping.

Pushing the screencast profile via CastMLT

Log into the host terminal and run the push script:

./push_cmlt.py --config radio-config.json --target "tv-living-room" --profile home-screen-overlay

That command sends a structured radio message: set the on-screen layout to a 16:9 overlay, enable gesture triggers for volume, and register three key event handlers (play/pause, capture, notification dismiss). The TV receives the message, validates the signature, and places the CastMLT module in its temporary app slot.

After the push completes, verify with adb shell pm list-installed | grep castmlt. You should see com.castmlt.sdk listed with a version number matching the SDK you deployed. If it shows as “unknown,” uninstall any leftover side-load files first, then retry.

Running the commands from the TV

Once the module is installed, you can trigger commands from the TV’s own cast endpoint. Open a browser on the TV, go to http://localhost:5000/cast, and send a POST with the following JSON payload:

{"action": "trigger", "event": "cast-play-pause", "payload": {"media_id": "local://intro.mp4"}}

Other useful payloads include "cast-capture-start" with a duration field, "cast-capture-stop", and "cast-gesture", "swipe-left". Each event logs to the CastMLT console view inside the TV settings menu, which you can read from a remote desktop session over SSH with VNC.

Trade-offs, risks, and troubleshooting tips

Sideloading CastMLT introduces two real trade-offs. First, the side-loaded APK has no automatic update path, so you must re-push the profile whenever the vendor releases a bug fix or new event schema. Second, if the TV’s verification daemon rejects the package because it is unsigned, the installation silently fails and the device just stays in its previous state.

If the push script exits with RC=12, the likely cause is a mismatch between the TV’s CPU architecture and the SDK’s target ABI — install the libc64 variant for the Shield or the correct ARM variant for other boxes. If the TV logs show signature verification failed after a successful push, delete the old CastMLT artifact, reboot the device, and re-push from scratch.

Always test on one device first. Once the profile works on a single TV, replicate it to the rest of your kiosk fleet. Keep your CastMLT scripts under version control and tag each release so rollback is possible if an event handler misfires.

Related reading: more Android TV notes