gaspode

gaspode is a Go-powered Chromecast toolbox for local playback, UPnP-backed media handoff, live screen sharing, and a compact embedded control UI.

It discovers available devices, can stream hosted or uploaded video files, can browse a UPnP or DLNA media server and relay one of its videos to Chromecast, shares full screens or single app windows through an on-the-fly media endpoint, and ships with a browser-based control plane embedded directly into the binary. In practice that means you can send a local or remote video to a TV, pick a movie from a media server without leaving the UI, use your desktop or a single app window as a live Chromecast source, browse host-side media without opening a terminal, and even hand control over to your phone by scanning the built-in QR code for the web UI.

Features

• Chromecast discovery with mDNS plus network-scan fallback
• CLI workflows for listing devices, sending media, and sharing screens
• Embedded web UI for device selection, source picking, audio options, UPnP browsing, stream control, and QR-based phone handoff
• Web UI host-file browsing restricted to an explicit media base directory
• UPnP or DLNA media-server browsing with direct Chromecast relay
• Local file streaming from the host machine without duplicating large source files
• Optional compatibility mode for Chromecast-friendlier MP4/H.264/AAC delivery
• Optional seekable-index creation for local media when Chromecast scrubbing matters
• Audio device enumeration for Windows and Linux screen-audio setups
• macOS screen capture support for full-screen sharing through FFmpeg avfoundation
• Cross-platform build targets for Linux, macOS, and Windows via Makefile, including release-ready arm64 artifacts
• GitHub Actions for tests, vulnerability checks, packaged release artifacts, and tag-based releases with checksums
• Optional GitLab CI/CD support for the same build and release flow

Installation

Download a release build

Download the archive that matches your platform from the GitHub Releases page, extract it, and place the gaspode binary somewhere on your PATH.

Release archives are published for:

• Linux amd64
• Linux arm64
• macOS amd64
• macOS arm64
• Windows amd64
• Windows arm64

Build from source

Requirements:

• Go 1.25.0 or newer
• Node.js 22 or newer for the embedded web UI build
• ffmpeg available on your PATH for media transcoding and live capture

gaspode relies on ffmpeg for the media-heavy parts of the experience, including live capture, compatibility transcoding, and seekable playback preparation.

ffmpeg is required for:

• local compatibility transcoding
• seekable MP4/index creation
• live screen capture
• live window capture

Build the project:

go mod tidy
make build

The compiled binaries are written to bin/.

Optional platform tools

Some workflows rely on extra OS tools:

• Linux audio device enumeration uses pactl
• Linux window enumeration uses wmctrl

macOS capture notes

On macOS, live screen capture uses FFmpeg's avfoundation input and requires Screen Recording permission for the gaspode process or the terminal app that starts it.

Current macOS limitations:

• full-screen capture is supported
• window preview is supported through the native screencapture tool
• window capture is supported
• screen-audio capture is not implemented

Quick Start

go mod tidy
go run ./cmd/gaspode list --to-json
go run ./cmd/gaspode send --device-name "Living Room TV" --media-url "https://samplelib.com/mp4/sample-5s.mp4"
go run ./cmd/gaspode send --device-name "Living Room TV" --media-url "F:\media\movie.mkv" --compatibility --create-index
go run ./cmd/gaspode screen --device-name "Living Room TV"
go run ./cmd/gaspode screen --device-name "Living Room TV" --latency-profile low
go run ./cmd/gaspode --web-ui=127.0.0.1:11999 --media-base-path "F:\\media"
go run ./cmd/gaspode --web-ui=0.0.0.0:11999 --web-ui-advertise "http://192.168.2.123:11999" --media-base-path "F:\\media"

On macOS, the screen workflow can capture either the full screen or a selected window and may trigger a Screen Recording permission prompt the first time it is used.

Open http://127.0.0.1:11999 after starting the web UI.

If you want to scan the built-in QR code from your phone, bind the web UI to a LAN-reachable address and optionally override the advertised URL with --web-ui-advertise.

Inside the web UI you can choose between host-file streaming, uploaded files, UPnP or DLNA media-server browsing, full-screen sharing, and single-window sharing.

Example Commands

go run ./cmd/gaspode list
go run ./cmd/gaspode list --to-json --timeout 10s --debug-discovery
go run ./cmd/gaspode audio-devices --to-json
go run ./cmd/gaspode send --device-name "Living Room TV" --media-url "F:\media\movie.mkv"
go run ./cmd/gaspode send --device-name "Living Room TV" --media-url "F:\media\movie.mkv" --compatibility
go run ./cmd/gaspode send --device-name "Living Room TV" --media-url "F:\media\movie.mkv" --compatibility --create-index
go run ./cmd/gaspode screen --device-name "Living Room TV" --audio-device "Stereo Mix (Realtek(R) Audio)"
go run ./cmd/gaspode screen --device-name "Living Room TV" --latency-profile stable
go run ./cmd/gaspode --web-ui=127.0.0.1:11999 --media-base-path "F:\\media"
go run ./cmd/gaspode --web-ui=0.0.0.0:11999 --web-ui-advertise "http://192.168.2.123:11999" --media-base-path "F:\\media"

Web UI Parameters

• --web-ui starts the embedded control UI on the given listen address
• --media-base-path is required when --web-ui is enabled and restricts the host file browser to that directory tree
• --web-ui-advertise overrides the URL shown in the QR code and preferred for phone access

Typical QR-code setup:

go run ./cmd/gaspode --web-ui=0.0.0.0:11999 --web-ui-advertise "http://192.168.2.123:11999" --media-base-path "F:\\media"

Build

make build
make release

Artifacts are written to bin/:

• gaspode-linux-amd64
• gaspode-linux-arm64
• gaspode-darwin-amd64
• gaspode-darwin-arm64
• gaspode-windows-amd64.exe
• gaspode-windows-arm64.exe
• SHA256SUMS after make release

License

Apache 2.0. See LICENSE.

Documentation

• CLI usage
• Web UI and streaming workflows
• Development and build notes

Project Layout

• cmd/gaspode - CLI entrypoint
• internal/app - app lifecycle and signal handling
• internal/cli - Cobra command definitions
• internal/chromecast - discovery, device loading, and session management
• internal/controlplane - embedded HTTP control plane and web UI
• internal/controlplane/webui - React Native Web frontend compiled into the Go binary
• internal/streamendpoint - local media and live-capture endpoints