chromecast-with-google-tv

Original source / Raw SKILL.md

---
name: chromecast-with-google-tv
description: Cast YouTube videos, Tubi TV show episodes, and TV show episodes from other video streaming apps via ADB to Chromecast with Android TV (Chromecast 4K supported, Google TV Streamer support is unknown)
metadata: {"openclaw":{"os":["darwin","linux"],"requires":{"bins":["adb","scrcpy","uv","yt-api"]},"install":[{"id":"brew-adb","kind":"brew","cask":"android-platform-tools","bins":["adb"],"label":"Install adb (android-platform-tools)"},{"id":"brew-scrcpy","kind":"brew","formula":"scrcpy","bins":["scrcpy"],"label":"Install scrcpy"},{"id":"brew-uv","kind":"brew","formula":"uv","bins":["uv"],"label":"Install uv"},{"id":"go-yt-api","kind":"go","module":"github.com/nerveband/youtube-api-cli/cmd/yt-api@latest","bins":["yt-api"],"label":"Install yt-api (go)"}]}}
---

# Chromecast with Google TV control

Use this skill when I ask to cast YouTube or Tubi video content, play or pause Chromecast media playback, check if the Chromecast is online, launch episodic content in another streaming app via global search fallback, or pair with a Chromecast device for the first time.

## Setup

This skill runs with `uv`, `adb`, `yt-api`, and `scrcpy` in the PATH. No venv required.

- Ensure `uv`, `adb`, `yt-api`, and `scrcpy` are available in the PATH.
- Use `./run` as a convenience wrapper around `uv run google_tv_skill.py`.

### First-time pairing

Before using this skill, you must pair your Chromecast with ADB wireless debugging:

1. Enable Developer Options on the Chromecast (Settings > System > About > tap "Android TV OS build" 7 times)
2. Enable USB debugging and Wireless debugging in Developer options
3. Use the `pair` command to pair with the pairing code shown on screen:
   - `./run pair --show-instructions` - Display detailed pairing instructions
   - `./run pair --pairing-ip <IP> --pairing-port <PORT> --pairing-code <CODE>` - Perform pairing

After pairing once, you can use the connection port shown on the Wireless debugging screen for all other commands.

## Capabilities

This skill provides a small CLI wrapper around ADB to control a Google TV device. It exposes the following subcommands:

- pair: pair with Chromecast using wireless debugging (first-time setup)
- status: show adb devices output
- play <query_or_id_or_url>: play content via YouTube, Tubi, or global-search fallback.
- pause: send media pause
- resume: send media play

### Usage examples

`./run pair --show-instructions`

`./run pair --pairing-ip 192.168.1.100 --pairing-port 12345 --pairing-code 123456`

`./run status --device 192.168.4.64 --port 5555`

`./run play "7m714Ls29ZA" --device 192.168.4.64 --port 5555`

`./run play "family guy" --app hulu --season 3 --episode 4 --device 192.168.4.64 --port 5555`

`./run pause --device 192.168.4.64 --port 5555`

### Device selection and env overrides

- You can pass --device (IP) and --port on the CLI.
- Alternatively, set CHROMECAST_HOST and CHROMECAST_PORT environment variables to override defaults.
- If you provide only --device or only --port, the script will use the cached counterpart when available; otherwise it will error.
- The script caches the last successful IP:PORT to `.last_device.json` in the skill folder and will use that cache if no explicit device is provided.
- If no explicit device is provided and no cache exists, the script will attempt ADB mDNS service discovery and use the first IP:PORT it finds.
- IMPORTANT: This skill does NOT perform any port probing or scanning. It will only attempt an adb connect to the explicit port provided or the cached port.

### YouTube handling

- If you provide a YouTube video ID or URL, the skill will launch the YouTube app directly via an ADB intent restricted to the YouTube package.
- The skill attempts to resolve titles/queries to a YouTube video ID using the `yt-api` CLI (in the PATH). If ID resolution fails, the skill will report failure.
- You can override the package name with `YOUTUBE_PACKAGE` (default `com.google.android.youtube.tv`).

### Tubi handling

- If you provide a Tubi https URL, the skill will send a VIEW intent with that URL (restricted to the Tubi package).
- If the canonical Tubi https URL is needed, the skill can look it up via web_search and supply it to this skill.
- You can override the package name with `TUBI_PACKAGE` (default `com.tubitv`).

### Global-search fallback for non-YouTube/Tubi

- If YouTube/Tubi resolution does not apply and you pass `--app` with another provider (for example `hulu`, `max`, `disney+`), the skill uses a Google TV global-search fallback.
- For this fallback, pass all three: `--app`, `--season`, and `--episode`.
- `scrcpy` must be installed and available in the PATH for this flow.
- The fallback starts `android.search.action.GLOBAL_SEARCH`, waits for the Series Overview UI, opens Seasons, picks season/episode, then confirms `Open in <app>` when available.
- Hulu profile-selection logic is intentionally not handled here.

### Pause / Resume

`./run pause`
`./run resume`

### Dependencies

- The script uses only the Python standard library (no pip packages required).
- The scripts run through `uv` to avoid PEP 668/system package constraints.
- The script expects `adb`, `scrcpy`, `uv`, and `yt-api` to be installed and available in the PATH.

### Caching and non-destructive defaults

- The script stores the last successful device (ip and port) in `.last_device.json` in the skill folder.
- It will not attempt port scanning; this keeps behavior predictable and avoids conflicts with Google's ADB port rotation.

### Troubleshooting

- If adb connect fails, run `adb connect IP:PORT` manually from your host to verify the current port.
- If adb connect is refused and you're running interactively, the script will prompt you for a new port and update `.last_device.json` on success.
- **Connection refused after pairing**: If connection is refused:
  - Verify Wireless debugging is still enabled on the Chromecast
  - The device may need to be re-paired if it was restarted or Wireless debugging was toggled off
  - The interactive prompt will offer options to retry with a different port or re-pair
  - Use `./run pair --show-instructions` for detailed setup steps

## Implementation notes

- The skill CLI code lives in `google_tv_skill.py` in this folder. It uses subprocess calls to `adb`, `scrcpy`, and `yt-api`, plus an internal global-search helper for fallback playback.
- For Tubi URL discovery, the assistant uses web_search to find canonical Tubi pages and pass the https URL to the skill.


---

## Skill Companion Files

> Additional files collected from the skill directory layout.

### README.md

```markdown
# Chromecast with Google TV Skill

CLI tooling for controlling a Chromecast with Google TV over ADB. It plays YouTube or Tubi directly, and falls back to Google TV global search for other streaming apps.

## Requirements

- macOS/Linux host with `adb`, `scrcpy`, `yt-api`, and `uv` in your PATH
- Python 3.11+
- Chromecast with Google TV with Developer Options enabled and Wireless Debugging paired

## Setup

Before you can use this skill, you need to pair your Chromecast with ADB wireless debugging:

### First-time setup: Enable Wireless Debugging and Pair

1. **Enable Developer Options** on your Chromecast:
   - Navigate to Settings > System > About
   - Scroll down to "Android TV OS build"
   - Press SELECT on the build number 7 times
   - You'll see "You are now a developer!" message

2. **Enable USB Debugging and Wireless Debugging**:
   - Go back to Settings > System > Developer options
   - Turn ON "USB debugging"
   - Turn ON "Wireless debugging"

3. **Pair with pairing code**:
   - In Wireless debugging menu, select "Pair device with pairing code"
   - A dialog will show IP address, port, and a 6-digit pairing code
   - Use the `pair` command with these values:
   ```bash
   ./run pair --pairing-ip 192.168.1.100 --pairing-port 12345 --pairing-code 123456
   ```

4. **Get the connection port**:
   - After successful pairing, press BACK on the Chromecast remote
   - You'll see the Wireless debugging screen with IP address and port
   - Use these values for all other commands

**Note**: Pairing only needs to be done once. After pairing, you can connect directly using the device IP and connection port.

## Quick start

```bash
# Show pairing instructions
./run pair --show-instructions

# Pair with device (first time only)
./run pair --pairing-ip 192.168.1.100 --pairing-port 12345 --pairing-code 123456

# Once paired, use other commands
./run status --device 192.168.4.64 --port 5555
./run play "7m714Ls29ZA" --device 192.168.4.64 --port 5555
./run play "family guy" --app hulu --season 3 --episode 4 --device 192.168.4.64 --port 5555
./run pause --device 192.168.4.64 --port 5555
./run resume --device 192.168.4.64 --port 5555
```

## Commands

- `pair`: pair with Chromecast using wireless debugging (first-time setup)
- `status`: show `adb devices` output
- `play <query_or_id_or_url>`: play via YouTube, Tubi, or global-search fallback
- `pause`: send media pause
- `resume`: send media play

## Device selection

The CLI accepts `--device` (IP) and `--port` (ADB port).

- If only one of `--device` or `--port` is provided, the other is pulled from cache when available.
- If neither is provided, the tool uses the last successful device from `.last_device.json`.
- If no cache exists, it attempts ADB mDNS discovery and uses the first result.
- No port scanning is performed. Only explicit, cached, or mDNS-provided ports are tried.

## Content routing

1. If `play` looks like a YouTube ID or URL, it launches YouTube directly.
2. If it looks like a Tubi URL, it launches Tubi directly.
3. Otherwise it tries to resolve the query to a YouTube ID with `yt-api`.
4. If that fails and `--app`, `--season`, and `--episode` are provided, it uses global search.

## Global search fallback

Global search is implemented in [play_show_via_global_search.py](play_show_via_global_search.py). It expects the device to already be connected by the main CLI and only runs UI automation.

Use it by providing `--app`, `--season`, and `--episode` to `play`:

```bash
./run play "family guy" --app hulu --season 3 --episode 4 --device 192.168.4.64 --port 5555
```

## Environment variables

- `CHROMECAST_HOST`: default device IP
- `CHROMECAST_PORT`: default ADB port
- `YOUTUBE_PACKAGE`: YouTube app package override (default `com.google.android.youtube.tv`)
- `TUBI_PACKAGE`: Tubi app package override (default `com.tubitv`)

## Caching

The last successful device is stored in `.last_device.json` in this folder:

```json
{"ip": "192.168.4.64", "port": 5555}
```

## Tests

```bash
uv run test_google_tv_skill.py
uv run test_google_tv_skill.py -v
uv run test_google_tv_skill.py TestYouTubeIDExtraction
```

## Troubleshooting

- If `adb connect` fails, verify the current port: `adb connect IP:PORT`.
- If connection is refused while running interactively, the CLI will prompt for a new port and update the cache on success.
- **Connection refused after pairing**: If you get "connection refused" errors:
  - Verify Wireless debugging is still enabled on the Chromecast
  - The Chromecast may need to be re-paired if it was restarted or Wireless debugging was toggled off
  - Run the interactive prompt which will offer options to retry with a different port or re-pair
  - Alternatively, use `./run pair --show-instructions` to see detailed setup steps


```

### _meta.json

```json
{
  "owner": "antgly",
  "slug": "chromecast-with-google-tv",
  "displayName": "Chromecast With Google Tv",
  "latest": {
    "version": "1.2.0",
    "publishedAt": 1770965672275,
    "commit": "https://github.com/openclaw/skills/commit/5c66424a8fbfe8919cc563fa8c86806bc82eff06"
  },
  "history": [
    {
      "version": "1.1.0",
      "publishedAt": 1770584583627,
      "commit": "https://github.com/openclaw/skills/commit/e4d98bb383411d811200c58d9874ee915164838d"
    },
    {
      "version": "1.0.1",
      "publishedAt": 1770510363131,
      "commit": "https://github.com/openclaw/skills/commit/23cea7dbbf1b9042ccb713382a91f767ee63ae46"
    }
  ]
}

```