RadioQueue - WordPress Music Queue Management Plugin

A WordPress plugin to manage a queue of requested music tracks, simulating a live, automated online radio station. This plugin provides a complete ecosystem for users to log in, for administrators to manage the queue, and for displaying the live status on the frontend.

Features

This plugin is packed with a robust set of features, turning a standard WordPress site into an automated music queue management system.

Core Functionality

• Custom Post Type (rq_track): A dedicated post type for managing tracks with essential metadata like Artist, Title, Duration, Requester's Email, Status, and a dynamic Priority Score.
• Custom Taxonomy (rq_artist): Manages artists in a structured way to prevent duplicates and allow for easy filtering.

Intelligent Queue & Playback Management

• Automated Server-Side Playback: A smart, "lazy evaluation" playback system that ensures the music queue progresses automatically and accurately, independent of cron jobs or site traffic. The queue state is calculated and updated on-the-fly whenever it's requested, creating a seamless 24/7 radio experience.
• Advanced Sorting Logic: The queue is intelligently sorted based on a multi-level criteria:
  1. Status: playing tracks are always first, followed by pending.
  2. Priority Score: Tracks with a priority score are prioritized over those without. Higher scores come first.
  3. Queue Time: For tracks with equal or no scores, the "first-in, first-out" rule applies.

Admin User Interface

• Enhanced Admin List: The rq_track list table features custom columns and is sorted by default to reflect the live queue position, giving admins an immediate and accurate overview.
• Custom Roles & Capabilities:
  • Adds a new Radio DJ role with specific permissions to manage the queue.
  • Introduces a manage_radioqueue capability, ensuring only authorized users (like Administrators and Radio DJs) can access sensitive features.

Background & External Services

• Optional Priority Scoring: A background job (WP-Cron) runs every 5 minutes to fetch a priority_score from a simulated external UDP service (rq_oracle). The plugin is designed to function perfectly even if this service is unavailable, falling back to time-based queuing.

Frontend Integration

• Dynamic Elementor Widget: A live "Radio Queue" widget displays the "Now Playing" track and the "Up Next" list. It uses AJAX to refresh its content every 10 seconds without page reloads.
• DJ Controls: Logged-in users with the manage_radioqueue capability see a "Play Next" button on the widget, allowing for manual override of the automated playback.
• OTP Login/Registration Shortcode: A [radio_queue_login] shortcode provides a secure, passwordless login and registration system using one-time codes sent via email. New users are automatically assigned the Radio DJ role.

API & Reporting

• REST API Endpoint: A secure GET /wp-json/rq/v1/summary endpoint provides daily statistics, including total requests, average wait time, and the top 3 tracks with the longest wait. Access is restricted to users with the manage_radioqueue capability.

Development & Quality

• Modern PHP & PSR-4: Built with clean, object-oriented PHP and organized according to the PSR-4 autoloading standard.
• Comprehensive Unit Tests: Includes a full suite of PHPUnit tests covering core logic, roles, cron jobs, and admin sorting to ensure stability and reliability.
• Secure & Optimized: Adheres to WordPress best practices for security (nonces, capability checks) and performance (assets are only loaded when their components are in use).

Installation

1. Clone or download this repository into your wp-content/plugins/ directory.
2. Navigate to the plugin directory via the command line: cd wp-content/plugins/radio-queue.
3. Install the required PHP dependencies (like PHPUnit) by running: composer install.
4. Activate the "RadioQueue" plugin through the WordPress admin panel.
5. Upon activation, the plugin automatically sets up the required custom roles and capabilities.

How to Use

1. Managing the Music Queue (Admin)

• A new menu item "Radio Queue" will appear in your admin dashboard.
• Add Artists: Go to Radio Queue -> Artists to add artists. This is recommended before adding tracks.
• Add Tracks: Go to Radio Queue -> Add New.
  • Enter the track title.
  • In the "Track Details" box, select an Artist.
  • Crucially, set a Duration (ms) (e.g., 180000 for 3 minutes). The automated playback system relies on this value.
  • Set the Status to pending.
• View the Queue: Go to Radio Queue -> All Tracks. The list is automatically sorted in the exact order of playback. The "Position / Score" column shows the priority score that influences this order.

2. (Optional) Running the Priority Score Service

The plugin works perfectly without this, using time-based queuing. To enable priority scores:

1. Navigate to the directory where you have placed the rq_oracle_server.php file.
2. Run the following command in a terminal and leave it running in the background:

   php rq_oracle_server.php

3. The plugin's background job will now automatically contact this service to update priority scores for pending tracks.

3. Displaying the Live Queue on the Frontend

• Edit any page or post with Elementor.
• In the widgets panel, search for "Radio Queue".
• Drag and drop the widget into your page. It will automatically display the live queue and update every 10 seconds.
• Users with "Administrator" or "Radio DJ" roles will see a "Play Next" button for manual control.

4. Using the OTP Login Form

• Create a new page (e.g., "Login").
• In the page editor, add the following shortcode to the content:

  [radio_queue_login]

• Save and view the page. A two-step login/registration form will be displayed. New users who sign up via this form will automatically be given the "Radio DJ" role.

5. Accessing the REST API for Reports

You can get daily queue summaries using a REST client like cURL. Access is restricted, so you must first authenticate.

Example using cURL:

# 1. Get an authentication token (requires a plugin like "JWT Authentication for WP REST API")
TOKEN=$(curl -s -X POST "http://your-site.local/wp-json/jwt-auth/v1/token" -d "username=your_admin_user" -d "password=your_password" | jq -r .token)

# 2. Make an authenticated request to the summary endpoint for a specific day
curl -X GET "http://your-site.local/wp-json/rq/v1/summary?day=2025-10-14" \
     -H "Authorization: Bearer $TOKEN"