{"id":5455,"library":"red-lavalink","title":"Red-Lavalink","description":"Red-Lavalink is a client library for the Lavalink audio server, specifically designed for use with Red-DiscordBot but usable in other `discord.py` projects. It enables advanced audio playback features for Discord bots, allowing them to connect to Lavalink nodes for powerful music and audio streaming capabilities. The library is actively maintained, with regular updates to support new `discord.py` versions and Lavalink protocol changes. The current stable version is 0.11.1.","status":"active","version":"0.11.1","language":"en","source_language":"en","source_url":"https://github.com/Cog-Creators/Red-Lavalink","tags":["discord","bot","music","lavalink","audio","red-discordbot"],"install":[{"cmd":"pip install red-lavalink","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Core dependency for Discord bot integration, specifically requires 2.0.0a+.","package":"discord.py","optional":false},{"reason":"Used for underlying HTTP and WebSocket communication with Lavalink.","package":"aiohttp","optional":false},{"reason":"Used for managing connection timeouts.","package":"async_timeout","optional":false}],"imports":[{"note":"The primary module for interacting with Red-Lavalink functionalities.","symbol":"lavalink","correct":"import lavalink"}],"quickstart":{"code":"import lavalink\nimport os\nfrom discord.ext.commands import Bot, Context\nimport discord\n\n# Replace with your bot token and Lavalink credentials\nBOT_TOKEN = os.environ.get('DISCORD_BOT_TOKEN', 'YOUR_BOT_TOKEN')\nLAVALINK_HOST = os.environ.get('LAVALINK_HOST', 'localhost')\nLAVALINK_PORT = int(os.environ.get('LAVALINK_PORT', '2333'))\nLAVALINK_PASSWORD = os.environ.get('LAVALINK_PASSWORD', 'youshallnotpass')\n\nclass MyBot(Bot):\n    def __init__(self):\n        super().__init__(command_prefix='!', intents=discord.Intents.default())\n\n    async def setup_hook(self):\n        # Initialize Lavalink AFTER the bot is ready\n        await lavalink.initialize(\n            self, \n            host=LAVALINK_HOST, \n            password=LAVALINK_PASSWORD, \n            port=LAVALINK_PORT\n        )\n        print(f\"Lavalink initialized to {LAVALINK_HOST}:{LAVALINK_PORT}\")\n\n    async def on_ready(self):\n        print(f'Logged in as {self.user} (ID: {self.user.id})')\n        print('------')\n\n    async def on_voice_state_update(self, member, before, after):\n        # Handle disconnects if the bot is alone in a voice channel\n        if member == self.user and not after.channel:\n            # Bot disconnected from voice\n            player = lavalink.get_player(member.guild.id)\n            if player:\n                await player.disconnect()\n\n    async def on_lavalink_event(self, player, event, extra=None):\n        print(f\"Lavalink Event: {event} for player in guild {player.guild.id}\")\n\n\n    @commands.command()\n    async def join(self, ctx: Context, *, channel: discord.VoiceChannel = None):\n        \"\"\"Joins a voice channel.\"\"\"\n        if not channel and not ctx.author.voice:\n            return await ctx.send(\"You are not in a voice channel nor specified one.\")\n\n        channel = channel or ctx.author.voice.channel\n        player = await lavalink.connect(channel)\n        await ctx.send(f\"Joined {channel.name}\")\n\n    @commands.command()\n    async def play(self, ctx: Context, *, query: str):\n        \"\"\"Searches and plays a song.\"\"\"\n        player = lavalink.get_player(ctx.guild.id)\n        if not player or not player.is_connected:\n            return await ctx.send(\"I am not connected to a voice channel.\")\n\n        tracks = await player.search_yt(query)\n        if not tracks:\n            return await ctx.send(\"No tracks found.\")\n\n        player.add(requester=ctx.author, track=tracks[0])\n        if not player.is_playing:\n            await player.play()\n            await ctx.send(f\"Now playing: {tracks[0].title}\")\n        else:\n            await ctx.send(f\"Added to queue: {tracks[0].title}\")\n\n    @commands.command()\n    async def stop(self, ctx: Context):\n        \"\"\"Stops playback and clears the queue.\"\"\"\n        player = lavalink.get_player(ctx.guild.id)\n        if not player or not player.is_connected:\n            return await ctx.send(\"I am not connected to a voice channel.\")\n        \n        await player.stop()\n        player.queue.clear()\n        await ctx.send(\"Playback stopped and queue cleared.\")\n\nbot = MyBot()\nbot.run(BOT_TOKEN)","lang":"python","description":"This quickstart demonstrates how to set up a basic `discord.py` bot using `red-lavalink` to connect to a Lavalink server, join a voice channel, and play music. It includes commands for joining, playing, and stopping audio. Ensure your `DISCORD_BOT_TOKEN`, `LAVALINK_HOST`, `LAVALINK_PORT`, and `LAVALINK_PASSWORD` are set either as environment variables or replaced directly in the code. A running Lavalink Java server is required."},"warnings":[{"fix":"Upgrade `discord.py` to `discord.py>=2.0.0a3020050800` (or the latest stable `discord.py v2` version).","message":"Version 0.11.0 dropped support for `discord.py` 1.x. Users must upgrade their `discord.py` installation to version 2.0.0a+ or newer.","severity":"breaking","affected_versions":">=0.11.0"},{"fix":"Refer to the `red-lavalink` 0.11.0 documentation or examples for updated usage patterns, particularly around voice connection and player management. The `lavalink.connect()` function should now be used to join voice channels.","message":"Version 0.11.0 introduced significant breaking changes to the internal API due to a switch to `discord.py`'s `VoiceProtocol`. This includes removal of `user_id`, `PlayerManager`, `enums.DiscordVoiceSocketResponses`, renaming of `lavalink.player_manager` module to `lavalink.player`, and removal of methods like `Player.manager`, `Node.player_manager`, `Node.get_voice_ws()`, and `Node.join_voice_channel()`.","severity":"breaking","affected_versions":">=0.11.0"},{"fix":"Remove the `secured` parameter from any calls to `Node.connect()`.","message":"The `secured` parameter in `Node.connect()` was removed in version 0.10.0. Secure WebSocket connections are now handled automatically based on the port and host settings.","severity":"breaking","affected_versions":">=0.10.0"},{"fix":"While `red-lavalink` handles this on the client side, ensure your deployed Lavalink Java server is running a recent version that supports the DAVE protocol for optimal compatibility.","message":"As of `red-lavalink` 0.11.1, the library sends the voice channel ID to the Lavalink server, which is required by newer Lavalink server versions to support Discord's DAVE protocol. Ensure your Lavalink server is also up-to-date to fully utilize this.","severity":"gotcha","affected_versions":">=0.11.1"},{"fix":"Update any code referencing `ExceptionSeverity.FATAL` to `ExceptionSeverity.FAULT`.","message":"The `ExceptionSeverity` enum value `FATAL` was renamed to `FAULT` in version 0.10.0 to align with Lavalink's API.","severity":"gotcha","affected_versions":">=0.10.0"},{"fix":"Set up and run a Lavalink Java server (e.g., from `https://github.com/Cog-Creators/Lavalink-Jars` or `https://github.com/Lavalink-Devs/Lavalink/`). Ensure it's running on Java 17+.","message":"Red-Lavalink requires a separate, running Lavalink Java server. For standalone projects, you must deploy and manage a Lavalink server instance. As of recent Red-DiscordBot updates (3.5.23/24), Lavalink servers typically require Java 17 or newer.","severity":"gotcha","affected_versions":"all"}],"env_vars":null,"last_verified":"2026-04-13T00:00:00.000Z","next_check":"2026-07-12T00:00:00.000Z"}