v5.2.0 - Major Management Improvements!

Please visit the What's New wiki page for an easy-to-read update list and upgrade guide for v5.1.0 and v5.1.1 users.

This release contains a large number of updates, so the limitations of this release description makes it hard to read!

Use the wiki link provided above instead!

Update Guide For v5.1.0 and v5.1.1 Users

• Required Update Config.ini File

  Update your config.ini file to include EnableDatabaseIntegrityCheck=True under the [Main Settings] section:

                          [Main Settings]
                          EnableDatabaseIntegrityCheck = True
                      

  Refer to the /templates/ directory to see a template of the file.

• Optional Setup Custom Aliases File

  Rename your global_aliases.csv file to custom_aliases.csv
  Alternatively, if you don't have custom aliases under global_aliases.csv you can simply delete it.

• Optional Setup Custom User Privileges File

  Create a custom_user_privileges.csv file (template provided in /templates/ folder) and fill it with custom user privileges as required.
  This is important since the new update will require the database to be regenerated, so doing this will prevent any loss of custom user privileges.

• Optional Setup Custom Command Permissions File

  Create a custom_permissions.csv file (template provided in /templates/ folder) and fill it with custom command permissions as required.
  This is important since the new update will require the database to be regenerated, so doing this will prevent any loss of custom command permissions.

Wiki Command For Server Tools Plugin NEW

This is a simple command that displays a link to the JJMumbleBot wiki for quick reference at runtime.
• !wiki: Displays a link to the JJMumbleBot wiki.

Custom Aliases And Runtime Modifications UPDATED

Previously, aliases could be updated by modifying the global_aliases.csv file. Every update to the file required restarting the bot which was very tedious!
In this update, the internal database handling of this process has been improved and the file has been renamed to custom_aliases.csv for consistency.
With this update, Updating multiple aliases can be updated at runtime using either a local csv file or a remote csv file downloaded through a URL.

Update Aliases With Local Files:

• Users can now set custom aliases for commands by utilizing a custom_aliases.csv file within the cfg folder.^*
  This is useful for everyone, but particularly helpful for docker containers and cloud-hosted solutions that have their /cfg/ folders mounted.
  ^*This file is automatically generated if it's missing and was formerly called the global_aliases.csv file.
  
• For example: "I want to have an alias to display information about the bot!"



alias,command
botinfo,(about)|(version)

In this simple example, the custom_aliases.csv is modified so that a !botinfo alias is made to call the !about and !version commands.

• You can update the database at runtime using the new command: !refreshaliases.

Update Aliases With Remote Files:

• Bot owners now have an option of updating aliases by utilizing a csv file on a remote endpoint/URL.
  This functions similarly to the local file method shown above, but has the advantage of not requiring extensive access to the filesystem.
  This is extremely useful for bot owners that use cloud-hosting solutions with limited filesystem access.
  The csv file is downloaded to the following temporary path: /cfg/downloads/_aliases.csv
• This can be achieved by utilizing this new command: !importaliases 'URL'

Custom Command Permissions And Runtime Modifications NEW

Previously, to update the command permissions, each command had to be meticulously updated by modifying multiple csv files across multiple plugin folders.
With this update, that is no longer the case and updating multiple commands can be updated at runtime using either a local csv file or a remote csv file downloaded through a URL.
In addition to those updates, new commands have been added to display/update individual command permissions.

Display/Update Individual Permissions With Commands:

• !getpermission 'command_name': Displays the permission level for the specified command.
  !setpermission 'command_name' 'permission_level': Modifies the permission level for the specified command.
  

Update Command Permissions With Local Files:

• Users can now set custom permission levels for commands by utilizing a custom_permissions.csv file within the cfg folder.^*
  This is useful for everyone, but particularly helpful for docker containers and cloud-hosted solutions that have their /cfg/ folders mounted.
  ^*This file is automatically generated if it's missing.
  
• For example: "I want to allow only administrators to change the bot volume!"



command,permission
volume,4

In this example, the custom_permissions.csv is modified so that the volume command is set to a permission level of 4 (administrators and above only).

• You can update the database at runtime using the new command: !refreshpermissions.

Update Command Permissions With Remote Files:

• Bot owners now have an option of updating the command permissions by utilizing a csv file on a remote endpoint/URL.
  This functions similarly to the local file method shown above, but has the advantage of not requiring extensive access to the filesystem.
  This is extremely useful for bot owners that use cloud-hosting solutions with limited filesystem access.
  The csv file is downloaded to the following temporary path: /cfg/downloads/_permissions.csv
• This can be achieved by utilizing this command: !importpermissions 'URL'

Custom User Privileges And Runtime Modifications NEW

Previously, to update the user privileges, administrators had to individually update user privileges using the !setprivileges command for every user.
With this update, It is much simpler to update multiple user privileges at a time at runtime using either a local csv file or a remove csv file downloaded with a URL.

Update User Privileges With Local Files:

• Users can now set custom...

v5.1.1 - New Command Line Arguments And Bug Fixes

Updating Notes

This update DOES NOT require you to reconfigure configs, aliases, or database files.
This should be a straight-forward update for v5.1.0 users.

New Command Line Arguments

• -usehttps: Enable the usage of HTTPS for the web interface.
• -nohttps: Disable the usage of HTTPS for the web interface if enabled in the config file.
• -websslcert: Enter the path to the SSL certificate file for the web interface (if HTTPS enabled).
• -websslkey: Enter the path to the SSL key file for the web interface (if HTTPS enabled).
• -webgeneratecert: Enables automatic certificate/key creation for the web interface (if HTTPS is enabled).
• -noautoreconnect: Disables auto-reconnecting if the bot disconnects from the mumble server if enabled in the config file.
• -noselfregister: Disables self-registration to the connected mumble server if enabled in the config file.
• -nodatabasebackups: Disables automatic database backups for the bot service if enabled in the config file.
• -noaudioduck: Disables audio ducking for the bot audio system if enabled in the config file.
• -nologging: Disables event logging for the bot service if enabled in the config file.
• -nologtrace: Disables stack trace logging for all logged events if enabled in the config file.

Bug Fixes

• Fixed multiple command line arguments that enabled bot features such as (-uselogging, -usedatabasebackups, -useweb, -autoreconnect, etc)
• Fixed -mediacookie command line argument documentation in wiki.

Misc

• Added -nostdin parameter to ffmpeg launch options in the internal handling of the audio interface.
• Updated bot version to v5.1.1

v5.1.0 - New Administration Commands and Web Updates

NOTE: Dependency Installation/Upgrading Instructions

Please make sure you are using the new and updated dependencies from the requirements/xxxxx.txt files.

In addition to that, please use the updated pymumble library from Github, as the PyPi repository is not updated.
To INSTALL the latest pymumble library and all other dependencies:
pip install -r requirements/requirements.txt -r requirements/web_server.txt
pip install git+git://github.com/azlux/pymumble@pymumble_py3
To UPDATE to the latest pymumble library and update all other dependencies:
pip install --upgrade -r requirements/requirements.txt -r requirements/web_server.txt
pip install --upgrade git+git://github.com/azlux/pymumble@pymumble_py3

New Web Server Plugin Dependency

• Added new web server dependency: fastapi-utils to the requirements/web_server.txt file. [Added in 6286906]

Administrative Updates - New Commands...

• Added ability to kick/ban users from the mumble server [Added in 10a5107]
  • !kickuser 'username' 'reason'
  • !banuser 'username' 'reason'
• Added ability to mute/unmute/deafen/undeafen users with commands [Updated in 520a806]
  • !muteuser 'username'
  • !unmuteuser 'username'
  • !deafenuser 'username'
  • !undeafenuser 'username'
• Added/Updated ability to make temporary/permanent channels [Updated in 7883ab7]
  • !makechannel 'channel_name' - This command now only make temporary channels.
  • !makepermanentchannel 'channel_name' - Creates a permanent channel.
• Updated the !removechannel command to require a channel name [Updated in 7883ab7]
  • !removechannel 'channel_name'
• Added ability to rename existing channels [Updated in 7883ab7]
  • !renamechannel 'channel_name' 'new_channel_name'
• Added ability to move users from one channel to another [Updated in 7883ab7]
  • !moveuser 'username' 'channel'

Web Interface Updates - HTTPS Support, Administrative Controls...

• Added optional HTTPS support. [Updated in 4d8fde4]
• The main components on the Commands page now have a limited height, and use scrollbars if the content overflows. [Updated in cb3ce18]
• Added user administration controls (mute/deafen/kick/ban) to users in the channel hierarchy list. [Updated in fcd0d8e]
• Added user audio status icons to users in the channel hierarchy list to show when a user is muted/deafened. [Updated in fcd0d8e]
• Added dialog prompts for kicking/banning users and removing channels. [Updated in 9cd5c80]

Web Server REST API Updates

• Added general administrative APIs [Updated in 51fbb55]
  • [GET] /api/general/uptime - Retrieves the bot up-time information.
  • [GET] /api/general/version - Retrieves the bot version information.
  • [GET] /api/general/about - Retrieves the bot about information.
• Added user administrative APIs: [Updated in 1ab311e]
  • [POST] /api/admin/users/join - Join the channel of a given user.
  • [POST] /api/admin/users/move - Move the given user to a channel.
  • [POST] /api/admin/users/kick - Kick the given user and provide an optional reason.
  • [POST] /api/admin/users/ban - Ban the given user and provide an optional reason.
  • [POST] /api/admin/users/mute - Mute/Unmute the given user.
  • [POST] /api/admin/users/deafen - Deafen/Undeafen the given user.
• Added channel administrative APIs: [Updated in 1ab311e]
  • [POST] /api/admin/channels/rename - Rename the given channel to a new name.
  • [POST] /api/admin/channels/remove - Remove the given channel.
  • [POST] /api/admin/channels/move - Move to the given channel.
  • [POST] /api/admin/channels/leave - Leave the current channel and return to the default channel.
  • [POST] /api/admin/channels/make_temporary - Make a temporary channel with the given name.
  • [POST] /api/admin/channels/make_permanent - Make a permanent channel with the given name.
• Added plugin administrative APIs: [Updated in 51fbb55]
  • [POST] /api/admin/plugins/stop - Stops an existing, running plugin with the given name.
  • [POST] /api/admin/plugins/start - Starts an existing, stopped plugin with the given name.
  • [POST] /api/admin/plugins/restart - Restarts an existing plugin with the given name.
  • [POST] /api/admin/plugins/restart_all - Restarts all existing plugins.
• Added plugin metadata APIs: [Updated in 6cda89f]
  • [POST] /api/admin/plugins/metadata/get - Retrieves the metadata file contents of the plugin with the given name.
  • [POST] /api/admin/plugins/metadata/set - Overwrites the metadata file contents of the plugin with the given name, with the provided data.
• Updated audio APIs: [Updated in 1ab311e]
  • Moved all /api/xxxx audio APIs to /api/audio/xxxx
• Updated sound_board APIs: [Updated in 1ab311e]
  • Changed /api/soundboardclips to /api/sound_board/clips
  • Changed /api/soundboard-play to /api/sound_board/play
  • Changed /api/soundboard-random to /api/sound_board/random
• Updated general APIs: [Updated in 1ab311e]
  • Changed /api/system to /api/general/system

Misc

• Optimized commands in bot_commands plugin.
• Optimized runtime utilities.
• Updated web server's monitor service to support user state data such as muted/deafened/etc. [Updated in 372a831]
• Updated default config parameter: MaxLogSize to 1500000 bytes (1.5Mb). [Updated in 83be3f2]
• Removed on_permission_denied callback in core bot service. [Updated in a30ae8a]
• Updated the -generatecert argument to use dynamic paths. [Updated in 1aa77c3]
• Updated bot and relevant plugins to v5.1.0

v5.0.0 - Updated Logging, Web Server, Many New Features!

This is a major update that requires users to reconfigure their config files.

Core Updates

Web Interface Changes

The web interface is now a part of the new web_server core plugin.
As a result, references to the web interface in the config.ini file has been moved to the web_server plugin's metadata.ini file. The new plugin will provide a REST API and serve the web interface.
This update has a change in dependencies as a result.

Dependency Updates - Changed Dependencies, Remember to Update!

There are now multiple requirements files located in the requirements/ directory.
This directory will contain a requirements.txt file which has the core requirements for the bot,
and additional requirement files for plugins such as the web_server.

To install all dependencies for v5.0.0, you can use the following commands:
pip install -r requirements/requirements.txt
pip install -r requirements/web_server.txt

This change will allow users who want a minimal setup without a web interface
to install the minimum number of dependencies to run the bot.

Updated Launch Parameters

• Renamed -webinterface to -useweb
• Renamed -ydlproxy to -mediaproxy
• Renamed -ydlcookie to -mediacookie
• Added -noweb parameter to disable the web interface on startup if it is enabled by default in the plugin metadata.
• Added -logtrace parameter to enable logging stack traces of events.

Plugin Template Generator Updates

The plugin template generator has been updated to v5.0.0.
If you are a developer looking to make a JJMumbleBot plugin, but don't know where to start, then generate a template plugin like so: python3 JJMumbleBot/utility/plugin_template_generator.py my_example_plugin.
This plugin will be generated in the JJMumbleBot/user_generated/directory, and must be placed in the JJMumbleBot/plugins/extensions/directory to work.

Persistent Plugin Data in Docker Containers

So far, docker images of JJMumbleBot haven't been able to store persistent data for plugins easily.
In this update each plugin will receive it's own directory in the /cfg/plugins/ directory to use for persistent data.
Since the content of this directory is dependent on the plugin, some plugins may opt not to use it.

• A persistent data utility is now available in the bot library for third-party plugins to utilize for containerized bots.

Updated Logging and Console Printing System

• More bot/plugin events are now logged.
• Added 'LogStackTrace' option to the config.ini file to allow the logging API to log the event stack trace.
  Launch parameter: -logtrace
• Logging API Updates

  • The logging API now supports multi-line messages as a list of strings.
    log ( INFO, [string1, string2, string3], ... )
  • Added new logging origin for plugins: L_PLUGIN
  • The logging API supports displaying custom error types.
  • The logging API now supports 'error' log level.
  • The logging API has been updated to make it easier than ever for third-party developed plugins to adopt logging features.
    For more information on the logging API, refer to the wiki page: [Logging API](https://duckboss.github.io/JJMumbleBot/wiki/general/logging.html)

Updated PGUI System

• PGUI System API Updates

  • The PGUI system now supports multi-line messages.

Plugin Updates

Bot Commands Plugin - New Commands

The bot commands plugin has new commands.

• !aliassearch 'search_term': Searches and returns a list of aliases that most closely matched the search term.

Core Commands Plugin - New Commands

The core commands plugin now has commands that can be used to individually stop/start/restart plugins.
A plugin's ability to be stopped/started/restarted in this way is controlled in the plugin's respective metadata.ini file.

• !stopplugin 'plugin_name': Stops the plugin by the name provided if it is running.
• !startplugin 'plugin_name': Starts the plugin by the name provided if it is currently inactive.
• !restartplugin 'plugin_name': Restarts the plugin by the name provided if it is currently running.

Server Tools Plugin

The server tools plugin is now considered a core plugin and has been moved from the extension plugin folder to the core plugin folder.
Some plugin commands have also been shortened so that they are easier to use.

• The server tools plugin now only uses audio clips from the sound_board permanent media directory if the option is enabled in the plugin's metadata.ini file.
• The plugin now comes with a default built-in "ping" sound clip to play when a user connects to the server.
  This can be configured in the metadata.ini file.
• The plugin can now send a welcome message to a user that connects to the server.
  The content of this message can be configured in the metadata.ini file.
• Shortened the !setuserrconnectionsound command to !setloginsound
• Shortened the !getuserconnectionsound command to !getloginsound
• Shortened the !clearuserconnectionsound command to !clearloginsound
• Shortened the !toggleuserconnectionsound command to !toggleloginsounds
• Shortened the !setdefaultconnectionsound command to !setdefaultloginsound

Web Server Plugin [NEW] - New Web Interface

The web interface is now a part of the web_server plugin, which gives it the benefit of being a drag-and-drop optional feature to the bot. This plugin is included by default, but it can be removed by simple deleting it from the plugins list.

• One port access for both the interface + socket: For example localhost:7000/ provides the web interface, and localhost:7000/ws will provide the socket connection for the interface.
• Modern front-end visuals: The interface has been completely reworked using ReactJS
• Transition to a plugin-based web server: The web interface is now a part of the web_server plugin, which gives it the benefit of being a drag-and-drop optional feature to the bot.
• Better API implementation: New, fast API system utilizing the FastAPI library that is open for customization and third-party web interfaces. The API can also be used for other third-party integrations.
• Dark/Light Mode themes: A new theme selector has been added so that users who prefer a dark/ or light interface scheme can select their preference.
• CLICK HERE TO SEE PREVIEW IMAGES

  Navigation Bar

  

  Commands Tab

  

  Audio Tab

  

  Debug Tab

  
• Web Server API

  • [POST] /api/command: Sends a given command to the bot.
    Example request body: { "text": "!echo test" }
  • [GET] /api/lastcommand: Retrieves the most recent command sent to the bot.
  • [POST] /api/pause: Pauses the audio interface.
    Example request body: No request body required
  • [POST] /api/pause: Pauses the current track in the audio interface.
    Example request body: No request body required
  • [POST] /api/resume: Resumes the current track in the audio interface.
    Example request body: No request body required
  • [POST] /api/replay: Replays the current track in the audio interface.
    Example request body: No request body required
  • [POST] /api/nexttrack: Skips to the next track in the audio interface queue.
    Example request body: No request body required
  • [POST] /api/decreasevolume: Decreases the volume of the audio interface by 0.1
    Example request body: No request body required
  • [POST] /api/increasevolume: Increases the volume of the audio interface by 0.1
    Example request body: No request body required
  • ...

v4.3.4 - Fixed user connection sounds

Bug Fixes

• Fixed user connection sounds not playing after recent update

v4.3.3 - !sbrandom/!sbrandomnow command hotfix

Bug Fixes

• Fixed sbrandom command (alias: !sbr)
• Fixed sbrandomnow command (alias: !sbrn)

v4.3.2 - Sound Board Interface, Bug Fixes, etc.

Sound Board and Web Interface Updates

• The web interface now has a new Sound Board tab which displays all the sound board clips available and can play these clips directly from the web interface.
• Sound board clips can now be queued by default (this can be disabled in the soundboard plugin's metadata.ini file)
• Changed sound board clip gathering to exclude file extensions. This means that commands that display sound clips will no longer display the file extension of the audio clip.

Bug Fixes

• Fixed ytsearch command.
• Fixed occassional issue where the bot audio thread got stuck on connecting to the server.

v4.3.1 - Logging Fixes and Updates

Bug Fixes and Updates

• Fixed launch parameters for logging functionality.
• Disabled logging by default for new users, this can be enabled in the config.ini file or with the -uselogging launch parameter.

Misc

• Updated youtube-dl dependency version.
• Updated and fixed unit tests.
• Updated documentation/wiki to reflect changes made in v4.3.1

v4.3.0 - Docker Support, Launch Parameters Update, Many Bug Fixes, etc

What's New

Check out what's new here: What's New or read the patch notes and updates below!

Launch Parameters Update

With the release of v4.3.0, I've added ALL the options available in the config.ini file to the launch parameters list.
This means that any config option can be overridden on launch.

47 New launch parameters:

• -generatecert : Automatically generates a certificate for the bot and updates the config.ini file to include the new certificate path.
• All the options in the config.ini file are now available as launch parameters (47 new launch parameters!)
• For the full list of launch parameters, check the wiki page: Launch Parameters List

Docker Builds Support

I've worked closely with @kaminascripts to prepare the JJMumbleBot project for Docker container support.
There's a lot to cover about this and the bot is easily configurable to run in a docker container.
For more information and a guide on setting up the bot with Docker, please check the wiki page: Docker Support

Server Tools Plugin

Added 'toggleuserconnectionsound' command to be able to toggle the user connection sound feature without manually editing the config.

• !toggleuserconnectionsound : Enables/disables the user connection sound feature in the metadata file for the plugin.
• Fixed issue where changes to the server_tools metadata file were not being saved.

Bug Fixes

• Fixed audio library bugs with the media/sound_board plugins.
• Fixed error with web interface trying to parse audio library metadata.
• Fixed logging issue with whisper plugin where it would try to log items when logging was disabled.
• Fixed errors that occurred when commands weren't formatted properly in the bot_commands plugin.
• Fixed audio library issue that prevented user connection sound playback in the server_tools plugin.
• Fixed issue in server_tools plugin where updating user connection sounds wouldn't properly update.

Other Updates

• A minimally setup config file is now generated if the config.ini file is missing.
• A minimally setup global_aliases file is now generated if the global_aliases.csv file is missing.
• Directories such as the media/logging directories are now generated if missing.
• Directories that are not configured in the config.ini file are now generated automatically instead of causing errors.
• The bot now automatically adds itself to the user privileges if the web interface is enabled (previously it had to be manually added).
• The default values in the config_template.ini have been changed to reflect a minimal config setup and make it easier for configuration.
• Self-registration in servers is now disabled by default, and can be enabled in the config.ini file (previously it was enabled).
• Logging is now enabled by default, and can be disabled in the config.ini file (previously it was disabled).
• Database backups are disabled by default, and can be enabled in the config.ini fie (previously it was enabled).
• Server_tools plugin's user_connections.csv file generates and is saved in the /cfg/plugins/ folder to improve usability.
• The default multi-command limit set in the config file has been increased to 200.
• The default command queue limit set in the config file has been increased to 600.
• The default GUI font has been changed to 'Georgia' (previously set to 'Calibri').
• The default GUI text color has been changed to 'Snow' instead of 'White'.
• Removed redundant unit test and associated files.
• Changed auto-generated media directories to generate in /cfg/ folder instead of root bot directory to keep media downloads persistent if the user is using docker. This won't make any difference to regular users.
• Moved templates folder out of the cfg folder ->JJMumbleBot/cfg/templates/ folder to JJMumbleBot/templates/

Wiki Updates

• Updated the wiki to include documentation and guides for Docker setups.
• Updated the wiki documentation to reflect changes in v4.3.0

v4.2.2 - VLC/FFmpeg Updates and Bug Fixes

VLC/FFmpeg Updates - A Compromise between functionality and reliability

I have been working with users of JJMumbleBot to get reliable youtube audio playback in the media plugin, and finer control over the sound_board plugin with each feature requiring different things.
For example, being able to trim downloaded audio clips with the !sbdownload command in the sound_board plugin required FFmpeg to work.
However, streaming youtube audio reliably without interruptions or errors required the use of VLC. I tried getting FFmpeg to do the job of both but it just wasn't reliable and consistent enough.
As a result, to get the functionality and features of both worlds I have made VLC and FFmpeg both a requirement for JJMumbleBot to allow future development of more advanced audio processing for audio plugins.

• VLC and FFmpeg is now a core requirement for JJMumbleBot.

Pros:

• Allows future development of advanced audio processing for audio plugins.
• Expands functionality for custom plugins to handle audio data.
• Gives plugin developers more than one choice for an audio library.

Cons:

• More requirements = Bigger project size

Fixed Sound Board Plugin

• Fixed an issue where sound_board plugin audio wasn't functioning correctly due to an invalid FFmpeg parameter.

Fixed Audio Playback Issue

• Fixed an issue with media playback from youtube links where the track would end early.

Updated Configs/Documentation/QSU

• The config_template.ini file has been updated, existing users should remember to update their config.ini file.
• All the documentation on available on the JJMumbleBot Wiki has been updated.
• The Quick Setup Utility web interface for config creation has been updated for v4.2.2