v5.3.1 - Server Tools Plugin Fixes

JJMumbleBot v5.3.1 - Server Tools Plugin Fixes

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

This project is no longer under active development, and the bot is being reworked in the following rework project: Mumimo However, I still use this older version of the bot and try to fix bugs when I find them, so here it is. There is no upgrade instructions specifically for v5.3.0 users.

Fixes

• Server Tools Plugin:
  • Fixed login/user-connection sounds: The feature to play a 'connection sound' when a user connects to the server is fixed with this update. You should now be able to set login sounds and it should play when the user connects to the server as it used to work before.

Known Issues From Previous Releases

• Text to Speech Plugin: The text to speech plugin is not functional to dynamically convert text to speech and currently only works for TTS clips that have already been downloaded previously. An update is required to use a new endpoint that still works.

v5.3.0 - New Features and Fixes

JJMumbleBot v5.3.0 - New Features and Fixes

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

This project is no longer under active development, and the bot is being reworked in the following rework project: Mumimo
However I wanted to release a patch for existing users while they wait for the rework project to be ready for an initial release. This patch mostly aims to add small features and fix some existing issues that prevented the bot from working. This patch includes dependency updates and contains some breaking changes as a result.
Most pre-existing issues and new features going forward will be addressed in the rework project: Mumimo.

New Features, Changes and Fixes

• Media Plugin:

  • Added support for streaming audio from radio stations.
    Simply use the !radiolink <link> command to start streaming from compatible radio stations.
    Radio streaming isn't supported for all radio stations and it requires a direct link to the icecast stream.
    Some examples of working radio station links are provided in the plugin's metadata file.
    • You can use existing audio commands with the radio streaming feature such as: !stop/!pause/!resume/!playing
  • Fixed audio-related stuttering and playback issues with the media plugin.
  • Fixed audio skipping at the end of the track when multiple tracks are in the queue.
  • Fixed parsing errors when playing youtube links and using the youtube search feature.
  • Increased the default maximum youtube video length to 14400 seconds. This can be changed in the metadata.ini file for the media plugin of course.
  • Renamed alias for the !ytplaylist command from !ytlist to !ytplist
  • Updated plugin version to v5.3.0

• Sound Board Plugin:

  • Adjusted logic for the !sbrandom... related commands to choose a different audio clip if it picks the same audio clip as the last time it was run. This change is to mitigate cases when it chooses the same audio clip back to back, making it feel less random.
  • Updated plugin version to v5.3.0

• Audio API + Audio Commands Plugin:

  • Split the audio ducking delay option into two separate delay options for finer control
    over the audio ducking feature:
    • Use !duckstartdelay <seconds> to specify how long the bot should wait before ducking the audio volume when it detects user voice activity.
    • Use !duckenddelay <seconds> to specify how long the bot should wait before restoring the ducked volume back to the original value when it detects no user voice activity.
    • Removed !duckdelay command and replaced it with !duckstartdelay and !duckenddelay.
    • Updated command line arguments and config options to match the above changes.
  • Updated plugin version to v5.3.0

• Image Plugin:

  • Fixed an issue where image thumbnails could not be generated due to an outdated API.

• Server Tools Plugin:

  • Added missing default user connection sound file: default_user_sound.wav
  • Improved error-handling and error log details.
  • Added utility methods to find audio clips from the plugin media directory and integrate better with the sound board plugin.

• Misc Changes:

  • General formatting fixes and test cases updates.
  • Improved and fixed documentation in several plugins.
  • Updated plugin templating to improve plugin creation experience.
  • Updated pymumble and pymumble callback references to use updated API.
  • Updated wiki with new requirements, upgrade guide, and release pages.

Minimum Requirements Updates

• This project now requires a minimum of Python 3.9+ (previously 3.7+) to improve compatibility with the 'yt-dlp' dependency and newer VLC versions which is heavily used for audio-related plugins.

Dependency Updates

• The project has been updated to use 'yt-dlp' instead of 'youtube-dl' since the original project is no longer in development. This new library works identically and is actively maintained.
• I've updated the pymumble dependency to use a stable fork that I've created of another fork by oopsbagel which aims to improve and modernize pymumble since the original project is no longer in active development. I've decided to fork it into my own repository so I can verify patches and ensure stability for usage in this bot.

Known Issues

• Server Tools Plugin: The feature to play a 'connection sound' when a user connects to the server is
  currently broken. I highly suggest not using this feature. I don't plan on
  fixing it in this project and I will be addressing it in the larger rework project 'Mumimo'.
  If you still decide to use it and the audio queue freezes, simply use !stop to flush the audio queue.
• Text to Speech Plugin: The text to speech plugin is not functional to dynamically convert text to speech and currently only works for TTS clips that have already been downloaded previously. An update is required to use a new endpoint that still works.

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