Set up Bedrock Simple Voice.

Preparation

What you need before installation

Understand the files

Which JAR belongs on which server?

Step by step

Install on Paper, Purpur, Spigot or Folia

1. Stop the game server completely before replacing plugin files.
2. Download the current BedrockSimpleVoice-Bukkit JAR from the official Modrinth project.
3. Also download the Bukkit builds of Simple Voice Chat and Geyser. Install Floodgate if possible.
4. Place every JAR in plugins. Do not extract the files.
5. Start the server. Bedrock Simple Voice creates plugins/BedrockSimpleVoice/config.yml and messages.yml.
6. For normal operation, only adjust the server name, language and optional message prefix.
7. Restart the server or run /bsv reload after changes.
8. Run /voice diagnose. Relay, pairing and Simple Voice Chat should be available.
9. Run /voice and scan the QR code, or open voice.byterider.xyz and enter the one-time numeric code.
10. Allow microphone access or choose listen-only. A saved device session reconnects automatically on future visits.

Java players with an installed Simple Voice Chat client mod continue using its in-game menu. Bedrock players and Java players without a native client connection can use the browser; the default join reminder targets both groups.

Downloads

Official beta on Modrinth

Modrinth is the official download location for the Bukkit JAR for Paper, Purpur, Spigot and Folia. The optional Velocity JAR for Beta 12 is a separate release asset; it does not go on game servers.

Beta note: Paper, Purpur, Spigot and Folia share the same Bukkit JAR. Fabric is not yet available as a public download. The Velocity JAR is listed separately in the Beta 12 release assets.

Velocity network

Installation on a proxy with multiple servers

Available from Beta 12: The optional Velocity companion supports automatic browser handoff between Bukkit backends and reconnect after a short logout.

The Velocity JAR connects multiple backend servers into one Bedrock Simple Voice network and securely hands an authenticated browser session to the next backend during a server switch. If a player leaves Minecraft and rejoins another backend within two minutes, the browser session follows automatically. Voice packets do not travel through Velocity; each backend remains connected to the relay and Simple Voice Chat itself.

Velocity Proxy
├── lobby      → Paper + Bedrock Simple Voice + Simple Voice Chat
├── survival   → Purpur + Bedrock Simple Voice + Simple Voice Chat
└── event      → Folia + Bedrock Simple Voice + Simple Voice Chat

Automatic handoff supports Bukkit backends: Paper, Purpur, Spigot and Folia. Fabric can run Bedrock Simple Voice individually but is not an automatic handoff target. BungeeCord and Waterfall do not have a companion plugin.

Prepare the proxy

1. Install the Velocity JAR and generate a secret

1. Stop Velocity and all backend servers.
2. Place BedrockSimpleVoice-Velocity-0.2.9-beta.12.jar only in the proxy's plugins folder.
3. Start Velocity once. The plugin creates plugins/bedrocksimplevoice/config.yml with a random strong secret.
4. Stop Velocity and protect this secret. Never publish it or include it in screenshots.
5. Optionally change network.id to a short identifier containing letters, numbers, dots, underscores or hyphens.

network:
  id: "my-network"
  secret: "automatically-generated-secret"
  handoff-timeout-seconds: 10
  backend-freshness-seconds: 45

Prepare backends

2. Install the plugin on every game server

1. Install BedrockSimpleVoice-Bukkit-0.2.9-beta.12.jar on every backend. Do not put the Velocity JAR on a backend.
2. Install Simple Voice Chat on every backend as well.
3. Start each backend once to create its configuration.
4. Enable network and copy the proxy's network ID and secret.
5. Assign a unique backend-id, ideally matching the name used in Velocity.
6. Keep the normal relay configuration on every backend and use relay mode. Each server connects to the same relay independently.

network:
  enabled: true
  network-id: "my-network"
  backend-id: "lobby"
  shared-secret: "same-secret-as-velocity"

The network ID, shared secret and handoff-timeout-seconds must match on the proxy and every backend. The backend ID must be unique per server.

Player identity

3. Connect Velocity, Geyser and Floodgate correctly

Velocity and all backends must see the same UUID for a player. Configure Velocity's secure player forwarding and follow the proxy documentation for Geyser and Floodgate. Bedrock Simple Voice does not replace identity forwarding.

Start and verify

4. Start the network and test handoff

1. Start the backends first and wait until Bedrock Simple Voice and Simple Voice Chat are ready.
2. Start Velocity. Run /bsvnetwork to inspect registered backends. Players need bedrocksimplevoice.network.admin.
3. Join through the proxy, connect the browser using /voice, then switch to another configured backend.
4. The same browser session should continue automatically without entering a new PIN.
5. Grant bedrocksimplevoice.network.admin only to trusted administrators who need the in-game status command.

Backends report readiness over their outbound Relay connection, even when empty. To test reconnect, connect voice on one backend, leave the Minecraft network, then rejoin within two minutes on another backend. The browser session should move automatically without a new code.

Proxy troubleshooting

If automatic server switching fails

Operating modes

Use the central connection or host the website yourself

server:
  connection-mode: "relay"
  relay:
    url: "wss://voice.byterider.xyz/relay/server"
    public-url: "https://voice.byterider.xyz"

Central website updates do not force an immediate plugin update. Older plugins remain usable through the stable relay protocol.

Web client

Available voice features

Optional reports

Self-hosted ecosystem reporting is opt-in

Self-hosted relays and direct installations are not automatically visible to Byterider. Operators may enable anonymous ecosystem counts. The feature is disabled by default.

status-reporting:
  enabled: false
  endpoint: "https://voice.byterider.xyz/api/ecosystem/heartbeat"
  interval-seconds: 60

Reports contain a random installation ID, product version, platform category, relay mode, aggregate server and user counts, timestamp and nonce. They never contain server names or domains, player identities, chat, groups, pairing codes, tokens or audio.

Set enabled: false to stop reporting. With the server stopped, delete data/status-reporting.json to remove the local reporting ID and token.

Error diagnostics

Pseudonymous plugin error overview

Plugin diagnostics are separate from the optional public ecosystem counts and are enabled by default. They help identify recurring errors across multiple installations.

diagnostics:
  enabled: true
  endpoint: "https://voice.byterider.xyz/api/diagnostics/heartbeat"
  interval-seconds: 60

Reports include a random installation ID, plugin version, platform, relay mode and Relay version/build, random Relay server ID for matching it in the admin panel, aggregate counts for all players, Bedrock players, Bedrock voice users and all browser voice users, plus player/voice high-water peaks. Peaks are stored maxima with no timeline or timestamp. Bedrock counts are unavailable when Geyser/Floodgate cannot be queried on the plugin platform. Bounded error fingerprints contain only the plugin component, operation, exception class and counter. Error messages, stack traces, server or player names, addresses, chat and audio are not sent. IP addresses are not stored in diagnostic records. Error events expire 30 days after their last occurrence; inactive installations are removed 30 days after their last heartbeat.

The /admin/ overview is protected by a local relay account. Set it up from the server console with java -jar relay.jar --set-admin-login. The password is stored as a PBKDF2 hash; there is no default password. Set diagnostics.enabled: false to stop reports. The local data/diagnostics-reporting.json file contains the random ID and token.

The private operator dashboard separates Relay servers, plugin installations, Voice monitoring, diagnostics, statistics and system settings. Live throughput and CPU/RAM are measured by the Relay; older plugins still work but may not provide Bedrock counters or a verified installation link. Minute-level operational histories default to 30 days (configurable: 1–90). Per-server data, errors and admin actions are not exposed through the public status page. Missing diagnostics does not prove a fault-free Voice connection.

The Relay operator can optionally set BSV_RELAY_DISCORD_WEBHOOK_URL to receive one alert after the first accepted heartbeat for a new plugin installation. The message contains only random installation and Relay IDs, version, platform and Relay mode. Failed deliveries are retried; existing installations are not reported retroactively. The alert is disabled when this variable is unset.

Classic self-hosting

Publish the embedded web server

Set server.connection-mode to direct. If Nginx runs on the same machine, bind the plugin to 127.0.0.1. Nginx then provides HTTPS and WebSocket upgrades.

server {
    listen 443 ssl http2;
    server_name voice.example.com;

    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_read_timeout 3600s;
        proxy_buffering off;
    }
}

This option requires your own domain, a valid SSL certificate and a web port reachable by the reverse proxy. Managed relay mode is easier on most game server panels.

Players

Important commands

Web chat

Server chat in its own view

When enabled by the server, a dedicated Chat tab appears after connecting. Public messages from Java and Bedrock players appear on the left and your own browser messages on the right with player name and time.

The browser keeps at most the latest 200 messages of the current page session. Bedrock Simple Voice does not store a permanent chat history.

Customization

Server name, prefix and messages

The server name, language and chat prefix are configured in config.yml. Minecraft, Geyser and browser messages can be changed in messages.yml. Keep placeholders such as {0} intact and run /bsv reload after changes.

server:
  name: "My Minecraft Server"
  prefix: "&7[&bVoice&7] &r"
  language: "en_US"

The bundled configuration is written in English. A fully commented German example is available separately.

A valid server-icon.png in the server directory is shown on the voice page. The QR code in the Bedrock form must be scanned with another device because Minecraft Bedrock cannot open an external browser from that form.

Updates

How the update checker works

At server startup, the update checker compares official Bedrock Simple Voice Modrinth versions with Byterider's public version service. It filters by server platform and Minecraft version, and can also detect a release before Modrinth's version list has synced. The console shows a notice and download link.

updatechecker:
  enable: true

The checker is enabled by default. Existing configurations are migrated once; set enable: false to opt out. It never downloads or installs a JAR automatically.

Find problems

If the connection does not work immediately

Security

Important connection properties