Quick Start

Mumimo is a plugin-based Mumble voice-server bot for Python 3.12+. Users type commands like !chat or !ytplay <url> in Mumble chat and the bot responds with audio playback or rich HTML “GUI” messages.

This guide walks you through installation and your first run.

Prerequisites

Before you begin, make sure you have:

• Python 3.12+
• ffmpeg and libopus for audio support
• A running Mumble server (murmur)

For full details on every dependency, see the Requirements page.

Installation

1. Clone the repository

   git clone https://codeberg.org/DuckBoss/Mumimo.git && cd Mumimo

2. Install Python dependencies

   With uv (recommended):

   uv sync

   Or with pip:

   pip install -e .

3. Install system dependencies

   On Debian / Ubuntu:

   sudo apt install ffmpeg libopus-dev nodejs

   On other distributions, install the equivalent packages for ffmpeg, the Opus development headers, and Node.js (needed by yt-dlp for some JS-based extractors).

First Run

Start the bot by pointing it at your Mumble server:

python -m mumimo --ip <server_ip> --port <port> [--password <pw>]

Alternatively, if the package entry-point is on your PATH:

mumimo --ip <server_ip> --port <port>

You can also provide connection details via environment variables instead of CLI flags:

Variable	Purpose
MUMBLE_IP	Server IP address
MUMBLE_PORT	Server port
MUMBLE_PASSWORD	Server password

Note

On the very first run, Mumimo auto-generates a default config.toml in the data directory (usually data/config.toml). You can edit this file to customise behaviour — see the Configuration page.

Safe Mode

Use the --safe flag to load only the core_commands and bot_commands plugins. This is useful for troubleshooting or running a minimal bot:

mumimo --ip <server_ip> --port <port> --safe

You can customise which plugins are considered safe-mode plugins in the [plugin] section of your config.

Docker Quick Start

Prefer a containerised run? Mumimo ships with a Dockerfile and docker-compose.yaml.

1. Clone the repository

   git clone https://codeberg.org/DuckBoss/Mumimo.git && cd Mumimo

2. Build and start with docker compose

   MUMBLE_IP=<server_ip> MUMBLE_PORT=64738 MUMBLE_PASSWORD=<pw> \
     docker compose up --build -d

   The compose file uses network_mode: "host" (recommended for Mumble’s UDP audio) and mounts ./data to /data inside the container.

3. Check the logs

   docker compose logs -f

4. Stop the bot

   docker compose down

Note

On first run, a default config.toml is auto-generated in ./data/ (mounted as /data inside the container). Edit it and restart to customise behaviour.

For more details, see the Docker Deployment page.

Verbose & Quiet Logging

Flag	Effect
--verbose	Enable debug-level logging
--quiet	Restrict output to warnings and above

The default log level is info.

Next Steps

• Configuration — customise the bot via TOML, env vars, and CLI flags.
• Command-Line Arguments — full reference for every CLI argument.
• Commands — explore built-in commands and how to use them.