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. After Modrinth approval, 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 the Simple Voice Chat client mod keep using its in-game menu. Bedrock players and Java players without the client mod can use the browser.

Downloads

Official beta on Modrinth

Modrinth is the official download location for Bedrock Simple Voice. The page may remain unavailable to visitors while project review is in progress. Once approved, it initially offers the Bukkit JAR for Paper, Purpur, Spigot and Folia. Fabric and the optional Velocity companion follow later.

Beta note: Paper, Purpur, Spigot and Folia share the same Bukkit JAR. No public Fabric or Velocity download is available yet.

Velocity network

Installation on a proxy with multiple servers

Preview: The Velocity companion follows in a later beta. This section already documents its planned setup.

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. 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 currently supports Bukkit backends: Paper, Purpur, Spigot and Folia. Fabric can run Bedrock Simple Voice individually but is not an automatic Velocity handoff target. BungeeCord and Waterfall are not currently supported by 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-<Version>.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

relay:
  public-url: "https://voice.byterider.xyz"

Prepare backends

2. Install the plugin on every game server

1. Install the same Bedrock Simple Voice Bukkit version on every 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. Each server connects to the Byterider relay independently.

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

The network ID and shared secret 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. Use /bsvnetwork status to inspect registered backends.
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.

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 status-reporting.json to remove the local reporting ID and token.

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

The Bedrock Simple Voice update checker only checks official releases by Pietriss. While the Modrinth project is under review it uses the public Byterider version endpoint and the final Modrinth download URL. It never uses the release feed of the original fork.

updatechecker:
  enable: false

The checker is disabled by default. It never downloads or installs a JAR automatically.

Find problems

If the connection does not work immediately

Security

Important connection properties