pyauralis 0.1.0__tar.gz

pyauralis-0.1.0/.gitignore

@@ -0,0 +1,6 @@
+.venv/
+__pycache__/
+*.egg-info/
+dist/
+build/
+.pytest_cache/

pyauralis-0.1.0/PKG-INFO

@@ -0,0 +1,122 @@
+Metadata-Version: 2.4
+Name: pyauralis
+Version: 0.1.0
+Summary: Official async Python SDK for the Auralis music platform
+Project-URL: Homepage, https://github.com/auralis/auralis
+Project-URL: Source, https://github.com/auralis/auralis/tree/main/sdks/python
+Author: Auralis
+License: MIT
+Keywords: audio,auralis,bot,discord,music
+Classifier: License :: OSI Approved :: MIT License
+Requires-Python: >=3.10
+Requires-Dist: aiohttp>=3.9
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Provides-Extra: speedups
+Requires-Dist: orjson>=3.9; extra == 'speedups'
+Description-Content-Type: text/markdown
+
+# auralis
+
+Official **async Python SDK** for the [Auralis](https://github.com/auralis/auralis) music platform.
+One dependency (`aiohttp`), a tiny command surface, and the whole queue/skip/loop/shuffle
+brain handled for you.
+
+```bash
+pip install auralis
+```
+
+## Quickstart
+
+```python
+import asyncio
+from auralis import Client, LoopMode
+
+client = Client("http://localhost:8080", "YOUR-API-TOKEN")
+
+@client.event
+async def on_track_start(player, data):
+    print("now playing:", player.current.title)
+
+@client.event
+async def on_queue_end(player):
+    await player.disconnect()
+
+async def main():
+    await client.start()
+    player = client.get_player(guild_id=123456789)
+
+    # --- wire your Discord library's voice events to the player (see below) ---
+
+    await player.play("ytsearch:never gonna give you up")
+    await player.add("https://youtu.be/dQw4w9WgXcQ")
+    player.set_loop(LoopMode.QUEUE)
+    await asyncio.Event().wait()
+
+asyncio.run(main())
+```
+
+## Player commands
+
+| Command | Does |
+|---|---|
+| `await player.play(query)` | resolve + enqueue, start if idle |
+| `await player.add(query)` | enqueue only |
+| `await player.skip()` | advance to next track |
+| `await player.stop()` | stop + clear queue (stays connected) |
+| `await player.pause()` / `resume()` | pause / resume |
+| `await player.seek(ms)` | seek |
+| `await player.set_volume(0..1000)` | volume (100 = unity) |
+| `player.set_loop(LoopMode.OFF/TRACK/QUEUE)` | loop mode |
+| `player.shuffle()` | shuffle the queue |
+| `player.now_playing()` | current `Track` |
+| `await player.set_filters("bass=g=8")` | raw ffmpeg `-af` filtergraph |
+| `await player.disconnect()` | tear down the player |
+
+`query` is a search string (`"ytsearch:…"`, a URL, a playlist URL) or a `Track` you
+already loaded via `client.search(...)` / `client.load_tracks(...)`.
+
+## Events
+
+`@client.event` on an `async def on_<name>(...)`, or `client.add_listener("<name>", cb)`:
+
+| Event | Args |
+|---|---|
+| `on_ready()` | — |
+| `on_track_start(player, data)` | track began |
+| `on_track_end(player, data)` | track ended (`data["reason"]`) |
+| `on_track_exception(player, data)` | playback error |
+| `on_track_stuck(player, data)` | stalled |
+| `on_player_update(player, data)` | live state (`player.state`) |
+| `on_voice_closed(player, data)` | Discord voice closed |
+| `on_queue_end(player)` | nothing left to play |
+| `on_disconnect()` | websocket dropped (auto-reconnects) |
+
+## Wiring Discord voice
+
+The SDK never touches the Discord gateway — your bot owns that. Join a channel with
+your library, then forward the two raw voice payloads:
+
+```python
+# discord.py raw gateway events
+@bot.event
+async def on_socket_raw_receive(...):
+    ...  # or use a gateway hook
+
+# when you get VOICE_SERVER_UPDATE for a guild:
+client.get_player(guild_id).update_voice_server({"token": ..., "endpoint": ...})
+
+# when you get VOICE_STATE_UPDATE for the bot:
+client.get_player(guild_id).update_voice_state(
+    {"session_id": ..., "channel_id": ..., "user_id": bot_user_id}
+)
+```
+
+Once both arrive, the player connects and starts anything already queued.
+
+## Notes
+
+- The queue lives in this process (lost on bot restart).
+- Node internals (node ids, endpoints, regions) are never exposed by this SDK.
+- `pip install "auralis[speedups]"` pulls in `orjson` for faster JSON.

pyauralis-0.1.0/README.md

@@ -0,0 +1,103 @@
+# auralis
+
+Official **async Python SDK** for the [Auralis](https://github.com/auralis/auralis) music platform.
+One dependency (`aiohttp`), a tiny command surface, and the whole queue/skip/loop/shuffle
+brain handled for you.
+
+```bash
+pip install auralis
+```
+
+## Quickstart
+
+```python
+import asyncio
+from auralis import Client, LoopMode
+
+client = Client("http://localhost:8080", "YOUR-API-TOKEN")
+
+@client.event
+async def on_track_start(player, data):
+    print("now playing:", player.current.title)
+
+@client.event
+async def on_queue_end(player):
+    await player.disconnect()
+
+async def main():
+    await client.start()
+    player = client.get_player(guild_id=123456789)
+
+    # --- wire your Discord library's voice events to the player (see below) ---
+
+    await player.play("ytsearch:never gonna give you up")
+    await player.add("https://youtu.be/dQw4w9WgXcQ")
+    player.set_loop(LoopMode.QUEUE)
+    await asyncio.Event().wait()
+
+asyncio.run(main())
+```
+
+## Player commands
+
+| Command | Does |
+|---|---|
+| `await player.play(query)` | resolve + enqueue, start if idle |
+| `await player.add(query)` | enqueue only |
+| `await player.skip()` | advance to next track |
+| `await player.stop()` | stop + clear queue (stays connected) |
+| `await player.pause()` / `resume()` | pause / resume |
+| `await player.seek(ms)` | seek |
+| `await player.set_volume(0..1000)` | volume (100 = unity) |
+| `player.set_loop(LoopMode.OFF/TRACK/QUEUE)` | loop mode |
+| `player.shuffle()` | shuffle the queue |
+| `player.now_playing()` | current `Track` |
+| `await player.set_filters("bass=g=8")` | raw ffmpeg `-af` filtergraph |
+| `await player.disconnect()` | tear down the player |
+
+`query` is a search string (`"ytsearch:…"`, a URL, a playlist URL) or a `Track` you
+already loaded via `client.search(...)` / `client.load_tracks(...)`.
+
+## Events
+
+`@client.event` on an `async def on_<name>(...)`, or `client.add_listener("<name>", cb)`:
+
+| Event | Args |
+|---|---|
+| `on_ready()` | — |
+| `on_track_start(player, data)` | track began |
+| `on_track_end(player, data)` | track ended (`data["reason"]`) |
+| `on_track_exception(player, data)` | playback error |
+| `on_track_stuck(player, data)` | stalled |
+| `on_player_update(player, data)` | live state (`player.state`) |
+| `on_voice_closed(player, data)` | Discord voice closed |
+| `on_queue_end(player)` | nothing left to play |
+| `on_disconnect()` | websocket dropped (auto-reconnects) |
+
+## Wiring Discord voice
+
+The SDK never touches the Discord gateway — your bot owns that. Join a channel with
+your library, then forward the two raw voice payloads:
+
+```python
+# discord.py raw gateway events
+@bot.event
+async def on_socket_raw_receive(...):
+    ...  # or use a gateway hook
+
+# when you get VOICE_SERVER_UPDATE for a guild:
+client.get_player(guild_id).update_voice_server({"token": ..., "endpoint": ...})
+
+# when you get VOICE_STATE_UPDATE for the bot:
+client.get_player(guild_id).update_voice_state(
+    {"session_id": ..., "channel_id": ..., "user_id": bot_user_id}
+)
+```
+
+Once both arrive, the player connects and starts anything already queued.
+
+## Notes
+
+- The queue lives in this process (lost on bot restart).
+- Node internals (node ids, endpoints, regions) are never exposed by this SDK.
+- `pip install "auralis[speedups]"` pulls in `orjson` for faster JSON.

pyauralis-0.1.0/examples/bot.py

@@ -0,0 +1,75 @@
+"""Minimal discord.py music bot on top of the Auralis SDK.
+
+    pip install auralis discord.py
+    AURALIS_URL=http://localhost:8080 AURALIS_TOKEN=... DISCORD_TOKEN=... python bot.py
+
+Commands: !play <query>, !skip, !stop, !queue
+"""
+
+import os
+
+import discord
+from discord.ext import commands
+
+from auralis import Client
+
+intents = discord.Intents.default()
+intents.message_content = True
+bot = commands.Bot(command_prefix="!", intents=intents)
+auralis = Client(os.environ["AURALIS_URL"], os.environ["AURALIS_TOKEN"])
+
+
+@bot.event
+async def on_ready():
+    await auralis.start()
+    print(f"logged in as {bot.user}")
+
+
+# Forward Discord's raw voice gateway events straight to the matching player.
+@bot.event
+async def on_socket_response(payload):
+    op, data = payload.get("t"), payload.get("d") or {}
+    if op == "VOICE_SERVER_UPDATE":
+        auralis.get_player(int(data["guild_id"])).update_voice_server(data)
+    elif op == "VOICE_STATE_UPDATE" and int(data["user_id"]) == bot.user.id:
+        auralis.get_player(int(data["guild_id"])).update_voice_state(data)
+
+
+@auralis.event
+async def on_track_start(player, _data):
+    print("now playing:", player.current.title)
+
+
+@bot.command()
+async def play(ctx, *, query: str):
+    if not ctx.author.voice:
+        return await ctx.send("join a voice channel first")
+    # Tell Discord to connect the bot — this triggers the voice events above.
+    await ctx.guild.change_voice_state(channel=ctx.author.voice.channel)
+    player = auralis.get_player(ctx.guild.id)
+    tracks = await player.play(query, requester=ctx.author.id)
+    await ctx.send(f"queued **{tracks[0].title}**")
+
+
+@bot.command()
+async def skip(ctx):
+    await auralis.get_player(ctx.guild.id).skip()
+    await ctx.send("⏭️ skipped")
+
+
+@bot.command()
+async def stop(ctx):
+    await auralis.get_player(ctx.guild.id).disconnect()
+    await ctx.guild.change_voice_state(channel=None)
+    await ctx.send("⏹️ stopped")
+
+
+@bot.command()
+async def queue(ctx):
+    player = auralis.get_player(ctx.guild.id)
+    lines = [f"**now:** {player.current.title}"] if player.current else []
+    lines += [f"{i + 1}. {t.title}" for i, t in enumerate(player.queue[:10])]
+    await ctx.send("\n".join(lines) or "queue is empty")
+
+
+bot.run(os.environ["DISCORD_TOKEN"])

pyauralis-0.1.0/pyproject.toml

@@ -0,0 +1,30 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "pyauralis"
+version = "0.1.0"
+description = "Official async Python SDK for the Auralis music platform"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "Auralis" }]
+keywords = ["auralis", "discord", "music", "audio", "bot"]
+classifiers = ["License :: OSI Approved :: MIT License"]
+dependencies = ["aiohttp>=3.9"]
+
+[project.optional-dependencies]
+speedups = ["orjson>=3.9"]
+dev = ["pytest>=8", "pytest-asyncio>=0.23"]
+
+[project.urls]
+Homepage = "https://github.com/auralis/auralis"
+Source = "https://github.com/auralis/auralis/tree/main/sdks/python"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/auralis"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]

pyauralis-0.1.0/src/auralis/__init__.py

@@ -0,0 +1,53 @@
+"""Auralis — the official async Python SDK for the Auralis music platform.
+
+    import asyncio
+    from auralis import Client
+
+    async def main():
+        client = Client("http://localhost:8080", "my-token")
+        await client.start()
+
+        @client.event
+        async def on_track_start(player, data):
+            print("now playing:", player.current.title)
+
+        player = client.get_player(guild_id)
+        # ... wire player.update_voice_server / update_voice_state from your bot ...
+        await player.play("ytsearch:never gonna give you up")
+
+The queue, skip, loop, and shuffle all live in this library — the backend only
+plays what it is told. See ``Player`` for the full command surface.
+"""
+
+from .client import Client
+from .enums import EndReason, LoadType, LoopMode
+from .errors import (
+    APIError,
+    AuralisError,
+    AuthError,
+    LoadError,
+    NotConnected,
+    RateLimited,
+)
+from .models import LoadResult, PlayerState, Track
+from .player import Player
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "Client",
+    "Player",
+    "Track",
+    "LoadResult",
+    "PlayerState",
+    "LoopMode",
+    "LoadType",
+    "EndReason",
+    "AuralisError",
+    "AuthError",
+    "RateLimited",
+    "APIError",
+    "NotConnected",
+    "LoadError",
+    "__version__",
+]

pyauralis-0.1.0/src/auralis/client.py

@@ -0,0 +1,266 @@
+"""The top-level client: owns the HTTP session, the WebSocket event loop, the
+per-guild players, and event dispatch."""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import logging
+import random
+import time
+from typing import Any, Awaitable, Callable
+
+import aiohttp
+
+from .enums import EndReason
+from .models import LoadResult, PlayerState, Track
+from .player import Player
+from .rest import REST
+
+log = logging.getLogger("auralis")
+
+Listener = Callable[..., Any]
+
+# WS op -> the event name we dispatch to user listeners.
+_EVENT_OPS = {
+    "TRACK_START": "track_start",
+    "TRACK_END": "track_end",
+    "TRACK_EXCEPTION": "track_exception",
+    "TRACK_STUCK": "track_stuck",
+    "PLAYER_UPDATE": "player_update",
+    "VOICE_CLOSED": "voice_closed",
+    "STATS": "stats",
+}
+
+
+class Client:
+    """Connect once, then drive playback through :meth:`get_player`.
+
+    ``base_url`` is the control-plane HTTP origin (e.g. ``http://localhost:8080``);
+    the WebSocket URL is derived from it.
+    """
+
+    def __init__(
+        self,
+        base_url: str,
+        token: str,
+        *,
+        reconnect: bool = True,
+        session: aiohttp.ClientSession | None = None,
+    ) -> None:
+        self.base_url = base_url.rstrip("/")
+        self._token = token
+        self._reconnect = reconnect
+        self._session = session
+        self._owns_session = session is None
+        self._rest: REST | None = None  # set in start()
+
+        self._players: dict[int, Player] = {}
+        self._listeners: dict[str, list[Listener]] = {}
+        self._tasks: set[asyncio.Task] = set()
+        self._ws: aiohttp.ClientWebSocketResponse | None = None
+        self._ws_task: asyncio.Task | None = None
+        self._session_id: str | None = None
+        self._closed = False
+        self._has_connected = False
+        self._heartbeat_sent_at = 0.0
+
+        #: Last measured heartbeat round-trip latency in seconds (-1 until first ack).
+        self.latency: float = -1.0
+        #: Most recent STATS frame payload from the node, or ``None``.
+        self.last_stats: dict[str, Any] | None = None
+
+    # --- lifecycle --------------------------------------------------------
+    async def start(self) -> None:
+        """Open the HTTP session and the event WebSocket."""
+        if self._session is None:
+            self._session = aiohttp.ClientSession()
+        self._rest = REST(self.base_url, self._token, self._session)
+        self._ws_task = self._schedule(self._ws_loop())
+
+    async def close(self) -> None:
+        self._closed = True
+        if self._ws is not None:
+            await self._ws.close()
+        if self._ws_task is not None:
+            self._ws_task.cancel()
+            with contextlib.suppress(asyncio.CancelledError):
+                await self._ws_task
+        for t in list(self._tasks):
+            t.cancel()
+        if self._owns_session and self._session is not None:
+            await self._session.close()
+
+    async def __aenter__(self) -> "Client":
+        await self.start()
+        return self
+
+    async def __aexit__(self, *exc: Any) -> None:
+        await self.close()
+
+    # --- players ----------------------------------------------------------
+    def get_player(self, guild_id: int) -> Player:
+        """Get (creating if needed) the player for a guild."""
+        p = self._players.get(guild_id)
+        if p is None:
+            p = Player(self, guild_id)
+            self._players[guild_id] = p
+        return p
+
+    def players(self) -> list[Player]:
+        return list(self._players.values())
+
+    def _drop_player(self, guild_id: int) -> None:
+        self._players.pop(guild_id, None)
+
+    # --- metadata convenience --------------------------------------------
+    async def load_tracks(self, identifier: str) -> LoadResult:
+        assert self._rest is not None, "call start() first"
+        return await self._rest.load_tracks(identifier)
+
+    async def search(self, query: str) -> list[Track]:
+        """``ytsearch:``-prefix a bare query and return the hits (empty on miss)."""
+        ident = query if ":" in query.split(" ", 1)[0] else f"ytsearch:{query}"
+        return (await self.load_tracks(ident)).tracks
+
+    # --- events -----------------------------------------------------------
+    def event(self, func: Listener) -> Listener:
+        """Decorator: ``@client.event`` on ``async def on_track_start(...)``."""
+        name = func.__name__[3:] if func.__name__.startswith("on_") else func.__name__
+        self.add_listener(name, func)
+        return func
+
+    def add_listener(self, name: str, func: Listener) -> None:
+        self._listeners.setdefault(name, []).append(func)
+
+    def _dispatch(self, name: str, *args: Any) -> None:
+        for cb in self._listeners.get(name, ()):
+            res = cb(*args)
+            if asyncio.iscoroutine(res):
+                self._schedule(res)
+
+    # --- task helper ------------------------------------------------------
+    def _schedule(self, coro: Awaitable[Any]) -> asyncio.Task:
+        task = asyncio.ensure_future(coro)
+        self._tasks.add(task)
+        task.add_done_callback(self._on_task_done)
+        return task
+
+    def _on_task_done(self, task: asyncio.Task) -> None:
+        # Surface (not swallow) background-task failures — e.g. a raising listener.
+        self._tasks.discard(task)
+        if not task.cancelled() and task.exception() is not None:
+            log.warning("background task error: %s", task.exception())
+
+    # --- websocket --------------------------------------------------------
+    @property
+    def _ws_url(self) -> str:
+        ws = self.base_url.replace("https://", "wss://").replace("http://", "ws://")
+        return f"{ws}/v1/ws"
+
+    async def _ws_loop(self) -> None:
+        backoff = 1.0
+        while not self._closed:
+            try:
+                assert self._session is not None
+                async with self._session.ws_connect(
+                    self._ws_url, headers={"Authorization": f"Bearer {self._token}"}
+                ) as ws:
+                    self._ws = ws
+                    backoff = 1.0
+                    await self._subscribe_all()
+                    async for msg in ws:
+                        if msg.type == aiohttp.WSMsgType.TEXT:
+                            # Isolate handler failures: a transient REST error while
+                            # auto-advancing must not tear down the socket. Log and
+                            # route to an "error" listener, then keep reading.
+                            try:
+                                await self._handle_frame(msg.json())
+                            except Exception as exc:  # noqa: BLE001
+                                log.warning("frame handler error: %s", exc)
+                                self._dispatch("error", exc)
+                        elif msg.type in (aiohttp.WSMsgType.CLOSED, aiohttp.WSMsgType.ERROR):
+                            break
+            except asyncio.CancelledError:
+                raise
+            except Exception as exc:  # noqa: BLE001 — log and retry; never crash the loop
+                log.warning("websocket error: %s", exc)
+            finally:
+                self._ws = None
+            if self._closed or not self._reconnect:
+                return
+            self._dispatch("disconnect")
+            # Backoff with ±25% jitter so many clients don't reconnect in lockstep.
+            await asyncio.sleep(backoff * (0.75 + random.random() * 0.5))
+            backoff = min(backoff * 2, 30.0)
+
+    async def _resync_players(self) -> None:
+        """After a reconnect, pull each player's authoritative state from the node
+        so position/volume/paused are accurate again. Per-player failures ignored."""
+        assert self._rest is not None
+        for p in self.players():
+            try:
+                p.state = await self._rest.get_state(p.guild_id)
+            except Exception:  # noqa: BLE001 — node may have dropped it during the gap
+                pass
+
+    async def _subscribe_all(self) -> None:
+        if self._ws is not None and self._players:
+            await self._ws.send_json(
+                {"op": "SUBSCRIBE", "d": {"guilds": [str(g) for g in self._players]}}
+            )
+
+    async def _send(self, payload: dict) -> None:
+        if self._ws is not None:
+            await self._ws.send_json(payload)
+
+    async def _handle_frame(self, frame: dict) -> None:
+        op = frame.get("op")
+        d = frame.get("d", {}) or {}
+
+        if op == "HELLO":
+            interval = d.get("heartbeat_interval_ms", 30000) / 1000.0
+            self._schedule(self._heartbeat(interval))
+            return
+        if op == "READY":
+            resumed = self._has_connected
+            self._session_id = d.get("session_id")
+            self._has_connected = True
+            await self._subscribe_all()
+            if resumed:
+                # Reconnect: resync each player's live state from the node so
+                # callers see accurate position/volume/paused (a practical resume).
+                await self._resync_players()
+                self._dispatch("resumed")
+            else:
+                self._dispatch("ready")
+            return
+        if op == "HEARTBEAT_ACK":
+            if self._heartbeat_sent_at:
+                self.latency = time.monotonic() - self._heartbeat_sent_at
+            return
+        if op == "STATS":
+            self.last_stats = d
+
+        guild_id = int(d["guild_id"]) if d.get("guild_id") else None
+        player = self._players.get(guild_id) if guild_id is not None else None
+
+        if op == "TRACK_END" and player is not None:
+            reason = EndReason(d.get("reason", "FINISHED"))
+            # Drive auto-advance BEFORE notifying the user so handlers see the new state.
+            await player._on_track_end(reason.advances)
+        elif op == "PLAYER_UPDATE" and player is not None:
+            player.state = PlayerState.from_dict(d.get("state", {}))
+
+        event_name = _EVENT_OPS.get(op or "")
+        if event_name is not None:
+            self._dispatch(event_name, player or guild_id, d)
+
+    async def _heartbeat(self, interval: float) -> None:
+        seq = 0
+        while self._ws is not None and not self._closed:
+            seq += 1
+            self._heartbeat_sent_at = time.monotonic()
+            with contextlib.suppress(Exception):
+                await self._send({"op": "HEARTBEAT", "d": {"seq": seq}})
+            await asyncio.sleep(interval)

pyauralis-0.1.0/src/auralis/enums.py

@@ -0,0 +1,37 @@
+"""Enums mirroring the control-plane wire vocabulary."""
+
+from __future__ import annotations
+
+from enum import Enum
+
+
+class LoopMode(str, Enum):
+    """How the queue advances when a track finishes."""
+
+    OFF = "off"
+    TRACK = "track"  # replay the current track forever
+    QUEUE = "queue"  # loop the whole queue
+
+
+class LoadType(str, Enum):
+    """`load_type` returned by ``GET /v1/loadtracks``."""
+
+    TRACK = "track"
+    PLAYLIST = "playlist"
+    SEARCH = "search"
+    EMPTY = "empty"
+    ERROR = "error"
+
+
+class EndReason(str, Enum):
+    """Why a track ended. Only FINISHED / LOAD_FAILED advance the queue."""
+
+    FINISHED = "FINISHED"
+    LOAD_FAILED = "LOAD_FAILED"
+    STOPPED = "STOPPED"
+    REPLACED = "REPLACED"
+    CLEANUP = "CLEANUP"
+
+    @property
+    def advances(self) -> bool:
+        return self in (EndReason.FINISHED, EndReason.LOAD_FAILED)