castor

Castor

Smart TVs won't cast arbitrary web video, and screen mirroring is laggy and drops resolution. Castor casts the real stream instead, at full quality, from your terminal.

Point Castor at a web page you are watching, or at a direct stream URL, and it finds the video, extracts the stream, transcodes it for your TV, and casts in real time. It can also resolve an IMDB/TMDB id against sources you configure yourself, and burn in auto-generated subtitles.

To extract, it launches headless Chrome and watches network traffic over the Chrome DevTools Protocol, then runs a short action pipeline to start playback: click the page, navigate into the largest iframe, and click again as a fallback. This works on pages that allow automated playback, and won't work everywhere.

A general-purpose casting tool: it casts only what you point it at. See Purpose and disclaimer.

_{Run castor cast to browse titles and cast, without leaving the terminal.}

Installation

Run Castor as a native binary (recommended): it runs on your machine, so it shares your TV's network, which device discovery needs. The binary shells out to three tools that must be on your PATH:

ffmpeg and ffprobe must be 7.1 or newer: Castor uses flags (-readrate_initial_burst, stricter HLS extension handling) that older builds reject. The Docker image bundles a suitable build (Linux only).

Homebrew (macOS)

brew install --cask stupside/tap/castor

git clone --recurse-submodules https://github.com/stupside/castor.git
cd castor
make          # builds libwhisper.a, then the castor binary

Quick start

Tell Castor which TV to use: find its name with castor scan and put it in config.yaml.

device:
  name: "Living Room TV"   # exact name from `castor scan`
  type: dlna

Can't discover the device? Pin it by address

If castor scan finds nothing, point Castor straight at the device by IP and it skips discovery:

device:
  name: "Living Room TV"   # now just a label
  type: dlna
  host: 192.168.0.3        # the device's LAN IP

Discovery uses SSDP/mDNS multicast, which doesn't cross VLANs/subnets and is blocked on Android/Termux (you'll see netlinkrib: permission denied). A pinned host reaches the device by unicast instead, so it works across those networks and skips the discovery wait on every cast.

• DLNA host is the device IP; Castor asks it for its description over a single unicast request. If your TV doesn't answer that, set host to its full description URL instead (e.g. http://192.168.0.3:9197/dmr).
• Chromecast / Roku host is the device IP.

On Android/Termux, also leave network.interface empty (the default): pinning one needs the same blocked interface lookup.

Now cast a page you are watching, or a stream URL you have:

castor cast player https://example.com/watch/some-video

For the interactive browser, which searches titles and casts them for you, add a TMDB key and a source (see Configuration), then run castor cast:

The commands you'll use most (run castor --help for all flags):

Configuration

Castor reads config.yaml from the working directory (or --config <path>). The only required key is the device shown in Quick start; everything else (timeouts, probing, capture, transcoding, network interface, Chrome discovery) has working defaults.

[!TIP] Keep secrets like your TMDB key out of the committed file: put them in a git-ignored config.local.yaml that overlays config.yaml, or in CASTOR_SECTION__FIELD environment variables. See SECURITY.md.

Everything below is optional.

sources:
  - proxies: ["https://your-source.example"]   # base URLs, tried in order
    templates:
      movie: "/embed/movie/{itemID}"
      episode: "/embed/tv/{itemID}/{season}-{episode}"

resolver:
  # The tallest video to cast. Source selection prefers the largest stream no
  # taller than this, and the encoder scales its output down to it. Defaults to
  # 1080; raise it to your TV's native height (e.g. 2160 for a 4K panel) to pass
  # 4K through, or lower it to save bandwidth.
  max_height: 2160
  # hls_timeout: 30s
  # probe_timeout: 30s
  # probe_max_concurrency: 2
  # ffprobe_path: ffprobe

tmdb:
  api_key: "<KEY>"

whisper:
  enable: true             # off by default
  # language: "fr"         # default: English
  # model_path: ""         # default: ggml-tiny.en (~75 MB, auto-downloaded)

device:
  name: "Living Room"   # the Roku's name, from `castor scan`
  type: roku
  roku:
    # Only needed the first time, to sideload Castor's channel (see below).
    password: "<dev-web-server-password>"

Supported devices

Run castor scan to list what is on your network.

Docker (optional)

The prebuilt ghcr.io/stupside/castor image bundles Chrome, ffmpeg, and ffprobe, so you install nothing by hand. Run it on a Linux host on the same LAN as your TV.

[!WARNING] --network host is required: device discovery (SSDP multicast) and the TV streaming back from Castor both need the container on your real LAN. On Docker Desktop (macOS/Windows) that flag is a no-op, so the container never reaches your TV and scan finds nothing. Use the native binary there instead.

# Discover devices (no config needed)
docker run --rm --network host ghcr.io/stupside/castor:latest scan

# Cast, passing the Intel GPU through for hardware transcoding
docker run --rm --network host --device /dev/dri \
  -v "$PWD/config.yaml:/config.yaml" \
  -v castor-cache:/root/.cache \
  ghcr.io/stupside/castor:latest \
  cast player https://example.com/watch/some-video

--device /dev/dri hands the container your Intel GPU for VA-API hardware H.264 encoding; without it (or on a non-Intel host) Castor falls back to software libx264. Either way, when your TV already accepts the source video Castor stream-copies it and skips encoding entirely.

Run commands from the directory holding your config.yaml (mounted at /config.yaml). The castor-cache volume persists the auto-downloaded whisper models.

Purpose and disclaimer

Castor is a general-purpose caster, not a service tied to any particular site.

• It hosts nothing. No bundled video, catalog, or sources: Castor casts only a page, stream URL, or source you supply and are authorized to use, much like a Chromecast.
• It does not touch DRM. Castor does not decrypt or circumvent DRM, and cannot cast DRM-protected services.
• Using it lawfully is your responsibility. Whether a site's terms of use and your local law allow what you do with Castor is on you. Do not use it to infringe copyright.

Castor is provided as-is for lawful, personal, and educational use.

Contributing

See CONTRIBUTING.md.