Transcribe Premium

Transcribe Premium listens to players through Simple Voice Chat and turns the keywords and phrases they speak into commands, skill casts and events. It runs on Paper and Folia, 1.21.x and the 26.x line.

How it works

1. A player opens a Listen Window, for example with Shift+Q.
2. Their speech is recognised on the server against the words you defined.
3. A match is checked against permissions, cooldown and mute state.
4. The actions and hooks in that keyword’s file run.

Features

• One file per keyword. Each word or phrase lives in plugins/Transcribe/keywords/ with its own cooldown, permission and actions.
• Light on resources. Audio is only processed while a window is open, and recognition load is capped.
• Fast. The window closes as soon as the player stops talking, so commands run right after they finish speaking.
• Safe reloads. If /transcribe reload finds a bad edit, the old setup keeps running.
• Integrations. MythicMobs, Nexo, ItemsAdder, Oraxen, PlaceholderAPI, or any plugin that exposes commands.

Where to go next

Installing for the first time: Install, then the Quick start. Writing your own keywords: Keywords and phrases and Recipes. Something not working: Troubleshooting or the Discord.

Install

Requirements

• Paper or Folia, 1.21.x or the 26.x line
• Simple Voice Chat on the server (required) and on each player’s client
• Java 21 for 1.21.x servers, Java 25 for 26.x servers
• A license key. If you bought the plugin on BuiltByBit, it is already inside the jar you downloaded.
• Outbound HTTPS from the server: to check the license on every start (and every 6 hours), and on first start to download the Vosk model (about 40 MB, one time). The model can also be installed by hand.

Steps

1. Download the plugin (from your account on eyman.dev, or from BuiltByBit) and pick the jar that matches your server: Transcribe-Premium-1.0.0-mc<target>.jar. Targets are 1.21.x, 1.21.8, 1.21.11, 26.1, 26.2 and 26.3.
2. Put one Transcribe jar in plugins/. All targets share the plugin name Transcribe, so never install two.
3. Start the server. The plugin finds the license key inside the jar, saves it to plugins/Transcribe/config.yml and checks it. Look for License OK. in the console. If it says the license check failed instead, see License key.
4. On first start the plugin also downloads the Vosk model, unzips it into plugins/Transcribe/models/vosk-model-small-en-us-0.15 and deletes the zip. Nothing to unpack yourself. Two example keywords, light (makes you glow) and fire ball, are created for you.
5. Wait for Vosk model ready - speech recognition is active. in the console. Recognition is off until then, and the server is not blocked while it downloads.
6. Hold Shift and press Q, then say “fire ball”.

License key

Transcribe Premium needs a license key to run. Keys look like TRSC-XXXXX-XXXXX-XXXXX-XXXXX and are stored in config.yml:

license:
  key: "TRSC-XXXXX-XXXXX-XXXXX-XXXXX"

Bought on BuiltByBit: you don’t need to do anything. BuiltByBit puts your personal key inside the jar when you download it, and on first start the plugin copies it into config.yml and logs License key from your BuiltByBit download was saved to config.yml. Downloading again, for example for an update, gives you the same key.

Bought on eyman.dev: buy from the store while signed in to your eyman.dev account. After paying, Tebex sends you back to the account page, and your key and the downloads for every version appear there within a few seconds. They stay there, so sign in any time to grab an update or an older build. Copy the key into license.key in config.yml, then restart the server. If you bought more than one copy, each one has its own key.

Bought on Tebex before accounts existed: sign in (or create an account) at eyman.dev/account and use Link an earlier purchase with the transaction ID (starts with tbx-) and the email from your Tebex receipt. BuiltByBit buyers can link their key the same way to get the downloads page too. The old claim page still shows the key for a transaction as well.

Forgot your password? There's no reset email yet. Ask on Discord and you'll get a temporary password.

Got a key some other way, or the console says the license check failed: paste the key into license.key in plugins/Transcribe/config.yml and restart the server. A key in config.yml always wins over the one in the jar.

How the check works:

• The key is checked on every start and again every 6 hours. Without a valid key the plugin stays loaded but not activated: voice features are off, and the rest of the server keeps running normally.
• When it is not activated, the console shows a warning box on start, and every player with transcribe.admin (ops by default) gets an in-game message a few seconds after joining. Each admin sees it once per restart, not on every join. /transcribe shows the same message.
• If a key is disabled while the server is running, admins who are online are told straight away and the plugin turns off.
• If the license server can’t be reached, a key that was confirmed within the last 3 days keeps working, so a short outage or network problem never takes your server down. A running server is only stopped when the key is actually rejected.
• On a fresh install (or after more than 3 days without reaching the license server), a check that gets no answer is retried twice, after 2 and 5 seconds, so a brief network hiccup doesn’t leave the plugin not activated.
• The check sends only the key, the plugin version and a random ID for this installation. No player data or audio is sent.
• Keep your key private. It belongs to your purchase.

Automatic model download

When engine.internal.model-path is missing or empty, the plugin fetches the model from engine.internal.auto-download.url (by default https://alphacephei.com/vosk/models/vosk-model-small-en-us-0.15.zip). The same check runs on /transcribe reload. In order, it:

1. Downloads the zip into a temporary folder inside plugins/Transcribe/models/.
2. Unzips it there, then deletes the zip.
3. Moves the unpacked model to model-path and removes the temporary folder.

The model folder only appears once it is complete, so an interrupted or failed download leaves nothing half-installed and is simply retried on the next start or reload. The download is HTTPS only. If it fails, the plugin stays enabled with recognition off, the console says why, and /transcribe reload tries again once the problem is fixed.

engine:
  internal:
    model-path: models/vosk-model-small-en-us-0.15
    auto-download:
      enabled: true
      url: https://alphacephei.com/vosk/models/vosk-model-small-en-us-0.15.zip

Installing the model by hand

If the server can’t reach alphacephei.com, or you prefer to manage models yourself, set engine.internal.auto-download.enabled: false, download a model from alphacephei.com/vosk/models on another machine, and unpack it so that the model folder (the one containing am, conf and graph) is at the path in engine.internal.model-path. With auto-download off and no model present, the plugin disables itself with a “Vosk model not found” error.

To use a different model, point model-path at a new folder name and change auto-download.url to that model’s zip. Whatever the zip’s inner folder is called, the model is installed at model-path. Keywords must use words that exist in the chosen model’s lexicon.

Quick start

This assumes the plugin, Simple Voice Chat and a Vosk model are already installed and the server has started.

Try the example keyword

A fresh install also ships with the keyword light: say light and you glow for 10 seconds. It uses effect give %player% minecraft:glowing 10 0 true, which on Folia may need a Folia-aware command instead (see Keywords and phrases). It also ships with the phrase fire ball. Hold Shift and press Q, wait for the “Listening” action bar, and say fire ball. You should get a red chat message and hear a pickup sound.

Add your own phrase

Create the file from in-game or the console. The plugin writes it and reloads straight away.

/transcribe add phrase "light up"

Open plugins/Transcribe/keywords/light_up.yml and give it an action:

actions:
  executor: CONSOLE
  commands:
    - "tellraw %player% {\"text\":\"Lights on\",\"color\":\"yellow\"}"

Run /transcribe reload, open a window and say light up.

Tune it

If it fires too rarely, lower min-confidence in the keyword file. If a multi-word phrase is cut short, raise endpointing.end-silence-millis in config.yml. Pick words that exist in the speech model’s vocabulary; invented words often never match.

Open a listen window

Nothing is recognised until a window is open. Triggers are set under activation in config.yml:

Triggers

Window length and access

The window lasts window-seconds (default 3.0) at most. With endpointing on it closes earlier, once the player stops speaking. Other plugins can open windows through the API.

Players need transcribe.use and must not be muted. With cancel-trigger-action: true the Shift+Q or Shift+F press does not drop or swap the item.

Keywords and phrases

Creating a keyword

One word is a keyword, two or more words (up to 6) are a phrase. Create a file with a command, then edit it:

/transcribe add keyword lightning
/transcribe add phrase "fire ball"

The id is the phrase in lower case with spaces turned into underscores, so fire ball has the id fire_ball. Allowed characters are a-z, digits, apostrophes and single spaces.

File format

enabled: true
phrase: "fire ball"
aliases:
  - "fireball"            # extra spoken forms for the same action
permission: ""            # blank = transcribe.phrase.fire_ball
min-confidence: 0.70      # 0.0 to 1.0
cooldown-seconds: 5       # per player
actions:
  executor: CONSOLE       # CONSOLE or PLAYER
  commands:
    - "tellraw %player% {\"text\":\"Fire ball!\",\"color\":\"red\"}"
hooks:
  mythicmobs:
    enabled: false
    skill: "Fireball"

Options

Things to know

Placeholders

Usable in commands and hook values. PlaceholderAPI placeholders are applied afterwards if it is installed.

Context placeholders

Dynamic placeholders

%keyword.<id>[.field]% reads single-word entries and %phrase.<id>[.field]% reads multi-word ones. The default field is matched.

Example: %keyword.light.count% or %phrase.fire_ball.last_ago%.

Plugin hooks

A hook runs only when it has enabled: true and its plugin is installed. Hook failures are logged and never stop other hooks.

Built-in hooks

Example

hooks:
  nexo:
    enabled: true
    executor: CONSOLE
    commands:
      - "nexo give %player% fire_wand 1"
  myplugin:
    enabled: true
    plugin: "ExamplePlugin"
    commands:
      - "example trigger %player% %keyword%"

config.yml

license

engine

performance

debug

activation, permissions, cues, messages

activation is covered on its own page. permissions.keyword-default sets the default for per-keyword nodes (TRUE, OP, FALSE, NOT_OP).

cues controls feedback in MiniMessage. Each of open, close and recognized takes actionbar, sound, volume and pitch. {keyword} works in the recognised cue, and an empty field disables it. messages.unmuted is sent when a temporary mute ends.

External engine

Running server.py

Run recognition on another machine with the bundled server.py (Python 3.11+, pip install websockets vosk). The model is not auto-downloaded for this script: use the same model folder the plugin downloads (plugins/Transcribe/models/vosk-model-small-en-us-0.15) if the machines share a disk, or unpack a model from alphacephei.com/vosk/models yourself.

python3 server.py --model /path/to/vosk-model-small-en-us-0.15 \
    --grammar fire,ball,fireball --host 0.0.0.0 --port 2700

Connecting the plugin

Then set engine.mode: EXTERNAL and engine.external.uri. The plugin does not push the grammar, so --grammar must list every enabled spoken form. The plugin reconnects automatically if the connection drops.

Recipes

Complete keyword files for common setups. Save each one in plugins/Transcribe/keywords/ and run /transcribe reload.

Cast a MythicMobs skill

The skill is cast with the speaker as caster. The alias covers the way the model sometimes splits the word.

enabled: true
phrase: "fire ball"
aliases:
  - "fireball"
min-confidence: 0.70
cooldown-seconds: 5
hooks:
  mythicmobs:
    enabled: true
    skill: "Fireball"

Run a command as the player

PLAYER runs on the speaker’s own region with their permissions, which is the safer choice on Folia.

enabled: true
phrase: "take me home"
cooldown-seconds: 30
actions:
  executor: PLAYER
  commands:
    - "home"

Limit a keyword to a rank

A permission: value replaces the default node, so any permissions plugin can gate it.

enabled: true
phrase: "ice spike"
permission: "myserver.spells.ice"
cooldown-seconds: 8
actions:
  executor: CONSOLE
  commands:
    - "execute at %player% run particle minecraft:snowflake ~ ~1 ~ 0.4 0.4 0.4 0.02 40 force"

Show usage stats

The dynamic placeholders read per-player counters, so you can report them in the same action.

actions:
  executor: CONSOLE
  commands:
    - "tellraw %player% {\"text\":\"Cast #%keyword.light.count% (%confidence_percent%%)\",\"color\":\"gold\"}"

Open the window from a hotbar slot

Selecting slot 9 (index 8) opens a window, no sneaking required. Set this in config.yml:

activation:
  window-seconds: 3.0
  shift-q: false
  shift-f: false
  hotbar-slot: 8

Commands

/transcribe, alias /tsc. Quotes group words, so "fire ball" is one argument.

Reference

Reloads

A reload runs off-thread and swaps in only if it succeeds. The reply shows active forms, disabled files and the first problems found.

Permissions

All permissions

transcribe.admin grants all four transcribe.admin.* nodes. To give a moderator only mutes, grant transcribe.admin.mute and transcribe.admin.unmute without transcribe.admin.

What a player needs to cast a keyword or phrase

1. transcribe.use,
2. the file’s own node: transcribe.keyword.<id> for a single word, transcribe.phrase.<id> for a phrase, or its custom permission:,
3. and no active mute.

Overrides and mutes

A permission: value in a keyword file replaces its default node. Muted players are denied even with transcribe.use.

Mutes

Muting a player

Use /transcribe mute Steve 30m. Units are s, m, h, d and w, and you can combine them (1h30m). The maximum is 365 days. Leave the duration off for a permanent mute.

Persistence

Muting closes the player’s open window and discards its audio. Mutes work on offline players, are saved to mutes.yml and survive restarts. Expiry is checked against the wall clock, so a mute that ended while the server was down is already over.

API and event

VoiceWordSpokenEvent

Fired on the speaker’s region thread when a keyword is recognised, after permission and cooldown checks. Cancel it to stop the actions and hooks. It has getPlayer(), getKeyword() and getConfidence().

@EventHandler
public void onWord(VoiceWordSpokenEvent e) {
    if (e.getKeyword().equals("fire ball") && !canCast(e.getPlayer())) {
        e.setCancelled(true);
    }
}

TranscribeAPI

All methods are thread-safe and Folia-safe. Get the instance with TranscribeAPI.get(), which throws if Transcribe is not enabled.

FAQ

Why doesn’t my word or phrase work?

Almost always because the speech model does not have the word in its vocabulary. The default model, vosk-model-small-en-us-0.15, is an English model and can only recognise words that exist in its English word list. If a word is not in that list, the model can never output it, no matter how clearly it is said. It will hear something else, or nothing, and the keyword never fires.

The old example keyword ignis is the classic case. It is Latin, not an English word, so the model cannot produce it. That is why the default example is now light, a real English word that the model knows.

Which words are safe to use?

• Ordinary English words: light, fire, freeze, thunder, shield, heal.
• Phrases made only of ordinary English words: fire ball, ice storm.

Likely to fail: invented spell names (lumos, ignis), non-English words, made-up names, and unusual brand or gamer-tag spellings.

How do I fix a word that never matches?

1. Swap it for a real English word with a similar meaning. This is the most reliable fix.
2. Add aliases. If the model sometimes splits or mishears a real word, list the other forms in aliases, for example fire ball with the alias fireball. Every alias must also be a real word in the model, or it is as useless as the original.
3. Use a model that contains the word. Point engine.internal.model-path and auto-download.url at another model from alphacephei.com/vosk/models. See Install. Larger models know more words but use more memory and CPU.

The word is a real English word but still fires rarely

• Lower min-confidence in the keyword file a little.
• Very short words are easy to confuse. A two-word phrase is often more reliable than a short single word.
• If a phrase gets cut off, raise endpointing.end-silence-millis to 600-800. If the window never closes early or the microphone is quiet, adjust endpointing.speech-rms-threshold. Both are in config.yml.

Nothing is recognised right after the first start

On first start the plugin is downloading the Vosk model in the background. Wait for Vosk model ready - speech recognition is active. in the console. If it never appears, the download failed; see Troubleshooting.

I updated the plugin and still have the ignis keyword

The default keyword files are only created when the plugins/Transcribe/keywords/ folder does not exist yet, so existing servers keep their old files. Delete ignis.yml if you do not want it, and add light with /transcribe add keyword light.

Does my players’ audio leave the server?

Not with the default INTERNAL engine. Recognition runs inside the server. The only network access is the one-time model download and the license check, which sends just the license key, the plugin version and a random installation ID. With EXTERNAL, audio is sent to the WebSocket service you configure.

What happens if the license server is down?

Nothing, as long as your key was confirmed in the last 3 days: the plugin keeps working and checks again later. Only a fresh install that has never reached the license server needs it to be online to start.

Troubleshooting

Debug logging

When a word doesn’t fire and you can’t tell why, set debug: true in config.yml and run /transcribe reload. Every step of a cast is then logged to the console with [debug]. Try the word once and read the lines in order:

Debug logging is chatty, so set it back to false and reload when you’re done.

Common problems

Known limits

• Cooldowns and stats are in memory. Cooldowns survive a relog but not a restart.
• With EXTERNAL, server.py --grammar must be kept in sync with your keywords.

Support

Questions, bug reports and setup help go through the support Discord.

Join the Discord

What to include in a report

• Your server software and version, and whether it is Paper or Folia
• The jar target you installed, such as mc1.21.8 or mc26.1
• Your engine mode, INTERNAL or EXTERNAL
• The keyword file involved
• The relevant part of the console log, from server start if the plugin fails to enable
• If a word doesn’t fire, the console output with debug logging turned on while you try it
• For license problems, your BuiltByBit username. Don’t post your license key in public channels.