Feat: Enhance Lavalink integration and track requester details

- Centralize Lavalink configuration in `settings.py` and refactor `LavalinkService` for robust node management and event handling.
- Enhance the `/status lavalink` command to provide comprehensive node details, including uptime, memory, CPU, frame statistics, and version.
- Implement detailed requester information storage on `lavalink.AudioTrack` objects, capturing all Discord user flags and badges.
- Integrate the display of these requester badges across various commands and events, including `/queue`, "Now Playing" embeds, playlist embeds, and profile embeds.
- Improve voice channel permission checks in `connection_commands.py` for more precise error messages.
- Update documentation workflow to use a Puppeteer configuration for `mmdc` to ensure consistent architecture diagram rendering.

Author: timhauke

.github/workflows/docs.yml

@@ -31,7 +31,7 @@ jobs:
         run: npm install -g @mermaid-js/mermaid-cli
 
       - name: Regenerate architecture diagram
-        run: mmdc -i docs/system_architecture.mmd -o assets/images/architecture.png -t dark
+        run: mmdc -i docs/system_architecture.mmd -o assets/images/architecture.png -t dark -p docs/puppeteer-config.json
 
       - name: Ensure diagram is committed
         run: git diff --exit-code assets/images/architecture.png

docs/puppeteer-config.json

@@ -0,0 +1,3 @@
+{
+  "args": ["--no-sandbox", "--disable-setuid-sandbox"]
+}

src/commands/connection_commands.py

@@ -6,6 +6,7 @@
 from typing import Optional
 
 import discord
+import lavalink
 from discord import app_commands
 from discord.ext import commands
 
@@ -31,16 +32,21 @@ def _channel_info(channel: discord.VoiceChannel) -> str:
             f"User limit `{channel.user_limit or '∞'}`"
         )
 
-    def _permissions_summary(self, member: discord.Member, channel: discord.VoiceChannel) -> str:
+    def _permissions_summary(
+        self, member: discord.Member, channel: discord.VoiceChannel
+    ) -> tuple[str, list[str]]:
         """List permission status for required voice capabilities."""
         perms = channel.permissions_for(member)
         lines = []
+        missing = []
         for attr in REQUIRED_VOICE_PERMS:
             label = attr.replace("_", " ").title()
             granted = getattr(perms, attr, False)
             icon = "✅" if granted else "❌"
             lines.append(f"{icon} {label}")
-        return "\n".join(lines)
+            if not granted:
+                missing.append(attr)
+        return "\n".join(lines), missing
 
     @staticmethod
     def _find_player(bot: commands.Bot, guild_id: int) -> Optional[lavalink.DefaultPlayer]:
@@ -85,12 +91,12 @@ async def connect(self, inter: discord.Interaction):
             if not me:
                 return await inter.response.send_message("Unable to resolve bot member.", ephemeral=True)
 
-            summary = self._permissions_summary(me, channel)
-            missing = [attr for attr in REQUIRED_VOICE_PERMS if "❌" in summary.splitlines()[REQUIRED_VOICE_PERMS.index(attr)]]
+            summary, missing = self._permissions_summary(me, channel)
             if missing:
+                missing_lines = "\n".join(f"- {attr.replace('_', ' ').title()}" for attr in missing)
                 embed = factory.error(
                     "I am missing voice permissions in this channel:",
-                    "\n".join(f"- {attr.replace('_', ' ').title()}" for attr in missing),
+                    missing_lines,
                 )
                 return await inter.response.send_message(embed=embed, ephemeral=True)
 
@@ -106,7 +112,8 @@ async def connect(self, inter: discord.Interaction):
                     if player.volume != profile.default_volume:
                         await player.set_volume(profile.default_volume)
 
-            embed = factory.success("Connected", f"Joined voice channel:\n{self._channel_info(channel)}")
+            connection_details = f"Joined voice channel:\n{self._channel_info(channel)}"
+            embed = factory.success("Connected", connection_details)
             embed.add_field(name="Permissions", value=summary, inline=False)
             await inter.response.send_message(embed=embed)
 
@@ -159,7 +166,7 @@ async def voiceinfo(self, inter: discord.Interaction):
         embed.add_field(name="Players Active", value=f"`{player.is_playing}`", inline=True)
         embed.add_field(name="Queue Size", value=f"`{len(player.queue)}`", inline=True)
 
-        summary = self._permissions_summary(inter.guild.me, channel)  # type: ignore
+        summary, _ = self._permissions_summary(inter.guild.me, channel)  # type: ignore[arg-type]
         embed.add_field(name="Permissions", value=summary, inline=False)
 
         await inter.response.send_message(embed=embed, ephemeral=True)

src/commands/info_commands.py

@@ -7,7 +7,6 @@
 import os
 import platform
 import statistics
-from collections import Counter
 from typing import Optional, Tuple
 
 import discord
@@ -202,10 +201,15 @@ async def status(self, inter: discord.Interaction):
 
             embed.add_field(
                 name="Guild Footprint",
-                value=(
-                    f"`{self._format_number(guild_count)}` guilds\n"
-                    f"`{self._format_number(member_count)}` members\n"
-                    f"`{self._format_number(text_channels)}` text / `{self._format_number(voice_channels)}` voice channels"
+                value="\n".join(
+                    [
+                        f"`{self._format_number(guild_count)}` guilds",
+                        f"`{self._format_number(member_count)}` members",
+                        (
+                            f"`{self._format_number(text_channels)}` text / "
+                            f"`{self._format_number(voice_channels)}` voice channels"
+                        ),
+                    ]
                 ),
                 inline=False,
             )
@@ -219,10 +223,12 @@ async def status(self, inter: discord.Interaction):
                 inline=True,
             )
 
-            runtime_info = (
-                f"Python `{platform.python_version()}`\n"
-                f"discord.py `{discord.__version__}`\n"
-                f"Host `{platform.system()} {platform.release()}`"
+            runtime_info = "\n".join(
+                [
+                    f"Python `{platform.python_version()}`",
+                    f"discord.py `{discord.__version__}`",
+                    f"Host `{platform.system()} {platform.release()}`",
+                ]
             )
             embed.add_field(name="Runtime", value=runtime_info, inline=True)
 
@@ -259,7 +265,13 @@ async def botinfo(self, inter: discord.Interaction):
         owner_names = ", ".join(owner.name for owner in ([app_info.owner] if app_info.owner else []))
         guild_count = len(self.bot.guilds)
         total_members = sum(g.member_count or 0 for g in self.bot.guilds)
-        unique_users = len({member.id for g in self.bot.guilds for member in g.members}) if inter.guild else total_members
+        if inter.guild:
+            unique_users = len({member.id for member in inter.guild.members})
+        else:
+            seen_users: set[int] = set()
+            for guild in self.bot.guilds:
+                seen_users.update(member.id for member in guild.members)
+            unique_users = len(seen_users)
         cpu_percent, memory_mb = self._process_metrics()
 
         embed = factory.primary("🤖 Bot Information")
@@ -275,15 +287,14 @@ async def botinfo(self, inter: discord.Interaction):
             ),
             inline=False,
         )
-        embed.add_field(
-            name="Runtime",
-            value=(
-                f"Python `{platform.python_version()}`\n"
-                f"discord.py `{discord.__version__}`\n"
-                f"Host `{platform.system()} {platform.release()}`"
-            ),
-            inline=True,
+        runtime_meta = "\n".join(
+            [
+                f"Python `{platform.python_version()}`",
+                f"discord.py `{discord.__version__}`",
+                f"Host `{platform.system()} {platform.release()}`",
+            ]
         )
+        embed.add_field(name="Runtime", value=runtime_meta, inline=True)
         if cpu_percent is not None or memory_mb is not None:
             process_lines = []
             if cpu_percent is not None:
@@ -348,16 +359,26 @@ async def lavalink(self, inter: discord.Interaction):
 
         embed = factory.primary("🎛️ Lavalink Nodes")
         for node in nodes:
+            cpu_line = (
+                f"CPU `{(node['cpu_lavalink'] or 0) * 100:.1f}%` LL / "
+                f"`{(node['cpu_system'] or 0) * 100:.1f}%` SYS"
+            )
+            memory_line = (
+                f"Memory `{self._format_bytes(node['memory_used'])}` / "
+                f"`{self._format_bytes(node['memory_allocated'])}`"
+            )
             lines = [
                 f"Region `{node['region']}`",
                 f"Players `{node['playing']}/{node['players']}`",
-                f"CPU `{(node['cpu_lavalink'] or 0)*100:.1f}%` LL / `{(node['cpu_system'] or 0)*100:.1f}%` SYS",
-                f"Memory `{self._format_bytes(node['memory_used'])}` / `{self._format_bytes(node['memory_allocated'])}`",
+                cpu_line,
+                memory_line,
             ]
             if node["frames"] is not None:
-                lines.append(
-                    f"Frames sent `{node['frames']}`, deficit `{node['deficit']}`, nulled `{node['nulled']}`"
+                frame_line = (
+                    f"Frames sent `{node['frames']}`, deficit `{node['deficit']}`, "
+                    f"nulled `{node['nulled']}`"
                 )
+                lines.append(frame_line)
             embed.add_field(name=node["name"], value="\n".join(lines), inline=False)
 
         await inter.response.send_message(embed=embed)

src/commands/music_controls.py

@@ -130,7 +130,9 @@ def _build_nowplaying_embed(
         embed.add_field(name="Up Next", value=self._up_next_block(player), inline=False)
         return embed
 
-    def _tag_tracks(self, tracks: List[lavalink.AudioTrack], requester: Optional[discord.abc.User]) -> List[lavalink.AudioTrack]:
+    def _tag_tracks(
+        self, tracks: List[lavalink.AudioTrack], requester: Optional[discord.abc.User]
+    ) -> List[lavalink.AudioTrack]:
         """Attach requester metadata to Lavalink track objects."""
         if requester:
             requester_id = requester.id
@@ -186,7 +188,8 @@ async def _player(self, inter: discord.Interaction) -> Optional[lavalink.Default
             player = self.bot.lavalink.player_manager.get(inter.guild.id)
 
         if not player:
-            await inter.response.send_message(embed=factory.error("Failed to establish Lavalink player."), ephemeral=True)
+            error_embed = factory.error("Failed to establish Lavalink player.")
+            await inter.response.send_message(embed=error_embed, ephemeral=True)
             return None
 
         if not player.is_connected:
@@ -471,7 +474,9 @@ def disable_all_items(self):
             child.disabled = True
 
     @discord.ui.button(label="Refresh", style=discord.ButtonStyle.secondary)
-    async def refresh_button(self, interaction: discord.Interaction, button: discord.ui.Button):  # type: ignore[override]
+    async def refresh_button(  # type: ignore[override]
+        self, interaction: discord.Interaction, button: discord.ui.Button
+    ):
         """Allow users to refresh the embed on demand."""
         await self.refresh()
         if not interaction.response.is_done():

src/commands/queue_commands.py

@@ -79,13 +79,21 @@ async def queue(self, inter: discord.Interaction):
             items.append(f"`Now` {track_str(player.current)}")
         items.extend(track_str(track) for track in player.queue)
 
-        paginator = EmbedPaginator(entries=items, per_page=10, guild_id=inter.guild.id if inter.guild else None)
+        paginator = EmbedPaginator(
+            entries=items,
+            per_page=10,
+            guild_id=inter.guild.id if inter.guild else None,
+        )
         embed = paginator.make_embed()
         embed.title = "🎶 Queue Overview"
         embed.description = "\n".join(items[:10])
-        embed.set_footer(
-            text=f"{embed.footer.text} • {self._queue_summary(player)}" if embed.footer and embed.footer.text else self._queue_summary(player)
-        )
+        summary_text = self._queue_summary(player)
+        footer_text = embed.footer.text if embed.footer else None
+        footer_icon = getattr(embed.footer, "icon_url", None) if embed.footer else None
+        if footer_text:
+            embed.set_footer(text=f"{footer_text} • {summary_text}", icon_url=footer_icon)
+        else:
+            embed.set_footer(text=summary_text, icon_url=None)
         await inter.response.send_message(embed=embed, view=paginator, ephemeral=True)
 
     @app_commands.command(name="remove", description="Remove a track by its 1-based position.")
@@ -143,7 +151,12 @@ async def shuffle(self, inter: discord.Interaction):
 
     @app_commands.command(name="move", description="Move a track within the queue.")
     @app_commands.describe(src="From (1-based)", dest="To (1-based)")
-    async def move(self, inter: discord.Interaction, src: app_commands.Range[int, 1, 9999], dest: app_commands.Range[int, 1, 9999]):
+    async def move(
+        self,
+        inter: discord.Interaction,
+        src: app_commands.Range[int, 1, 9999],
+        dest: app_commands.Range[int, 1, 9999],
+    ):
         """Reorder a track within the queue."""
         factory = EmbedFactory(inter.guild.id if inter.guild else None)
         if not inter.guild:
@@ -224,11 +237,13 @@ async def playlist_save(self, inter: discord.Interaction, name: str, include_cur
 
         cleaned = name.strip()
         if not cleaned or len(cleaned) > 64:
-            return await inter.response.send_message(embed=factory.error("Playlist name must be 1-64 characters."), ephemeral=True)
+            error_embed = factory.error("Playlist name must be 1-64 characters.")
+            return await inter.response.send_message(embed=error_embed, ephemeral=True)
 
         player = self._player(inter.guild)
         if not player or (not player.queue and not player.current):
-            return await inter.response.send_message(embed=factory.warning("No tracks to persist."), ephemeral=True)
+            warning_embed = factory.warning("No tracks to persist.")
+            return await inter.response.send_message(embed=warning_embed, ephemeral=True)
 
         tracks: List[lavalink.AudioTrack] = []
         if include_current and player.current:
@@ -255,10 +270,10 @@ async def playlist_save(self, inter: discord.Interaction, name: str, include_cur
                     inter.user.id,
                     exc,
                 )
-            return await inter.response.send_message(
-                embed=factory.error("Failed to save playlist. Please try again later."), ephemeral=True
-            )
-        embed = factory.success("Playlist Saved", f"Stored **{count}** track(s) as `{cleaned}`.")
+            error_embed = factory.error("Failed to save playlist. Please try again later.")
+            return await inter.response.send_message(embed=error_embed, ephemeral=True)
+        save_message = f"Stored **{count}** track(s) as `{cleaned}`."
+        embed = factory.success("Playlist Saved", save_message)
         embed.add_field(name="Tip", value="Use `/playlist load` to queue the playlist later.", inline=False)
         await inter.response.send_message(embed=embed, ephemeral=True)
 
@@ -274,17 +289,22 @@ async def playlist_load(self, inter: discord.Interaction, name: str, replace_que
 
         player = self._player(inter.guild)
         if not player or not player.is_connected:
-            return await inter.response.send_message(
-                embed=factory.error("VectoBeat must be connected to voice before loading a playlist. Use `/connect` first."),
-                ephemeral=True,
+            message = (
+                "VectoBeat must be connected to voice before loading a playlist. "
+                "Use `/connect` first."
             )
+            error_embed = factory.error(message)
+            return await inter.response.send_message(embed=error_embed, ephemeral=True)
 
         await inter.response.defer(ephemeral=True)
 
         service = self._playlist_service()
+        default_requester = inter.user.id if isinstance(inter.user, discord.User) else None
         try:
             tracks = await service.load_playlist(
-                inter.guild.id, name.strip(), default_requester=inter.user.id if isinstance(inter.user, discord.User) else None
+                inter.guild.id,
+                name.strip(),
+                default_requester=default_requester,
             )
             if self.bot.logger:
                 self.bot.logger.info(
@@ -303,12 +323,11 @@ async def playlist_load(self, inter: discord.Interaction, name: str, replace_que
                     inter.user.id,
                     exc,
                 )
-            return await inter.followup.send(
-                embed=factory.error("Failed to load playlist from storage. Please try again later."),
-                ephemeral=True,
-            )
+            error_embed = factory.error("Failed to load playlist from storage. Please try again later.")
+            return await inter.followup.send(embed=error_embed, ephemeral=True)
         if not tracks:
-            return await inter.followup.send(embed=factory.warning(f"No playlist found with the name `{name}`."), ephemeral=True)
+            warning = factory.warning(f"No playlist found with the name `{name}`.")
+            return await inter.followup.send(embed=warning, ephemeral=True)
 
         autop_flag = player.fetch("autoplay_enabled")
         if replace_queue:
@@ -337,7 +356,8 @@ async def playlist_load(self, inter: discord.Interaction, name: str, replace_que
         if len(tracks) > 5:
             summary += f"\n...`{len(tracks) - 5}` more"
 
-        embed = factory.success("Playlist Loaded", f"Queued **{len(tracks)}** track(s) from `{name}`.")
+        load_message = f"Queued **{len(tracks)}** track(s) from `{name}`."
+        embed = factory.success("Playlist Loaded", load_message)
         embed.add_field(name="Preview", value=summary, inline=False)
         embed.add_field(name="Queue Summary", value=self._queue_summary(player), inline=False)
         await inter.followup.send(embed=embed, ephemeral=True)
@@ -356,11 +376,11 @@ async def playlist_list(self, inter: discord.Interaction):
         except PlaylistStorageError as exc:
             if self.bot.logger:
                 self.bot.logger.error("Failed to list playlists for guild %s: %s", inter.guild.id, exc)
-            return await inter.response.send_message(
-                embed=factory.error("Unable to query playlists from storage. Please try again later."), ephemeral=True
-            )
+            error_embed = factory.error("Unable to query playlists from storage. Please try again later.")
+            return await inter.response.send_message(embed=error_embed, ephemeral=True)
         if not names:
-            return await inter.response.send_message(embed=factory.warning("No playlists saved yet."), ephemeral=True)
+            warning_embed = factory.warning("No playlists saved yet.")
+            return await inter.response.send_message(embed=warning_embed, ephemeral=True)
 
         embed = factory.primary("Saved Playlists")
         embed.description = "\n".join(f"- `{name}`" for name in names)
@@ -378,7 +398,10 @@ async def playlist_delete(self, inter: discord.Interaction, name: str):
             removed = await service.delete_playlist(inter.guild.id, cleaned)
             if removed and self.bot.logger:
                 self.bot.logger.info(
-                    "Deleted playlist '%s' for guild %s by user %s", cleaned, inter.guild.id, inter.user.id
+                    "Deleted playlist '%s' for guild %s by user %s",
+                    cleaned,
+                    inter.guild.id,
+                    inter.user.id,
                 )
         except PlaylistStorageError as exc:
             if self.bot.logger:
@@ -389,13 +412,11 @@ async def playlist_delete(self, inter: discord.Interaction, name: str):
                     inter.user.id,
                     exc,
                 )
-            return await inter.response.send_message(
-                embed=factory.error("Failed to delete playlist from storage. Please try again later."), ephemeral=True
-            )
+            error_embed = factory.error("Failed to delete playlist from storage. Please try again later.")
+            return await inter.response.send_message(embed=error_embed, ephemeral=True)
         if not removed:
-            return await inter.response.send_message(
-                embed=factory.warning(f"No playlist found with the name `{cleaned}`."), ephemeral=True
-            )
+            warning_embed = factory.warning(f"No playlist found with the name `{cleaned}`.")
+            return await inter.response.send_message(embed=warning_embed, ephemeral=True)
 
         embed = factory.success("Playlist Deleted", f"Removed `{cleaned}` from storage.")
         await inter.response.send_message(embed=embed, ephemeral=True)