chromecast

name	chromecast
description	Control Chromecast devices on your local network - discover, cast media, control playback, manage queues, and save/restore states
homepage	https://github.com/skorokithakis/catt
metadata	{"clawdbot":{"emoji":"📺","requires":{"bins":["catt"]},"install":[{"id":"pip","kind":"uv","package":"catt","bins":["catt"],"label":"Install via pip/uv"}]}}

Chromecast Control

Control Chromecast and Google Cast-enabled devices on your local network using catt (Cast All The Things).

Quick Reference

Command	Description
catt scan	Find all Chromecasts on network
catt cast <url>	Cast video/audio
catt pause / play	Pause/resume
catt stop	Stop playback
catt status	Current playback info
catt volume <0-100>	Set volume

Use -d <device> to target a specific device by name or IP.

Discovery & Device Management

# Find all devices
catt scan

# Set a default device (saves to config)
catt -d "Living Room TV" set_default

# Create an alias for easier access
catt -d 192.168.1.163 set_alias tv

# Remove alias or default
catt -d tv del_alias
catt del_default

Casting Media

Basic Casting

# Cast from URL (YouTube, Vimeo, and hundreds of yt-dlp supported sites)
catt cast "https://www.youtube.com/watch?v=VIDEO_ID"

# Cast local file
catt cast ./video.mp4

# Cast a website (displays webpage on TV)
catt cast_site "https://example.com"

Advanced Cast Options

# Cast with subtitles
catt cast -s ./subtitles.srt ./video.mp4

# Start at specific timestamp
catt cast -t 01:30:00 "https://youtube.com/watch?v=VIDEO_ID"

# Play random item from playlist
catt cast -r "https://youtube.com/playlist?list=PLAYLIST_ID"

# Play only video (ignore playlist in URL)
catt cast -n "https://youtube.com/watch?v=VIDEO_ID&list=PLAYLIST_ID"

# Disable automatic subtitle loading
catt cast --no-subs ./video.mp4

# Pass yt-dlp options (e.g., select format)
catt cast -y format=best "https://youtube.com/watch?v=VIDEO_ID"

# Block until playback ends (useful for scripts)
catt cast -b "https://example.com/video.mp4"

Playback Control

catt play              # Resume playback
catt pause             # Pause playback
catt play_toggle       # Toggle play/pause
catt stop              # Stop playback completely
catt skip              # Skip to end of content

# Seeking
catt seek 300          # Jump to 5 minutes (seconds)
catt seek 01:30:00     # Jump to 1h 30m (HH:MM:SS)
catt ffwd 30           # Fast forward 30 seconds
catt rewind 30         # Rewind 30 seconds

Volume Control

catt volume 50         # Set volume to 50%
catt volumeup 10       # Increase by 10
catt volumedown 10     # Decrease by 10
catt volumemute on     # Mute
catt volumemute off    # Unmute

Queue Management (YouTube)

# Add video to end of queue
catt add "https://youtube.com/watch?v=VIDEO_ID"

# Add video to play next
catt add -n "https://youtube.com/watch?v=VIDEO_ID"

# Remove video from queue
catt remove "https://youtube.com/watch?v=VIDEO_ID"

# Clear entire queue
catt clear

State Management

# Save current state (position, volume, what's playing)
catt save

# Restore saved state later
catt restore

Device Information

catt status    # Brief: time, volume, mute status
catt info      # Full: title, URL, player state, media type, etc.

Configuration

Config file: ~/.config/catt/catt.cfg

[options]
device = Living Room TV

[aliases]
tv = Living Room TV
bedroom = Bedroom Speaker

Network Requirements

• Chromecast and computer must be on same network
• For local file casting: TCP ports 45000-47000 must be open
• Some networks block mDNS - use IP address directly if catt scan fails

Supported Sources

Catt uses yt-dlp internally, supporting:

• YouTube (videos, playlists, live streams)
• Vimeo, Dailymotion, Twitch
• Direct video URLs (MP4, MKV, WebM, etc.)
• Local files (video, audio, images)
• Hundreds more sites (see yt-dlp supported sites)