catt: casting YouTube and local files to a Chromecast from the command line

The gap catt fills between a browser tab and a television

Chromecast has no command line. A phone app or a browser button is the normal way to start playback, which is fine until the thing you want to watch is a URL you already have in a terminal, a file on a headless machine, or a page you want on a big screen without opening Chrome. catt exists for those cases. The README describes it as a way to send videos from many online sources to a Chromecast, plus local files and websites.

The intended user is someone with a shell prompt and a device on the same network. There is no daemon, no web interface and no account. You run a command, the cast starts. That makes it useful in scripts, in cron jobs and on machines that have no desktop session at all, which is exactly where the phone app cannot help you. It is not aimed at people who want a remote control with a touchscreen.

yt-dlp resolves the stream, pychromecast drives the device

catt is a thin orchestration layer, and the two dependencies named in the README explain the whole data flow. yt-dlp handles anything that is an online video source; the README states that catt supports any service yt-dlp supports, and links to yt-dlp's supported sites list, which runs to a few hundred entries. pychromecast handles discovery and control of the Chromecast itself. A third library, casttube, is credited for the YouTube Chromecast API.

That division has a consequence worth understanding before you install it. The set of sites that work is not fixed by catt; it moves with yt-dlp. The README is explicit about the failure mode that follows: if catt stops working with video sites, upgrade yt-dlp with pip install -U yt-dlp and that will probably fix it, because sites keep changing and yt-dlp is updated very regularly. So the reliability of the online-video path is inherited, not owned. When a site changes its player, you wait for yt-dlp, not for catt.

Local files take a different route. They are served from your machine to the device, which is why the README has a firewall section: for the casting of local files to work you need to allow the port range 45000-47000 over tcp. Online URLs do not need that, because the Chromecast fetches them itself. This is the single most common thing to get wrong on a machine with a restrictive firewall or a container network that is not bridged to the host.

Installing catt and casting your first video

catt requires Python 3.11 or higher. The README offers three install paths and ranks them: uvx to run it without installing, pipx as the recommended install, and pip with the note that it is not as good. For older Python versions the README points at catt 0.12.x, which supports Python 3.7 and later.

Running it without a permanent install is one command:

uvx catt

If you would rather have the catt command on your PATH, use pipx:

pipx install catt

The first real use is a URL. The README's example is a YouTube link, and the same form works for any site yt-dlp supports:

catt cast "https://www.youtube.com/watch?v=dQw4w9WgXcQ"

On success the video starts playing on the selected Chromecast. If you have more than one device on the network, the README documents a config file at ~/.config/catt/catt.cfg, with %APPDATA%\catt\catt.cfg on Windows and ~/Library/Application Support/catt/catt.cfg on macOS. It has an [options] section for a default device and an [aliases] section for short names:

[options]
device = chromecast_one

[aliases]
one = chromecast_one
two = chromecast_two

Rather than editing that file by hand, you can write to it from the CLI. To set the default device, run catt -d <name_of_chromecast> set_default. To create an alias, run catt -d <name_of_chromecast> set_alias <alias>. After that, catt -d <alias> <command> selects the device by short name.

Local files work the same way, provided the format is one the Chromecast supports natively: catt cast ./myvideo.mp4. Subtitles are handled automatically when the subtitle file has a name similar to the video file. Chromecast only supports WEBVTT, TTML and Line 21 subtitles, and the README notes that catt converts SRT to WEBVTT on the fly. To attach one explicitly:

catt cast -s ./mysubtitle.srt /myvideo.mp4

For a web page instead of a video, the README gives catt cast_site https://en.wikipedia.org/wiki/Rickrolling, with two caveats stated plainly: the Chromecast has a slow CPU but a reasonably recent version of Google Chrome, and the display resolution is 1280x720. Treat that as a rendering target, not a general purpose browser.

Playback control is available as subcommands, for example catt pause. Running catt --help lists the full set.

Where catt stops being the right tool

The clearest limitation is the one the README states itself: the Chromecast's CPU is slow and its rendering surface is 1280x720, so cast_site is not a way to put a demanding web application on a television. Pages that assume a desktop GPU, a large viewport or a modern JavaScript bundle will disappoint you.

Local file casting depends on the network path between your machine and the device. If the host is behind NAT, on a guest network, or inside a container without host networking, the 45000-47000 TCP range will not be reachable and the cast will fail even though discovery succeeded. The README's own Docker example uses --net=host for this reason.

The online path is only as good as the installed yt-dlp. On a system where you cannot upgrade packages, or where a distribution pins an old yt-dlp, sites will break and catt will look broken too. The README's advice is to upgrade yt-dlp rather than catt, which tells you where the maintenance burden actually sits.

Finally, the README does not document a mobile app, a graphical client or a Home Assistant integration. Search results for this project include phrases like "Skorokithakis catt android" and "Cast all the things Home Assistant", but the repository material describes a command line tool only. If your requirement is a phone remote or an automation platform integration, catt as documented does not provide it.

How catt differs from pychromecast and from Home Assistant casting

The honest alternative depends on what you actually want. If you want to write your own casting logic in Python, pychromecast is the lower level library that catt itself depends on, and the README credits it as the component that communicates with the Chromecast. Using pychromecast directly gives you control over discovery, media controllers and connection lifecycle, at the cost of writing and maintaining that code yourself. catt is the packaged, opinionated version of the same job: one command, sensible defaults, a config file.

If what you want is casting inside a home automation system, Home Assistant is the other route people search for, and it has its own casting support and its own dashboard casting component. The difference in approach is architectural: Home Assistant keeps a long running process that knows about your devices and exposes casting as an action inside automations, while catt is a one shot CLI invocation that exits. If your trigger is "when I press a button in my dashboard", Home Assistant fits. If your trigger is "this shell script just finished transcoding a file", catt fits, and there is no service to keep running.

Maintenance, releases and what the BSD licence means for you

The repository is not archived, and the last push was on 2026-08-30, the same day as the v0.13.2 release. The release history is worth reading before you depend on it: v0.12.0 landed on 2020-10-28, v0.13.0 (Arcane Anemone) on 2025-08-19, and v0.13.2 on 2026-08-30. That is a long quiet stretch followed by recent activity, so the project's cadence is bursty rather than steady. Plan for that.

The Python floor is a real upgrade cost. catt requires Python 3.11 or higher, and the pyproject file declares support for 3.11, 3.12 and 3.13. On a distribution that ships an older interpreter, your options are the 0.12.x line, which the README says supports Python 3.7 and later, or a container. The README's Docker example installs catt inside a python:3.7 image, which is consistent with that older line rather than with the current one.

The licence is BSD-2-Clause, listed in the repository as LICENSE and declared as BSD in the package metadata. In practical terms that is a permissive licence: you can use, modify and redistribute catt, including in closed products, provided the copyright notice and licence text are retained. This is a description of the licence terms, not legal advice; if you are redistributing catt inside a commercial product, read the LICENSE file and talk to your own counsel. Note also that catt pulls in yt-dlp, pychromecast, click, ifaddr and requests, each with its own licence, so a bundled distribution has more than one licence to account for.

Editorial conclusion

Adopt catt if you want a scriptable command line for pushing YouTube links, local media or a web page to a Chromecast and you are comfortable with Python packaging. Skip it if you need a GUI, a mobile client or a supported Home Assistant integration, because the README documents none of those. Before relying on it, verify that your host can open TCP ports 45000 to 47000 for local file casting, and check that yt-dlp is current, because the README states that stale yt-dlp is the usual cause when video sites stop working.

Frequently asked questions

Official sources

1. Issues
2. License: BSD-2-Clause
3. README
4. Releases
5. skorokithakis/catt on GitHub