Skip to content

TouchStream · Technical docs

How it works underneath.

For the technically minded: what it runs on, the network, how it talks to YouTube, and how it stays up to date and secure. The full guides are in the repository.

How it fits together

TouchStream has two parts. A spoke sits beside each camera: it takes HDMI in, encodes it in hardware, and streams it. The hub runs on a computer you already have: it keeps the schedule, talks to YouTube, records every broadcast, and makes the edits, transcripts and Shorts.

While a broadcast is live, the spoke sends its video to the hub (SRT, on your network), and the hub sends it on to YouTube. Both record it. If the hub is off, the spoke streams straight to YouTube itself, from the copy of the schedule it keeps. Nothing goes through Cinderwire: there are no TouchStream servers.

The hub

Runs onInstalls with
macOS 12 or laterThe TouchStream installer, or one Terminal command
Windows 10 or 11The TouchStream installer, or one PowerShell command
Linux (systemd)One command
Docker, CoolifyThe image ghcr.io/cinderwire-co/touchstream-hub

It’s Python (FastAPI), with FFmpeg for video, MediaMTX to take streams in, and SQLite for its data. The installer brings everything it needs, in its own folder; it starts with the computer and keeps running in the background. The dashboard is a web page it serves, at http://localhost:8080 on its own computer or its address on your network from any other. A dashboard password protects it.

Recordings go to Movies/TouchStream (Videos on Windows and Linux), one folder per broadcast, or a folder you choose. Plan on about 3.6 GB per hour of 1080p at the default 8 Mbps.

The spoke

The spoke is an off-the-shelf box, the Luckfox PicoKVM (the version with the 1.54-inch touchscreen, on Amazon or from Waveshare), running TouchStream’s own software in place of its maker’s. Nothing to build or solder.

ProcessorRockchip RV1106G3: one Cortex-A7 core at 1.2 GHz, with a hardware H.264 encoder
Memory, storage256 MB RAM, 8 GB eMMC (TouchStream), a microSD card for recordings (32 GB comes with a spoke from us)
Video inHDMI, with its sound, 1080p at 24, 25, 30, 50 or 60 fps
Network, power10/100 Ethernet (no Wi-Fi), USB-C 5 V 2 A
Screen1.54-inch touchscreen: Go live, its recordings, their QR codes, setup

The software is Go, with a small C helper for capture and the encoder. A spoke bought from Cinderwire comes with it installed; for one of your own, the installer writes a microSD card that installs it. A new spoke calls itself by its chip (Spoke 4F2A) until it’s paired with a hub and named.

Network and ports

PortWhat for
8080/tcpThe dashboard, and spokes checking in (the installer picks the next free port if 8080 is taken)
8890/udpVideo from spokes to the hub (SRT)
1935/tcpVideo from other encoders: OBS, vMix, an ATEM (RTMP, optional)
9999/udpFinding spokes on the local network (their beacons)

A hub finds new spokes by their beacons, so it needs to be on the same network to adopt one with a click; anywhere else, a spoke pairs with a code entered on its screen. Each spoke then has its own token for the hub. When the hub is off, a spoke goes live on YouTube by itself, over the internet.

YouTube and Google

The hub uses the YouTube Data API v3 and Google’s device sign-in: you connect a channel by entering a code at google.com/device, and the hub then holds that channel’s sign-in and talks to Google directly. It signs in with TouchStream’s own Google OAuth client (a client of type “TVs and Limited Input devices”), which it reads from cinderwire.co once a day: just the client’s ID and secret, which Google treats as public for this kind of client. Nothing about you is sent. If you’d rather, use a client of your own instead, from your own Google Cloud project (step by step in the YouTube guide); each channel keeps the client it was connected with.

It asks for one permission, youtube (manage your YouTube account), and uses it to:

  • create each broadcast (title, description, time, visibility, thumbnail) and a stream for each spoke, and bind them
  • start and end the broadcasts it made, on time, and check their state
  • upload edited videos and Shorts when you choose Publish, and make a livestream private or unlisted if you ask
  • read your channel’s name and picture, and the view, like and comment counts of the videos it made (one quota unit per 50 videos)

Live broadcasts don’t count against YouTube’s upload limit; publishing edits does. If TouchStream’s shared allowance runs short, a Google client of your own has its own. Disconnecting a channel in Settings deletes its sign-in from the hub and gives the access back to Google. TouchStream’s use of YouTube API Services follows Google’s Limited Use requirements: see the privacy policy.

Transcripts and the assistant

Transcripts are made on the hub itself with Whisper (faster-whisper), on its own CPU or GPU, for free: the audio never leaves your computer. The model downloads once (150 to 500 MB, by the model you pick).

The assistant, which picks the moments for Shorts, plans the edits your edit profiles make (finding the message and the songs) and can schedule and edit for you, is optional and off until you add your own OpenRouter key. When it’s on, the transcript text it works from goes to the AI model you chose through OpenRouter, with an edit profile’s instructions and what it learned from your edits (in words); nothing else does.

AI agents and the API

The hub is an MCP server at http://<hub address>/mcp, and everything the dashboard does is in its API, described at /api/openapi.json (OpenAPI 3). Both take a token: Authorization: Bearer ts_….

The easy way to get one: tell your agent to read http://<hub address>/agent. It asks for access there, the request shows up in the dashboard with a code the agent shows you too, and you approve it, with less access than it asked for if you like. Or make a token in Settings, under Assistant and API.

AccessCan
Read onlySee everything, change nothing
ControlAlso schedule, go live, edit and publish
AdminAlso change the hub’s settings

Agents get fourteen tools: the hub at a glance (with its edit profiles); listing broadcasts and getting one (with paths to download each recording, or just its sound as an MP3); scheduling, changing and deleting broadcasts (once or repeating, with an edit profile); going live and ending; reading transcripts; editing by hand or with an edit profile; publishing; and making and publishing Shorts. It works with Claude Code, Cursor, VS Code, n8n and other apps that speak MCP:

claude mcp add --transport http touchstream http://192.168.1.20:8080/mcp --header "Authorization: Bearer ts_..."

Claude Desktop and claude.ai connectors sign in with OAuth, which the hub doesn’t offer yet. Agents on another network need to reach the hub: a hub on Coolify has an HTTPS address already; for one at home, use something like Tailscale. The full guide is in docs/api.md.

Updates

The hub checks GitHub for a new release every six hours. With automatic updates on, it updates itself when nothing is live or due within the hour and nothing is rendering or uploading; with them off, every dashboard page says when one is ready. A hub in Docker says when there’s a new image instead.

Spokes get their update from their hub when they’re idle. Each one is signed with TouchStream’s release key (Ed25519), and a spoke installs only what that key signed. It keeps the version before: if the new one can’t reach the hub after three starts, it goes back by itself.

Security

  • No way in by default. A spoke’s system has no telnet, and its SSH takes keys only, with none installed: the box maker’s published root password doesn’t open it.
  • No shared secrets. Neither the spoke’s software nor the installer carries a password, key or token of Cinderwire’s. Each hub makes its own tokens for its spokes; each channel’s YouTube sign-in is made on your hub and stays there. TouchStream’s Google client is public by Google’s design for device sign-in.
  • Open source, and yours to change. Everything is MIT-licensed on GitHub. You can build your own spoke image with your own SSH key in it (tools/picokvm_image.py --ssh-key), change anything, and run it your way.
  • On your network. The dashboard has a password; run the hub on a trusted network, and put it behind HTTPS if you open it to the internet.

Your data

Recordings, transcripts, edits and YouTube sign-ins stay on your hub and your spokes. Cinderwire never receives them. What the hub and spokes reach out to, and why:

ServiceWhy
Google (YouTube)Your broadcasts, uploads and view counts, with your permission
cinderwire.coReading TouchStream’s Google sign-in (its client ID and secret), once a day; nothing about you is sent
GitHubChecking for and downloading updates
OpenRouterOnly with your key: the assistant
ipinfo.io, ipapi.coA new spoke finding its time zone
CloudflareInternet speed tests, when you run one

Removing it

Open the installer and choose Remove the hub from this computer. Your settings and recordings stay for a hub installed again, unless you tick Remove its settings and recordings too, which moves them to the Trash (the Recycle Bin on Windows). Spokes wait for a hub until one is installed again; removing a spoke from a hub puts it back to setup, with its own name.

One touch and you’re live.

TouchStream is made by Cinderwire and released under the MIT License.

TouchStreamEvery featureTechnical docsPrivacy policyTerms GitHub