What's New

v1.0.0

Full Architecture Rework

Breaking changes

v1.0.0 is a complete rewrite. The legacy JJMumbleBot/ package has been removed. See the migration guide below if you are upgrading from JJMumbleBot v5.

Highlights

• New package name: jjmumblebot → mumimo (Python package, CLI entry point, imports). Product renamed from “JJMumbleBot” to “Mumimo”.
• New entry point: python -m mumimo or the mumimo console script. No more python . or python main.py.
• Plugin system overhauled: metadata.ini → plugin.toml, privileges.csv → RBAC roles in plugin.toml, aliases.csv → aliases in plugin.toml.
• RBAC privilege model: integer levels (0–5) replaced with named roles (blacklisted, admin, moderator, user + custom roles in config.toml).
• Config format: config.ini → config.toml (typed Config dataclass with TOML/env/CLI loading).
• Audio engine: VLC dropped — ffmpeg only. New AudioEngine with TrackQueue, VolumeController (lerp-based ducking), DniLock (do-not-interrupt), and Feeder (PCM → opus).
• AI assistant: OpenRouter-backed chat, TTS (Gemini voices), STT (!speak), emotion tracking (10 states), karma system, memory store, 15 client-side tools, personas, voice profiles.
• !help reworked: !help lists loaded plugins; !help <plugin> lists that plugin’s commands. No more multi-page pagination.
• Testing: ~1365 unit tests + 6 end-to-end smoke tests against a real murmur Docker container.
• Python 3.12+ required (was 3.9+). audioop-lts auto-installed on Python 3.13+.

Breaking Changes

Area	v5	v6
Package name	JJMumbleBot/	mumimo/
Entry point	python .	python -m mumimo or mumimo
Plugin metadata	metadata.ini	plugin.toml
Privileges	privileges.csv (integer levels 0–5)	RBAC roles in plugin.toml + DB
Aliases	aliases.csv / custom_aliases.csv	plugin.toml + DB (AliasService)
Config	config.ini	config.toml
Audio backend	VLC + ffmpeg	ffmpeg only
Web interface plugin	Included	Removed
Text-to-speech plugin	Separate plugin	Built into ai_assistant
Python version	3.9+	3.12+
Env var prefix	JJMB_*	MUMIMO_*

Changelog

Architecture

• mumimo/app.py — App dataclass + boot() wires all subsystems.
• mumimo/config.py — typed Config dataclass (TOML/env/CLI loading).
• mumimo/core/ — framework internals:
  • command_router.py — 9-step command dispatch pipeline.
  • mumble_session.py — pymumble wrapper (connect, channels, users).
  • event_bus.py — synchronous pub/sub event system.
  • privilege_service.py — PrivilegeService + RoleService.
  • alias_service.py — command alias resolution.
  • bot_service.py — bot lifecycle helpers.
  • lifecycle.py — lifecycle state machine.
  • scheduler.py — scheduled task runner (audio ducking lerps, plugin tasks).
  • history.py — per-user command history.
• mumimo/audio/ — audio engine:
  • engine.py — AudioEngine (playback, queue, loop, DNI).
  • queue.py — TrackQueue (FIFO + move/remove/shuffle).
  • feeder.py — PCM → opus feeder (lazy audioop import for 3.13+).
  • volume.py — volume control with scheduler-driven ducking lerp.
  • dni.py — do-not-interrupt lock state.
  • gui_bridge.py — AudioGuiBridge (TrackStarted → thumbnail display).
• mumimo/db/ — SQLite database:
  • connection.py — Database (WAL mode, integrity check, backup).
  • schema.py — migrations (v1: users, user_roles, aliases).
  • repositories/ — users.py, privileges.py, aliases.py.
• mumimo/messaging/ — GUI and HTML:
  • gui.py — GuiService with semantic helpers (gui_error, gui_info, gui_result, gui_list, gui_reply) + quick_gui.
  • html_builder.py — HTML table construction + normalize_html.
  • theme.py / theme_registry.py — theme rendering and registry.
• mumimo/plugins/ — plugin system:
  • plugin_base.py — PluginBase ABC, PluginContext, @command decorator.
  • loader.py — PluginLoader (plugin.toml parsing, contract validation).
  • registry.py — PluginRegistry (command → plugin map).

Plugins

Core plugins (7 plugins, 85 commands):

• audio_commands (19) — playback control (play, pause, resume, stop, skip, seek, volume, loop, shuffle, queue management, ducking config).
• auto_updater (2) — dependency update checker.
• bot_commands (23) — role management, bot lifecycle, channel management.
• core_commands (23) — !help, !version, history, aliases, plugin lifecycle.
• server_tools (6) — login sounds, wiki link.
• themes (4) — runtime theme switching.
• whisper (8) — Mumble whisper target management.

Extension plugins (5 plugins, 47 commands):

• ai_assistant (22) — OpenRouter chat, TTS, STT, emotion, karma, memory, tool calling, personas, voice profiles, !feed.
• images (4) — image display and search.
• media (5) — YouTube/radio playback via yt-dlp + ffmpeg.
• randomizer (10) — dice rolls (coinflip, d4–d100, customroll).
• sound_board (6) — soundboard clip management and playback.

Testing

• Unit tests: ~1365 tests across mumimo/tests/ and each plugin’s tests/.
• Smoke tests: 6 end-to-end tests against a real murmur Docker container. Skipped by default — set SMOKE_TEST=1 to run.
• Lint: ruff check .

Dependencies

• pymumble — fork from git+https://github.com/DuckBoss/pymumble@main.
• yt-dlp, Pillow, requests, beautifulsoup4, markdown, fuzzywuzzy, python-Levenshtein, structlog, setuptools<82.
• audioop-lts — auto-installed on Python 3.13+.
• System deps: ffmpeg, libopus.

Migration from JJMumbleBot v5 to Mumimo v1

1. Install Mumimo

   git clone https://codeberg.org/DuckBoss/Mumimo.git
   cd Mumimo
   uv sync  # or: pip install -e .

   See the Quick Start guide for full installation instructions including system dependencies and Python version requirements. A Docker deployment is also available if you prefer containerized deployment.

2. Convert your config

   • Delete cfg/config.ini.
   • On first run, Mumimo auto-generates data/config.toml from the bundled template.
   • Manually transfer any custom settings (server IP, port, password, etc.) into the new config.toml. See the configuration reference for the full schema.

3. Convert your aliases

   • Delete cfg/custom_aliases.csv and any aliases.csv files.
   • Aliases are now declared in each plugin’s plugin.toml and managed at runtime via !setalias / !removealias / !importaliases.
   • If you had custom aliases, re-create them with !setalias <name> <command>.

4. Convert your privileges

   • Delete cfg/custom_user_privileges.csv and cfg/custom_permissions.csv.
   • Privileges are now RBAC roles stored in the SQLite database.
   • Use !role add <user> <role> to assign roles (admin only).
   • Built-in roles: blacklisted, admin, moderator, user.
   • Custom roles can be defined in config.toml under [roles.<name>].
   • See the RBAC guide for details.

5. Update your plugins

   • If you wrote custom plugins, convert metadata.ini → plugin.toml.
   • Replace integer privilege levels with roles = ["admin", ...] in plugin.toml.
   • Subclass PluginBase from mumimo.plugins.plugin_base.
   • See the plugin development guide for the new plugin structure.

6. Update your environment variables

   • JJMB_* env vars are now MUMIMO_* (e.g. MUMIMO_DATA_DIR).
   • MUMBLE_IP, MUMBLE_PORT, MUMBLE_PASSWORD are unchanged.

7. Run Mumimo

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

Quick StartGet Mumimo running in under 5 minutes.

ConfigurationFull config.toml reference.

Plugin DevelopmentBuild your own plugins.

VLC no longer required

v6 uses ffmpeg only for audio playback. You can uninstall VLC if it was only used by the bot. ffmpeg and libopus are the only system audio dependencies.

Web interface and TTS plugins removed

The standalone web interface plugin and text-to-speech plugin have been removed. TTS is now built into the AI assistant plugin via OpenRouter voice synthesis. There is no replacement for the web interface.