YOUR CABINET, YOUR MUSIC

RetroPinJuke user guide

Everything you need to get started, choose music and make the jukebox fit your cabinet.

Getting started

  1. Download and run the installer, or run the portable executable. On first launch, Setup opens on your primary monitor.
  2. In Displays, select your playfield monitor and enable a backglass or DMD if you have them. Use Identify all displays / test patterns to check each screen. Return with Escape, your Back button or Return to Setup.
  3. In Input, map your cabinet buttons. For YouTube, add a key under YouTube; for your own music, enable MP3s and choose a folder under Local MP3.
  4. Choose Save & launch jukebox. Select a music mode and a card to play. Without a YouTube key, demo labels let you try the interface but do not play music. Radio and local MP3s do not need a YouTube key.

Use Setup on the jukebox to return to settings. Save profile saves changes and stays in Setup; Save & launch jukebox saves and opens the jukebox. The saved-profile selector switches profiles, while Save as profile names the profile being saved.

Playing music

Radio / live stations
Browse stations by genre or decade, or use Search stations to choose a country, genre and station name. More stations loads more results. Select a station to tune in. Saved stations and Favourites show your saved stations. Add station saves a name and direct HTTP or HTTPS stream URL, including HLS; use the stream address rather than a station website or playlist.
Video / all artists
Choose a decade or genre to load a batch of tracks. The Artists panel shows the artists in that batch. Select an artist to see their tracks, or select All Artists to restore the whole batch. In Favourites, the panel shows artists from your saved tracks. The official YouTube player remains visible; if playback requires interaction, press its Play button. A configured YouTube Data API key and internet connection are needed for discovery.
Local MP3 / hard drive
Appears when MP3 playback is enabled in Setup. Browse or search the selected folder. Genre and decade filters use the files’ tags, and untagged files remain in All Music. In Artists, choose A–Z or 0–9, then choose the first letter or digit of an artist’s name. Letters and digits without matches stay visible but disabled. The index takes up one card row while open, and you can scroll to the cards below. Use Rescan folder after adding or removing files.
Random
In Video or Local MP3, choose a card in Decades & Genres, then press Random to shuffle that selection. The bottom of the Random card shows the selected card, such as 60S or ALL MUSIC. In Video mode, the shuffle uses the selected card's YouTube search keywords. In Local MP3 mode, All Music shuffles your whole MP3 library. To play a random track by one MP3 artist, select the artist first and press Random. The hinge reads ARTIST and the bottom shows the artist's name. Press Random again to reshuffle the same selection.
Search
Open the Search card to enter text with the on-screen keyboard or a keyboard. Results can include video, MP3 and radio; All / Video / MP3 / Radio filters the results. Clear restores normal browsing.
Favourites
Hold Select on a track or station for 0.8 seconds to save it; hold again to remove it. The F key also toggles a favourite. Select the Favourites card to browse saved selections for the current mode.
Queue
Press Q on a focused track, or right-click or touch-hold a track, to queue it. The Queued mode card stays visible and shows the count, including 0 Tracks when empty. Open it to see upcoming songs in order. Select a queued card to play that occurrence, or use the queue controls to move or remove entries. U removes the focused queue occurrence. Radio stations play live and do not enter the song queue.

Buttons and navigation

Use a mouse, touch, keyboard or mapped cabinet controls. Navigate to a card and briefly press Select to play it; hold Select to toggle a favourite. Left and right can move through the screen with two flipper buttons; the focused card scrolls into view.

ActionDefault keyWhat it does
Navigate / SelectArrow keys / EnterMove focus / choose the focused item.
Play / PauseSpacePause or resume playback. Radio resumes at the live broadcast.
Previous / NextPage Up / Page DownChange track, or cycle saved radio stations.
Previous / Next bank[ / ]Move through cards a screen at a time.
Queue / UnqueueQ / UAdd a track or remove the focused queued occurrence.
FavouriteFSave or remove the focused track or station.
Search / Genres / RefreshS / G / ROpen search, browse genres or refresh selections.
Back / ExitBackspace or EscapeClose a menu; Escape outside a menu exits the application.

The playback controls include Previous, Play/Pause, Next and, for radio and MP3, Stop. Adjust Volume or use Mute. On a focused volume control, press Select, adjust left or right, then press Select or Back to return to navigation. Some Vintage Hi-Fi knobs and buttons are decorative; the labelled transport controls operate local music.

Setup reference

Displays

Assign a monitor to each enabled role: playfield, backglass and DMD. Choose window mode, software rotation and canvas scaling for each. Rotation is inside RetroPinJuke and does not change Windows display settings. Allow combined layout on a shared monitor lets roles share a screen; shared roles must use the same rotation. With the backglass disabled, video appears beside the playfield controls.

Logical resolution and bezel margins provide optional sizing and edge adjustments. DMD options select its content, colours and font. For a shared DMD, choose whether to show its border, or set a custom width, height and alignment. Use the display test before saving; if a display is missing or assignments are ambiguous, Setup opens so you can correct them.

Input

Choose Add binding beside an action and press a key or controller button. Enable gamepad / XInput for a controller and adjust the stick dead zone if needed. You can enter a zero-based controller button number and choose Assign button, remove individual bindings, or use Reset to defaults. Assigning a button moves it from its previous action. Save the profile to keep changes.

YouTube

You do not need a YouTube Premium subscription to create or use an API key. You need a Google account and a Google Cloud project. Google applies a daily API quota, so frequent searches can reach the limit. The key is used to find videos and does not itself provide Premium benefits such as ad-free playback. See the Google YouTube Data API guide for current requirements and quota details.

Enable YouTube Data API v3 in a Google Cloud project, create an API key, then enter it in Setup and choose Validate key. Restrict the key to that API. Remove saved key removes the stored key. Region, language, Safe Search, results per request and cache lifetime control discovery. Full-screen YouTube video fills the backglass area; Look up release years uses MusicBrainz to find original years when possible.

Local MP3

Play MP3 files enables local music; enter a folder or use Choose music folder. Include subfolders scans below it. Start with local MP3 cards selects the local view. Search online for missing album art sends artist and title to MusicBrainz and the Cover Art Archive when local artwork is unavailable. Saving scans the folder; files stay in place and are not modified. Up to 20,000 MP3 files are supported.

Normalise MP3 volume is unticked by default. Tick it under Setup → Local MP3 and choose Save profile to reduce volume differences between songs. Existing saved choices are preserved. Tracks are analysed in the background and unchanged files reuse saved results. A first selection may briefly show PREPARING MP3 VOLUME…. A fixed adjustment preserves quiet and loud passages within each song, while peak protection limits boosts to avoid clipping. Original MP3 files stay untouched. If analysis fails, playback uses the original level and shows a message. Radio and YouTube are unaffected.

Casting

In Setup → Casting, connect an AirPlay TV on the same network with Find TVs, or enter its IP address and pair if prompted. For Miracast, use Open Windows Cast, connect the TV, then press Win + P and choose Extend. In RetroPinJuke, select the extended screen and choose Use screen as TV.

In Displays, use Cast to on Backglass or DMD to assign that display to a connected TV. Each TV can show one display at a time. Keep the playfield on a local screen. Stop casting clears the assignment while keeping the TV connected. Casting changes apply immediately.

Appearance

Colour scheme and backglass skin
Choose blue/white or brown/ivory, and the Standard or Vintage Hi-Fi backglass. Vintage Hi-Fi includes sound-reactive meters and a cassette or YouTube CRT.
Show video / album info
Shows media and extra track details with the selected visualization. Turning it off hides extra information; YouTube's player remains visible.
Visualization and backglass layout
Choose None or a sound-reactive effect and position it with the media. Width, height, spectrum bar width and media width adjust the drawing; mirror repeats it at the opposite edge where available. Cycle visualization colours changes colours during playback.
Title-card bank
Preferred columns, visible rows and card gap control the grid. Card flip duration and ripple delay set animation timing. Font scale, backlight brightness and background texture change its appearance. Queued music font scale sizes the next-up and playback text separately.
Music selection panels
Set Rows and Columns for both Decades & Genres and Artists. Both default to four columns and three rows. Choose 2–6 rows and 2–8 columns, then save the profile. The Mode panel uses one column of four full-width slots.
Cabinet sound effects
Enable or disable navigation and selection sounds and set their volume. They also follow the main volume and mute controls.
Dim playfield while music is playing
Dims the playfield after the chosen delay to the selected brightness. Input restores brightness and restarts the delay; menus stay bright.
Show artist cards / Alternate coloured labels
Show or hide artist cards, or alternate the colours of track labels.
Reduce motion

Reduce motion affects these visuals:

  • Cards and interface: disables title-card flips and other interface animations and transitions.
  • Scrolling text: stops automatic scrolling in the next-up ticker, DMD and Vintage Hi-Fi text. Long ticker and DMD text can still be scrolled manually.
  • Visualizations: limits drawing to 12 frames per second and disables glow, trails and automatic colour cycling. Full-screen effects use fewer shapes and stop travelling or rotating motion. Radiating Contours and Waveform Mountains show stationary, audio-reactive patterns instead of moving histories.
  • Vintage Hi-Fi: cassette reels still turn during radio or MP3 playback, and the VU meters still respond to sound.

Audio playback and volume are unchanged. Windows’ own reduced-motion setting also affects animations and visualizations.

Playback

Start with favourites independently opens saved Radio, Video or MP3 selections when that mode is selected. Auto DJ plays queued songs first, then continues with music related to the selected track and visible cards. It is suspended during radio. Begin playback after selecting a track controls autoplay after selection; Initial volume sets the starting volume. The application does not begin playing on launch.

Clear local library and cache removes the local queue, favourites, history, search cache and saved radio stations; it does not change a YouTube account.

Diagnostics

View display and session information, run the interactive display test, and check the installed version and updates. Check for updates checks manually; an update is downloaded only when you choose to update.

Editing genres JSON

In Setup → Genres, edit Genre definitions (JSON) directly, then save the profile. This is a JSON array stored with the profile, not a separate file you need to create. Each object creates a decade or genre card. For example:

[
  {
    "id": "jazz",
    "label": "JAZZ",
    "queries": ["jazz classics official music video", "jazz classics official audio"],
    "enabled": true,
    "negativeKeywords": ["reaction", "tutorial", "interview", "karaoke"],
    "positiveKeywords": ["official"]
  }
]

id is a unique identifier using letters, numbers, underscores or hyphens; label is the text on the card; queries is a list of YouTube search phrases; and enabled shows or hides the card. The optional keyword lists help filter and rank video candidates; they do not prove a video is official. Genre searches also filter compilation-style titles. MP3 filters use file tags, and radio filters use station directory tags, rather than the YouTube queries.

Keep the surrounding square brackets, use double quotes, and put commas between entries but not after the last one. IDs must be unique; keep at least one genre enabled. You can have 1–60 genres and 1–20 queries per genre. Copy the existing JSON before editing so you can restore it if needed. Setup reports invalid JSON or invalid settings when you save.

PinUP Popper

Configure RetroPinJuke as an external system or emulator and point Popper at the installed executable. Select the saved profile with --profile "Default Cabinet". The PinUP setup tab shows a sample command and available options. The mapped Exit action stops playback, saves the library and closes all jukebox windows so Popper can regain control.

Use --setup to open settings, --display-test for display testing, or --safe-mode to open Setup in a normal window on the primary monitor.

Troubleshooting

No YouTube results or playback
Check your internet connection and API key in Setup. Demo labels do not play music. If the player asks for interaction, use its native Play button.
Music folder changes are missing
Check that MP3 playback is enabled and the correct folder and subfolder option are selected, then rescan. Genre and decade browsing depends on file tags.
A screen is missing or rotated incorrectly
Open Setup, check monitor assignments and software rotation, and run the display test. If you cannot reach Setup, launch with --safe-mode.
A radio station does not play
Try another station or check the direct stream URL; directory listings do not guarantee that a stream works in every location.

For suggestions and community help, visit the RetroPinJuke VPForums thread.