Command-Line Options

Full Command-Line Options Reference

This section provides a detailed reference for all command-line options available in Moonbeam. Understanding these options will help you fine-tune your streaming experience and take full advantage of Moonbeam’s capabilities.

Basic Usage

The basic structure of a Moonbeam command is:

moonbeam [options] stream <host> <app>

moonbeam: The name of the application you’re running.
[options]: Optional flags and parameters that modify how Moonbeam behaves (we’ll cover these in the Core Settings section).
stream: The action you want Moonbeam to perform, telling it to start a streaming session.
<host>: The hostname or IP address of the computer you want to stream from.
<app>: The name of the game or application you want to stream.

Moonbeam-Specific Options

These options are unique to Moonbeam and provide additional functionality beyond standard Moonlight options.

Resolution Options

--resolution <WxH>

Set both minimum and maximum resolution simultaneously (e.g., 1920x1080). This option is a shorthand for setting both --min-resolution and --max-resolution to the same value. It’s useful when you want to force a specific resolution. If specified, it overrides individual --min-resolution and --max-resolution settings.

--max-resolution <WxH>

Set the maximum resolution for the stream (e.g., 1920x1080). Moonbeam will not exceed this resolution even if higher resolutions are available on your system. This is useful for limiting bandwidth usage or ensuring compatibility with certain displays.

--min-resolution <WxH>

Set the minimum resolution for the stream (e.g., 640x360). Moonbeam will not go below this resolution even in low bandwidth conditions. This ensures a baseline quality for your stream.

--resolution-steps <steps>

Set the number of intermediate steps for resolution scaling. Default is 128. Higher values provide more granular resolution options, allowing Moonbeam to fine-tune the resolution based on network conditions. For example, with a higher step count, Moonbeam might choose 1600x900 instead of jumping directly from 1080p to 720p.

Resolution Shorthand Options

Moonbeam provides convenient shorthand options for common resolutions:

--360

Force a 640x360 resolution

--480

Force a 854x480 resolution

--540

Force a 960x540 resolution

--720

Force a 1280x720 resolution

--900

Force a 1600x900 resolution

--1080

Force a 1920x1080 resolution

--1440

Force a 2560x1440 resolution

--2K

Force a 2048x1080 resolution

--4K

Force a 3840x2160 resolution

FPS Options

--fps <fps>

Set both minimum and maximum FPS (frames per second) simultaneously (e.g., 60). This option is a shorthand for setting both --min-fps and --max-fps to the same value. It’s useful when you want to lock the stream to a specific frame rate.

--max-fps <fps>

Set the maximum FPS for the stream (e.g., 120). Moonbeam will not exceed this frame rate even if higher rates are available. This can be useful for capping the frame rate to match your display’s refresh rate or to reduce bandwidth usage.

--min-fps <fps>

Set the minimum FPS for the stream (e.g., 30). Moonbeam will not go below this frame rate even in low bandwidth conditions. This ensures a baseline smoothness for your stream.

Bitrate Options

--max-bitrate <bitrate>

Set the maximum available bitrate for the stream. This option allows you to manually specify the maximum bandwidth in kilobits per second (Kbps). If not provided, Moonbeam will automatically calculate an appropriate bitrate based on the maximum resolution and FPS.

--max-bitrate is an alias for --bitrate. Both options function identically.
You can use suffixes like ‘Mbps’ for convenience (e.g., ‘10Mbps’).
If no suffix is provided, the value is assumed to be in Kbps.
When specified, Moonbeam will adjust the FPS and resolution settings to match the given bitrate, unless fixed values for --fps or --resolution are also provided.

Latency Option

--max-latency <ms>

Set the maximum allowed latency in milliseconds. If the measured latency exceeds this value, Moonbeam will abort the connection. This helps ensure a responsive gaming experience by setting an upper limit on acceptable input lag.

Priority Option

--priority <resolution|fps>

Set the priority for optimization. Use resolution to prioritize higher resolutions, or fps to prioritize higher frame rates. Default is fps. This option tells Moonbeam which aspect to favor when it needs to make trade-offs due to bandwidth limitations.

Other Moonbeam Options

--reconnect

Enable automatic reconnection if the stream is disconnected. This is particularly useful for unstable network conditions or when switching between different networks (e.g., moving from Wi-Fi to cellular data).

--log-level <level>

Set the logging verbosity. Valid levels are QUIET, SIMPLE, INFO, WARN, DEBUG, TRACE, and VERBOSE. Higher levels provide more detailed output, which can be useful for troubleshooting. QUIET provides minimal output, while VERBOSE gives the most detailed logs.

--dry-run

Show the Moonlight command that would be executed without actually starting the stream. This is useful for testing and debugging your Moonbeam configuration without initiating a connection. It allows you to see how Moonbeam would interpret your settings and what command it would pass to Moonlight.

Moonlight Options

Moonbeam supports Moonlight’s stream options as well. These options will be forwarded directly to Moonlight when the streaming session is launched. For a complete list of available Moonlight options, refer to the Moonlight documentation.

Display Options

--[no-]vsync

Enable or disable vertical synchronization. Vsync synchronizes the game’s frame rate with your monitor’s refresh rate, which can reduce screen tearing. However, it may also increase input latency. Use --vsync to enable, or --no-vsync to disable this feature.

--display-mode <display-mode>

Set the display mode for the stream. Common options include:

fullscreen: Run the stream in full-screen mode
windowed: Run the stream in a window
borderless: Run the stream in a borderless window

Example: --display-mode fullscreen

Audio Options

--audio-config <audio-config>

Configure advanced audio settings. This can include options for:

Surround sound configuration (e.g., 5.1, 7.1)
Stereo or mono output
Specific audio device selection

Example: --audio-config surround51

--[no-]mute-on-focus-loss

Control whether the stream’s audio is muted when the window loses focus. This can be useful to automatically silence the game when you switch to another application. Use --mute-on-focus-loss to enable this feature, or --no-mute-on-focus-loss to keep audio playing even when the window is not focused.

--[no-]audio-on-host

Enable or disable audio playback on the host machine (the computer running the game). This can be useful if you want to stream a game to another device but still hear the audio on your main computer. Use --audio-on-host to enable host audio, or --no-audio-on-host to disable it.

Input Options

--[no-]multi-controller

Enable or disable support for multiple controllers. When enabled, Moonlight will support multiple gamepads connected to the client device. Use --multi-controller to enable this feature, or --no-multi-controller to limit input to a single controller.

--[no-]absolute-mouse

Choose between absolute or relative mouse mode. Absolute mode directly maps your mouse position to the game, which can be more precise but may feel less natural for some users. Relative mode translates mouse movements, which can feel more natural but may be less precise. Use --absolute-mouse for absolute mode, or --no-absolute-mouse for relative mode.

--[no-]mouse-buttons-swap

Swap the functions of the left and right mouse buttons. This can be useful for left-handed users or for games with unconventional mouse controls. Use --mouse-buttons-swap to enable button swapping, or --no-mouse-buttons-swap to use default button mapping.

--[no-]touchscreen-trackpad

Enable or disable the use of a touchscreen as a trackpad. When enabled, you can use touch input to control the mouse cursor. This is particularly useful for mobile devices. Use --touchscreen-trackpad to enable this feature, or --no-touchscreen-trackpad to disable it.

--[no-]reverse-scroll-direction

Reverse the direction of scrolling. This can be useful if you’re more comfortable with “natural” scrolling as used on some operating systems. Use --reverse-scroll-direction to enable reversed scrolling, or --no-reverse-scroll-direction for standard scrolling.

--[no-]swap-gamepad-buttons

Swap the A/B and X/Y gamepad buttons. This can be helpful when switching between consoles with different button layouts. Use --swap-gamepad-buttons to enable button swapping, or --no-swap-gamepad-buttons to use the default layout.

--[no-]background-gamepad

Allow or disallow gamepad input when the Moonlight window is not in focus. This can be useful if you want to use your gamepad for other applications while streaming. Use --background-gamepad to allow background input, or --no-background-gamepad to restrict gamepad input to when the Moonlight window is focused.

Performance and Optimization

--packet-size <packet-size>

Set the maximum packet size for network transmissions. This can be adjusted to optimize performance on different networks. Smaller packet sizes may work better on less stable connections, while larger sizes can improve efficiency on good connections. Example: --packet-size 1024

--[no-]quit-after

Control whether Moonlight should quit after the game exits. Use --quit-after to automatically close Moonlight when you exit the game, or --no-quit-after to keep Moonlight running.

--[no-]game-optimization

Enable or disable game-specific optimizations. When enabled, Moonlight may apply specific settings or tweaks for known games to improve performance or compatibility. Use --game-optimization to enable these optimizations, or --no-game-optimization to disable them.

--[no-]frame-pacing

Enable or disable frame pacing. Frame pacing helps to smooth out irregular frame rates, which can result in a more consistent visual experience. Use --frame-pacing to enable this feature, or --no-frame-pacing to disable it.

--[no-]keep-awake

Control whether the device should stay awake during streaming. This is particularly useful for mobile devices to prevent them from going to sleep during longer gaming sessions. Use --keep-awake to keep the device awake, or --no-keep-awake to allow normal sleep behavior.

--[no-]performance-overlay

Show or hide a performance overlay during streaming. This overlay displays real-time information about stream quality, network performance, and system resource usage. Use --performance-overlay to show this information, or --no-performance-overlay to hide it.

Video Options

--[no-]hdr

Enable or disable High Dynamic Range (HDR) streaming. HDR can provide more vibrant colors and better contrast, but requires compatible hardware on both the host and client. Use --hdr to enable HDR streaming if supported, or --no-hdr to force SDR mode.

--video-codec <video-codec>

Specify the video codec to use for streaming. Common options include H.264 and HEVC (H.265). HEVC can provide better quality at lower bitrates but requires more processing power. Example: --video-codec HEVC

--video-decoder <video-decoder>

Specify the video decoder to use for decoding the stream. This can be used to force a specific hardware or software decoder. Options may vary depending on your system. Example: --video-decoder h264_mmal

System Integration

--capture-system-keys <capture-system-keys>

Configure how system keys (like Alt+Tab or the Windows key) are captured during streaming. Options typically include:

always: Always capture system keys
never: Never capture system keys
fullscreen: Only capture system keys in fullscreen mode

Example: --capture-system-keys fullscreen