Better and Cheaper Than IPTV: An Overview of Castor

Castor is a powerful utility designed to bridge the gap between web-based video content and your living room. While most Smart TVs refuse to cast random web videos and screen mirroring is notoriously laggy with poor resolution, Castor solves this by casting the actual stream at its original quality directly from your command line.

🛠 How It Works

Castor doesn't just mirror your screen; it intercepts the media. When you provide a URL, Castor:

1. Launches a headless Chrome instance.
2. Monitors network traffic via the Chrome DevTools Protocol.
3. Executes a fallback action pipeline (clicking the page $\rightarrow$ entering the largest iframe $\rightarrow$ clicking again).
4. Extracts the raw stream, transcodes it for TV compatibility, and casts it in real-time.

Note: This method relies on the page allowing automated playback; therefore, it is not a universal solution for every single website on the internet.

---

🚀 Getting Started

Installation Options

Depending on your OS, you have several ways to get Castor running. It requires ffmpeg, ffprobe, and Chrome/Chromium to be available in your system's PATH.

Building from source: If you choose the source route, remember that go install will not work because of the local whisper.cpp bindings. Use this sequence:

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

Quick Start Checklist

• Run castor scan to identify your TV's name.
• Add the device name to your config.yaml.
• Execute castor cast player <URL> to start streaming.
• (Optional) Add a TMDB key to use the interactive castor cast browser.

---

⚙️ Configuration

Castor utilizes a config.yaml file (or a custom path via --config). To keep your private keys safe, it is recommended to use a config.local.yaml file (which should be git-ignored) or environment variables following the pattern CASTOR_SECTION__FIELD.

Device Setup

The only mandatory configuration is the target device:

device:
  name: "Living Room TV" # Must match 'castor scan' output
  type: dlna

Custom Sources

Castor does not come with built-in catalogs. Instead, you define your own authorized sources using proxies and templates. For example, if you use a source that follows a specific URL pattern, you can configure it like this:

sources:
  - proxies: ["https://your-source.example"]
    templates:
      movie: "/embed/movie/{itemID}"
      episode: "/embed/tv/{itemID}/{season}-{episode}"

Example: Running castor cast movie tt12300742 would resolve to https://your-source.example/embed/movie/tt12300742.

TMDB & Subtitles

• TMDB: To use the interactive terminal browser, provide an API key from themoviedb.org in your config under tmdb: api_key: "KEY".
• Subtitles: Castor can use Whisper to generate and burn-in subtitles.

  whisper:
    enable: true # Set to true to activate
    language: "en" # Default is English
    model_path: "" # Defaults to ggml-tiny.en (~75 MB)
  

---

📺 Compatibility & Deployment

Supported Hardware

Castor works with any device implementing the MediaRenderer:1 profile of DLNA/UPnP. This includes almost every major brand from the last decade:

• Samsung, LG, Sony Bravia
• Panasonic Viera, Philips, Hisense
• TCL, VIZIO, Sharp

Docker Considerations

While a Docker image is available for Linux, it comes with networking caveats. Because discovery relies on SSDP multicast, you must use --network host.

On macOS or Windows, Docker Desktop runs in a VM, meaning the container is isolated on a subnet such as: $\text{Subnet} = 192.168.65.x$ Because this is not the same as your local LAN, the --network host flag is a no-op and the TV will not be discoverable. Use the native binary instead.