Voice Message

Voice Message is a Minecraft NeoForge 1.21.1 mod that lets players record short voice messages and send them to other players as clickable chat messages — no external voice server or account required.

• ✅ Server-authoritative configuration (anti-abuse, rate limiting)
• ✅ Works in single-player, LAN and dedicated servers
• ✅ Free installation: playable even if the other side doesn't have the mod

---

English

Overview

Record a short voice clip with a single key press, and it is broadcast into the chat as a green, clickable message. Any player who clicks it hears your voice instantly — the audio is downloaded on demand and cached locally for the session.

Features

• Record with the V key — hold to record, release to send. Rebindable in the vanilla Controls screen.
• Green boss-bar HUD at the top of the screen shows the remaining recording time (countdown).
• Clickable chat message broadcast to everyone after you finish recording.
• Click to play — the client checks its local cache first and plays immediately; on a miss it downloads, caches and plays.
• Microphone volume (0–200%) adjustable with a slider in the config screen.
• Rate limit / anti-spam — a configurable cap on how many voice messages a player can send per rolling 5-minute window, enforced server-side.
• Server-authoritative audio configuration — max recording duration, sample rate, bitrate, codec (WAV/OPUS) and server cache interval.
• Ephemeral local cache — wiped automatically when you close the game or leave the server.
• Fail-safe compatibility:
  • Server without the mod → voice features are silently disabled on the client; you can still join.
  • Client without the mod → the server simply ignores its (nonexistent) voice traffic.
• Off-game-thread audio — capture, encode, decode and playback never block the game thread.

How to use

1. Put voicemessage-<version>.jar into the mods/ folder on the client (and on the server if you want voice to work there).
2. Join a server that also runs the mod.
3. Hold V to record — a green boss bar counts down the remaining time.
4. Release V to send. Releasing too quickly (< 150 ms) discards the clip.
5. Everyone sees your message in chat; clicking it plays the audio.

Commands

Command	Description
/voicemessage play <uuid>	Play the given voice message (used by the clickable chat message).

Permissions

The mod exposes two permission nodes through the NeoForge permission API. Both default to granted for everyone, so the mod works without a permission plugin. Use LuckPerms to control who can send or receive voice messages:

Node	Default	Effect
voicemessage.send	true	Allows recording and sending voice messages.
voicemessage.receive	true	Allows seeing and playing other players' voice messages.

LuckPerms examples (restrict everyone, then grant to a group):

/lp group default permission set voicemessage.send false
/lp group default permission set voicemessage.receive false
/lp group vip permission set voicemessage.* true

Configuration

Server-side (config/voicemessage-server.toml):

Key	Default	Description
maxRecordingSeconds	30	Max recording length in seconds (1–300).
sampleRate	16000	Audio sample rate in Hz (8000–48000).
bitrate	24000	Audio bitrate in bps (used by OPUS).
codec	WAV	WAV or OPUS.
serverCacheClearInterval	300	Seconds between server cache cleanups.
maxVoiceMessagesPer5Minutes	10	Max voice messages per rolling 5-minute window (0 = unlimited).

Client-side (config/voicemessage-client.toml):

Key	Default	Description
microphoneVolume	100	Microphone volume in percent (0–200), applied to recordings.
localCacheEnabled	true	Whether to cache downloaded messages on disk for the session.
localCacheMaxMb	256	Local cache size limit before old entries are evicted.

The local cache is cleared automatically when the game closes or you leave a server/world.

OPUS codec (optional)

Opus uses the pure-Java Concentus library, which is not bundled by default. To enable it, add the dependency, bundle it (JarJar/shading) and set codec = "OPUS". Clients without Concentus automatically fall back to WAV.

Building

gradlew build

The built jar is build/libs/voicemessage-<version>.jar.

License

The mod is licensed under the GNU General Public License v3 (GPL-3.0) — see LICENSE. The project scaffolding generated from the NeoForged MDK remains covered by its MIT template license — see TEMPLATE_LICENSE.txt.

---

中文

模组简介

Voice Message（语音消息） 是一款基于 NeoForge 1.21.1 的 Minecraft 模组，让玩家可以用按键 录制一小段语音，并以聊天栏中可点击的绿色消息发送给其他玩家——无需外部语音服务器或账号。

• ✅ 服务端权威配置（防滥用、限流）
• ✅ 支持单机、局域网与专用服务器
• ✅ 自由安装：任意一方未安装也可正常进服

功能特性

• 按 V 键录音——长按开始录音，松开发送；可在原版控制设置中更改按键。
• 绿色 BOSS 血条 HUD 显示在屏幕顶部，实时倒计时剩余录音时间。
• 可点击的聊天消息，录音结束后广播给所有人。
• 点击播放——客户端先查本地缓存，命中立即播放；未命中则下载、缓存后播放。
• 麦克风音量（0–200%），可在配置界面用滑块调节。
• 消息冷却 / 防刷屏——服务端可配置每个玩家在滚动 5 分钟内最多发送的语音消息条数。
• 服务端权威的音频配置——最大录音时长、采样率、比特率、编解码器（WAV/OPUS）、服务端缓存清理间隔。
• 临时本地缓存——关闭游戏或离开服务器时自动清除。
• Fail-safe 兼容：
  • 服务端未装模组 → 客户端语音功能静默失效，但仍可正常进服。
  • 客户端未装模组 → 服务端直接忽略其语音流量。
• 离线程音频处理——录音、编码、解码、播放全部在非游戏主线程执行，不影响渲染与 Tick。

使用方法

1. 将 voicemessage-<版本>.jar 放入客户端（如希望服务端生效则也放入服务端）的 mods/ 文件夹。
2. 进入同样安装了本模组的服务器。
3. 长按 V 开始录音——绿色血条显示剩余时间。
4. 松开 V 发送；若松手过快（< 150 ms）将丢弃该段录音。
5. 所有玩家都会在聊天栏看到你的语音消息，点击即可播放。

权限

模组通过 NeoForge 权限 API 暴露两个权限节点，默认对所有玩家开放，因此不装权限插件也能正常使用。 如需用 LuckPerms 控制谁能收发语音，可对以下节点进行管理：

节点	默认	作用
voicemessage.send	true	允许录音并发送语音消息。
voicemessage.receive	true	允许看到并播放他人的语音消息。

LuckPerms 示例（先限制所有人，再向某用户组授权）：

/lp group default permission set voicemessage.send false
/lp group default permission set voicemessage.receive false
/lp group vip permission set voicemessage.* true

配置

服务端（config/voicemessage-server.toml）：

配置项	默认值	说明
maxRecordingSeconds	30	最大录音时长（秒，1–300）。
sampleRate	16000	音频采样率（Hz，8000–48000）。
bitrate	24000	音频比特率（bps，仅 OPUS 使用）。
codec	WAV	WAV 或 OPUS。
serverCacheClearInterval	300	服务端缓存清理间隔（秒）。
maxVoiceMessagesPer5Minutes	10	每个玩家在滚动 5 分钟内最多发送的语音消息数（0 = 不限）。

客户端（config/voicemessage-client.toml）：

配置项	默认值	说明
microphoneVolume	100	麦克风音量（0–200%，作用于录音）。
localCacheEnabled	true	是否将会话内下载的语音缓存到本地。
localCacheMaxMb	256	本地缓存大小上限，超出后淘汰最旧条目。

本地缓存在关闭游戏或离开服务器/世界时自动清除。

OPUS 编解码器（可选）

Opus 使用纯 Java 的 Concentus 库，默认未打包。如需启用，请添加依赖并以 JarJar/遮蔽方式打包， 然后在服务端配置中设置 codec = "OPUS"。未安装 Concentus 的客户端会自动回退到 WAV。

构建

gradlew build

构建产物为 build/libs/voicemessage-<版本>.jar。

开源许可

本模组以 GNU 通用公共许可证 v3（GPL-3.0） 开源——见 LICENSE。 由 NeoForge MDK 生成的工程脚手架仍遵循其 MIT 模板许可——见 TEMPLATE_LICENSE.txt。