docs(examples): added example about how to handle discords waveform

Author: Lulalaby

examples/voice_message_waveform.py

@@ -0,0 +1,175 @@
+from __future__ import annotations
+
+import io
+from typing import Any, Union
+import numpy as np
+import discord
+import base64
+from PIL import Image, ImageDraw
+
+
+class WaveformVisualizer:
+    """
+    A class to visualize audio waveforms.
+
+    Attributes
+    ----------
+    waveform_byte_data : numpy.ndarray
+        The decoded waveform byte data.
+
+    Methods
+    -------
+    decode_waveform(base64_waveform: str) -> np.ndarray[Any, np.dtype[np.uint8]]:
+        Decodes the base64 encoded waveform string into a numpy array.
+
+    create_waveform_image(width: int = 500, height: int = 100,
+                          background_color: Union[float, tuple[float, ...], str, None] = (0, 0, 0),
+                          bar_colors: Union[None, list[tuple[int, int, int]]] = None) -> Image.Image:
+        Creates a visual representation of the waveform as an image.
+    """
+
+    def __init__(self, base64_waveform: str) -> None:
+        """
+        Initializes the WaveformVisualizer with the provided base64 waveform string.
+
+        Parameters
+        ----------
+        base64_waveform : str
+            A base64 encoded string representing the waveform.
+        """
+        self.waveform_byte_data: np.ndarray[Any, np.dtype[np.uint8]] = self.decode_waveform(base64_waveform)
+
+    @staticmethod
+    def decode_waveform(base64_waveform: str) -> np.ndarray[Any, np.dtype[np.uint8]]:
+        """
+        Decodes the base64 encoded waveform string into a numpy array.
+
+        Parameters
+        ----------
+        base64_waveform : str
+            The base64 encoded string of the waveform.
+
+        Returns
+        -------
+        np.ndarray
+            A numpy array containing the decoded waveform byte data.
+        """
+        return np.frombuffer(base64.b64decode(base64_waveform), dtype=np.uint8)
+
+    def create_waveform_image(self, width: int = 500, height: int = 100,
+                              background_color: Union[float, tuple[float, ...], str, None] = (0, 0, 0),
+                              bar_colors: Union[None, list[tuple[int, int, int]]] = None) -> Image.Image:
+        """
+        Creates a visual representation of the waveform as an image.
+
+        Parameters
+        ----------
+        width : int, optional
+            The width of the resulting image, by default 500.
+        height : int, optional
+            The height of the resulting image, by default 100.
+        background_color : float | tuple[float, ...] | str | None, optional
+            The background color of the image, by default (0, 0, 0).
+        bar_colors : list[tuple[int, int, int]] | None, optional
+            A list of colors for the waveform bars, by default None.
+
+        Returns
+        -------
+        Image.Image
+            A PIL Image object representing the waveform.
+        """
+        if bar_colors is None:
+            bar_colors = [(173, 216, 230), (135, 206, 235), (0, 191, 255)]
+
+        image = Image.new('RGB', (width, height), background_color)
+        draw = ImageDraw.Draw(image)
+
+        bar_width = width / len(self.waveform_byte_data) / 2
+        x_scale = width / len(self.waveform_byte_data)
+        y_scale = height / 2 / 255
+
+        for i, value in enumerate(self.waveform_byte_data):
+            if isinstance(value, tuple):  # Check if value is a tuple
+                value = value[0]  # Extract the first item if it's a tuple
+
+            x1 = i * x_scale
+            bar_height = max(2.0, float(value) * y_scale)
+            y1 = height / 2 - bar_height
+            y2 = height / 2 + bar_height
+
+            color_index = i % len(bar_colors)
+            color = bar_colors[color_index]
+
+            draw.rectangle([x1, y1, x1 + bar_width, y2], fill=color)
+
+        return image
+
+
+intents = discord.Intents.default()
+intents.message_content = True
+intents.members = True
+
+bot = discord.Bot(intents=intents)
+
+
+@bot.event
+async def on_ready() -> None:
+    """
+    Event handler for when the bot is ready.
+
+    This method is called automatically by the pycord library when the bot has successfully connected to Discord
+    and is ready to start receiving events and commands.
+    """
+    print("Ready!")
+
+
+@bot.event
+async def on_message(message: discord.Message) -> None:
+    """
+    Event handler for when a message is received.
+
+    This method is called automatically whenever a new message is sent in any channel the bot can access.
+
+    Parameters
+    ----------
+    message : discord.Message
+        The message object containing information about the message sent.
+    """
+    if message.author.id == bot.user.id:
+        return
+
+    if message.attachments and len(message.attachments) == 1:
+        target_attachment = message.attachments[0]
+        if target_attachment.content_type == "audio/ogg" and target_attachment.filename == "voice-message.ogg":
+            print("We got a voice message!")
+            await handle_voice_message(message, target_attachment)
+
+
+async def handle_voice_message(message: discord.Message, attachment: discord.Attachment) -> None:
+    """
+    Handles the processing of voice message attachments.
+
+    Converts the waveform of the voice message to a visual image and sends it back in an embed.
+
+    Parameters
+    ----------
+    message : discord.Message
+        The message object containing the voice message.
+    attachment : discord.Attachment
+        The attachment object representing the voice message.
+    """
+    image = WaveformVisualizer(attachment.waveform).create_waveform_image()
+    image_buffer = io.BytesIO()
+    image.save(image_buffer, format='PNG')
+    image_buffer.seek(0)
+    file = discord.File(image_buffer, "waveform.png", description="A neat waveform image!")
+    embed = discord.Embed()
+    embed.set_author(name=message.author.display_name, icon_url=message.author.display_avatar)
+    embed.title = "Voice Message"
+    embed.add_field(name="Duration", value=str(attachment.duration_secs))
+    embed.set_image(url="attachment://waveform.png")
+    embed.timestamp = message.created_at
+    await message.reply(None, embed=embed, file=file)
+
+
+bot.run("TOKEN")