Castor: casting web pages to a DLNA TV through headless Chrome and ffmpeg
Point it at any web page and it finds the video, extracts the stream, transcodes it and casts in real time to your TV. It even burns subtitles….
At a glance
- What is it?
- Castor is a Go program that opens a web page in headless Chrome, captures the video stream, transcodes it with ffmpeg and pushes it to a DLNA, Chromecast or Roku TV. This piece covers how its three services split the work, what each setup needs, and where the evidence for TV support is thin.
- Who is it for?
- Castor suits someone with a DLNA TV, Chrome and ffmpeg 7.1 or newer already on a computer, and a page or stream URL they are allowed to play. It is a poor fit for DRM-protected video, for Roku owners who need proven hardware support, and for anyone who wants to expose the API server beyond a trusted LAN.
- Can I use it commercially?
- Yes. MIT 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 received new commits within the last day.
- What is it written in?
- Mainly Go, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on November 22, 2026, and from our analysis. They are not legal advice.
Star history
- stupside/castor2,550 ★ · +173
| Repository | 2026-09-29 | 2026-11-22 |
|---|---|---|
| stupside/castor | 2.4k | 2.6k |
173 Stars in the last 54 days, measured from the daily GitHub snapshot. Compare with other projects
Editorial analysis
One binary, three services, and a Chrome dependency on the casting machine
Castor ships as a single binary that contains an API server, a scraping server and a media server. The API server finds TVs and controls playback, and every client talks to it over the castor.v1 API. The scraping server opens a page in headless Chrome and captures the video stream. The media server runs ffmpeg when the TV cannot play what the page serves, then serves the result to the TV.
Running castor cast starts all three inside one process, so a laptop needs no setup beyond the prerequisites: Chrome, plus ffmpeg and ffprobe at version 7.1 or newer, both on your PATH. On Windows the install notes give winget install Google.Chrome and winget install Gyan.FFmpeg, and then ask you to allow castor on private networks. The Go module pulls in chromedp for the browser side, goupnp for UPnP discovery and go-chromecast for the Chromecast protocol.
The consequence is that scraping is browser-based. A page that only reveals its stream after scripts run is reachable, but every cast carries the weight of a real Chrome instance, which is why the scraping service is the first one people move off a small machine.
Casting a page versus casting a stream URL are two different commands
The first step is castor scan, which lists the TVs on your network with the name and type to copy into config.yaml. The device block takes a name and a type, and the type must be dlna, chromecast or roku.
castor scandevice:
name: "Living Room TV"
type: dlna # dlna, chromecast, or rokuFrom there you choose between two entry points. castor cast player takes a web page that plays a video and runs the scraping step to find the stream. castor cast url takes a direct stream or video file, such as an m3u8 playlist, and skips the browser hunt.
castor cast player https://example.com/watch/some-video
castor cast url https://example.com/video.m3u8Three flags are worth knowing. --at 1h12m starts playback at a position. --dry-run lists the streams found without casting, which is the safe way to check whether castor can see anything on a page. --debug shows why castor made each decision. If a page exposes several candidate streams, --dry-run is where you find out before the TV is involved.
Configuration layers merge from four places, and the environment wins
Castor reads config.yaml from your user config directory or the current directory. On Linux that directory is ~/.config/castor/, on macOS it is ~/Library/Application Support/castor/, and on Windows it is %AppData%\castor\. Four layers merge, each over the one before: castor/config.yaml in the user directory, config.yaml in the current directory, the file passed with --config, and finally CASTOR_ environment variables.
The environment layer separates nesting levels with two consecutive characters, which the project's own example shows as CASTOR_CAST__MAX_HEIGHT=720. The Docker Compose file uses the same pattern for servers, for instance CASTOR_SERVERS__MEDIA__LISTEN and CASTOR_SERVERS__MEDIA__TOKEN. Inside a name a single separator is part of the key, so MAX_HEIGHT stays one setting while the doubled form descends a level.
Secrets such as the TMDB key belong in a git-ignored config.local.yaml sitting next to config.yaml. The practical risk is committing the main file with a key in it, since castor happily reads either. People upgrading from 1.x have a separate migration guide at migrations/1.x-to-2.0.md, and the version history shows 2.3.0, 2.4.0 and 2.5.0 landing between 22 and 27 October 2026, so settings may still be moving.
Only DLNA has TVs behind it; Chromecast and Roku are experimental
The support table ranks the protocols honestly. DLNA and UPnP are the main target, with reports from Samsung Q70 and Q80 sets (issue 15) and a Philips 50PUD6654 (pull request 23). Chromecast is marked experimental, with a Xiaomi TV Box (issue 5) and an LG C2 in Chromecast mode driven from the Android client (pull request 68). Roku is also experimental and is listed as not tested on hardware yet.
A Hisense VIDAA TV is reported working in the device discussion, but the report does not say which protocol it used. That matters if you own one, because you cannot tell whether to set type to dlna or chromecast without trying both.
The Roku path has the most manual work. You enable Developer Mode with a remote key sequence (Home three times, Up twice, then Right Left Right Left Right) and set a web server password. That password goes into servers.api.devices.roku.password in config.local.yaml, and castor installs its channel the first time you cast. Because no hardware test is recorded, a Roku owner is the first tester, not the second.
Moving transcoding to a NAS still needs the TV to reach the media address
Because each service is also a command, castor api-server, castor media-server and castor scraping-server can run on other machines. You give castor the URL of a remote server in config.yaml, and anything without a URL still runs locally. The setup table has three rows: everything on your computer, transcoding only on the NAS with castor media-server plus servers.media.url and its token, and everything on the NAS with docker compose up -d plus servers.api.url and its token.
docker compose up -dThe bundled docker-compose.yml shows the networking cost. The media server and the API server both use network_mode: host, with comments explaining why: on a Linux host, host networking lets TVs reach the advertised media address, and device discovery and control have to run on the TV's LAN rather than a bridge network. Only the scraping server publishes a port, as 127.0.0.1:8412.
The consequence is that the NAS route is Linux-shaped. Host networking behaves differently on Docker Desktop for macOS and Windows, and the compose file comments only address the Linux case, so a non-Linux NAS or desktop host needs its own verification before you trust it.
The Docker image runs Chromium without a sandbox and encodes on Intel GPUs only
The Dockerfile starts from debian:trixie-slim and installs ca-certificates, chromium, ffmpeg, fonts-liberation, libgomp1, libstdc++6 and libva2. When the build architecture is amd64 it also adds intel-media-va-driver and vainfo. The first comment in the file says Trixie's ffmpeg encodes on VA-API and that you should pass --device /dev/dri, and the compose file mounts /dev/dri accordingly, with a comment telling you to drop that line on hosts without it.
Two environment defaults deserve attention. CASTOR_SERVERS__SCRAPING__BROWSER__CHROME_PATH points at /usr/bin/chromium, and CASTOR_SERVERS__SCRAPING__BROWSER__NO_SANDBOX is set to true. Disabling the Chromium sandbox is a common container workaround, but it means pages you scrape run in a browser without that isolation layer, so only point the scraping server at pages you would open yourself.
Hardware encoding is limited by the driver packages. The Intel VA-API driver is installed only for amd64, so an arm64 image has no equivalent driver in the Dockerfile. The platform table agrees: Linux on x86-64 and arm64 can use npm, a release download or Docker, and the Docker image is the one that encodes on Intel GPUs.
The compose file refuses to start without three tokens, and the title browser needs your own sources
Each service in docker-compose.yml reads a token from the environment with a required-variable guard that fails with the message set it in .env. That covers CASTOR_SERVERS__API__TOKEN, CASTOR_SERVERS__MEDIA__TOKEN and CASTOR_SERVERS__SCRAPING__TOKEN. The api-server also depends_on the media and scraping services and addresses them at 127.0.0.1:8410 and 127.0.0.1:8412. The image tag is ghcr.io/stupside/castor:latest, so a docker compose pull moves you to whatever is newest, with no version pinned.
The title browser has its own prerequisites. castor cast with no arguments opens a terminal UI where you search TMDB or browse what is trending, pick a title and a TV, and castor finds it on your sources. That needs a free TMDB key and at least one source with proxies and templates.
tmdb:
api_key: "<KEY>"
sources:
- proxies: ["https://your-source.example"]
templates:
movie: "/embed/movie/{itemID}"
episode: "/embed/tv/{itemID}/{season}-{episode}"Castor ships no content and no sources, and it refuses DRM streams. If you have no site you are authorized to use, the TUI has nothing to search, and castor cast movie or castor cast episode with --season and --episode flags will find nothing either. Direct URLs through castor cast url remain the way to play your own material.
Editorial conclusion
Castor suits someone with a DLNA TV, Chrome and ffmpeg 7.1 or newer already on a computer, and a page or stream URL they are allowed to play. It is a poor fit for DRM-protected video, for Roku owners who need proven hardware support, and for anyone who wants to expose the API server beyond a trusted LAN. Before relying on it, run castor scan against your own TV and try castor cast player with --dry-run on one page.
Frequently asked questions
What does Castor need installed before it can cast a web page?
Castor needs Chrome and ffmpeg plus ffprobe at version 7.1 or newer on your PATH. Installation is brew install --cask stupside/tap/castor on macOS, or npm install -g @castor-dev/cli on any platform with Node 20 or newer.
Which TVs does Castor work with?
DLNA and UPnP is the main target, with Samsung Q70 and Q80 and a Philips 50PUD6654 reported working. Chromecast and Roku are experimental, and Roku has not been tested on hardware yet.
Can Castor run its services on a NAS?
Yes. castor media-server moves only transcoding to another machine, and docker compose up -d runs the whole stack there. In both cases you add the server URL and token to config.yaml.
Does Castor play DRM-protected video?
No. Castor refuses DRM streams and ships no content and no sources, so it is meant for video you are allowed to watch.
Official sources
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.
[](https://hysenlabs.com/projects/stupside-castor)Star history chart for your README
[](https://hysenlabs.com/projects/stupside-castor)Was this useful?