wavecord

A high-performance Lavalink client for Python, powered by a Rust core.

WaveCord speaks both Lavalink v3 and v4 through a single, version-neutral API, with the version detected automatically on connect. The performance-critical work (WebSocket, REST, serialization, reconnect, and node management) runs in native Rust, off the Python GIL, while a thin async layer on top works with every major Discord library.

Features

Lavalink v3 and v4 behind one API, auto-detected on connect.
Off-GIL networking. The WebSocket, REST, JSON parsing, and v3/v4 normalization run on native tokio threads, keeping your event loop responsive under load.
Typed events. Handlers receive real objects (event.track.info.title), decoded straight into msgspec structs.
Library-agnostic. Adapters for discord.py, py-cord, disnake, and nextcord.
Batteries included. Queue with auto-advance, filters and equalizer, and a typed event dispatcher.
Plugin-ready. Search-source helpers (Spotify, Apple Music, Deezer via LavaSrc), LavaSearch, LavaLyrics, and SponsorBlock, plus track pluginInfo on typed events.
Survives restarts. Persist and reuse the session id and Lavalink keeps playing across a bot process restart.
Observability. Turn the node pool into a metrics snapshot or Prometheus text with wavecord.metrics.
Built to scale. Multi-node pool with load balancing, automatic reconnect with backoff, session resuming, and failover.

Requirements

Python 3.9 or newer
A running Lavalink v3 or v4 node
One of the supported Discord libraries (for voice)

Installation

Prebuilt wheels are on PyPI, so there is no Rust toolchain to install:

pip install wavecord

Add the Discord library you use as an extra:

pip install "wavecord[discordpy]"   # or [pycord], [disnake], [nextcord]

Quick start

import discord
from discord.ext import commands

import wavecord
from wavecord.adapters.discordpy import WaveCordVoiceClient
from wavecord.dispatcher import EventDispatcher

intents = discord.Intents.default()
intents.message_content = True
bot = commands.Bot(command_prefix="!", intents=intents)
node: wavecord.Node


@bot.event
async def on_ready():
    global node
    node = wavecord.Node("127.0.0.1", 2333, "youshallnotpass", str(bot.user.id))
    await node.connect()

    dispatcher = EventDispatcher(node)

    @dispatcher.on("track_end")
    async def on_track_end(event):  # a typed wavecord.events.Event
        print("finished", event.guild_id, event.reason)

    dispatcher.start()


@bot.command()
async def play(ctx, *, query: str):
    vc = await ctx.author.voice.channel.connect(
        cls=WaveCordVoiceClient.with_node(node)
    )
    result = await vc.player.search(query)
    track = result["data"] if result["loadType"] == "track" else result["data"][0]
    await vc.player.play(track["encoded"])
    await ctx.send(f"Playing {track['info']['title']}")


bot.run("YOUR_TOKEN")

A fuller bot is in examples/music_bot.py.

Supported Discord libraries

Library	Adapter
discord.py	`wavecord.adapters.discordpy`
py-cord	`wavecord.adapters.pycord`
disnake	`wavecord.adapters.disnake`
nextcord	`wavecord.adapters.nextcord`

Performance

Event throughput: WaveCord sustains about 1.35x the events per second of a pure-Python client.

A Lavalink client cannot make playback itself faster, since the audio work happens on the Lavalink server. WaveCord's edge is architectural: the WebSocket read, JSON parse, and v3/v4 normalization run in native Rust off the GIL, so the asyncio event loop only pays for the final msgspec decode. In a burst benchmark against the real Rust path (500k player updates), WaveCord sustained roughly 1.35x the event throughput of an equivalent pure-Python client, and kept the typical (median) event-loop latency about 2x lower. Batched delivery trades a little tail latency for that throughput; drop the next_events batch size if you prefer smoother tails. Reproduce it yourself with python benchmarks/off_gil.py.

Architecture

Python layer (asyncio, Discord adapters, dispatcher, queue, pool)
        |  PyO3 + pyo3-async-runtimes  (Rust future <-> asyncio coroutine)
Rust core (tokio): WebSocket, REST, Protocol(v3/v4), reconnect, node manager

crates/wavecord-core: the pure-Rust engine (testable and benchmarkable alone)
crates/wavecord-py: the PyO3 bindings (thin glue)
python/wavecord: the public Python API and Discord-library adapters

Development

maturin develop      # build the extension into the active venv
cargo test           # Rust tests (no Python needed)
pytest               # Python tests

To try it end to end you need a running Lavalink node (v3 or v4). Point WaveCord at it and run one of the bots in examples/.

Contributing

Contributions are welcome. Please read CONTRIBUTING.md for how to set up the project, run the tests, and open a pull request. Bug reports and feature ideas are just as valuable as code.

By taking part in this project you agree to abide by our Code of Conduct. To report a security issue, see our Security Policy.

Contributors

WaveCord · Lavalink, in Rust and Python
Documentation · Changelog · Contributing
Licensed under the MIT License · Copyright © 2026 WaveCord Contributors

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

wavecord-1.1.0.tar.gz (53.1 kB view details)

Uploaded Jul 25, 2026 Source

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

wavecord-1.1.0-pp311-pypy311_pp73-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (2.8 MB view details)

Uploaded Jul 25, 2026 PyPymanylinux: glibc 2.17+ x86-64

wavecord-1.1.0-cp315-cp315t-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (2.8 MB view details)

Uploaded Jul 25, 2026 CPython 3.15tmanylinux: glibc 2.17+ x86-64

wavecord-1.1.0-cp315-cp315-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (2.8 MB view details)

Uploaded Jul 25, 2026 CPython 3.15manylinux: glibc 2.17+ x86-64

wavecord-1.1.0-cp314-cp314t-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (2.8 MB view details)

Uploaded Jul 25, 2026 CPython 3.14tmanylinux: glibc 2.17+ x86-64

wavecord-1.1.0-cp314-cp314-win_amd64.whl (2.7 MB view details)

Uploaded Jul 25, 2026 CPython 3.14Windows x86-64

wavecord-1.1.0-cp314-cp314-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (2.8 MB view details)

Uploaded Jul 25, 2026 CPython 3.14manylinux: glibc 2.17+ x86-64

wavecord-1.1.0-cp314-cp314-macosx_11_0_arm64.whl (2.6 MB view details)

Uploaded Jul 25, 2026 CPython 3.14macOS 11.0+ ARM64

wavecord-1.1.0-cp314-cp314-macosx_10_12_x86_64.whl (2.7 MB view details)

Uploaded Jul 25, 2026 CPython 3.14macOS 10.12+ x86-64

wavecord-1.1.0-cp313-cp313-win_amd64.whl (2.7 MB view details)

Uploaded Jul 25, 2026 CPython 3.13Windows x86-64

wavecord-1.1.0-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (2.8 MB view details)

Uploaded Jul 25, 2026 CPython 3.13manylinux: glibc 2.17+ x86-64

wavecord-1.1.0-cp313-cp313-macosx_11_0_arm64.whl (2.6 MB view details)

Uploaded Jul 25, 2026 CPython 3.13macOS 11.0+ ARM64

wavecord-1.1.0-cp313-cp313-macosx_10_12_x86_64.whl (2.7 MB view details)

Uploaded Jul 25, 2026 CPython 3.13macOS 10.12+ x86-64

wavecord-1.1.0-cp312-cp312-win_amd64.whl (2.7 MB view details)

Uploaded Jul 25, 2026 CPython 3.12Windows x86-64

wavecord-1.1.0-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (2.8 MB view details)

Uploaded Jul 25, 2026 CPython 3.12manylinux: glibc 2.17+ x86-64

wavecord-1.1.0-cp312-cp312-macosx_11_0_arm64.whl (2.6 MB view details)

Uploaded Jul 25, 2026 CPython 3.12macOS 11.0+ ARM64

wavecord-1.1.0-cp312-cp312-macosx_10_12_x86_64.whl (2.7 MB view details)

Uploaded Jul 25, 2026 CPython 3.12macOS 10.12+ x86-64

wavecord-1.1.0-cp311-cp311-win_amd64.whl (2.7 MB view details)

Uploaded Jul 25, 2026 CPython 3.11Windows x86-64

wavecord-1.1.0-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (2.8 MB view details)

Uploaded Jul 25, 2026 CPython 3.11manylinux: glibc 2.17+ x86-64

wavecord-1.1.0-cp311-cp311-macosx_11_0_arm64.whl (2.6 MB view details)

Uploaded Jul 25, 2026 CPython 3.11macOS 11.0+ ARM64

wavecord-1.1.0-cp311-cp311-macosx_10_12_x86_64.whl (2.6 MB view details)

Uploaded Jul 25, 2026 CPython 3.11macOS 10.12+ x86-64

wavecord-1.1.0-cp310-cp310-win_amd64.whl (2.7 MB view details)

Uploaded Jul 25, 2026 CPython 3.10Windows x86-64

wavecord-1.1.0-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (2.8 MB view details)

Uploaded Jul 25, 2026 CPython 3.10manylinux: glibc 2.17+ x86-64

wavecord-1.1.0-cp39-cp39-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (2.8 MB view details)

Uploaded Jul 25, 2026 CPython 3.9manylinux: glibc 2.17+ x86-64

File details

Details for the file wavecord-1.1.0.tar.gz.

File metadata

Download URL: wavecord-1.1.0.tar.gz
Upload date: Jul 25, 2026
Size: 53.1 kB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/6.1.0 CPython/3.13.14

File hashes

Hashes for wavecord-1.1.0.tar.gz
Algorithm	Hash digest
SHA256	`0f47c09358368fad99daab820c7a46c7a497743c67ab3aace33a807c8bf8642c`
MD5	`68a9eaa10b3bfe967a198ff7abaa9a31`
BLAKE2b-256	`e7543387d8a038f98dc0d1f00475bf83ad59303b2caf2f533332db2043a76ac4`

Algorithm	Hash digest
SHA256	`fb6be083383fb27bbabf623e3e6df17fdb147ea00ff370aa36859e2af39cdaa5`
MD5	`1c52691160a78364f2070bd7c1ae359f`
BLAKE2b-256	`25004e0ae9aa3141960bea85c94c948287a5e62ae8a3995b751173184c596386`

Algorithm	Hash digest
SHA256	`285df53710e351549355cf05bb0da79de4ba92920197fad4a989f7d907fdd0e2`
MD5	`e81db70e8784b7f70e0a567436fe2a7e`
BLAKE2b-256	`08f09691281c5d52847c01faf44c4ed509a7655abd792d377d0d45a760c2c70b`

Algorithm	Hash digest
SHA256	`d4c639344f3ee0f715a06386bd66c5628c679d982cba164ee57acceb2cb1c452`
MD5	`201d60e2742497935124e6ebcf9381de`
BLAKE2b-256	`87342399754c397ed03cde2e8b36536be00bb36097ee1bb4eeee4714be8e3e11`

Algorithm	Hash digest
SHA256	`9c57205c01393eb07cb7c8c8692c2016e37e16eac04883a085332db4bce44cb7`
MD5	`bba9b4fdf9fdb4f461bbb54592a5ab75`
BLAKE2b-256	`69c42fee41cc920329f554322a6360063358100b7c55bf6caa08d680a760a6dc`

Algorithm	Hash digest
SHA256	`12ae8f0fd660f8782360170cc1551d97cc37626a6e730719fb2a9c9ae5ed6868`
MD5	`8ae793adbe8de9323ec6c4f5d0c3b189`
BLAKE2b-256	`d251748fede166737c9c97151911038816ed18712b9f9b19f361e02b50332116`

Algorithm	Hash digest
SHA256	`c573dff2595ab27a5363133df68e4a06b71a4d7af420407b4976f301c145ff1e`
MD5	`a9b4eeadeebb490cdb0985736d55a82c`
BLAKE2b-256	`46999f5ffd49ac330b02115caca2e4bb19d38eca268368a796460a5f031996a0`

Algorithm	Hash digest
SHA256	`4623aabe1f0249143069c9ea3b2eb985b55b9f9ba232cfca2012fb60c5aaaae0`
MD5	`2a5fd91494db6dda05713c40d1c081c0`
BLAKE2b-256	`7f2b6c45f0cfb40e3c227fb36821494669c5fc97ee030608a200acc5b7782013`

Algorithm	Hash digest
SHA256	`056dbc4d1822438b25a8d2fc01f2cb9097ef5feb617fc8cad71a13ad2bd87026`
MD5	`1263123c7df7e63828af2890eace7e57`
BLAKE2b-256	`bd5d22d4a187b1d277549d66dfd25527067ae583e43bdf7812b00a03b61bfbcb`

Algorithm	Hash digest
SHA256	`84d17d63a5db7cd27a61f34173f9ff695d0b56342a998b4f01fd2eb0785fb947`
MD5	`acd730f9074c6df511d100d1a30c237a`
BLAKE2b-256	`4316f75132738fa12d9868ef64649eb94250ca6ad4fe28f968f717dd882cd7af`

Algorithm	Hash digest
SHA256	`6335f263fe29be7a75a5d879b2c14003fd28a54c842bfc477ba1d664276a5dbd`
MD5	`58d21257717297f34404790f500368c1`
BLAKE2b-256	`93033a2a98d325c4728ff5303b4b16edf6f01edacb7e164110e2397748e73b80`

Algorithm	Hash digest
SHA256	`b4e8fb80f249496806e8d04ff90e905117a31069287574a74cf52e4f96ab8b47`
MD5	`dde44b28026126edb6798b6438a7bdb8`
BLAKE2b-256	`737223ce864319f7c8a3883fc49f047130ae68e0b5b97a9ac82bf7af69403f84`

Algorithm	Hash digest
SHA256	`5f5fbcf3c87ac465b5020b30b99ff938a12d6eb342658bde44d2d954c3ddb315`
MD5	`643633b57c129aa7ca115a91a579176f`
BLAKE2b-256	`90ee0efcedbf66b45aad2555c63577de43511f18bbde290d33391691be7f9503`

Algorithm	Hash digest
SHA256	`61955fcfab684ced7193d833306dc4cd448b75894e3ea32c396606d37f0a2236`
MD5	`b9751a5520260b25a0d712e9f293c0fc`
BLAKE2b-256	`46f38efb4e2fad251bae558af294d82b3785a3916ae101968f346531d067f56f`

Algorithm	Hash digest
SHA256	`1cfa3523a1fcc71aa960d50604ca2b82dd43b3f23e82231467fb1253cfa5e421`
MD5	`b0034f47b9cf6446709bf001c848e730`
BLAKE2b-256	`0ea697e12bd4396094b281d5d46ec0db85ea4398a169d10b6e2fe94c4450764f`

Algorithm	Hash digest
SHA256	`0a30af3a6b03e0841fd6444b6b0a0821138d3213f9db3113ad23a1a543a43d59`
MD5	`361955ad817979d20fb81b69e3301e2c`
BLAKE2b-256	`e2c31a74e2948b4e14a3e2e9b3bdee1cc986792fd2e630b035cbdd35f1f120d7`

Algorithm	Hash digest
SHA256	`c0782ebdc9b0a3be78bee66dd1f97cef86852218d21160b1810c5b00dab0ebf3`
MD5	`299806cab2fee5870566f9dda358cba5`
BLAKE2b-256	`9fb2a9bd7bc15d2bc42127cc1e2fa40d813984ffddca0fef7c4b7ae3724d0c7c`

Algorithm	Hash digest
SHA256	`ed6f789a0c184f90aca6c28ba9cbeb157e1afbc05046977aaea9865998f215d3`
MD5	`18cfec90f7f4a8162045fb1e4278319c`
BLAKE2b-256	`4766d2028cdd1257269559f126be2a52488468c3fb0388fc72e51fca4810710c`

Algorithm	Hash digest
SHA256	`768cb4015094163f028398fec12cf49a1aecce6fa719b43bee028f4957fd0271`
MD5	`7e0696eafcf4ea615b84836010119b8f`
BLAKE2b-256	`410dfb4af091007baa5668750ad8cfcd390f9d3a2b3dbc984243e894245625ed`

Algorithm	Hash digest
SHA256	`86fd9a537901ba9097bcd13fc9a08b4a578012faad935557ee14af904a98adc0`
MD5	`68e8a1ba18b1982bb87d30f9ec58407b`
BLAKE2b-256	`5076d6b890aa229ec6c5d6c7697d99b37e421fa5e07d5c2b9b36ddc16baafb2d`

Algorithm	Hash digest
SHA256	`22f13b64be02bb7098c691c9cff8fe7be544896fddccd607bc06b8fbd838a681`
MD5	`85b9ab7e4874cb4ce4edcc7b77a36344`
BLAKE2b-256	`c6a24c16ef1391651a4c38ae7a59d4e338df753f13b162b957e45dabbab8d646`

wavecord 1.1.0

Features

Requirements

Installation

Quick start

Supported Discord libraries

Performance

Architecture

Development

Contributing

Contributors

Project links

Key dates

1 maintainer

Credits

GitHub Statistics

License

Requires

Provides Extra

Tags

Classifiers

Download files

Source Distribution

Built Distributions

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

Algorithm	Hash digest
SHA256	`e1f396cbe19044b080e7b6ac71c7d3376996286cd66de64185f88ba865ac223a`
MD5	`6d8203b545604522d29b8233b2c96d1e`
BLAKE2b-256	`e45aab2ab48d4b23abd3bf376547be9354323f54242d83c22cc55a871602f532`

Algorithm	Hash digest
SHA256	`c47eca4fbf8ebadc7fe7d41bbf778e5d6806d3c4198569399273a7b1d4e22b6a`
MD5	`aa60bb4aeff1b1687cdf323d83604164`
BLAKE2b-256	`c69e69da063af15d07f76329eed7736cb99aabd776ce28476f0e2f3de94fc3ee`

Algorithm	Hash digest
SHA256	`0f31c973afefbe765a203f2d70c035c369a5e152a7088194651dc287200d206c`
MD5	`87f46b0499cca9f66dd795021c7e67c3`
BLAKE2b-256	`bc140f2f868070b19df0871e065927070b537709a4a81bcc3b90a7e6c07e06d0`