thebradleysanders/queue-the-magic repository overview

⁠🎄 QueueTheMagic

A real-time holiday light show song request and donation platform.

QueueTheMagic lets visitors request songs, donate, and interact with your light show in real time. It integrates directly with Falcon Player (FPP) to control playback, while a default playlist keeps your show running between requests.

Perfect for Christmas light displays, fundraisers, and interactive neighborhood shows.

Built by Brad Sanders⁠

⁠✨ Why QueueTheMagic?

If you run a holiday light show, you’ve probably heard:

• “How can I donate?”
• “Where can I see the song list or hours?”
• “Can you play that song from last year again?”

QueueTheMagic solves all of that with a simple, self-hosted web app accessible via:

• QR codes (yard signs, flyers)
• Social media links
• Direct URL

⁠🚀 Features

• 🎵 Song request queue with Stripe payments ($1+ per request)
• ⏫ Queue bumping via additional donations
• ❤️ “Just Because” donations (no song required)
• 🔄 Live queue updates via SignalR (WebSockets)
• 🎛️ Direct FPP integration (controls playback automatically)
• 📅 Weekly show schedule
• ❄️ Season toggle with custom off-season message
• ⭐ Song ratings + admin reporting
• 🛠️ Admin dashboard
  • Live queue management
  • Configuration
  • Reports & diagnostics
• 📡 MQTT integration (optional)
• 🌙 Light/Dark mode
• 📱 Mobile-first responsive UI

⁠🐳 Quick Start (Docker)

⁠Prerequisites

• Docker + Docker Compose
• Stripe account (test keys work fine)
• Falcon Player (FPP) on your network

⁠1. Create docker-compose.yml

services:
  app:
    image: thebradleysanders/queuethemagic:latest
    container_name: qtm
    ports:
      - "80:80"
    environment:
      - Stripe__SecretKey=sk_live_...
      - Stripe__PublishableKey=pk_live_...
      - AdminPassword=your-secure-password
      - Jwt__Secret=change-this-to-a-long-random-string-min-32-chars
      - AllowedOrigins=http://your-server-ip
    volumes:
      - qtm-data:/app/data
    restart: unless-stopped

volumes:
  qtm-data:
    name: qtm-data