Wolf (Custom Fork)

This is a personal fork of the Games on Whales: Wolf streaming server. All core streaming architecture and code credit belong to the upstream Games on Whales team.

I created this fork to address two specific issues encountered while running Wolf in my multi-node homelab setup (Twierdza):

1. Premature release of keyboard modifier keys (Shift, Ctrl, Alt, Meta) in the virtual input handler.
2. PulseAudio auto-router conflicts with out-of-band VBAN microphone streams.

---

Patches Applied in this Fork

1. Keyboard Modifier & Caps Lock State Handling

• File: src/moonlight-server/control/input_handler.cpp
• Problem: In upstream Wolf, synthetic modifier press/release calls caused modifier keys to drop prematurely during continuous actions (such as Shift + W sprint) and caused modifier lockups (e.g., permanently stuck Shift state) when Caps Lock was toggled on the client.
• Fix: Transitioned to pure 1:1 event passthrough driven by explicit client keydown/keyup events, ensuring modifier keys stay held naturally and Caps Lock does not lock up subsequent inputs.

2. VBAN Audio Isolation and Virtual Sink

• Files: src/moonlight-server/audio/pulse_router.cpp, src/moonlight-server/sessions/moonlight.cpp, src/moonlight-server/sessions/common.cpp
• Problem: Wolf's automatic PulseAudio router re-routes all application audio into the default streaming sink. When running VBAN (Voice Band Audio Network) inside the guest container for player microphone talkback, Wolf intercepted the voice stream and mixed it back into the outgoing stream. Additionally, hardcoding PULSE_SINK prevented manual audio sink management.
• Fix:
  • Excluded processes with "vban" in their name or binary path from the automatic sink router (pulse_router.cpp).
  • Added automated creation of a dedicated vban_mic_sink virtual sink on session startup (moonlight.cpp).
  • Removed forced PULSE_SINK environment export in common.cpp to allow applications to bind to custom sinks.

---

How to Build

git clone https://github.com/Mateosek/wolf.git
cd wolf
docker build -t gow/wolf:custom -f docker/wolf.Dockerfile .

---

Architecture & Integration

In my homelab setup (Twierdza), this custom Wolf image runs alongside a tailored guest container (gow/xfce-steam:edge) and a FastAPI management agent: See Mateosek/twierdza-cloud-gaming.

flowchart TD
    Client["Moonlight Client + VBAN Talkie"] <-->|"Encrypted Mesh (NetBird / WireGuard)"| Host["Host (Wolf Custom Image)"]
    Host -->|"C++ Core + GStreamer NVENC/VAAPI"| VideoStream["Video & Audio Stream (Moonlight)"]
    Host -->|"PulseAudio vban_mic_sink"| AudioMic["Isolated Microphone Channel"]
    Host -->|"Linux /dev/uinput"| InputSubsys["Virtual Keyboard & Gamepads"]
    AudioMic --> Container["Guest Gaming Container (XFCE / Proton / Steam)"]
    InputSubsys --> Container

Loading

---

Upstream Project & Credits

• Original Project: games-on-whales/wolf
• Client Protocol: Moonlight Game Streaming
• Developed and maintained by the Games on Whales community.