openplugdj 1.0.1 → 1.0.3

package/README.md

@@ -0,0 +1,337 @@
+# OpenPlugDJ
+
+[![npm version](https://img.shields.io/npm/v/openplugdj.svg)](https://www.npmjs.com/package/openplugdj)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+A lightweight, event-driven DJ queue and room engine inspired by plug.dj. Build collaborative music listening experiences with real-time queue management, voting, and multiple room support.
+
+## Features
+
+- 🎵 **Queue Management** - Add, remove, and reorder tracks in a DJ queue
+- 🏠 **Multi-Room Support** - Create and manage multiple music rooms
+- 👥 **User Management** - Handle users with different roles (listener, DJ, admin)
+- 🗳️ **Voting System** - Built-in upvote/downvote functionality for tracks
+- 📦 **Flexible Storage** - Memory or Redis-backed storage adapters
+- 🔌 **Event-Driven** - React to track changes, votes, and queue updates
+- 🎯 **TypeScript First** - Full type safety and IntelliSense support
+- 🪶 **Lightweight** - Minimal dependencies, maximum performance
+
+## Installation
+
+```bash
+npm install openplugdj
+```
+
+For Redis support:
+```bash
+npm install openplugdj ioredis
+```
+
+## Quick Start
+
+```typescript
+import { DJ, Room, Track, DJEntry } from "openplugdj";
+
+// Create a custom stream service (implement your audio logic)
+const streamService = {
+  async play(track: Track) {
+    console.log(`Playing: ${track.title}`);
+    // Your audio streaming logic here
+    await new Promise(resolve => setTimeout(resolve, track.duration));
+  },
+  async stop() {
+    console.log("Stopped playback");
+  }
+};
+
+// Initialize the DJ engine
+const dj = new DJ(streamService);
+
+// Create a room
+const room = dj.createRoom("room-1");
+
+// Add a user
+room.addUser({
+  id: "user-1",
+  username: "DJ Cool",
+  role: "dj",
+  joinedAt: Date.now()
+});
+
+// Add a track to the queue
+const entry: DJEntry = {
+  id: "entry-1",
+  track: {
+    id: "track-1",
+    title: "Awesome Song",
+    url: "https://example.com/song.mp3",
+    duration: 180000, // 3 minutes in milliseconds
+    addedBy: "user-1",
+    createdAt: Date.now()
+  },
+  userId: "user-1",
+  position: 0,
+  createdAt: Date.now()
+};
+
+room.addEntry(entry);
+
+// Listen to events
+room.on("trackStart", (track) => {
+  console.log(`Now playing: ${track.title}`);
+});
+
+room.on("trackEnd", (track) => {
+  console.log(`Finished: ${track.title}`);
+});
+
+room.on("voteUpdated", (votes) => {
+  console.log(`Votes: ${votes.up} up, ${votes.down} down`);
+});
+
+// Start playback
+room.start();
+```
+
+## Core Concepts
+
+### DJ
+
+The main engine that manages multiple rooms.
+
+```typescript
+import { DJ } from "openplugdj";
+
+const dj = new DJ(streamService);
+
+// Create rooms
+const room1 = dj.createRoom("rock-room");
+const room2 = dj.createRoom("jazz-room");
+
+// Get a room
+const room = dj.getRoom("rock-room");
+
+// Delete a room
+dj.deleteRoom("rock-room");
+
+// Listen to room events
+dj.on("roomCreated", (room) => {
+  console.log(`Room created: ${room.id}`);
+});
+```
+
+### Room
+
+A room contains a queue, player, and manages users.
+
+```typescript
+// Add users
+room.addUser(user);
+room.removeUser(userId);
+
+// Access the queue
+room.queue.add(entry);
+room.queue.remove(entryId);
+room.queue.reorder(0, 2); // Move from index 0 to index 2
+const allEntries = room.queue.getAll();
+
+// Player controls
+room.player.skip(); // Skip current track
+room.player.vote(userId, "up"); // Vote on current track
+const current = room.player.getCurrent();
+
+// Events
+room.on("userJoined", (user) => {});
+room.on("userLeft", (user) => {});
+room.on("queueUpdated", (entries) => {});
+room.on("trackStart", (track) => {});
+room.on("trackEnd", (track) => {});
+room.on("voteUpdated", (results) => {});
+room.on("queueEmpty", () => {});
+```
+
+### StreamService
+
+Implement this interface to connect your audio streaming logic:
+
+```typescript
+import { StreamService, Track } from "openplugdj";
+
+class MyStreamService implements StreamService {
+  async play(track: Track): Promise<void> {
+    // Start streaming the track
+    // Wait for track.duration milliseconds or until stop() is called
+  }
+
+  async stop(): Promise<void> {
+    // Stop current playback
+  }
+}
+```
+
+### Storage Adapters
+
+Choose between in-memory or Redis storage:
+
+```typescript
+import { MemoryStore, RedisStore } from "openplugdj";
+
+// In-memory (default)
+const memoryStore = new MemoryStore<Room>();
+
+// Redis
+const redisStore = new RedisStore<Room>(
+  "redis://localhost:6379",
+  "rooms" // namespace
+);
+
+// Use with custom storage
+await redisStore.set("room-1", room);
+const room = await redisStore.get("room-1");
+```
+
+## API Reference
+
+### Types
+
+#### Track
+```typescript
+interface Track {
+  id: string;
+  title: string;
+  url: string;
+  duration: number; // milliseconds
+  addedBy: string;
+  createdAt: number;
+}
+```
+
+#### User
+```typescript
+type UserRole = "listener" | "dj" | "admin";
+
+interface User {
+  id: string;
+  username: string;
+  role: UserRole;
+  joinedAt: number;
+}
+```
+
+#### DJEntry
+```typescript
+interface DJEntry {
+  id: string;
+  track: Track;
+  userId: string;
+  position: number;
+  createdAt: number;
+}
+```
+
+## Advanced Usage
+
+### Using Redis for Persistence
+
+```typescript
+import { DJ, RedisStore, Room } from "openplugdj";
+
+const dj = new DJ(streamService);
+const roomStore = new RedisStore<Room>("redis://localhost:6379", "rooms");
+
+// Your rooms persist across restarts
+const room = dj.createRoom("persistent-room");
+await roomStore.set(room.id, room);
+```
+
+### Vote Management
+
+```typescript
+// Users can vote on the current track
+room.player.vote("user-1", "up");
+room.player.vote("user-2", "down");
+
+room.on("voteUpdated", (results) => {
+  console.log(`Score: ${results.up - results.down}`);
+  
+  // Auto-skip if too many downvotes
+  if (results.down > 5) {
+    room.player.skip();
+  }
+});
+```
+
+### Queue Management
+
+```typescript
+// Add multiple tracks
+const entries = [entry1, entry2, entry3];
+entries.forEach(entry => room.queue.add(entry));
+
+// Reorder queue (drag and drop)
+room.queue.reorder(0, 2);
+
+// Remove a track
+room.queue.remove(entryId);
+
+// Clear entire queue
+room.queue.clear();
+
+// Get queue info
+console.log(`Queue size: ${room.queue.size()}`);
+```
+
+## Examples
+
+Check out these example implementations:
+
+- **Simple Bot** - Basic DJ bot with preset playlist
+- **Web Server** - Express + Socket.IO integration
+- **Discord Bot** - Voice channel music bot
+- **REST API** - Full-featured API backend
+
+See the `/examples` directory in the repository.
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -m 'Add some amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request
+
+## License
+
+MIT © [bulondra](https://github.com/bulondra)
+
+## Links
+
+- [GitHub Repository](https://github.com/bulondra/openplugdj)
+- [Issue Tracker](https://github.com/bulondra/openplugdj/issues)
+- [npm Package](https://www.npmjs.com/package/openplugdj)
+
+## Support
+
+If you find this project helpful, please consider giving it a ⭐ on GitHub!
+
+### Error Handling
+
+All errors are emitted via the `error` event:
+
+```typescript
+room.on("error", (error) => {
+  console.error(`[${error.type}]:`, error.error.message);
+  
+  if (error.track) {
+    console.error(`Track: ${error.track.title}`);
+  }
+  
+  // Error types:
+  // - "stream": Audio streaming failed
+  // - "vote": Voting failed
+  // - "skip": Skip operation failed
+  // - "metadata": Metadata fetching failed
+  // - "storage": Storage operation failed
+});

package/dist/core/Player.d.ts

@@ -8,9 +8,11 @@ export declare class Player extends EventEmitter {
     private current;
     private voteService;
     private playing;
+    private abortController;
     constructor(queue: Queue, streamService: StreamService);
     playNext(): Promise<void>;
     vote(userId: string, type: "up" | "down"): void;
-    skip(): void;
+    skip(): Promise<void>;
     getCurrent(): DJEntry | null;
+    isPlaying(): boolean;
 }

package/dist/core/Player.js

@@ -11,6 +11,7 @@ class Player extends events_1.EventEmitter {
         this.current = null;
         this.voteService = new VoteService_1.VoteService();
         this.playing = false;
+        this.abortController = null;
     }
     async playNext() {
         if (this.playing)
@@ -23,23 +24,68 @@ class Player extends events_1.EventEmitter {
         this.current = entry;
         this.voteService.clear();
         this.playing = true;
+        this.abortController = new AbortController();
         this.emit("trackStart", entry.track);
-        await this.streamService.play(entry.track);
-        this.emit("trackEnd", entry.track);
-        this.playing = false;
+        try {
+            await this.streamService.play(entry.track);
+            // Check if we were cancelled during playback
+            if (this.abortController.signal.aborted) {
+                return;
+            }
+            this.emit("trackEnd", entry.track);
+        }
+        catch (error) {
+            this.emit("error", {
+                type: "stream",
+                track: entry.track,
+                error: error instanceof Error ? error : new Error(String(error))
+            });
+        }
+        finally {
+            this.playing = false;
+            this.abortController = null;
+        }
+        // Continue to next track (recursive call happens after cleanup)
         this.playNext();
     }
     vote(userId, type) {
-        this.voteService.vote(userId, type);
-        this.emit("voteUpdated", this.voteService.getResults());
+        try {
+            this.voteService.vote(userId, type);
+            this.emit("voteUpdated", this.voteService.getResults());
+        }
+        catch (error) {
+            this.emit("error", {
+                type: "vote",
+                error: error instanceof Error ? error : new Error(String(error))
+            });
+        }
     }
-    skip() {
-        this.streamService.stop();
+    async skip() {
+        if (!this.playing)
+            return;
+        // Signal cancellation
+        if (this.abortController) {
+            this.abortController.abort();
+        }
+        try {
+            await this.streamService.stop();
+        }
+        catch (error) {
+            this.emit("error", {
+                type: "skip",
+                error: error instanceof Error ? error : new Error(String(error))
+            });
+        }
         this.playing = false;
+        this.abortController = null;
+        // Continue to next track
         this.playNext();
     }
     getCurrent() {
         return this.current;
     }
+    isPlaying() {
+        return this.playing;
+    }
 }
 exports.Player = Player;

package/dist/core/Queue.js

@@ -15,6 +15,16 @@ class Queue {
         this.entries = this.entries.filter(e => e.id !== entryId);
     }
     reorder(from, to) {
+        // Validate bounds
+        if (from < 0 || from >= this.entries.length) {
+            throw new Error(`Invalid 'from' index: ${from}. Queue length: ${this.entries.length}`);
+        }
+        if (to < 0 || to >= this.entries.length) {
+            throw new Error(`Invalid 'to' index: ${to}. Queue length: ${this.entries.length}`);
+        }
+        if (from === to) {
+            return; // No-op
+        }
         const [item] = this.entries.splice(from, 1);
         this.entries.splice(to, 0, item);
     }

package/dist/core/Room.d.ts

@@ -14,4 +14,5 @@ export declare class Room extends EventEmitter {
     removeUser(userId: string): void;
     addEntry(entry: DJEntry): void;
     start(): void;
+    getUsers(): User[];
 }

package/dist/core/Room.js

@@ -15,6 +15,7 @@ class Room extends events_1.EventEmitter {
         this.player.on("trackEnd", t => this.emit("trackEnd", t));
         this.player.on("voteUpdated", v => this.emit("voteUpdated", v));
         this.player.on("queueEmpty", () => this.emit("queueEmpty"));
+        this.player.on("error", e => this.emit("error", e));
     }
     addUser(user) {
         this.users.set(user.id, user);
@@ -28,11 +29,22 @@ class Room extends events_1.EventEmitter {
         this.emit("userLeft", user);
     }
     addEntry(entry) {
-        this.queue.add(entry);
-        this.emit("queueUpdated", this.queue.getAll());
+        try {
+            this.queue.add(entry);
+            this.emit("queueUpdated", this.queue.getAll());
+        }
+        catch (error) {
+            this.emit("error", {
+                type: "storage",
+                error: error instanceof Error ? error : new Error(String(error))
+            });
+        }
     }
     start() {
         this.player.playNext();
     }
+    getUsers() {
+        return Array.from(this.users.values());
+    }
 }
 exports.Room = Room;

package/dist/events/EventTypes.d.ts

@@ -10,6 +10,12 @@ export interface RoomEvents {
     voteUpdated: (votes: {
         up: number;
         down: number;
+        total: number;
     }) => void;
     queueEmpty: () => void;
+    error: (error: {
+        type: "stream" | "vote" | "skip" | "metadata" | "storage";
+        error: Error;
+        track?: Track;
+    }) => void;
 }

package/package.json

@@ -1,19 +1,30 @@
 {
   "name": "openplugdj",
-  "version": "1.0.1",
+  "version": "1.0.3",
   "description": "A lightweight DJ queue and room engine inspired by plug.dj",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "exports": {
     ".": "./dist/index.js"
   },
-  "files": ["dist", "README.md", "LICENSE", "package.json"],
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "package.json"
+  ],
   "scripts": {
     "build": "tsc",
     "dev": "tsc -w",
     "prepublishOnly": "npm run build"
   },
-  "keywords": ["dj", "queue", "music", "room", "realtime"],
+  "keywords": [
+    "dj",
+    "queue",
+    "music",
+    "room",
+    "realtime"
+  ],
   "author": "bulondra",
   "license": "MIT",
   "dependencies": {
@@ -23,5 +34,13 @@
     "@types/node": "^25.2.3",
     "typescript": "^5.5.3"
   },
-  "private": false
-}
+  "private": false,
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/bulondra/openplugdj.git"
+  },
+  "bugs": {
+    "url": "https://github.com/bulondra/openplugdj/issues"
+  },
+  "homepage": "https://github.com/bulondra/openplugdj#readme"
+}