wittycouch

package module
v0.2.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 2, 2026 License: Apache-2.0 Imports: 3 Imported by: 0

README

WittyCouch

Plays the games on any PC running Sunshine, in your browser, through WittyMediaServer. You need it if you, or a friend, have a gaming PC with Sunshine on it.

It isn't part of, or made by, the Moonlight or Sunshine projects.

The Game PCs page

Game PCs in WittyMediaServer, on a server with none added yet.

The Game PCs page in Settings

Settings, Game PCs, on a server with none added yet.

What it does

  • Finds PCs and pairs with them using a PIN, with the PC's certificate pinned.
  • Lists a PC's games, and starts, resumes and quits them. It can wake a PC.
  • Plays them in the page with controllers, keyboard, mouse and touch. Frames travel over WebRTC and aren't decoded or re-encoded on the server.
  • Hands off to the separately installed Moonlight app on a device that can't play in a page.

Playing needs WittyCouch Host, a separate program. Without it, everything but playing still works. It connects to a PC someone else may run, and what that PC offers isn't provided or checked. No games come with it.

How to use it is in Help inside WittyMediaServer: see Game PCs.

How to get it

An admin adds it from the module store inside WittyMediaServer: Settings → Modules, then Browse the store, then Add beside WittyCouch. That needs WittyMediaServer 0.6.0-alpha or later, and it works with nothing older. The range this version fits is in module.json: 0.6.0-alpha through 0.6.x.

Adding it brings WittyCouch Host, which it's built on.

What it needs

  • WittyCouch Host, which carries the stream.
  • A PC running Sunshine, which you set up yourself.
  • It asks the server for three permissions: network, running programs, and data.

It's built on pion/webrtc and WittyModule, built in. It's written in Go with no cgo, and the player in web/ is React.

Platforms

A real browser, Edge on Windows, has played a real stream from a real Sunshine. Real games on real gaming PCs haven't been tried yet.

A program is built for each system below, and the server uses the right one.

System Where it stands
Linux (x64, arm64, 32-bit ARM, x86) Its tests pass on x64, and it installs on a test server with its host. The other CPUs are only built
Windows (x64, arm64) Built. This version hasn't been run on Windows since it became its own program
macOS (Intel, Apple silicon) Built by the release tool. It has not been run on a real Mac
FreeBSD (amd64, arm64) Cross-compiled only. It has not been run

On macOS and FreeBSD the server has no sandbox for a module's helper: it gets a small environment and a soft memory limit, and nothing more.

WittyCouch Host has no FreeBSD build, so on FreeBSD the store says so in place of Add. It also has none for 32-bit Linux or Windows on arm64.

Building and testing

You need Go 1.26 or newer. In a worktree, first run the copy of dev-modules.mjs kept above the repositories (node D:/projects/dev-modules.mjs on the development machine). It writes a go.work that git ignores, so the checkout builds against the repositories beside it. Never run go work use.

go vet ./...
go test ./... -count=1
go run github.com/wittywilla/wittymodule/cmd/wittymodule check .

The last one checks the manifest. On the same tool, pack -targets linux/amd64 -out release . builds a release for one system. CI also builds for every system.

npm install
npm run build:bundle

Automated tests run gamestream against the stand-in for Sunshine in gamestream/fake, and relay over real WebRTC with a stand-in for the host program. To test against a real Sunshine:

WITTYCOUCH_REAL=127.0.0.1 WITTYCOUCH_USER=name WITTYCOUCH_PASS=secret go test ./gamestream -run TestRealSunshine -v
WITTYCOUCH_REAL=127.0.0.1 WITTYCOUCH_USER=name WITTYCOUCH_PASS=secret WITTYCOUCH_HOST=/path/to/wittycouch-host go test ./relay -run TestRealStream -v
Part What for
gamestream A PC's client API: Browse, Rig.Pair, Apps, AppImage, Launch, Resume, Quit, Wake, and the rules on which addresses may be reached
relay Runs WittyCouch Host and carries its frames to a browser over WebRTC, and input back
web The player
plan.go What each device can do when it can't play in a page

facade.json lists what the server calls in this module. Changing it means rerunning the generator in WittyModule's kit/facade, which writes the stubs on both sides.

Licence

Apache-2.0: see LICENSE and NOTICE. If you redistribute it or build on it, keep the NOTICE attribution. It contains no Moonlight or Sunshine code. Linked in: pion/webrtc and its dependencies (MIT).

To stream, it starts WittyCouch Host, a separate program under the GPL-3.0, built on moonlight-common-c. The two only exchange the messages in that program's PROTOCOL.md, over pipes. Moonlight and Sunshine are GPL-3.0 programs. Each release archive carries a THIRD-PARTY-NOTICES.txt for what its programs link.

WittyCouch is an independent open-source project. It isn't associated with, sponsored by or endorsed by the Moonlight or Sunshine projects, NVIDIA, or any game publisher. It connects to a PC someone else may run, and what that PC offers isn't provided or checked by this project. No games come with it. Any third-party names here only describe what it works with, and belong to their owners. It's provided “as is”, with no warranty; see LICENSE. Local law applies to how you use it. This isn't legal advice.

Releasing

A version tag builds a program for every platform, signs the checksum list, and publishes a release that servers can install.

Versions move in small steps as work lands. go run github.com/wittywilla/wittymodule/cmd/wittymodule@v0.3.0 bump . raises it everywhere it is written (add -part minor for a bigger step). A bump isn't a release: nothing is tagged or published until you tag it. CI fails when code changed since the last tag and the version didn't, because tags never move.

To release:

  1. Check that version in module.json is the one to publish, with the bump committed.
  2. Tag that commit and push the tag: git tag vX.Y.Z, then git push origin vX.Y.Z. A tag with a suffix, such as v1.2.0-beta, is published as a prerelease.
  3. Watch the Actions tab. The signing step uses the WMS_SIGNING_KEY secret of the release environment, and nothing is published without it.

To take a version back, run the withdraw workflow from the Actions tab. It adds the version to a signed list on the release tagged withdrawals, which servers read.

Licensed under Apache-2.0: see LICENSE and NOTICE.

Documentation

Overview

Package wittycouch gets a person from "Play" to a game running on a PC with Sunshine: it works out what each device can really do, and falls back to the separately installed Moonlight app where a page can't play. The stream goes through relay and the separate WittyCouch Host. It contains no Moonlight code, which is GPL-3.0: see docs/GAME-RIGS.md.

Index

Constants

View Source
const (
	AndroidPackage  = "com.limelight"
	AndroidActivity = "com.limelight.ShortcutTrampoline"
)

The Moonlight app on Android: an activity it exports for launcher shortcuts takes a PC and an app by these names.

Variables

View Source
var ManifestJSON []byte

ManifestJSON is this module's manifest (docs/MODULES.md, "The manifest").

Functions

func MoonlightArgs

func MoonlightArgs(t Target) []string

MoonlightArgs are the arguments that start a game with the desktop Moonlight app. Nil means this game's name can't be passed safely.

func PairArgs

func PairArgs(address string, port int, pin string) []string

PairArgs are the arguments that make the desktop Moonlight app ask a PC to pair, with a PIN chosen in advance so it can be shown anywhere.

func SetupSteps

func SetupSteps(os, rigName, address string, port int) []string

SetupSteps is how a device pairs with a rig the first time, in words for that device.

Types

type Credit

type Credit struct {
	Name    string `json:"name"`
	Role    string `json:"role"`
	License string `json:"license"`
	Source  string `json:"source"`
}

Credit says what a piece is, under what licence, and where its source is, for anywhere that shows licences. Being clear about this is part of using other people's work properly.

func Credits

func Credits() []Credit

Credits lists every piece a game stream goes through.

type Device

type Device struct {
	Client string `json:"client"` // browser, desktop (the desktop app), android (the Android app), apple (the Apple app)
	OS     string `json:"os"`     // windows, mac, linux, chromeos, android, androidtv, firetv, ios, tvos, or anything else
}

Device is what a client says it is.

type Extras

type Extras map[string]string

Extras are an Android intent's string extras.

type Install

type Install struct {
	Name    string `json:"name"`
	URL     string `json:"url"`
	Note    string `json:"note,omitempty"`
	License string `json:"license"`
	Source  string `json:"source"`
}

Install says where this device gets the Moonlight app.

func InstallFor

func InstallFor(os string) *Install

InstallFor says where to get Moonlight for an OS, from the Moonlight project's own download page or store listing. Nothing is bundled or re-hosted here. Nil means no client is known.

type Method

type Method struct {
	Kind     string   `json:"kind"`               // client, command, intent, steps
	Label    string   `json:"label"`              // what a button says
	OneClick bool     `json:"oneClick"`           // nothing more to do once it's set up
	Note     string   `json:"note,omitempty"`     // anything worth saying first
	Args     []string `json:"args,omitempty"`     // command: arguments for the moonlight program
	Text     string   `json:"text,omitempty"`     // command: the same, as a line to copy
	Package  string   `json:"package,omitempty"`  // intent
	Activity string   `json:"activity,omitempty"` // intent
	Extras   Extras   `json:"extras,omitempty"`   // intent
	Steps    []string `json:"steps,omitempty"`    // steps
}

Method is one way to play, best first.

func Plan

func Plan(d Device, t Target, inPage bool, clientNote string) []Method

Plan lists what really works on this device, best first. Playing in the page, through this server, comes first wherever a device can run it: clientNote is empty unless there's something to say first. Handing off to the Moonlight app is the fallback. What's listed here is checked against the table in docs/GAME-RIGS.md.

type Target

type Target struct {
	RigName string
	Address string // what this device should use from where it is now; empty if nothing works from here
	Port    int    // the base port, 0 for the default
	UUID    string
	AppID   int
	AppName string
	Away    bool // the person isn't on the home network
}

Target is the rig and game to reach. The address is only filled in for people allowed to play this game, and Moonlight still needs its own pairing before it can do anything.

Directories

Path Synopsis
cmd
wittycouch-module command
Command wittycouch-module is WittyCouch's service: the only way a server reaches it.
Command wittycouch-module is WittyCouch's service: the only way a server reaches it.
Package gamestream speaks the protocol a Sunshine server offers to its clients: finding a PC, pairing with it, listing what it offers and starting it.
Package gamestream speaks the protocol a Sunshine server offers to its clients: finding a PC, pairing with it, listing what it offers and starting it.
fake
Package fake is a stand-in for Sunshine, for tests.
Package fake is a stand-in for Sunshine, for tests.
Package relay carries a game stream between the Moonlight host program and a browser.
Package relay carries a game stream between the Moonlight host program and a browser.
fakehost
Package fakehost stands in for the Moonlight host program, in tests.
Package fakehost stands in for the Moonlight host program, in tests.
Package rpc answers a server's calls to WittyCouch's service: gen.go is generated, by kit/facade in WittyModule, and this is what can't be.
Package rpc answers a server's calls to WittyCouch's service: gen.go is generated, by kit/facade in WittyModule, and this is what can't be.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL