auris-core 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rishi Bhardwaj / Omnikon
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,155 @@
+<div align="center">
+  <h1>Auris</h1>
+  <p><strong>A self-hosted, legally-clean music bot library for discord.js.</strong></p>
+  <p><i>Code. Create. Conquer. — Brought to you by Omnikon</i></p>
+
+  <p>
+    <a href="https://github.com/Omnikon-Org/Auris/actions"><img src="https://img.shields.io/github/actions/workflow/status/Omnikon-Org/Auris/ci.yml?branch=main" alt="Build Status" /></a>
+    <a href="https://www.npmjs.com/package/@omnikon/auris"><img src="https://img.shields.io/npm/v/@omnikon/auris.svg" alt="npm version" /></a>
+    <a href="https://www.npmjs.com/package/@omnikon/auris"><img src="https://img.shields.io/npm/dt/@omnikon/auris.svg" alt="npm downloads" /></a>
+    <a href="https://github.com/Omnikon-Org/Auris/blob/main/LICENSE"><img src="https://img.shields.io/npm/l/@omnikon/auris.svg" alt="License" /></a>
+    <img src="https://img.shields.io/badge/TypeScript-Ready-blue.svg" alt="TypeScript Ready" />
+  </p>
+</div>
+
+---
+
+## 🛑 The Problem: Why not YouTube?
+
+Most Discord music bots scrape YouTube audio, violating YouTube's Terms of Service. This gets bots DMCA'd, IP-blocked, or banned completely. Existing alternatives are either abandoned or rely on fragile scraper libraries like `ytdl-core`.
+
+**`Auris`** solves this by providing a robust, legal-only audio pipeline. Built from the ground up without YouTube scraping, this library guarantees peace of mind while delivering a high-quality, feature-rich audio experience for your users.
+
+---
+
+## ✨ Features
+
+- 🎵 **Legally Safe Audio Sources**: Native support for safe, authorized streaming.
+  - **Local Files**: Play MP3, OGG, WAV, and FLAC directly from your server.
+  - **Direct URLs**: Stream from any directly hosted audio file.
+  - **Jamendo API**: Access thousands of royalty-free / Creative Commons tracks.
+  - **SoundCloud API**: Stream officially permitted tracks from SoundCloud.
+- 🔌 **BYO Adapter System**: Easily integrate your own licensed catalog or corporate library using our simple 2-method interface.
+- 🔁 **Robust Playback Engine**: Complete queue management with Loop (Track/Queue), Skip, Pause/Resume, and granular Volume control.
+- ⚙️ **Smart Voice Management**: Automatically reconnects on network drops and gracefully disconnects when inactive or alone.
+- ⚡ **Modern Architecture**: Written in strict TypeScript, exporting both ESM and CommonJS for seamless integration in any Node environment.
+
+---
+
+## 🛠 Installation
+
+### 1. Prerequisites
+- **Node.js**: v18.0.0 or higher.
+- **FFmpeg**: *Required for audio processing.*
+  - **Ubuntu/Debian:** `sudo apt install ffmpeg`
+  - **MacOS:** `brew install ffmpeg`
+  - **Windows:** Download from [ffmpeg.org](https://ffmpeg.org/download.html) and add to PATH.
+
+### 2. Install Package
+```bash
+npm install @omnikon/auris discord.js @discordjs/voice libsodium-wrappers
+```
+
+---
+
+## 🚀 Quickstart (Under 10 Lines)
+
+Integrate music into your existing `discord.js` bot instantly:
+
+```typescript
+import { Client, GatewayIntentBits } from 'discord.js';
+import { Player, LocalFileAdapter } from '@omnikon/auris';
+
+const client = new Client({ intents: [GatewayIntentBits.Guilds, GatewayIntentBits.GuildVoiceStates] });
+const player = new Player();
+const localAdapter = new LocalFileAdapter();
+
+player.registerAdapter(localAdapter);
+
+// Inside your command execution block:
+await player.connect(interaction.member.voice.channel);
+const track = await localAdapter.getTrack('./assets/music/track.mp3');
+await player.play(track);
+```
+
+---
+
+## 🔌 Supported Adapters
+
+| Adapter | Description | Setup |
+|---------|-------------|-------|
+| **LocalFileAdapter** | Plays audio from your local filesystem. | `new LocalFileAdapter()` |
+| **DirectUrlAdapter** | Streams audio directly from an HTTP URL. | `new DirectUrlAdapter()` |
+| **JamendoAdapter** | Searches and streams from Jamendo API. | `new JamendoAdapter('YOUR_CLIENT_ID')` |
+| **SoundCloudAdapter** | Streams permitted tracks from SoundCloud. | `new SoundCloudAdapter('YOUR_CLIENT_ID')` |
+
+---
+
+## 📖 API Reference
+
+### `Player` Class
+The core queue and playback manager.
+
+#### Connection & Playback
+- **`connect(channel: VoiceBasedChannel)`**: Joins the voice channel and prepares playback.
+- **`disconnect()`**: Gracefully leaves the voice channel and flushes the queue.
+- **`play(track: Track | Track[])`**: Appends track(s) to the queue and starts playing if idle.
+- **`pause()` / `resume()`**: Toggles playback state.
+- **`skip()`**: Skips the currently playing track.
+- **`stop()`**: Halts playback entirely and clears the queue.
+
+#### Controls
+- **`setVolume(level: number)`**: Adjusts the volume between `0` and `200`.
+- **`setLoopMode(mode: LoopMode)`**: Sets looping behavior.
+  - `LoopMode.OFF`
+  - `LoopMode.TRACK`
+  - `LoopMode.QUEUE`
+
+#### State & Events
+- **`getQueue(): Track[]`**: Returns the pending tracks.
+- **`getCurrentTrack(): Track | null`**: Returns the active track.
+
+The `Player` emits standard events you can hook into for logging or sending Discord embeds:
+```typescript
+player.on('trackStart', (track) => console.log(`Now playing: ${track.title}`));
+player.on('trackEnd', (track) => console.log(`Finished: ${track.title}`));
+player.on('queueEnd', () => console.log(`Queue empty!`));
+```
+
+---
+
+## 🧑‍💻 Running the Example Bot
+
+We've provided a fully functioning Discord bot showcasing all slash commands (`/play`, `/pause`, `/skip`, `/loop`, `/queue`, `/volume`).
+
+1. Clone the repository.
+2. Run `npm install`.
+3. Copy `examples/bot/.env.example` to `examples/bot/.env`.
+4. Configure your `.env` file:
+   
+   **Required:**
+   - `DISCORD_TOKEN`: Your Discord bot token.
+
+   **Optional:**
+   - `JAMENDO_CLIENT_ID`: Enables the Jamendo adapter.
+   - `SOUNDCLOUD_CLIENT_ID`: Enables the SoundCloud adapter.
+
+   *Note: Without these optional credentials, the bot still fully supports all core playback features (Local Files, Direct URLs, Queueing, Pausing, etc.). Jamendo and SoundCloud will simply be disabled gracefully.*
+
+5. Start the bot:
+   ```bash
+   npm run dev:example
+   ```
+6. Invite the bot to your server and type `/play` in any channel!
+
+---
+
+<div align="center">
+  <p><strong>Part of the Omnikon Ecosystem</strong></p>
+  <p>
+    <a href="https://github.com/Omnikon-Org/schema-cast">schema-cast</a> • 
+    <a href="https://github.com/Omnikon-Org/PackVault">PackVault</a> • 
+    <a href="https://github.com/Omnikon-Org/IssueSwipe">IssueSwipe</a> • 
+    <a href="https://github.com/Omnikon-Org/Abyss">Abyss</a>
+  </p>
+</div>

package/dist/index.d.mts

@@ -0,0 +1,111 @@
+import * as stream from 'stream';
+import { VoiceConnection, AudioPlayer, AudioResource } from '@discordjs/voice';
+import { EventEmitter } from 'events';
+import { VoiceBasedChannel } from 'discord.js';
+import * as fs from 'fs';
+
+interface Track {
+    title: string;
+    url: string;
+    duration?: number;
+    source: string;
+    thumbnail?: string;
+    author?: string;
+    adapterKey: string;
+}
+interface AudioSource {
+    name: string;
+    getTrack(query: string): Promise<Track | Track[] | null>;
+    getStream(track: Track): Promise<string | stream.Readable>;
+}
+declare enum LoopMode {
+    OFF = 0,
+    TRACK = 1,
+    QUEUE = 2
+}
+interface PlayerEvents {
+    trackStart: (track: Track) => void;
+    trackEnd: (track: Track) => void;
+    queueEnd: () => void;
+    error: (error: Error) => void;
+    disconnect: () => void;
+}
+
+declare class VoiceConnectionManager {
+    connection: VoiceConnection | null;
+    channelId: string | null;
+    guildId: string | null;
+    private timeoutId;
+    private readonly timeoutMs;
+    constructor(timeoutMs?: number);
+    connect(channel: VoiceBasedChannel): Promise<VoiceConnection>;
+    subscribe(player: AudioPlayer): void;
+    destroy(): void;
+    startAloneTimeout(onTimeout: () => void): void;
+    stopAloneTimeout(): void;
+}
+
+declare class Player extends EventEmitter {
+    queue: Track[];
+    loopMode: LoopMode;
+    volume: number;
+    isPlaying: boolean;
+    audioPlayer: AudioPlayer;
+    currentResource: AudioResource | null;
+    connectionManager: VoiceConnectionManager;
+    private adapters;
+    private currentTrack;
+    private debugInterval;
+    constructor(timeoutMs?: number);
+    registerAdapter(adapter: AudioSource): void;
+    connect(channel: VoiceBasedChannel): Promise<void>;
+    disconnect(): void;
+    play(trackOrTracks: Track | Track[]): Promise<void>;
+    private processQueue;
+    pause(): void;
+    resume(): void;
+    skip(): void;
+    stop(): void;
+    setVolume(volume: number): void;
+    setLoopMode(mode: LoopMode): void;
+    getQueue(): Track[];
+    getCurrentTrack(): Track | null;
+}
+interface Player {
+    on<K extends keyof PlayerEvents>(event: K, listener: PlayerEvents[K]): this;
+    once<K extends keyof PlayerEvents>(event: K, listener: PlayerEvents[K]): this;
+    emit<K extends keyof PlayerEvents>(event: K, ...args: Parameters<PlayerEvents[K]>): boolean;
+}
+
+declare class LocalFileAdapter implements AudioSource {
+    name: string;
+    getTrack(query: string): Promise<Track | null>;
+    getStream(track: Track): Promise<fs.ReadStream>;
+}
+
+declare class DirectUrlAdapter implements AudioSource {
+    name: string;
+    getTrack(query: string): Promise<Track | null>;
+    getStream(track: Track): Promise<string>;
+}
+
+declare class JamendoAdapter implements AudioSource {
+    name: string;
+    private clientId;
+    constructor(clientId: string);
+    getTrack(query: string): Promise<Track | Track[] | null>;
+    private fetchTrackById;
+    private searchTrack;
+    getStream(track: Track): Promise<string>;
+}
+
+declare class SoundCloudAdapter implements AudioSource {
+    name: string;
+    private clientId;
+    constructor(clientId: string);
+    getTrack(query: string): Promise<Track | null>;
+    private mapTrack;
+    getStream(track: Track): Promise<any>;
+}
+
+export { type AudioSource, DirectUrlAdapter, JamendoAdapter, LocalFileAdapter, LoopMode, Player, type PlayerEvents, SoundCloudAdapter, type Track, VoiceConnectionManager };

package/dist/index.d.ts

@@ -0,0 +1,111 @@
+import * as stream from 'stream';
+import { VoiceConnection, AudioPlayer, AudioResource } from '@discordjs/voice';
+import { EventEmitter } from 'events';
+import { VoiceBasedChannel } from 'discord.js';
+import * as fs from 'fs';
+
+interface Track {
+    title: string;
+    url: string;
+    duration?: number;
+    source: string;
+    thumbnail?: string;
+    author?: string;
+    adapterKey: string;
+}
+interface AudioSource {
+    name: string;
+    getTrack(query: string): Promise<Track | Track[] | null>;
+    getStream(track: Track): Promise<string | stream.Readable>;
+}
+declare enum LoopMode {
+    OFF = 0,
+    TRACK = 1,
+    QUEUE = 2
+}
+interface PlayerEvents {
+    trackStart: (track: Track) => void;
+    trackEnd: (track: Track) => void;
+    queueEnd: () => void;
+    error: (error: Error) => void;
+    disconnect: () => void;
+}
+
+declare class VoiceConnectionManager {
+    connection: VoiceConnection | null;
+    channelId: string | null;
+    guildId: string | null;
+    private timeoutId;
+    private readonly timeoutMs;
+    constructor(timeoutMs?: number);
+    connect(channel: VoiceBasedChannel): Promise<VoiceConnection>;
+    subscribe(player: AudioPlayer): void;
+    destroy(): void;
+    startAloneTimeout(onTimeout: () => void): void;
+    stopAloneTimeout(): void;
+}
+
+declare class Player extends EventEmitter {
+    queue: Track[];
+    loopMode: LoopMode;
+    volume: number;
+    isPlaying: boolean;
+    audioPlayer: AudioPlayer;
+    currentResource: AudioResource | null;
+    connectionManager: VoiceConnectionManager;
+    private adapters;
+    private currentTrack;
+    private debugInterval;
+    constructor(timeoutMs?: number);
+    registerAdapter(adapter: AudioSource): void;
+    connect(channel: VoiceBasedChannel): Promise<void>;
+    disconnect(): void;
+    play(trackOrTracks: Track | Track[]): Promise<void>;
+    private processQueue;
+    pause(): void;
+    resume(): void;
+    skip(): void;
+    stop(): void;
+    setVolume(volume: number): void;
+    setLoopMode(mode: LoopMode): void;
+    getQueue(): Track[];
+    getCurrentTrack(): Track | null;
+}
+interface Player {
+    on<K extends keyof PlayerEvents>(event: K, listener: PlayerEvents[K]): this;
+    once<K extends keyof PlayerEvents>(event: K, listener: PlayerEvents[K]): this;
+    emit<K extends keyof PlayerEvents>(event: K, ...args: Parameters<PlayerEvents[K]>): boolean;
+}
+
+declare class LocalFileAdapter implements AudioSource {
+    name: string;
+    getTrack(query: string): Promise<Track | null>;
+    getStream(track: Track): Promise<fs.ReadStream>;
+}
+
+declare class DirectUrlAdapter implements AudioSource {
+    name: string;
+    getTrack(query: string): Promise<Track | null>;
+    getStream(track: Track): Promise<string>;
+}
+
+declare class JamendoAdapter implements AudioSource {
+    name: string;
+    private clientId;
+    constructor(clientId: string);
+    getTrack(query: string): Promise<Track | Track[] | null>;
+    private fetchTrackById;
+    private searchTrack;
+    getStream(track: Track): Promise<string>;
+}
+
+declare class SoundCloudAdapter implements AudioSource {
+    name: string;
+    private clientId;
+    constructor(clientId: string);
+    getTrack(query: string): Promise<Track | null>;
+    private mapTrack;
+    getStream(track: Track): Promise<any>;
+}
+
+export { type AudioSource, DirectUrlAdapter, JamendoAdapter, LocalFileAdapter, LoopMode, Player, type PlayerEvents, SoundCloudAdapter, type Track, VoiceConnectionManager };