Frequently Asked Questions

How do I update yt-dlp?

yt-dlp is a Python dependency. Update it with your package manager:

# With uv
uv pip install --upgrade yt-dlp

# With pip
pip install --upgrade yt-dlp

You can also use the built-in auto-updater command (admin only):

!updatedependency yt-dlp

The bot can’t connect to my Mumble server

Check the following:

• IP and port are correct. Verify with:

  python -m mumimo --ip <ip> --port <port>

• Server password. If the server requires a password, pass it via --password or set the MUMBLE_PASSWORD environment variable.
• Server is reachable. Confirm the Mumble server is running and accessible from the bot’s host. Check firewalls and port forwarding.
• Username is available. The bot’s configured username may already be in use on the server. Change the username in config.toml or via the --user flag.

Audio playback is choppy

This is a known issue being tracked. The ffmpeg feeder needs better buffering. As a workaround:

• Reduce the queue length in your config.toml.
• Ensure ffmpeg is installed and up to date.
• Use a wired connection if the Mumble server is remote.
• Avoid running the bot on a heavily loaded machine.

How do I disable a plugin?

Add the plugin name to the disabled_plugins list in your config.toml:

[plugin]
disabled_plugins = ["sound_board", "images"]

Disabled plugins are never loaded, regardless of mode.

How do I run in safe mode?

Use the --safe flag:

python -m mumimo --ip <ip> --port <port> --safe

In safe mode, only plugins listed in the safe_mode_plugins configuration are loaded. By default this includes core_commands and bot_commands. You can customise the list in config.toml:

[plugin]
safe_mode_plugins = ["core_commands", "bot_commands"]

How do I reset the database?

1. Stop the bot.
2. Delete the .db file in your data directory (e.g. data/mumimo.db).
3. Restart the bot.

On the next boot, the database is recreated with the default schema. All stored users, roles, plugins, and aliases will be lost.

Caution

Back up the database file before deleting it if you want to preserve any data.

Python 3.13+ says “No module named audioop”

Python 3.13 removed the audioop module from the standard library. Mumimo declares audioop-lts as a conditional dependency that is installed automatically on Python 3.13+. If it is missing:

pip install audioop-lts

This should only be necessary if you installed dependencies manually without using uv sync or pip install -e ..

How do I set up the AI assistant?

1. Get an API key from OpenRouter.

2. Add the key to your config. In config.toml:

   [ai_assistant]
   api_key = "sk-or-v1-..."

   Alternatively, use an environment variable:

   [ai_assistant]
   api_key_env_var = "OPENROUTER_API_KEY"

   Then export the variable before starting the bot:

   export OPENROUTER_API_KEY="sk-or-v1-..."

3. Restart the bot and test with:

   !chat Hello!

How do I change the bot’s command prefix?

Set command_token in config.toml under the [main] section:

[main]
command_token = "!"

You can change this to any string (e.g. ?, ., !m ). The prefix is used to identify commands in Mumble chat.

How do I create a custom role?

Define the role in config.toml under [roles.<name>]:

[roles.dj]
description = "Can manage audio playback."

Then assign it to users at runtime (admin only):

!role add <username> dj

To remove a role:

!role remove <username> dj

To list all assigned roles:

!role list

Note

Custom roles can be used in plugin.toml command declarations just like built-in roles. For example, roles = ["dj"] on a command restricts it to users with the dj role.