This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

Voice — Join-to-Create

One private voice channel per user: anyone who joins the lobby channel automatically gets a fresh channel in the configured category, with owner permissions to rename, lock, set user limits, kick, and more.

---

Activation

In configs/config.yml:

addons:
  voice: true

channels:
  voice-lobby: "VOICE_CHANNEL_ID"   # Lobby — user joins here and gets their own channel

Then restart the bot (or run /voice reload).

---

voice.yml

configs/modules/voice.yml:

enabled: true
lobbyChannelId: "0"              # Override for channels.voice-lobby (0 = use fallback)
categoryId: "0"                  # Category where new channels are created (0 = parent of lobby)
nameTemplate: "🎮 %user%"         # Placeholders: %user% (= %user_name%), %user_id%
defaultLimit: 0                  # User limit for new channels (0 = unlimited, 1-99)
emptyDeleteSeconds: 30           # Auto-delete timer when channel is empty (5-600s)
maxChannelsPerUser: 1            # Max concurrent channels per user (1-5)
defaultBitrate: 64               # Bitrate in kbps (8-384)

Field	Default	Meaning
lobbyChannelId	"0"	If set, overrides channels.voice-lobby from config.yml
categoryId	"0"	Category for new channels — fallback: parent of the lobby
nameTemplate	"🎮 %user%"	Channel name. Placeholders: %user% / %user_name% (display name, identical), %user_id%
defaultBitrate	64	Bitrate in kbps — automatically capped to guild.maximumBitrate if the server boost tier allows less
defaultLimit	0	Initial user limit (can be changed by the owner with /voice limit)
emptyDeleteSeconds	30	How long an empty channel stays open before being deleted
maxChannelsPerUser	1	Users at the maximum are moved to their existing channel instead of getting a new one

---

How It Works

1. User joins #voice-lobby
2. Bot checks: does the user already have their own channel?
   - Yes, max reached → moves the user into their existing channel
   - No → creates a new channel with:
     • Name from nameTemplate
     • Category from categoryId (or parent of the lobby)
     • Permission overwrite: owner gets ManageChannels + Move/Mute/Deafen/PrioritySpeaker
     • User limit: defaultLimit
     • Bitrate: defaultBitrate
3. Bot moves the user into the new channel
4. When the channel is later empty:
   - Timer starts (emptyDeleteSeconds)
   - Re-join → timer cancelled
   - Timer expires → channel + DB entry deleted

On Bot Restart

On startup, the bot scans all known voice channels in the DB:

• Channel no longer exists in Discord → delete DB entry
• Channel is empty → delete channel + DB entry
• Channel has users → leave it alone

⚠️ Cleanup uses channel.fetch() instead of cache — the cache is often incomplete right after a restart.

⚠️ Root channel warning: If categoryId is not set and the lobby has no parent category, the new voice channel will land at the server root. The bot logs a warning in this case — admins should configure voice.yml > categoryId.

Move failure: If the bot cannot move the user into the new channel (e.g. missing Move Members permission in the target), the user is disconnected from the lobby instead of being left there.

---

Owner Commands

These only work inside your own voice channel.

Command	Function
/voice rename <name>	Rename the channel (5-min cooldown — protects Discord's rate limit of 2 renames per 10 min)
/voice lock	Deny Connect for @everyone — only trusted users can join
/voice unlock	Remove the lock
/voice limit <count>	Set user limit (0 = unlimited, 1–99)
/voice kick <user>	Kick a user from the channel
/voice trust <user>	Allow a user to join even when the channel is locked
/voice untrust <user>	Remove trust
/voice transfer <user>	Hand over ownership (target must be in the channel)
/voice claim	Claim an abandoned channel — only works if the owner is no longer in it
/voice info	Show channel details

See the Voice Commands page for more details.

---

Admin Commands

Command	Permission	Function
/voice reload	Manage Server	Reloads voice.yml — new settings take effect immediately

---

FAQ

What happens when the owner leaves? The channel stays open but will eventually hit the auto-delete timer (once no one is left inside). As long as someone is still in the channel, another user can take over with /voice claim.

Can a user have multiple channels? Yes, if maxChannelsPerUser > 1. The default is 1 — the user is moved to their existing channel instead of getting a new one.

What happens when the lobby channel is changed? Simply update voice-lobby in config.yml and restart the bot — it will use the new channel from the next join onward.

Audit log: Voice channel creation and deletion by the Voice module are logged by the Server Audit Logger as CHANNEL_CREATE / CHANNEL_DELETE — visible in the mod-log channel.