Documentation
¶
Overview ¶
Package stream runs game sessions on the server: it starts a runner process, reads its raw frames, encodes them with FFmpeg and sends them to viewers over WebRTC or a WebSocket. docs/GAMING.md has the reasoning.
Index ¶
- Constants
- Variables
- func SandboxStrength() (string, bool)
- func SlotName(slot int) (string, error)
- type AU
- type Config
- type ConnStats
- type Connected
- type CoreChoice
- type Display
- type EncodeStats
- type GPUProbe
- type Hello
- type Info
- type LEDState
- type LatencyMode
- type Manager
- func (m *Manager) Configure(update func(*Config))
- func (m *Manager) Count() int
- func (m *Manager) ForUser(userID int64) *Session
- func (m *Manager) Get(id string) *Session
- func (m *Manager) Modes(client string) []Mode
- func (m *Manager) ProbeOptions(ctx context.Context, core, systemDir, tmp string) ([]ipc.Option, error)
- func (m *Manager) Start(opt Options) (*Session, error)
- func (m *Manager) StopAll()
- func (m *Manager) UsingCore(path string) int
- type Mode
- type MotionWant
- type Options
- type ProbeError
- type ProbeOptions
- type ProbeResult
- type ProcessIDs
- type Runner
- type Seat
- type Session
- func (s *Session) Advance(frames int) error
- func (s *Session) Answer(ctx context.Context, offer, prefer string) (string, error)
- func (s *Session) Apply(c ipc.Control, coreOptions map[string]string) error
- func (s *Session) ChangeDisc(index int) error
- func (s *Session) Connect(ctx context.Context, hello Hello, offer string, away bool) (Connected, error)
- func (s *Session) CoreID() string
- func (s *Session) CoreOptions() []ipc.Option
- func (s *Session) Done() <-chan struct{}
- func (s *Session) EncodeStats() *EncodeStats
- func (s *Session) Failure() string
- func (s *Session) ID() string
- func (s *Session) Info() Info
- func (s *Session) Input(p []byte)
- func (s *Session) ItemID() int64
- func (s *Session) LoadState(slot int) error
- func (s *Session) MarshalJSON() ([]byte, error)
- func (s *Session) Pause(on bool) error
- func (s *Session) Processes() ProcessIDs
- func (s *Session) RawFrame() (ipc.VideoHeader, []byte)
- func (s *Session) Reset() error
- func (s *Session) Safe() bool
- func (s *Session) SaveState(ctx context.Context, slot int) error
- func (s *Session) Screenshot() ([]byte, error)
- func (s *Session) ServeStream(w http.ResponseWriter, r *http.Request, away bool)
- func (s *Session) ServeWS(w http.ResponseWriter, r *http.Request, mode string)
- func (s *Session) SetAutoSave(on bool)
- func (s *Session) SetCheats(list []ipc.Cheat) error
- func (s *Session) SetDevice(port int, id uint32) error
- func (s *Session) SetOption(key, value string) error
- func (s *Session) SetRewinding(on bool) error
- func (s *Session) SetSpeed(v float64) (float64, error)
- func (s *Session) Stats() Stats
- func (s *Session) Stop()
- func (s *Session) Undo(ctx context.Context) error
- func (s *Session) UserID() int64
- func (s *Session) WaitOptions(ctx context.Context)
- type SlotMeta
- type Stats
- type StreamError
- type StreamInfo
Constants ¶
const ( CodeBadHello = "bad-hello" CodeNoSession = "no-session" CodeTooLarge = "too-large" CodeNoCodec = "no-codec" CodeBusy = "busy" CodeFailed = "failed" CodeSeatTaken = "seat-taken" CodeBadSeat = "bad-seat" CodeBadMsg = "bad-message" )
What a refusal can say.
const ( EndStopped = "stopped" EndQuit = "quit" EndCrashed = "crashed" EndIdle = "idle" EndEvicted = "evicted" )
Why a game ended, in the "ended" event.
const ( MaxSlot = ipc.MaxStateSlot SlotUndo = ipc.SlotUndo SlotPrevAuto = ipc.SlotPrevAuto )
Save slots. 0 is automatic, 1 to MaxSlot are a person's own, and two more are kept for mistakes: the state from before the last load, and the automatic save that the last "start over" would otherwise have lost.
const ( ClientBrowser = "browser" ClientNative = "native" )
Client kinds a server can be asked about.
const ( ProbeRefused = "refused" // it loaded far enough to say no, or isn't a core ProbeCrashed = "crashed" ProbeHung = "hung" ProbeInvalid = "invalid" // it wrote something that isn't the protocol ProbeRunner = "runner" // our side: the runner couldn't start )
How a test-load can fail.
const MaxOfferSize = 64 << 10
MaxOfferSize bounds an SDP offer; a real one is a few kilobytes.
const MaxPlayers = 8
MaxPlayers is how many players a game takes input for: as many as a core with a multitap can have, through libretro's ports: the runner's MaxPorts, which a test holds this to. The stream says how many this game has.
const MaxSaveBytes = 4 << 30
MaxSaveBytes is how much one account may keep for one game.
const NoGPUText = "no usable graphics card"
NoGPUText is in the error a runner gives when a game needs a graphics card and this server has none it can use.
const ProbeTimeout = 2 * time.Minute
ProbeTimeout is how long a core gets to load. A big core on a slow disk takes seconds, and a virus scanner looking at a new library on a busy machine was seen taking most of a minute. A hang costs only the wait.
const StreamVersion = 2
StreamVersion is the version a mode says it can be reached with, in Mode.Stream.
Variables ¶
var ( ErrBusy = errors.New("this server is already running as many games as it allows; stop one first") ErrGPUBusy = errors.New("The graphics card is already running as many games as this server allows; stop one first, or raise the limit in Settings, Consoles & cores") ErrStopped = errors.New("the game has stopped") // ErrReplaced: the game was stopped while it loaded, by another being started or by // the server closing. No other core gets a turn, and nothing's wrong with this one. ErrReplaced = errors.New("this game was stopped before it finished loading") // ErrRunnerDied is behind the plain words for a runner that ended by itself. ErrRunnerDied = errors.New("the game runner ended by itself") ErrNoSlot = errors.New("there is no such save slot") // ErrNoDevice: the core didn't offer that kind of controller for that port. ErrNoDevice = errors.New("this game has no such kind of controller") )
Errors a caller shows to people.
var ErrSaveFull = errors.New("this game's saved states have used all the space they may; delete some first")
ErrSaveFull: this game's saves have reached their limit.
Functions ¶
func SandboxStrength ¶ added in v0.3.3
SandboxStrength says what boxes a core in on this platform, for people deciding whether to allow custom cores.
Types ¶
type AU ¶
type AU struct {
Data []byte
Key bool
PTS time.Duration // from the first frame the encoder was given
}
AU is one encoded frame in Annex B form (H.264) or as a VP8 frame.
type Config ¶
type Config struct {
Runner string // the wittyplay-game-runner program, or another runner speaking ipc
RunnerArgs []string // extra arguments, before the ones added here
FFmpeg string
HWEncoders []string // hardware encoders known to work here and switched on, best first
GPUEncoders []string // hardware encoders known to work here at all, best first
HaveEncoder func(string) bool // FFmpeg was built with this encoder
MaxSessions int // 0 means 2
MaxGPU int // games drawn on the graphics card at once; 0 means 2
MemoryMB int64 // 0 means 2048
GPUMemoryMB int64 // the same for a game with a graphics driver loaded; 0 means 8192
Log *slog.Logger
// WebRTC networking; all optional. A fixed UDP port is what a firewall or
// a container needs; the public address is what NAT needs.
UDPPort int
PublicIPs []string
STUN []string
// LoopbackOnly keeps WebRTC to this machine's loopback address, for testing where a
// wider address would stop to ask a firewall.
LoopbackOnly bool
}
Config is how the server runs games.
type ConnStats ¶ added in v0.3.5
type ConnStats struct {
Transport string `json:"transport"`
Video string `json:"video"`
Audio string `json:"audio"`
Kbps float64 `json:"kbps"`
RTTMs float64 `json:"rttMs"`
Lost float64 `json:"lost"`
QueueMs float64 `json:"queueMs"`
Dropped int64 `json:"dropped"`
Seats []int `json:"seats"`
}
ConnStats is one connection's part of the stats event.
type Connected ¶ added in v0.3.5
type Connected struct {
Stream StreamInfo `json:"stream"`
SDP string `json:"sdp"`
}
Connected is the answer to a WebRTC connection: what it gets, and the SDP.
type CoreChoice ¶ added in v0.3.3
type CoreChoice struct {
Core string
GPU bool
Options map[string]string
RunnerArgs []string // what this core asks of its runner: see wittyplay.RunnerArgs
CoreID string
}
CoreChoice is a core and the settings it starts with.
type Display ¶ added in v0.3.5
type Display struct {
Hz float64 `json:"hz,omitempty"`
Width int `json:"width,omitempty"`
Height int `json:"height,omitempty"`
}
Display is the screen a client shows the game on.
type EncodeStats ¶ added in v0.3.3
type EncodeStats struct {
// contains filtered or unexported fields
}
EncodeStats counts frames through the encoder.
func (*EncodeStats) Take ¶ added in v0.3.3
func (st *EncodeStats) Take() (frames int64, meanMS, maxMS float64)
Take returns frames encoded, the mean and the worst time from going in to coming out, in milliseconds, since it was last asked.
type GPUProbe ¶ added in v0.3.3
type GPUProbe struct {
Name string `json:"name,omitempty"`
Error string `json:"error,omitempty"`
Checking bool `json:"checking,omitempty"` // the answer isn't in yet
Again bool `json:"-"` // says nothing about the card, so ask again later
}
GPUProbe is what a runner found when asked which graphics card it would use.
func ProbeGPU ¶ added in v0.3.3
ProbeGPU asks the runner which graphics card games would draw with, in the same sandbox a game gets, so the answer is the one a game will see. A hidden window is the most it opens. The folder is made writable to a sandboxed process, so it must be one with nothing else in it.
type Hello ¶ added in v0.3.5
type Hello struct {
Type string `json:"type,omitempty"` // "hello", over a WebSocket
V int `json:"v"`
App string `json:"app,omitempty"`
Device string `json:"device,omitempty"`
Name string `json:"name,omitempty"`
Watch *bool `json:"watch,omitempty"` // false: a controller only; left out is true
Video []string `json:"video,omitempty"` // codecs it decodes, best first
Audio []string `json:"audio,omitempty"` // opus, pcm
Seats []int `json:"seats"` // the players it drives; nil: any nobody holds
Display Display `json:"display"`
Latency string `json:"latency,omitempty"`
MaxKbps int `json:"maxKbps,omitempty"`
}
Hello is what a client says about itself as it connects.
type Info ¶
type Info struct {
ID string `json:"id"`
ItemID int64 `json:"itemId"`
Title string `json:"title"`
Console string `json:"console"`
Core string `json:"core"`
Width int `json:"width"`
Height int `json:"height"`
Aspect float64 `json:"aspect"`
FPS float64 `json:"fps"`
SampleRate float64 `json:"sampleRate"`
Resumed bool `json:"resumed"`
Encoder string `json:"encoder,omitempty"`
Turns int `json:"turns,omitempty"` // quarter turns anticlockwise to draw the picture
Disc int `json:"disc,omitempty"` // the disc in the drive, from 0
Discs int `json:"discs,omitempty"` // how many the game has
Renderer string `json:"renderer,omitempty"` // the graphics card, for a game drawn on one
Modes []Mode `json:"modes"` // what this client can connect with, best first
// Devices: the kinds of controller this game's core lets each port choose from.
Devices []ipc.PortDevices `json:"devices,omitempty"`
// SafeMode: started with default settings, on request.
SafeMode bool `json:"safeMode,omitempty"`
// MaxSpeed is the fastest this game may be made to run here.
MaxSpeed float64 `json:"maxSpeed"`
// Notices are things worth telling the person, such as a patch that didn't apply.
Notices []string `json:"notices,omitempty"`
}
Info is what a browser needs to know about a session.
type LatencyMode ¶ added in v0.3.3
type LatencyMode byte
LatencyMode is the choice a person makes between speed and steadiness.
const ( LatencyFastest LatencyMode = iota LatencyBalanced LatencySteady )
type Manager ¶
type Manager struct {
// contains filtered or unexported fields
}
Manager holds the running sessions.
func NewManager ¶
NewManager makes a manager; sessions start with Start.
func (*Manager) ForUser ¶ added in v0.3.3
ForUser finds the game an account is playing. An account plays one at a time.
func (*Manager) ProbeOptions ¶ added in v0.3.3
func (m *Manager) ProbeOptions(ctx context.Context, core, systemDir, tmp string) ([]ipc.Option, error)
ProbeOptions runs a core with no game for long enough to ask what options it offers. Most cores say as soon as they load; a core that only says with a game loaded gives an empty list, and the list comes at the next play. The runner is boxed in as it always is, in a throwaway folder.
func (*Manager) Start ¶
Start launches a game. An account plays one game at a time: starting another saves and ends the first, on any device.
type Mode ¶
type Mode struct {
ID string `json:"id"` // webrtc | ws-h264 | ws-jpeg
Video []string `json:"video"` // codecs, best first
Audio string `json:"audio"` // opus | pcm
Input string `json:"input"` // datachannel | websocket
Needs string `json:"needs,omitempty"` // what a client must have, in words
// BrowserOnly marks a mode only a web browser can use. None exists yet; in-browser
// emulation will be one, and is left out of the answer for native clients.
BrowserOnly bool `json:"browserOnly,omitempty"`
// Stream is the version of /play/{sid}/stream this mode can be reached through: 2. Left
// out, only version 1's own route.
Stream int `json:"stream,omitempty"`
}
Mode is a way a client can receive a game. The server says which ones it has, so a client never has to guess, and new modes can appear without breaking old clients.
type MotionWant ¶ added in v0.3.5
type MotionWant struct {
Port int `json:"port"`
Accel bool `json:"accel"`
Gyro bool `json:"gyro"`
Hz int `json:"hz"`
}
MotionWant is a player whose motion the game reads now, and how often.
type Options ¶
type Options struct {
UserID, ItemID int64
Title string
Console string
Core string // a shared library path, or ipc.TestCore
ROM string
SystemDir string
SaveDir string // this account's folder for this game
Resume bool // continue from auto.state
Quality string // "" (auto) | low | high
GPU bool // the core draws with a graphics card
RunnerArgs []string // extra arguments for this game's runner: wittyplay.RunnerArgs
CoreID string // the core's name, for working out its starting options again
CoreOptions map[string]string
PreferDevices []string // the kind of controller to plug in, by words in its name
CoreAssets string // support files of its own, if it has any
// LoadLimit is how long it may take to load, when it's more than a game usually gets.
LoadLimit time.Duration
Cleanup func() // runs when the session has ended
// Fallbacks are cores to try, in order, if this game won't load on Core. Dumps
// that one core refuses often play on another, and nobody should have to know.
Fallbacks []CoreChoice
Control *ipc.Control // how the game runs from the first frame
Cheats []ipc.Cheat // given to the core before the first frame
MaxSpeed float64 // the fastest it may be made to run; 0 means normal speed only
NoAutoSave bool // leaving doesn't write the resume state
SafeMode bool // started with defaults; settings aren't applied while it runs
Notices []string // things to tell whoever started it
OnCoreOptions func(coreID string, list []ipc.Option) // a core has said what it offers
Stamp bool // draw numbers into each picture, for measuring: wittyplay-probe
// contains filtered or unexported fields
}
Options start one game.
type ProbeError ¶ added in v0.3.3
ProbeError says, in words for people, why a core failed its test-load.
func (*ProbeError) Error ¶ added in v0.3.3
func (e *ProbeError) Error() string
type ProbeOptions ¶ added in v0.3.3
type ProbeOptions struct {
Runner string // wittyplay-game-runner: this is a question for our own runner
Core string
SystemDir string
WorkDir string // an empty folder, the only one the runner may write to
Timeout time.Duration // 0 means ProbeTimeout
MemoryMB int64 // 0 means 2048
Log *slog.Logger
}
ProbeOptions test-load one core file.
type ProbeResult ¶ added in v0.3.3
type ProbeResult struct {
ipc.Probe
SandboxNote string // a sandbox layer this machine couldn't apply, if any
}
ProbeResult is a successful test-load.
func Probe ¶ added in v0.3.3
func Probe(ctx context.Context, opt ProbeOptions) (*ProbeResult, error)
Probe test-loads a core in a runner process boxed in exactly as a game's is, and reports what it says about itself. Nothing the core does can reach this process: a crash is an exit code, a hang is a timeout, and anything it writes is read as hostile through the same size limits a game's frames get.
type ProcessIDs ¶ added in v0.3.3
type ProcessIDs struct {
Runner int `json:"runner"`
Video int `json:"video"`
Audio int `json:"audio"`
VideoStarts int `json:"videoStarts"`
}
ProcessIDs names what's running for a game, for tools that watch or test it.
type Runner ¶ added in v0.3.3
type Runner struct {
Cmd *exec.Cmd
Stdin io.WriteCloser
Stdout io.ReadCloser
Stderr io.ReadCloser
// contains filtered or unexported fields
}
Runner is a started runner process, boxed in the way every game's is. Nothing has been loaded yet: it waits for a load command on Stdin.
func StartRunner ¶ added in v0.3.3
func StartRunner(program string, args []string, saveDir string, memoryMB int64, log *slog.Logger) (*Runner, error)
StartRunner starts one runner with its sandbox on. Sessions start theirs here, and so does cmd/wittyplay-check, so what is tested is what the server runs.
type Seat ¶ added in v0.3.5
type Seat struct {
Port int `json:"port"`
Conn string `json:"conn"`
Name string `json:"name,omitempty"`
You bool `json:"you,omitempty"`
}
Seat is one player and the device that has it.
type Session ¶
type Session struct {
// contains filtered or unexported fields
}
Session is one running game.
func (*Session) Answer ¶
Answer connects a browser over WebRTC: it takes the browser's offer and returns the answer. prefer is "" or "vp8". Which codec is used depends on what the browser offered and what FFmpeg here can encode.
func (*Session) Apply ¶ added in v0.3.3
Apply brings a running game into line with new settings. Only what differs from the last time is sent, and a safe-mode game takes nothing: it's running with defaults so that someone can get out of a mess.
func (*Session) ChangeDisc ¶ added in v0.3.3
ChangeDisc swaps the disc in a game that has several.
func (*Session) Connect ¶ added in v0.3.5
func (s *Session) Connect(ctx context.Context, hello Hello, offer string, away bool) (Connected, error)
Connect answers a version 2 connection over WebRTC. away says the server counts the device as away from home, which it starts lower for.
func (*Session) CoreOptions ¶ added in v0.3.3
CoreOptions is what the core offers and what each is set to.
func (*Session) Done ¶
func (s *Session) Done() <-chan struct{}
Done is closed when the game has ended.
func (*Session) EncodeStats ¶ added in v0.3.3
func (s *Session) EncodeStats() *EncodeStats
EncodeStats is for logs and tests.
func (*Session) Failure ¶ added in v0.3.3
Failure says why a game ended by itself, or "" when it was simply stopped.
func (*Session) Input ¶
Input applies a message from a viewer: an 11-byte pad state or a pointer state. Malformed ones and players beyond what the player offers are ignored.
func (*Session) MarshalJSON ¶ added in v0.3.3
MarshalJSON names a session to a server, which reaches it by that name.
func (*Session) Processes ¶ added in v0.3.3
func (s *Session) Processes() ProcessIDs
Processes says what's running for this game right now. Anything not running is 0.
func (*Session) RawFrame ¶ added in v0.3.3
func (s *Session) RawFrame() (ipc.VideoHeader, []byte)
RawFrame is a copy of the newest picture to leave the core, for comparing with what a viewer sees.
func (*Session) Safe ¶ added in v0.3.3
Safe says this game started with defaults, whatever its settings say.
func (*Session) Screenshot ¶ added in v0.3.3
Screenshot is the current picture as a PNG, without any effects: those only exist on the device showing them.
func (*Session) ServeStream ¶ added in v0.3.5
ServeStream is version 2's WebSocket: the hello comes first, as text, and the stream's description goes back. away is the server's word on where the device is.
func (*Session) ServeWS ¶
ServeWS is the fallback transport. mode is "h264" (decoded with WebCodecs) or "jpeg". Origin checks are done by Accept, as for the rest of the API.
func (*Session) SetAutoSave ¶ added in v0.3.3
SetAutoSave says whether leaving writes the resume state.
func (*Session) SetDevice ¶ added in v0.3.3
SetDevice plugs a kind of controller into a port, if the core offered that kind.
func (*Session) SetOption ¶ added in v0.3.3
SetOption changes one core option for this session. It's refused here when it can be, so that a client gets an answer. The runner checks again whatever it's sent.
func (*Session) SetRewinding ¶ added in v0.3.3
SetRewinding goes backwards while on. It's refused when rewind isn't turned on, so that a button doing nothing can say why.
func (*Session) SetSpeed ¶ added in v0.3.3
SetSpeed changes how fast the game runs, and says what it was held to.
func (*Session) Stats ¶ added in v0.3.3
Stats reports the session's numbers since the last time anyone asked.
func (*Session) Stop ¶
func (s *Session) Stop()
Stop saves the game and ends it. It returns once everything is written.
func (*Session) Undo ¶ added in v0.3.3
Undo goes back to before the last load, and the game as it stands becomes the undo, so pressing it again goes forward.
func (*Session) WaitOptions ¶ added in v0.3.3
WaitOptions waits a moment for the core's list, for a client asking right after a start.
type Stats ¶ added in v0.3.3
type Stats struct {
GameFPS float64 `json:"gameFps"` // frames the game ran each second
SentFPS float64 `json:"sentFps"` // frames the runner sent each second
Skipped int `json:"skipped"` // frames left out in the last second
EncodedFPS float64 `json:"encodedFps"` // frames the encoder finished each second
EncodeMs float64 `json:"encodeMs"` // time to encode a frame
Kbps float64 `json:"kbps"` // what's being sent, over the last second
DroppedFrames int64 `json:"droppedFrames"` // frames an encoder never got, since the start
Width int `json:"width"`
Height int `json:"height"`
Core string `json:"core"`
Encoder string `json:"encoder,omitempty"`
Speed float64 `json:"speed"`
Paused bool `json:"paused"`
RewindBytes int64 `json:"rewindBytes,omitempty"`
RewindFrames int `json:"rewindFrames,omitempty"`
}
Stats is what the player's on-screen numbers show. Reading it does no work beyond a few counters, and only a client that shows them asks.
type StreamError ¶ added in v0.3.5
type StreamError struct {
Status int `json:"status"`
Code string `json:"code"`
Text string `json:"text"`
}
StreamError is a refusal with its HTTP status and a code a client can act on.
func (*StreamError) Error ¶ added in v0.3.5
func (e *StreamError) Error() string
type StreamInfo ¶ added in v0.3.5
type StreamInfo struct {
Type string `json:"type"` // "stream"
V int `json:"v"`
Conn string `json:"conn"`
Transport string `json:"transport"` // webrtc | websocket
Video string `json:"video"` // h264 | vp8 | jpeg | ""
Audio string `json:"audio"` // opus | pcm | ""
Width int `json:"width"`
Height int `json:"height"`
Aspect float64 `json:"aspect"`
FPS float64 `json:"fps"`
Rate int `json:"rate"`
Turns int `json:"turns"`
Ports int `json:"ports"`
Motion bool `json:"motion"`
MotionOn []MotionWant `json:"motionOn"`
LEDs []LEDState `json:"leds"`
Pace float64 `json:"pace"`
Seats []Seat `json:"seats"`
Kbps int `json:"kbps"`
Away bool `json:"away"`
}
StreamInfo is what a connection gets: in the answer, and as the first event.