================================================================================ JUKEBOX BY AMBER MARLOW Quick Setup Guide — Version 1.0 ================================================================================ -------------------------------------------------------------------------------- WHAT IS JUKEBOX? -------------------------------------------------------------------------------- Jukebox is a self-serve song request portal for your 3DXChat room. Visitors open a webpage, paste a YouTube link, and the song streams directly into your room automatically. No DJ software. No mixer. No technical knowledge required on their end. Visitors spend tokens to queue songs. The playlist updates in real time. Everything runs on your computer and is completely under your control. -------------------------------------------------------------------------------- WHAT YOU NEED -------------------------------------------------------------------------------- 1. A 3DXChat room with radio enabled. 2. An Icecast-compatible stream host (e.g. Zeno.fm). You need your host, port, mount point, username, and password. 3. A free ngrok account. Sign up at https://ngrok.com — no credit card required for testing. A paid plan is recommended for stable, permanent links in a live room. 4. That's it. Everything else installs automatically on first run. -------------------------------------------------------------------------------- FIRST RUN — AUTOMATIC SETUP -------------------------------------------------------------------------------- When you run Jukebox for the first time via run.bat, it will automatically detect and silently install any missing dependencies: - VB-Cable (virtual audio device for streaming) - Node.js (required for YouTube downloads to work) - Firefox (required for YouTube login — see below) You may be prompted by Windows to allow these installations. Click Yes when asked. This only happens once. -------------------------------------------------------------------------------- FIREFOX AND YOUTUBE LOGIN (ONE TIME ONLY) -------------------------------------------------------------------------------- Jukebox downloads songs from YouTube using your logged-in YouTube account to avoid download restrictions. It reads your login directly from Firefox in the background — you never need to export anything manually. What you need to do once: 1. Open Firefox. 2. Go to youtube.com. 3. Log into your Google/YouTube account. 4. Close Firefox. Done. Jukebox handles everything from here. You do not need to keep Firefox open. If your YouTube session expires after several months, simply log back in and you're good again. -------------------------------------------------------------------------------- LINKING YOUR NGROK ACCOUNT -------------------------------------------------------------------------------- ngrok creates a secure public link to your Jukebox page so visitors can reach it from inside 3DXChat. Without it, your page is only visible on your own machine. 1. Go to https://ngrok.com and create a free account. 2. After logging in, find your Authtoken in the ngrok dashboard. 3. Open Jukebox and click Settings. 4. Paste your Authtoken into the ngrok Token field. 5. Click Link Account. You'll see a green confirmation when it's done. 6. Change Mode from Local to Public. 7. Save and restart Jukebox. Your public URL will appear in the console when Jukebox starts. Share that link with your room visitors. Note: Free ngrok accounts generate a new random URL every time you restart. A paid ngrok plan gives you a stable, permanent URL. -------------------------------------------------------------------------------- CONFIGURING YOUR STREAM -------------------------------------------------------------------------------- 1. Open Jukebox and click Settings. 2. Fill in your Icecast stream details: Icecast Host e.g. link.zeno.fm Icecast Port e.g. 80 Mount Point e.g. r3t4u5ekh0buf (no slash needed) Username usually: source Password your stream password 3. Save. Your room's radio URL stays exactly the same as always. Jukebox takes over the audio feed when it's running. -------------------------------------------------------------------------------- BRANDING AND THEMING -------------------------------------------------------------------------------- Every room owner can skin their Jukebox page to match their room's aesthetic. No coding required. 1. Open Jukebox and click Theme. 2. Customize any of the following: Header Title Your room name or any title you want. Custom Logo Upload your own image. Replaces the default artwork. Background Void The darkest base color of the page. Panel Color Color of cards and panels. Borders / Lines Color of borders and dividers. Primary Accent Main highlight color — buttons, now-playing text. Dim Accent Darker shade of your accent for subtle elements. Preparing Tag BG Badge color for songs still downloading. 3. Click Save. The page updates on the next browser refresh. No restart required. The footer copyright ("Jukebox authored by Amber Marlow") is permanent and cannot be removed. This protects the creator's attribution on every install. -------------------------------------------------------------------------------- HOW IT WORKS FOR VISITORS -------------------------------------------------------------------------------- When a visitor opens your Jukebox page they see their token count, a YouTube link box, and the live playlist. To request a song: 1. Copy any YouTube video link. 2. Paste it into the box. 3. Click Queue or Priority. 4. The page confirms the request or explains why it was rejected. 5. The song appears as "preparing" while it downloads, then plays automatically. Songs are limited to 5 minutes and 30 seconds. Longer videos are rejected immediately. -------------------------------------------------------------------------------- THE TOKEN SYSTEM -------------------------------------------------------------------------------- Tokens are how visitors request songs. They prevent spam and keep things fair. Starting tokens: 3 Token cap: 10 Refill: +3 every 5 minutes, always running Normal queue: 1 token Priority play: 2 tokens The refill window scales with room population. For every person beyond 5 connected listeners, the timer adds 1 minute. A busy room slows the refill slightly to keep the queue manageable. If a song fails to download, tokens are automatically refunded. If the room owner skips a song, tokens are automatically refunded to the visitor who requested it. -------------------------------------------------------------------------------- NORMAL VS PRIORITY PLAY -------------------------------------------------------------------------------- NORMAL (1 token) Added to the end of the queue. Plays in order after any priority songs. PRIORITY (2 tokens) Jumps ahead of the normal queue. Plays before normal songs resume. FAIRNESS RULE After every 3 consecutive priority plays by the same person, one normal song plays before their priority songs continue. Their counter then resets. This prevents anyone from locking out the queue indefinitely. Priority songs are marked with a star in the playlist. -------------------------------------------------------------------------------- SKIPPING SONGS -------------------------------------------------------------------------------- As the room owner, you can skip the current song at any time by clicking the Skip button in the Jukebox console. The visitor who requested the song will have their tokens automatically refunded. This protects visitors from losing tokens to an abusive skip. -------------------------------------------------------------------------------- ERROR AND FAILURE MODES -------------------------------------------------------------------------------- Song too long Rejected immediately. Tokens not spent. Video unavailable Private, deleted, or region-locked. Tokens not spent. Age-restricted Cannot be downloaded. Tokens not spent. Not enough tokens Request rejected with refill countdown shown. Download failure Retried automatically. Tokens refunded if it fails. Stream disconnection Jukebox reconnects automatically. You may need to re-toggle your radio in 3DXChat if audio drops. -------------------------------------------------------------------------------- QUICK REFERENCE -------------------------------------------------------------------------------- First run installs automatically? Yes. Click Yes on any UAC prompts. Firefox required? Yes. Log into YouTube once, then close. ngrok required for visitors? Yes. Local mode is for testing only. Song length limit? 5 minutes. Starting tokens? 3 Token cap? 10 Refill rate? +3 every 5 minutes (scales with crowd) Normal play cost? 1 token Priority play cost? 2 tokens Tokens refunded on failure? Yes, automatically. Tokens refunded on skip? Yes, automatically. -------------------------------------------------------------------------------- CREDITS -------------------------------------------------------------------------------- Jukebox by Amber Marlow https://ambermarlowofficial.com Copyright Amber Marlow 2026. All rights reserved. ================================================================================