CLI tool
skorokithakis/catt avatar
skorokithakis/catt

catt casts a web page, a local file, or anything yt-dlp can reach

Cast All The Things allows you to send videos from many, many online sources to your Chromecast.

3,720 stars176 forksPythonBSD-2-Clause

At a glance

What is it?
skorokithakis/catt is a command line client for Chromecast devices whose real dependency is not the cast protocol but a downloader. It supports any site the yt-dlp project handles, converts subtitle formats the device cannot read, and the readme's most useful section is the one on why the tool breaks every few months.
Who is it for?
catt suits someone who wants to send a video, a photo or a web page to a screen from a terminal, and who already runs a downloader on the same machine. It does not suit someone who needs a stable service, because the readme says outright that sites change and the tool will stop working until its dependency is upgraded.
Can I use it commercially?
Yes. BSD-2-Clause is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
Is it still maintained?
Yes. The repository last received commits 52 days ago.
What is it written in?
Mainly Python, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 14, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • skorokithakis/catt3,720 ★ · +23
Star history
Repository2026-09-242026-11-14
skorokithakis/catt3.7k3.7k

23 Stars in the last 51 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

Three install routes and one version floor

The README documents three options: `uvx catt` runs it without a permanent install, `pipx install catt` installs the command in an isolated environment, and `pip3 install catt` uses pip. The current release requires Python 3.11 or later; the README points users on Python 3.7 and newer to catt 0.12.x.

Casting a page and casting a file take different commands

Cast an online video with `catt cast "https://example.com/video"`, or a local file with `catt cast ./myvideo.mp4`. The device must support the local format natively. To display a website use `catt cast_site https://example.com`; `catt pause` pauses playback, and `catt --help` lists the available commands. Online source support depends on yt-dlp.

Subtitles are converted on the fly

Subtitle handling is a small feature with a large amount of detail behind it, and it is the clearest example of the tool accommodating the device rather than the reverse. The device supports three subtitle formats. If you have subtitles and the filename is similar to the local video's name, the tool picks them up automatically. If you want a specific file, you name it. And if your subtitles are in the widely used format that the device does not accept, the tool converts them during streaming rather than asking you to convert them first. The result is that the failure mode a cast is most prone to, subtitles appearing at the wrong time or not at all, is handled by the tool instead.

A slow CPU and a fixed resolution

There is a short paragraph of hardware reality that is worth reading before choosing what to cast. The device has a slow processor and a reasonably recent browser engine, and the display resolution is fixed at a modest size. Two consequences follow. A heavy page will render slowly, because the work happens on the device rather than on your machine, which is the opposite of how a networked renderer behaves. And content designed for a large display will be scaled down into a fixed canvas, so a page laid out for a desktop monitor will not use the space. Neither point is framed as a limitation to work around; they are stated so that a reader choosing what to send knows what they are sending.

That paragraph also explains a design choice visible elsewhere: casting a website is a separate verb rather than a flag on the video command, because it is a different operation on the device. A video is fetched and played by the device's own media stack, while a page is handed to its browser. Treating them as one command with a mode argument would imply they share a code path, and they do not.

Two config locations, two commands, and an alias section

The configuration file lives at one path per platform, and the readme gives all three: a dot-directory under the user's home on Linux, an application-data path on Windows, and the conventional application support path on macOS. The file has two sections. The options section holds one setting, the default device, which is what gets selected when you have not named one on the command line. The aliases section holds names for your devices, so you can select by alias instead of by the long name the device advertises. Both can be written by hand, and both can be written by the tool, with one subcommand to set the default and another to set an alias. So the config file is optional, and the tool will create the settings you want.

Local file casting needs a port range opened

There is a firewall section and it exists for one reason. Casting a local file works differently from casting a stream: the device has to fetch the file from your machine, which means your machine has to accept an inbound connection on a port it chooses from a range. The README specifies inbound TCP ports 45000–47000 for local-file casting. The stated requirement specifically concerns local-file casting. Anyone deploying this on a locked-down network should note that the requirement is an inbound allowance, not an outbound one.

The readme tells you the tool will break, and why

The most useful paragraph in the documentation is the one about failure. It says that if the tool stops working with video sites, you should upgrade the downloader dependency, and that this will probably fix it, because sites keep changing and the downloader is updated very regularly to keep them all working. That is a candid statement of the architecture: this tool has no video extraction of its own, so its reliability is bounded by a third party's ability to keep up with a moving web. The readme also notes that passing options through to the downloader requires its internal option name rather than its command line name, which is a small signpost pointing at exactly how entangled the two are.

bash
python -m catt.cli --help

Editorial conclusion

catt suits someone who wants to send a video, a photo or a web page to a screen from a terminal, and who already runs a downloader on the same machine. It does not suit someone who needs a stable service, because the readme says outright that sites change and the tool will stop working until its dependency is upgraded. Before adopting it, decide whether you want the no-install route or a permanent install, remember that local file casting needs a range of inbound ports opened, and plan on keeping the downloader current rather than the tool.

Frequently asked questions

How do I install catt without installing anything?

Run `uvx catt` without a permanent installation, install with `pipx install catt`, or use `pip3 install catt`. The README requires Python 3.11 or later; for Python 3.7 and newer it points to catt 0.12.x.

What can catt cast to a Chromecast?

Three separate things, each with its own command: a video from any online source the downloader dependency supports, a local file in a format the device plays natively, and any website. The device can also be driven directly through the same commands, for example to pause playback.

Why does catt stop working with video sites?

Because the tool has no extraction logic of its own and inherits the support of a third-party downloader, which the readme says is updated very regularly to keep up with sites that keep changing. The documented fix is to upgrade that dependency, which the readme says will probably resolve it.

Official sources

  1. Issues
  2. License: BSD-2-Clause
  3. README
  4. Releases
  5. skorokithakis/catt on GitHub
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/skorokithakis-catt.svg)](https://hysenlabs.com/projects/skorokithakis-catt)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/skorokithakis-catt.svg)](https://hysenlabs.com/projects/skorokithakis-catt)

Was this useful?