Lumen

Native macOS game streaming, built for Apple Silicon.

Lumen is a fork of Sunshine that fixes macOS support from the ground up. Stream your Mac's display to any Moonlight client — TV, phone, tablet, another PC — with native system audio, automatic virtual display management, and hardware-accelerated encoding.

Tested on M4 Mac Mini (16GB RAM) — 1ms encode-to-network latency over local network with H.264 VideoToolbox encoding.

---

Why Lumen?

Upstream Sunshine has significant issues on macOS:

| Problem | Sunshine (upstream) | Lumen | |---------|-------------------|-------| | Build on macOS | Fails with C++ toolchain errors on modern Xcode/CLT | Builds cleanly with automated dependency management | | System audio | No capture — requires BlackHole virtual audio device | Native ScreenCaptureKit audio — zero-config, no extra software | | Virtual displays | Manual setup with BetterDisplay ($15 app) | Automatic — creates/destroys virtual displays on connect/disconnect | | Gamepad support | None on macOS | Virtual HID gamepad via IOHIDUserDevice (works with Dolphin, Steam, etc.) | | H.264 encoding | All-IDR bug on Apple Silicon (every frame is a keyframe) | Fixed — proper P-frame generation, 3x bandwidth reduction | | Encoder performance | Capture and encode on same thread | Parallel capture/encode pipeline |

---

Features

• Zero-config system audio — ScreenCaptureKit captures all desktop audio natively. No BlackHole, no Soundflower, no virtual audio devices to install or configure.

• Automatic virtual displays — When a Moonlight client connects, Lumen creates a virtual display matching the client's requested resolution and refresh rate (e.g., 4K@60Hz). When the last client disconnects, the virtual display is destroyed. No third-party display managers needed.

• Hardware-accelerated encoding — VideoToolbox H.264 and HEVC encoding with Apple Silicon hardware acceleration. H.264 at 1080p60 encodes in ~15ms on M4 (fits within the 16.67ms frame budget). HEVC available for higher quality at the cost of slightly higher latency (~18ms on M4).

• Virtual gamepad — Creates a system-wide virtual HID gamepad that appears as a real controller to any application. Works with SDL-based games, Dolphin Emulator, Steam, Ryujinx, and more. Requires one-time security configuration (see Gamepad Setup).

• Low latency — Measured 1ms encode-to-network latency on local network with H.264 VideoToolbox on M4 Mac Mini.

---

Requirements

• macOS 14 (Sonoma) or later — required for CGVirtualDisplay API
• Apple Silicon Mac (M1/M2/M3/M4) — ARM64 only
• Moonlight client on your target device — moonlight-stream.org

---

Quick Install

git clone https://github.com/trollzem/Lumen.git
cd Lumen
./install.sh

The install script handles everything:

1. Checks macOS version and architecture
2. Installs Homebrew (if not present)
3. Installs all build dependencies with correct versions:
   • cmake — build system
   • boost — C++ utility libraries (Asio, Log, Process, Locale)
   • pkg-config — library path resolution
   • openssl@3 — TLS/SSL for HTTPS web UI and RTSP
   • opus — audio codec for streaming
   • llvm — Clang/LLVM toolchain
   • doxygen — documentation generation (build requirement)
   • graphviz — documentation graphs (build requirement)
   • node — web UI build (Vue 3 + Vite)
   • icu4c@78 — Unicode support (Boost.Locale dependency)
   • miniupnpc — UPnP port mapping for NAT traversal
4. Detects the correct macOS SDK path and C++ header location
5. Configures cmake with all necessary flags (see macOS Build Fixes for why this is needed)
6. Builds from source with all CPU cores
7. Installs the binary, virtual display helper, and assets to ~/.local/share/lumen/
8. Sets up default configuration in ~/.config/sunshine/
9. Creates a lumen launch command in ~/.local/bin/

After installation, grant these macOS permissions when prompted:

• Screen Recording (System Settings > Privacy & Security > Screen Recording)
• Accessibility (System Settings > Privacy & Security > Accessibility)

---

Usage

Start Lumen

lumen

Or if ~/.local/bin isn't in your PATH:

~/.local/bin/lumen

Pair with Moonlight

1. Open the Lumen web UI at https://localhost:47990
2. Log in with the credentials you set during installation
3. Open Moonlight on your client device
4. Moonlight will discover Lumen automatically via mDNS
5. Enter the PIN shown in Moonlight into the Lumen web UI
6. Connect — a virtual display is created automatically at your client's resolution

Stop Lumen

Press Ctrl+C in the terminal, or quit from the system tray icon.

---

Configuration

Config files live in ~/.config/sunshine/:

| File | Purpose | |------|---------| | sunshine.conf | Runtime settings (bitrate, audio source, encoder, etc.) | | apps.json | Applications visible in Moonlight's app list | | credentials/ | TLS certificates for HTTPS and client pairing (auto-generated) |

Key Settings (sunshine.conf)

# Audio source — "system" uses ScreenCaptureKit (recommended)
audio_sink = system

# Maximum streaming bitrate in kbps
max_bitrate = 80000

# Virtual display — "enabled" creates displays on-demand (recommended)
virtual_display = enabled

# UPnP port mapping for remote access
upnp = enabled

Adding Apps (apps.json)

Apps appear in Moonlight's launcher. Example for Dolphin Emulator:

{
  "name": "Dolphin Emulator",
  "detached": [
    "~/.config/sunshine/scripts/launch_dolphin.sh"
  ],
  "prep-cmd": [
    {
      "do": "",
      "undo": "osascript -e 'tell application \"Dolphin\" to quit'"
    }
  ]
}

Launch scripts can use the virtual display position file (/tmp/sunshine_vd_id) to move app windows to the streaming display automatically. See scripts/launch_dolphin.sh for an example.

---

Gamepad Setup (Optional)

Virtual gamepad support requires a one-time security configuration because it uses Apple's IOHIDUserDevice API with a restricted entitlement. This is only needed if you want gamepad/controller support. Keyboard and mouse input work without this step.

Why This Is Needed

macOS restricts the creation of virtual HID devices to prevent malicious software from injecting fake input. Lumen creates a virtual gamepad that appears as a real USB controller to the system — this requires the com.apple.developer.hid.virtual.device entitlement, which Apple only allows with AMFI (Apple Mobile File Integrity) disabled.

SIP (System Integrity Protection) does NOT need to be disabled — only AMFI. This is a less invasive change that specifically allows ad-hoc signed binaries to use restricted entitlements.

Steps

1. Shut down your Mac completely (not restart)

2. Boot into Recovery Mode:

   • Apple Silicon: Hold the power button until "Loading startup options" appears
   • Select Options > Continue

3. Open Terminal from the Utilities menu in Recovery Mode

4. Disable AMFI (allows restricted entitlements on ad-hoc signed binaries):

   nvram boot-args="amfi_get_out_of_my_way=1"
   

5. Restart your Mac normally

6. Sign the Lumen binaries with the HID entitlement:

   codesign --sign - --entitlements ~/.local/share/lumen/hid_entitlements.plist --force ~/.local/share/lumen/sunshine
   codesign --sign - --force ~/.local/share/lumen/vd_helper
   

That's it. The gamepad will now appear in any application as a generic USB controller. You can verify it's working by connecting from Moonlight with a controller and checking System Information > USB.

Important Notes

• AMFI disable persists across reboots — you only need to do this once
• Re-sign after every rebuild — if you rebuild from source, run the codesign commands again
• The lumen launcher auto-signs on every launch — the manual step above is only needed if you bypass the launcher
• To re-enable AMFI later: boot into Recovery Mode and run nvram -d boot-args
• Without AMFI disabled, Lumen still works fully — you just won't have gamepad support. Keyboard, mouse, virtual displays, audio, and all other features work normally.
• Security note: Disabling AMFI reduces one layer of macOS security. Only do this if you understand the implications and need gamepad support.

---

Building From Source

If you want to build manually instead of using install.sh:

Prerequisites

# Install Homebrew if not already installed
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install all build dependencies
brew install cmake boost pkg-config openssl@3 opus llvm doxygen graphviz node icu4c@78 miniupnpc

Build

cd Lumen

# Detect macOS SDK path
SDK_PATH=$(xcrun --show-sdk-path)

mkdir -p build && cd build

cmake -DCMAKE_BUILD_TYPE=Release \
  -DBUILD_WERROR=ON \
  -DHOMEBREW_ALLOW_FETCHCONTENT=ON \
  -DOPENSSL_ROOT_DIR=$(brew --prefix openssl@3) \
  -DSUNSHINE_ASSETS_DIR=sunshine/assets \
  -DSUNSHINE_BUILD_HOMEBREW=ON \
  -DSUNSHINE_ENABLE_TRAY=ON \
  -DBOOST_USE_STATIC=OFF \
  -DCMAKE_OSX_SYSROOT="$SDK_PATH" \
  -DCMAKE_CXX_FLAGS="-nostdinc++ -cxx-isystem $SDK_PATH/usr/include/c++/v1 -std=gnu++2b -I$(brew --prefix openssl@3)/include" \
  -DCMAKE_C_FLAGS="-I$(brew --prefix openssl@3)/include" \
  ..

make sunshine web-ui vd_helper -j$(sysctl -n hw.ncpu)

Run

cd build
./sunshine

---

Networking

| Port | Protocol | Purpose | |------|----------|---------| | 47984-47990 | TCP | Control, RTSP, Web UI (HTTPS) | | 47998-48010 | UDP | Video/audio streaming | | 47990 | HTTPS | Web configuration UI |

Lumen supports UPnP for automatic port mapping. For manual port forw