GhostInput routes physical controllers and optional audio between Raspberry Pis and presents them to a target gaming computer as standard USB or Bluetooth devices.
This guide covers normal installation, provisioning, routing, device configuration, diagnostics, and maintenance through GhostInput Studio.
For additional information:
- FAQ — quick answers to common questions
- Hardware and Environment — Raspberry Pi, USB, network, Bluetooth, and audio guidance
- Troubleshooting — failures, logs, and recovery
- Security — authentication, trusted-LAN model, and limitations
- Developer Documentation — architecture and implementation details
- Understand the GhostInput Layout
- Install GhostInput Studio
- Prepare the Raspberry Pis
- Provision Hosts and Clients
- Create Your First Route
- Understand Routes
- Applying and Protecting Changes
- Grouped Controllers and USB Lanes
- Virtual Joysticks
- Virtual Keyboards
- USB Identity and Master Devices
- Rumble, LEDs, and Force Feedback
- Bluetooth
- Audio Relay
- Status and Diagnostics
- Security
- Updates and Reprovisioning
- Manual Service Installation
- Known Limitations
- Getting Help
A typical GhostInput installation has three roles:
- Host: Raspberry Pi near the physical controllers or audio hardware
- Client: Raspberry Pi connected to the target computer through USB OTG and/or Bluetooth
- Studio: Windows application used to configure and manage GhostInput; it may run on a different computer on the same trusted network
The realtime data path is separate from Studio's management connection:
flowchart LR
controls["Physical controls<br/>USB / Bluetooth"]
host["Host Pi<br/>Capture and stream"]
client["Client Pi<br/>Virtual devices"]
target["Target computer<br/>Windows or Linux"]
studio["GhostInput Studio<br/>Configure and monitor"]
controls --> host
host -->|LAN / Wi-Fi| client
client -->|USB OTG / Bluetooth LE| target
studio -.->|Control API| host
studio -.->|Control API| client
The Host reads physical devices. The Client creates the virtual devices the target computer sees. Studio provisions and manages both without carrying the realtime HID or audio traffic itself.
GhostInput Studio currently requires Windows, but Studio does not need to run on the gaming computer. The Client may connect to a Windows or Linux target, including gaming-focused distributions such as SteamOS or Bazzite. That target does not need a GhostInput application or plugin; it consumes the standard USB HID, Bluetooth HID, and USB audio interfaces presented by the Client.
Windows remains the primary tested target. Linux compatibility depends on the distribution, kernel, Bluetooth stack, audio stack, and game, so verify device enumeration and bindings on the intended system. A separate Windows computer running Studio only needs network access to the provisioned Pis.
GhostInput is not limited to one Host and one Client. A Host can serve more than one Client, and a Client can receive routes from multiple Hosts. For a first installation, start with one Host and one Client.
Download the current GhostInput Studio package from the official GitHub releases page.
- Download the Windows x64 Studio
.zip. - Extract the complete archive to a normal Windows folder you control.
- Keep the extracted files together.
- Run
GhostInput.Studio.exe.
The Studio package is self-contained and contains the Host and Client payloads used for provisioning and updates.
Public preview builds are not currently code-signed, so Microsoft Defender SmartScreen may warn the first time Studio runs.
If you downloaded GhostInput from the official GitHub release and trust the package, select More info and then Run anyway. Do not disable SmartScreen globally.
Release packages include checksums.txt, which can be used to verify the
downloaded archive.
The About page shows information such as:
- Studio version
- Bundled Host and Client versions
- Discovered GhostInput devices
- Device hardware information
- Update status
When a Studio update is available, Download Update downloads it with an activity indicator. Install Update first checks for unsaved profile or device settings, then explains that Studio will exit, install the downloaded version, and restart. Apply or discard pending changes before continuing.
The normal setup path uses Raspberry Pi OS and Studio provisioning over SSH.
For each Pi:
- Flash a supported Raspberry Pi OS image.
- Open Raspberry Pi Imager advanced options.
- Configure:
- Hostname
- Username and password
- Wi-Fi SSID, password, and country if required
- SSH with password authentication
- Boot the Pi.
- Wait for it to join the network.
Example hostnames are GhostInput-Host-1 and GhostInput-Client-1. These are
only examples; GhostInput does not require a particular naming pattern.
For role recommendations and tested hardware, see Hardware and Environment.
The easiest way to install GhostInput on a Pi is through Studio. Open Provisioning and select the intended role.
- Select Host.
- Enter the Pi hostname or IP address.
- Enter the SSH username and password.
- Start provisioning.
- Allow Studio to complete the installation and reboot sequence.
The Host normally sits near physical joysticks, throttles, pedals, keyboards, mice, button boxes, microphones, and speaker/headphone hardware.
- Select Client.
- Enter the Client Pi hostname or IP address.
- Enter the SSH username and password.
- Start provisioning.
- Allow Studio to complete the required reboot.
The Client normally sits near the target gaming computer and connects through the Raspberry Pi USB OTG port.
Depending on the role, provisioning installs and configures:
- GhostInput runtime
- systemd services
- Required runtime packages
- Service accounts and permissions
- Bluetooth support
- Audio dependencies
- Client USB gadget configuration
Provisioning also disables Wi-Fi power saving persistently to improve realtime behavior on wireless GhostInput devices. That setting can still be changed later from the device's Network page.
Once installation starts, Studio locks the provisioning controls so a second SSH/bootstrap operation cannot be submitted accidentally. The password is cleared after each provisioning attempt.
Provisioning can require a reboot. Studio reports the process through stages such as:
- Reboot scheduled
- Device offline
- SSH restored
- Service active
- API responding
- Updating Device Status
Stop Waiting stops only Studio's reboot monitoring. It does not cancel or damage an installation that has already been applied to the Pi.
After a successful reboot, Studio refreshes discovery, versions, device counts, selectors, and the About-page inventory. A newly provisioned Client becomes active automatically when no Client is selected. If another Client is already active, Studio asks whether to switch.
Preflight detects an existing GhostInput installation. A same-role reinstall or update normally preserves the device's configuration and Bluetooth bonds.
Provisioning a Client over a Host, or a Host over a Client, is a role replacement. Studio warns before proceeding because it removes settings and Bluetooth state belonging to the previous role.
Enable Start with a clean GhostInput configuration when you intentionally want to remove the existing role-specific routes and runtime settings during a same-role reprovision. Studio asks for confirmation after preflight. The reset preserves the installation identity, network configuration, hostname, stable Host identity where applicable, and same-role Bluetooth pairings.
Studio reports the target address, failed stage, and last successful stage. Use Copy Diagnostics to capture detailed stage results for troubleshooting intermittent SSH, reboot, or service failures.
See Troubleshooting for recovery guidance.
GhostInput normally uses multicast discovery to find Hosts and Clients. If discovery is unavailable but the device API is reachable, use Connect by IP.
Studio validates the address and adds the device only after a successful connection. An invalid or unreachable address is not left in the known-device list.
After at least one Host and one Client have been provisioned:
- Open Devices.
- Select the Client connected to the target gaming computer.
- Select Add Input Source.
- Choose a Host.
- Choose the physical device you want to route.
- Choose the desired Client output.
- Apply the Client profile.
For the first test, use a simple physical controller and an ordinary USB route where possible. Once applied, the target OS should enumerate the virtual device exposed by the Client.
Test the device in the target OS or simulator before adding grouping, mappings, Bluetooth, or Audio Relay.
A route connects an input source on a Host to a target-facing output on a Client:
flowchart LR
physical["Physical joystick"]
host["Host Pi<br/>Read HID reports"]
client["Client Pi<br/>Apply route"]
virtual["Virtual USB joystick"]
target["Target computer<br/>Game or simulator"]
physical --> host
host -->|InputReportBatch over UDP| client
client --> virtual
virtual -->|USB OTG| target
GhostInput supports route types including:
- USB joystick, keyboard, and mouse routes
- Bluetooth LE keyboard and mouse routes
- Grouped USB HID routes
- Virtual joystick routes
- Virtual keyboard routes
Studio displays route state visually:
- Green / resolved: route is ready
- Blue / sleeping: route is known but currently inactive
- Orange / unresolved: route requires attention
A sleeping Bluetooth device remains available to the profile and can reconnect without being re-added. An unresolved route means the source cannot currently be matched. While the Device Routing page is open, Studio periodically refreshes Host inventory so a newly connected source can resolve without restarting Studio.
See Troubleshooting if a previously working route remains unresolved.
Studio uses a consistent Apply Changes workflow on the Devices page and the editable Manage Host/Client pages:
- With no pending edits, the button uses its normal appearance.
- When settings change, the button becomes orange.
- Apply sends only the settings owned by the current page. Applying Audio Relay settings, for example, does not overwrite unrelated routes.
- Studio requests a Host or Client restart when required, waits for the API to return, and reports the result.
- After a successful apply, the button returns to its normal state.
If you navigate away, switch devices, close an editor, close Studio, or begin a Studio update with changes pending, Studio offers:
- Apply Changes
- Discard
- Cancel
Cancel keeps you on the current page. Discard restores the last loaded values.
The Client presents USB devices through the Raspberry Pi USB gadget system. That gadget has a limited number of usable HID/audio functions, shown in Studio as USB lanes. A normal USB route usually consumes one lane, and Audio Relay also consumes one lane.
Grouped controllers let several joystick sources and an optional generated Virtual Keyboard share one USB HID function:
flowchart LR
throttle["Throttle"]
panel["Button box"]
pedals["Pedals / trim panel"]
keyboard["Virtual keyboard"]
grouped["Grouped USB HID<br/>One Client USB lane"]
target["Target computer"]
throttle --> grouped
panel --> grouped
pedals --> grouped
keyboard -.->|Optional| grouped
grouped -->|USB OTG| target
Inside GhostInput, the routes remain separate logical members. To the target OS, they are reports within the shared grouped USB device.
Use grouping when:
- The Client has more joystick-style sources than USB lanes
- Related controllers can share one generated USB function
- A rig contains many button boxes, throttles, pedals, or panels
- A Virtual Keyboard should not consume a separate USB lane
A grouped member no longer receives a separate USB function with the original device's descriptor, VID, PID, and USB identity. Games may require bindings to be reassigned because the target OS sees a generated device.
Keep identity-sensitive devices as direct USB routes where possible. This is especially important for hardware that relies on vendor software, LEDs, displays, force feedback, rumble, or proprietary output reports.
Grouping applies only to USB output. Ungroup a Virtual Keyboard before changing its output to Bluetooth.
A Virtual Joystick creates a custom controller instead of reproducing one physical device exactly. You choose what the target OS should see:
- Number of axes
- Number of buttons
- Number of hats
You then map physical Host inputs onto those controls.
- Select Add Input Source from Devices.
- Open Virtual Devices.
- Create a Virtual Joystick.
- Choose its axes, buttons, and hats.
- Add the required mappings.
- Apply the Client profile.
Virtual-joystick mappings are evaluated on the Client. The Host continues sending physical input state; the Client transforms that state into the virtual HID report received by the target computer.
- Direct button mapping: map a physical button to a momentary virtual button.
- Button toggle: toggle a virtual button on or off with each physical press.
- Button to fixed axis value: move an axis to a configured value while a button is held.
- Button pair to axis: use one button to increment an axis and another to decrement it. This works well for trim, mixture, radiator, zoom, and camera controls.
- Held-button axis ramp: repeatedly increment or decrement an axis while a button is held, using a configured step and interval.
- Hat direction to button: turn a physical hat direction into a virtual button.
- Hat direction to axis: increment, decrement, or hold a virtual axis from a hat direction.
- Axis curve: reshape a physical axis to soften the center, make response more aggressive, or limit usable travel.
Example:
Physical button 1 -> Virtual button 1 -> Momentary
Physical button 2 -> Virtual axis 1 -> Increment while held
Physical button 3 -> Virtual axis 1 -> Decrement while held
Physical hat up -> Virtual axis 2 -> Increment while held
Physical hat down -> Virtual axis 2 -> Decrement while held
Virtual Joysticks are generated devices, so expect to configure bindings manually in many games. They are best suited to input-focused routes. For hardware that requires substantial downstream HID communication, use a direct ungrouped route where possible.
Changing the axes, buttons, hats, or identity-related options can cause the target OS or simulator to treat the Virtual Joystick as a changed device. Review its bindings afterward.
A Virtual Keyboard converts controller input into keyboard input. Create one from Device Routing > Add Input Source > Virtual Devices.
It uses the standard HID boot-keyboard model: eight modifier keys and up to six simultaneous ordinary keys. The virtual keyboard remains neutral until a mapping activates; creating one by itself does not produce keystrokes.
Physical buttons, hats, and axes can generate:
- Held keys and key combinations
- Key taps
- Repeat-while-held actions
- Axis threshold and range actions
- Detent transitions
- Short bounded macros
Examples:
Joystick button -> Ctrl+Shift+G
Hat up -> Arrow Up
Axis > 80% -> F10
Button held -> Repeat key
The mapping editor uses visual key and modifier selection rather than requiring HID key codes. Chords are displayed as removable key pills.
Virtual Keyboard mappings can contain short, bounded sequences with separate hold and delay values. Macros are limited to 16 steps and five seconds. They cannot execute applications, commands, or scripts.
A Virtual Keyboard can be exposed through:
- A dedicated USB keyboard function
- The Client's paired Bluetooth LE keyboard
- A grouped USB HID function
A Bluetooth Virtual Keyboard does not consume a USB gadget lane. A grouped Virtual Keyboard must be ungrouped before switching it to Bluetooth.
Keeping generated keyboard state separate from physical keyboard passthrough prevents a virtual action from replacing keys held on a physical keyboard.
The Client's composite USB gadget has one top-level USB identity. In compatibility mode, Studio can designate one resolved direct USB HID route as the Master.
The Master supplies identity fields such as:
- Vendor ID
- Product ID
- Manufacturer
- Product name
The target-visible gadget serial is not copied from the physical Master. It is derived from the provisioned Client's stable device identity so two Clients do not accidentally expose the same USB serial.
Use a Master when a game, simulator, or companion utility expects a particular controller identity. Other USB routes can remain separate functions within the same composite gadget but do not change its top-level identity.
Master rules:
- Choose an individual, resolved direct USB route.
- Do not choose a Bluetooth route; it is not part of the USB gadget.
- Do not choose a grouped controller or generated virtual device.
- Prefer a direct ungrouped USB route for devices that need downstream output.
Some HID devices need communication in both directions:
flowchart LR
device["Physical HID device"]
host["Host Pi"]
client["Client virtual HID"]
target["Target OS / game"]
device -->|Input reports| host
host -->|Realtime UDP| client
client -->|USB HID| target
target -->|Output / feature reports| client
client -->|Downstream UDP| host
host -->|HID write| device
Examples of downstream HID output include:
- Keyboard lock LEDs
- Gamepad rumble
- Joystick force feedback
- Annunciator lights
- Displays
- Vendor-specific feature reports
GhostInput preserves and forwards compatible report bytes; it does not need to understand every vendor protocol.
For best compatibility, hardware that relies on downstream reports should normally remain a direct ungrouped route. Grouped and custom virtual routes should be treated as input-focused unless explicit output support exists for their virtual shape.
GhostInput uses Bluetooth on the Host and Client for different purposes.
The selected Host can manage paired Bluetooth input and audio devices.
The Host Bluetooth page can:
- Inspect the adapter
- Discover and pair devices
- Remove pairings
- Connect or disconnect known devices
- Review trust state
GhostInput devices are filtered from the Host's nearby-device list to avoid offering another Host or Client as a controller to pair.
Host Bluetooth is enabled by default so known devices can reconnect without Studio being open. When no device is connected and discovery is off, BlueZ remains mostly idle. Disabling Host Bluetooth from Services stops BlueZ and blocks the radio until it is enabled again.
Supported physical keyboard and mouse routes, as well as mapped Virtual Keyboards, can expose input through the Client's Bluetooth LE HID device.
This is useful when USB gadget lanes are limited or wireless presentation to the target computer is preferred. Pair the target computer with the Client Bluetooth HID device after enabling the route.
The Client BLE helper remains dormant when no Bluetooth HID route uses it. Operating systems can cache older pairing information; if a substantially changed BLE configuration behaves incorrectly, remove the old pairing and pair again. The exact pairing workflow varies by target OS.
GhostInput can relay audio in both directions between the target computer and a Host. Both directions use Opus.
flowchart LR
target["Target-computer audio"]
client["Client Pi<br/>USB capture and Opus encode"]
host["Host Pi<br/>Recover, decode, and play"]
output["Speakers / headphones"]
target -->|USB Audio| client
client -->|Opus over UDP| host
host -->|ALSA| output
The output can be a Raspberry Pi headphone jack, a USB sound device, or a compatible Bluetooth playback sink.
Volume and mute changes made through the GhostInput USB audio device are applied to that relayed stream when the target OS exposes the standard UAC2 controls. They do not change the Host's global ALSA mixer or other Host audio.
Speaker relay uses bounded, deadline-aware replay for missing UDP frames. The Client retains a small circular cache and the Host may request a missing frame only while it can still arrive before the playback deadline. New audio always takes priority; Opus FEC and packet-loss concealment remain the fallback when a frame cannot be recovered in time.
flowchart LR
microphone["Microphone"]
host["Host Pi<br/>ALSA capture and Opus encode"]
client["Client Pi<br/>Decode and feed USB audio"]
target["Target-computer microphone input"]
microphone -->|ALSA| host
host -->|Opus over UDP| client
client -->|USB Audio| target
The Host captures the physical microphone. The Client decodes the stream and feeds it to the target-facing USB microphone endpoint.
Audio Relay consumes one Client USB gadget lane. If no lane is available:
- Group compatible joystick routes or a Virtual Keyboard.
- Move physical keyboard/mouse routes or a Virtual Keyboard to Bluetooth.
- Remove unused USB routes.
- Disable Audio Relay if it is not required.
| Setting | Starting value |
|---|---|
| Speaker Opus bitrate | 96 kbps stereo |
| Speaker sample rate | 48 kHz |
| Microphone sample rate | 24 kHz |
| Frame duration | 20 ms |
| Network buffer | Balanced (120 ms) |
| Opus in-band FEC | Enabled |
| Packet-loss hint | 5% |
The Client Audio Relay Network buffer controls how much decoded audio the Host keeps ready for network jitter and replay delay:
- Low latency (60 ms): wired or exceptionally clean Wi-Fi
- Balanced (120 ms): recommended starting point
- Stable (180 ms): greater burst tolerance at the cost of latency
- High stability (240 ms): highest preset tolerance and latency
The Host Services Speaker output buffer is separate. It controls how much decoded audio ALSA queues before the sound device starts or resumes. Increase the network buffer for delivery variation; increase the speaker output buffer for local playback underruns.
Where the hardware supports the configured format directly, prefer the ALSA
hw: endpoint. Use plughw: only when ALSA conversion is required.
Typical direct endpoints include:
- Client UAC2 capture:
hw:1,0 - Raspberry Pi analog output:
hw:CARD=Headphones,DEV=0
If playback sounds distorted while telemetry shows steady 50 fps, no network
gaps, no increasing FEC/PLC counts, and no increasing underruns, compare the
direct hw: endpoint with plughw:.
Bluetooth headset playback through BlueALSA normally uses classic Bluetooth A2DP, not Bluetooth LE Audio. It generally adds latency through the codec, transport, BlueALSA, and headset buffering.
If network delivery remains healthy but playback underruns increase, a larger Host speaker output buffer may improve stability. It also adds latency, so use the smallest stable value.
Each managed Host or Client has pages for:
- General identity and hostname
- Network settings
- Service settings
- Bluetooth state
- Audio Relay
- Runtime health and telemetry
- Network diagnostics
Studio stops treating stale device data as current when a Host or Client is no longer reachable.
GhostInput can report conditions such as:
- High Raspberry Pi temperature
- Current or previous throttling
- Undervoltage
- Stale communication
- Stream timeout
- Packet gaps or invalid traffic
- Audio Relay errors
A previous-throttling warning can remain after the immediate problem ends because Raspberry Pi firmware records that throttling occurred earlier in the boot. Correct the power or cooling issue and reboot to clear the latched state.
Cumulative packet and recovery counters do not necessarily mean the current stream is unhealthy. Studio's health determination also considers whether errors are recent and whether the stream has recovered.
Use Network Test before assuming a joystick, Audio Relay, or mapping problem is caused by GhostInput itself. Diagnostics can identify packet loss, ordering, pacing, and latency variation.
The Host-to-Client input pacing benchmark starts at 4 ms and increases the candidate interval in 2 ms steps until both the initial and longer confirmation trials are stable. Use its recommendation as a measured starting point for the specific Host, Client, and network path.
Wi-Fi can show excellent signal while still suffering from interference, airtime congestion, driver behavior, or packet loss. For realtime GhostInput traffic, consistency matters as much as signal strength. Wired Ethernet for the Host is preferred where practical.
GhostInput is designed for a trusted private network.
Provisioning creates one installation identity shared by Studio and the provisioned Pis. Studio and Clients use HMAC challenge-response authentication and temporary, role-scoped tokens before protected management or stream-start requests are accepted. Normal users do not manage this manually.
Authentication is used for actions such as:
- Reading detailed inventories and profiles
- Changing routes and device settings
- Starting and stopping streams
- Managing Bluetooth
- Running network tests and diagnostics
- Restarting or updating GhostInput services
Basic discovery information remains visible so Studio can locate devices before authenticating.
Current limitations include:
- Control APIs use HTTP rather than HTTPS.
- HID realtime traffic uses unencrypted UDP.
- Audio realtime traffic uses unencrypted UDP.
- Realtime packets are not cryptographically authenticated.
The challenge-response procedure avoids sending the installation secret over the network, but subsequent access tokens and API data are not encrypted. GhostInput is not intended to secure a hostile or monitored LAN.
- Use GhostInput on a private network you trust.
- Do not expose GhostInput ports directly to the internet.
- Keep guest and untrusted IoT networks separate where practical.
- Protect the Windows account running Studio and the Pi SSH credentials.
- Change or disable temporary provisioning passwords when no longer required.
- Use a trusted VPN rather than direct port forwarding for remote access.
The installation secret is stored in Windows Credential Manager and a protected identity file on each provisioned Pi. If Studio is reinstalled or the PC is reimaged, Studio can recover the identity from an existing Pi over SSH during provisioning.
See Security for the full trust model, recovery procedure, and developer design.
Studio includes the Host and Client versions intended to work with that Studio release. Keep Studio, Hosts, and Clients on compatible/current versions.
The About page checks for Studio updates. When an update is available, Studio can download and install the package. Pending configuration changes must be applied or discarded first.
Provisioned devices can normally be updated from Studio without rebuilding the Raspberry Pi OS image. Normal updates are designed to preserve:
- Routes and device settings
- Service configuration
- Bluetooth bonds and reconnect state
- Audio Relay configuration
- GhostInput installation identity
The Bluetooth HID helper is restarted during an update only when its helper or systemd unit actually changes. This avoids unnecessarily disrupting an active Windows Bluetooth connection.
Reprovisioning should not normally be necessary just to install an updated runtime.
Use Start with a clean GhostInput configuration when you intentionally want to reinstall a Pi without retaining the existing role-specific routes and runtime settings.
A clean same-role reprovision preserves the installation identity, network configuration, hostname, same-role Bluetooth pairings, and stable Host identity where applicable. A Host-to-Client or Client-to-Host role replacement is more destructive and clears state that belongs to the old role. Studio warns before continuing.
Studio provisioning is recommended for normal users. Advanced and development deployments can use the command-line scripts.
Host:
./scripts/deploy-host-ssh.sh pi@ghostinput-host.local
./scripts/install-host-service.sh pi@ghostinput-host.localClient:
./scripts/deploy-client-ssh.sh pi@ghostinput-client.local
./scripts/install-client-service.sh --start pi@ghostinput-client.localThe Client installer configures BlueZ BLE as the default Bluetooth HID mode. The radio and helper remain dormant while no Bluetooth keyboard, mouse, or Virtual Keyboard route uses them. Bluetooth HID can still be disabled from Manage Client > Services.
Manual installation is intended for development, testing, and customized deployments. Studio provisioning also handles prerequisite setup and role-specific configuration.
The Client cannot expose an unlimited number of USB HID/audio functions. When lanes are exhausted, group compatible joystick routes or a Virtual Keyboard, move keyboard/mouse output to Bluetooth, remove unused routes, or disable Audio Relay.
Grouped devices do not preserve each source device's original descriptor, VID, PID, or individual USB identity. Keep identity-sensitive hardware as direct USB routes where possible.
Grouped and custom virtual devices appear to Windows as generated hardware. Games and simulators may require manual controller assignment. Review bindings after grouping devices, creating Virtual Joysticks, changing virtual-device shape, or changing USB identity.
GhostInput forwards compatible downstream HID reports but does not interpret every vendor protocol. Devices that depend heavily on proprietary output behavior are best kept as direct ungrouped routes.
Bluetooth behavior differs with Raspberry Pi model, chipset, firmware, Windows version, pairing history, and device firmware. Removing an old pairing and pairing again can be necessary after major Bluetooth device-shape changes.
Low-latency audio is sensitive to Wi-Fi quality, packet loss, latency variation, Host playback hardware, microphone hardware, ALSA behavior, Raspberry Pi load, and buffering. Occasional startup artifacts or glitches are more likely on marginal wireless links.
Undervoltage or thermal throttling can cause input timing irregularities, packet instability, Bluetooth problems, audio glitches, and USB gadget failures. Use an adequate power supply and cooling solution.
See Hardware and Environment for hardware recommendations.
Start with the FAQ for general questions and Troubleshooting for failures and recovery steps.
Useful information for a problem report includes:
- Studio, Host, and Client versions
- Raspberry Pi models and Raspberry Pi OS version
- Target operating system and version
- Studio Windows version when relevant
- Source-device name
- Route type and USB/Bluetooth output
- Whether the route is direct, grouped, or virtual
- Exact error text and relevant screenshots
- Provisioning diagnostics where applicable
- Network Test results where relevant
Do not publish passwords, GhostInput installation secrets, access tokens, or other credentials.
| Document | Purpose |
|---|---|
| Main README | GhostInput overview and download information |
| FAQ | Quick answers to common questions |
| Hardware and Environment | Raspberry Pi, network, USB, Bluetooth, audio, and role guidance |
| Troubleshooting | Recovery steps, logs, and common failures |
| Security | Authentication, installation identity, trusted-LAN model, and limitations |
| Build From Source | Developer build and deployment instructions |
| Developer Documentation | Architecture, protocol, HID model, and implementation references |