Masterman Studios | System Manual

System Overview

What is the DJ Request System?

The Masterman Studios DJ Request System is a real-time, cloud-based song request platform. Guests submit requests from any device. DJs manage an instant-updating queue. Everything syncs live with no page refresh required.

Clientside.html

Guest-facing request portal. Any phone or tablet.

VIP.html

Priority request portal for authorized VIP accounts.

Admin.html

Mobile admin panel. Designed for booth tablets and phones.

AdminD.html

Full-featured desktop command center. Widescreen optimized.

Guest App

Clientside.html - the guest-facing request portal

01. Making a Request

Open Clientside.html on your phone or tablet. No app install required.

Type the Song Name and Artist. Both fields are required.

Optionally add your Name and Shoutout in the Personalize section.

Tap Send Request. Added to the DJ's live queue immediately.

🛡 Security Check - A silent Cloudflare Turnstile check runs automatically. No guest action needed. The form is gated until it passes.

⚠ Duplicate Prevention - If the same song was requested in the last 30 minutes, submission is blocked with an alert.

⏱ Request Cooldown - After submitting, the button shows a 2-minute countdown. Persists across page refreshes to prevent spam.

⚠ If the request form is not visible - the DJ has temporarily closed requests. A 🔒 Requests Paused message will appear.

02. Live Status Tracking

After sending a request, a real-time status indicator appears below the form.

Request Pending - Your request is in the queue, waiting for the DJ.

✅

Request Accepted! - The DJ has confirmed your song. Get ready to dance.

💡 Your request status is remembered in your browser session.

03. DJ Lineup (Up Next)

When the DJ enables Guest Lineup, an Up Next section appears at the top of the page.

✦ This lineup is controlled entirely by the DJ.

04. Song Autocomplete

When autocomplete is enabled, typing shows a live dropdown of matching tracks with album art.

Suggestion mode - Dropdown appears as you type. Click a suggestion to fill both fields, or type freely.

Enforce mode - You must select a track from the list. Free text entry is disabled.

Off - No suggestions appear. The song field behaves as a standard text input.

💡 Selecting a track from autocomplete may pre-fill BPM, duration, and release year visible to the admin.

05. Trending & Public Voting

The Trending Requests section shows songs the DJ has pushed to the public vote.

💡 Voting is a one-click toggle. Each device gets one vote per song.

06. Request Filter

When the admin has configured a Request Filter (only active in Enforce autocomplete mode), your song choices are restricted to what the DJ has approved.

🔒 Artist Lock — The Artist field is pre-filled and greyed out — you cannot change it. The autocomplete only shows that artist's songs. Requests for a different artist are rejected.

★ Song Whitelist — The autocomplete only shows songs from the DJ's curated list, marked with a ★ List badge. Only these songs can be submitted — anything else is rejected.

💡 If no songs appear, try shorter search terms. In Whitelist mode, a few letters of the title is usually enough.

07. Text Moderation

When the admin has Text Moderation enabled, your Name and Shoutout fields are automatically scanned for profanity before your request is submitted.

⚠ Blocked submission - If your Name or Shoutout is flagged, you will see an error message. Edit the field and tap Send Request again.

🛡 The check uses a local word list plus the PurgoMalum API. If the API is temporarily unavailable, your request still goes through - no legitimate request is ever lost.

VIP Priority Portal

VIP.html - priority requests for authorized accounts

Accessing the VIP Portal

The VIP Access button appears on the Guest App only when VIP Mode is enabled by the DJ.

🛡 Login Security - VIP login requires a Turnstile challenge. May show a brief interactive challenge if risk is elevated.

⚠ Duplicate Prevention - Same 30-minute duplicate window applies system-wide, not just per VIP user.

⏱ VIP Cooldown - VIPs get a 1-minute cooldown vs. 2 minutes for guests. Countdown is shown live on the button.

Admin Mobile

Admin.html - booth-ready mobile management panel

Admin Mobile provides the core DJ controls in a touch-optimized layout.

System Live / Closed

Opens or closes guest requests globally.

Voting On / Off

Enables the public trending vote queue visible on Clientside.

Confirm / Delete

Confirm marks a request accepted. Delete removes it permanently.

Admin Desktop

AdminD.html - the full command center

Login & UI Selection

Enter your master admin email and password. Local preferences (theme, layout, etc.) load automatically on every login.

Left Sidebar - System Controls

The left sidebar houses all live system controls that affect guests in real time.

Venue

Venue Name

Sets the name shown on Clientside and the index page header.

Toggle

Requests Open/Closed

Toggles the guest request form on Clientside.

Toggle

Public Voting

Enables the DJ to push requests to the trending vote list.

Toggle

VIP Mode

Reveals the VIP Access button and unlocks the VIP portal.

Toggle

Guest Lineup

Controls whether the DJ Lineup section is visible to guests on Clientside.html.

Field

Background URL

Paste any direct image URL to set a custom background on Clientside and VIP pages.

⚠ Remember to Save - All left sidebar controls require clicking Save Changes to persist.

Queue Bar & Sort Controls

The queue toolbar contains sort controls that re-order requests instantly without any server round-trip.

Oldest

Default. Longest-waiting at top.

Newest

Most recently submitted shown first.

Top Voted

Sort by public upvotes, highest to lowest.

💡 Sort order is local - it does not affect what guests see.

Button

+ Add Track

A sidebar button that opens the Add Track popup. Bypasses the guest form. Only visible with the Can Add Tracks permission.

Toggle

Voting Interval

In the Request Behavior section of the sidebar. Enables a timed voting cycle with configurable 1–30 minute intervals. Note: this entire section is automatically hidden when Public Voting is turned off.

Toggle

Music Source & MusicBrainz Fallback

Moved to Local Settings drawer → Source section. Music Source selects the autocomplete API (iTunes / Deezer / Both). MusicBrainz Fallback fills missing genre or year. Never overwrites existing data.

Up Next - DJ Lineup Panel

The DJ Lineup system lets you build an ordered setlist. Two separate controls govern admin visibility and guest visibility independently.

Understanding the Two Controls

Guest Lineup (Sidebar)

Global setting. Controls guest visibility. The lineup order is saved here.

Up Next Panel (Settings)

Local setting per account. Controls admin-side panel visibility only.

Building Your Lineup

Enable the Up Next Panel in Local Settings → Layout → Up Next Panel.

Click ↑ Up Next on any request card to add it. The track disappears from the main queue to avoid duplication.

Each item shows the song, artist, and metadata pills - BPM, duration, VIP badge - at a glance.

Drag the ⠿ handle to reorder your playlist. New order saves automatically.

Click ✕ to remove a track. It returns to the main queue.

When ready, enable Guest Lineup in the sidebar and click Save Changes to publish.

Add Track Popup

The + Add Track button opens a modal to manually inject any song - no guest submission required. Useful for verbal walk-in requests or filler tracks.

Using Add Track

Click + Add Track in the left sidebar. The popup appears over the queue.

Type the Song Title. Click a suggestion to auto-fill title, artist, and metadata (BPM, duration, year).

Fill in the Artist field if not auto-populated.

Optionally enter a Requester Name. Appears in the admin queue card like any normal request.

Click Add to Requests or ↑ Add to Up Next to direct the track where you want it.

Autocorrect Toggle

Disables browser spellcheck on the song field. Useful for stylized names or foreign-language titles.

Metadata Preview

Shows BPM, duration, and release year badges when a track is selected from autocomplete.

Permission Required

Only visible with the Can Add Tracks permission. Sub-admins without it see nothing. Master Admin always has access.

Audience Polls

The poll system runs live multiple-choice votes. Requires Public Voting to be enabled. The 📊 Create Poll button sits below Add Track in the sidebar and is greyed out when voting is off.

Creating a Poll

Ensure Public Voting is on, then click 📊 Create Poll in the sidebar.

Enter a question and between 2–6 answer options.

Set a runtime (1–30 min or No Limit). Poll ends automatically when the timer expires.

Toggle Keep results visible to guests to show the final tally on Clientside after the poll closes.

If Display is enabled, toggle Show live results on Public Display to broadcast to Display.html.

Click Publish Poll. Goes live instantly on all connected guest devices.

Managing an Active Poll

Once live, the button becomes Manage Poll. The overlay shows live result bars, a countdown, and action buttons to end early or toggle Display broadcast.

Poll Ended State

Badge turns orange and pulses. All edits locked. Click New Poll in the Manage overlay to clear it.

Broadcast to Display

When Display is enabled, a prompt appears on poll end. Final results with the 🏆 winner show on Display.html until a new poll starts.

Poll History

Ended polls auto-archive to pollHistory. Last 5 shown in the Manage overlay - click to expand per-option breakdowns.

🗑 Delete Poll

Permanently removes the poll document from Firestore (votes and all). Unlike New Poll which resets to blank, this fully deletes it. Confirmation required. Cannot be undone.

💡 Guest experience - Poll card appears above the vote queue on Clientside. Before voting: plain buttons. After voting: animated bars + totals. Ended with Keep results: locked Final Results card. No poll running: dimmed Previous Poll card from last archived poll.

Request Filter

The Request Filter restricts guest song choices. Only active in Enforce autocomplete mode. Access it via the Manage button that appears in the sidebar Autocomplete section when Enforce is selected.

Filter Modes

None

Filter off. Any song in the autocomplete results is acceptable.

🔒 Artist Lock

Enter one artist name and save. The Artist field on the guest form is pre-filled and locked. Autocomplete shows only that artist's tracks. Non-matching submissions are rejected.

★ Song Whitelist

Build a list of song + artist pairs. The search field has live autocomplete (iTunes/Deezer). Click a result to add instantly, or add manually. Guest autocomplete shows only these songs with a ★ List badge.

How Filtering Works

Set Autocomplete Mode to Enforce in the left sidebar — the Manage button appears.

Click Manage next to the Mode selector to open the Request Filter modal.

Choose a tab, configure it, and click Save Filter. Settings save to Firestore and take effect on all guest devices immediately.

To disable, open the modal, select None, and save.

⚠ Enforce mode required — The Request Filter has no effect in Suggestion or Off mode. The Manage button only appears in Enforce mode.

Request Cards

Confirm

Marks the request confirmed. Guest sees ✅ Accepted in real time.

Delete

Permanently removes the request. Cannot be undone.

Add to Vote

Pushes the request to the public voting queue on Clientside.

Played

Moves the track to History. Admin stays on the current tab - the history move happens silently in the background.

↑ Up Next

Adds the track to the DJ Lineup. Card disappears from main queue to avoid duplication.

Card Indicators: ━ Gold stripe = VIP request ━ Green stripe = Confirmed ▲ count = Public vote tally ━ Orange stripe = Played

Source Button - Every card has a Source button. Opens a search popup with YouTube, Spotify, SoundCloud, Beatport, and TIDAL.

Public Display Panel

Display.html is the public-facing Now Playing screen for projection at venue scale. Launch it from Local Settings drawer → Display section using the Panel or New Window buttons.

Fullscreen

Pushes the display into true browser fullscreen. Ideal for projecting onto a venue screen.

Close

Dismisses the overlay. The underlying Display.html continues running unaffected.

Panel Mode vs Popup

Panel mode (embedded) or standalone popup. Popup mode is ideal for second monitors.

💡 Projector Setup - Open in panel mode first to verify, then Fullscreen to project. Now Playing updates in real time.

Local Settings Drawer

Open with ⚙ Settings in the top nav. Settings persist per account. Only affect the Admin Desktop view.

Theme

Default / Darker / Midnight Blue / High Contrast. Live preview on select.

Density

Compact / Comfortable / Spacious queue card spacing. Preview applies immediately.

Left Sidebar

Always visible or Start collapsed. Use collapsed on smaller screens to maximize queue space.

Up Next Panel

Enables the Up Next tab. Full-height draggable DJ lineup. Independent from guest view.

Performance Mode

Disables CSS animations. Use on low-power hardware.

Auto-Move to History

Auto-archives Played songs after a configurable delay (1–30 min). Saved per account.

Show History Panel

Adds a History tab. Toggle without losing archived data.

Source Preselection

Choose a default streaming service. Skips the picker popup and opens that service directly. Saved per account.

Content Moderation

Found in the Content Moderation section at the bottom of the Settings drawer. Enables profanity filtering on guest Name and Shoutout fields. Auto-saves to Firestore instantly - no Save click required. Only affects Clientside.html.

History System

The History system marks songs as Played and auto-archives them after a configurable delay. Keeps the active queue clean.

Played Button

Marks the song as played. Adds an orange stripe. Auto-transfers to History if Auto-Move is enabled.

Restore

In the History tab. Moves the entry back to the active queue. Useful for mistakes.

Security & Cloudflare Turnstile

The system uses Cloudflare Turnstile across all pages as a bot-protection layer.

Managed Mode

Used on all admin and VIP login forms. Widget completes automatically in most cases; may show a brief challenge if risk is elevated.

Non-Interactive Mode

Runs silently in the background on guest and VIP submission forms. Guests never see a challenge. Form gates on completion.

✦ Where each mode applies - Managed: all admin logins + VIP login. Non-Interactive: guest request form + VIP submission form.

⚠ Turnstile Keys - Site keys are safe to include in client-side pages. Secret keys must never be placed in client-facing code.

VIP User Management

Master Admin only - Service Admin tab

The Master Admin can add and remove VIP users directly from the Service Admin tab - no external tools needed.

Adding a VIP User

Open the Service Admin tab in Admin Desktop (Master Admin only).

Scroll to the ★ VIP User Management section at the bottom.

Enter the VIP user's email address and click Add VIP. Added immediately.

Ensure VIP Mode is enabled in the sidebar so the login button is visible on the guest page.

Removing a VIP User

Each listed email has a Remove button. Prompts for confirmation. Change takes effect immediately.

✦ VIP Credentials - VIP users log in with their regular system account. Create the account first, then add their email here to grant VIP access.

Sub-Admin Management

Service Administration - Master Admin only

The Service Admin tab lets the Master Admin grant limited dashboard control to trusted assistants - without giving them full system access.

How to Add a Sub-Admin

Open the Service Admin tab in Admin Desktop (Master Admin only).

Create an account for the sub-admin and obtain their UID. Enter their email and UID, tick permissions, click Save Sub-Admin.

Share the AdminD.html URL and their credentials. The panel auto-restricts to their permissions on login.

Permission Flags

Can Delete

Allows permanent deletion of requests. Without it, the Delete button is locked 🔒.

Can Toggle System

Grants access to the Live/Closed toggle in the sidebar.

Can Toggle VIP

Grants access to the VIP Mode toggle in the sidebar.

Can Toggle Voting

Grants access to the public Voting toggle. Base card actions always available.

Can Toggle Guest Lineup

Grants access to the Guest Lineup visibility toggle in the sidebar.

Can Change Venue Name

Allows editing and saving the venue name. Without it, the field is locked and dimmed.

Can Set Background

Allows the sub-admin to update the guest page background image URL.

Can Manage Up Next

Allows adding tracks to and reordering the DJ Lineup (Up Next) panel.

Can Use Mobile UI

Allows signing into Admin Mobile. Access denied at login if this flag is off.

Can Add Tracks

Shows the Add Track popup button. Sub-admin can manually add tracks to the queue or Up Next.

Can Change Suggestion Settings

Reveals the Autocomplete section in the sidebar. Hidden entirely without this permission.

✦ Permission Groups - 11 flags organized into two visual groups: Queue & System and Display & Tools. Grouping is visual only - all flags work independently.

✦ Locked Buttons - When a permission is missing, the button is dimmed with a 🔒 tooltip on hover. Clicking shows an alert instead of acting. No hidden controls.

Tips & Best Practices

🎛 Use Both Admin Views

Keep Admin Desktop at the booth for full view; use Admin Mobile for quick confirms on-the-fly.

📸 Background Images

Use direct image links ending in .jpg/.png/.webp. Unsplash works great.

🗳 Use Voting Strategically

Push only 3–5 requests to vote at a time. Use Top Voted sort to see the crowd favorites.

🔒 VIP Best Practices

Enable VIP Mode only when VIP guests arrive. Pre-create Firebase accounts before the event.

📋 Lineup Workflow

Build the lineup privately, then publish with Guest Lineup when ready.

💡 Share the Link

Display the Clientside URL as a QR code around the venue. No installation needed for guests.