The jukebox is designed to emulate a real, physical jukebox, not a
media player or video jukebox. thus, it is designed to use physical
buttons on a control panel rather than a mouse or keyboard. The
standard way to do this is through a keyboard encoder such as a
KeyWiz or I-Pac, or by hacking a keyboard or game controller.
All jukebox functions can be mapped to any keyboard key, or to the two
main axes or buttons on a gamepad.
Control information is stored in a separate configuration file. The
default control map file is controls.ini; however, you can select a
different file by changing the Controls setting in the Controls section
in jukebox.ini.
In controls.ini, physical keys or gamepad buttons are mapped to jukebox
functions. This allows more than one key or button to provide the same
function. The jukebox can read any key on a standard PC keyboard,
including the Shift, Ctrl, Alt, Lock, and Windows keys, and it can read
up to 14 buttons and the 4 main directions on the first two axes of the
first four gamepads or joysticks in the system. (DOS users will be
limited to two buttons on two gamepads or four buttons on one gamepad
due to limitations on the DOS PC gameport.)
The default controls.ini file includes every mappable key and button for
demonstration purposes; however, you are only required to include keys
or buttons that you are actually using.
Some buttons are required for basic jukebox operation, such as controls
to change pages or select songs. Others represent optional functions
such as displaying a list of the most popular songs, volume control,
etc.
These are the letters used by jukeboxes that use
either one letter and one number or just one letter to select a song.
BTN_A through BTN_Z are available. The default controls.ini maps
BTN_A through BTN_J to their PC keyboard counterparts. The default
skin uses BTN_A through BTN_D for song selection and ignores higher
letters.
See also:
BTN_SELECT.
These are the number buttons on the jukebox; they
are used in all control setups except those that use just a single
letter to select a song. BTN_1 through BTN_25 are available. Note
that BTN_10 through BTN_25 represent a single button with the
two-digit number on its face and not two separate buttons. In
addition, if the skin file is designed to use a zero, BTN_0 will
also be used. The default controls.ini maps all of the number keys
on the numeric keypad to the appropriate jukebox buttons; however,
only keys 1 through 4 of the number keys along the top of the keyboard
are mapped to the corresponding jukebox buttons. The default skin
uses BTN_1 through BTN_4 for song selection and ignores higher numbers.
See also:
BTN_SELECT.
These buttons page through the available songs.
By default, they are mapped to the Page Up and Page Down keys.
See also:
BTN_PREVALPHA,
BTN_NEXTALPHA,
BTN_FIRSTPG,
BTN_LASTPG.
Selects the song entered. This button is optional is the
AutoSelect option is enabled in jukebox.ini; otherwise it is required.
By default, for the default skin, the user should press a letter
button and a number button followed by the Select button to start a
song. If you would prefer the song to be started immediately rather
than requiring the Select button, enable the AutoSelect option in
jukebox.ini. By default, it is mapped to both Enter keys on the
keyboard.
See also:
AutoSelect.
These buttons will jump to the first or last pages of the available songs.
See also:
BTN_PREVPG,
BTN_NEXTPG,
BTN_PREVALPHA,
BTN_NEXTALPHA.
These buttons skip to the next or previous page where the first
letter of the artist is different (not counting the word "THE").
This allows paging through large collections quickly. By default,
these functions are mapped to the comma and period keys (think
of < and > as arrows pointing to the next character in the alphabet).
See also:
BTN_PREVPG,
BTN_NEXTPG.
BTN_POPULAR temporarily changes the Coming Up display to show the most
popular songs rather than the song queue. Pressing this button again
will show the next page of popular songs. After a few seconds, the
display will return to showing the upcoming song queue. (The exact
number of seconds the popular song list is displayed can be set in
jukebox.ini via the MostPopularDisplayTime setting, which defaults
to 5 seconds.) This button is mapped to the P key on the keyboard by
default.
BTN_RADIO toggles "radio mode" on and off where random songs will be
continually played. Pressing BTN_RADIO again will stop radio mode.
BTN_RADIO is mapped to the R key by default.
BTN_PLAYSTIMULATOR toggles the play stimulator
on and off. If no time was specified for the play stimulator, it
is set to 10 minutes when enabled.
This selects a random song and adds it to the queue.
As this is a selection button, it requires a credit if credits
are required.
BTN_TOPTUNE selects the most-played song on the popularity list. If
that song is already playing or already in the queue, the next most
popular song will be played, etc. As this is a selection button, it
requires a credit if credits are required.
See also:
BTN_POPULAR.
The BTN_COIN buttons represent the coin slots on a jukebox
that requires credits to play. Up to 4 individual coin slots can be
defined. Coins are only required if RequireCredits is enabled in
jukebox.ini. By default, the keyboard keys 5 and 6 are mapped to
BTN_COIN1 and BTN_COIN2, which matches the MAME default. Credits
are added to the jukebox based on the CoinXCredit settings in
jukebox.ini.
BTN_PAUSE will pause the currently playing song. It is by default
mapped to the F8 key.
BTN_SCREENSHOT will save a snapshot of the jukebox to
a file. In higher resolutions, it may take several seconds to save the
screenshot, during which the music will probably repeatedly loop a short
section of music. BTN_SCREENSHOT is mapped to the F12 key by default.
Exits the jukebox. BTN_EXIT is mapped to the Escape key by
default.
Clears the last entered button. By default, this is
mapped to the Backspace key on the keyboard.
Clears all currently entered buttons. This button is not
mapped by default.
Cancels the currently playing song and starts the next
song in the queue. As this action does not restore credit to the credits
counter, it should probably not be included on a jukebox that is set
up to use credits. By default, it is mapped to the Delete key.
See also:
BTN_SKIPLAST.
Cancels all of the songs in the queue. If credits
are enabled, a number of credits equal to the number of songs
waiting in the queue will be added. By default, it is mapped to the
F1 key.
See also:
BTN_CLEARALL.
Cancels all of the songs in the queue, including the
currently playing song. If credits are enabled, a number of credits
equal to the number of songs waiting in the queue will be added.
Credit is not returned for the currently playing song. This button
is not mapped by default.
See also:
BTN_CLEARQUEUE.
Switches between free play and credits required modes.
Deletes the last song in the queue. Note that you cannot
skip the currently playing song this way. This button can only be used
during the time specified by SkipLastTimeLimit in jukebox.ini.
See also:
BTN_SKIP.
On a control panel with very limited controls, such as a single 4-way
joystick with one button, the jukebox can be navigated as a GUI. This
is not the recommended way to use the jukebox, but it is available for
those who need it. The available GUI controls are:
Moves the GUI focus in the appropriate direction. The control with
focus will be marked with a dotted line. These buttons are mapped
to the cursor keys by default. The directions are relative to the
screen rotation.
Selects the control that currently has focus, i.e. "clicks" the button.
By default, this is mapped to the spacebar.
Moves the focus to the next or previous control. By default,
BTN_GUI_NEXT is mapped to the Tab key; BTN_GUI_PREV is not mapped by
default.
In order to interact with the skin, the jukebox sends status
messages to the skin and can receive control messages from icons
mapped to locations on the screen.
When a message is received that matches the Action setting of an
icon, that icon's OnImage is displayed, and when the negative
version of the message is received, the icon reverts to its OffImage.
More than one icon can have the same Action, but each icon can only
have one Action. If no OnImage is defined, the OffImage will appear
down and to the right as if "pressed" in like a button. If no
OffImage is specified, the background image in the area specified
by the icon is used.
An Action may contain any of the button definitions listed above.
When a button definition is used, the icon will move to the OnImage
state for a tenth of a second, and then return to the OffImage state.
If the icon is marked as Clickable, it will send the button command as
well as receive it.
In addition to button messages, there are several state messages that
can be assigned as actions. State messages should not be marked as
Clickable, as they are not commands. State messages are often used
to activate "lights" on the jukebox, indicating credits being
available, that a song is paused, that radio mode is turned on, etc.
This is done by putting an image of a turned-on lamp for the icon's
OnImage and of an unlit lamp for the OffImage.
The state messages are:
Activated when a filter is in place; deactivated when the filter is
cleared.
Activated when the Most Popular list is shown; deactivated when the
Song Queue display is restored.
Activated when one or more credits are available; deactivated when
no credits are remaining. When the jukebox is set to not require
credits, this message is always active.
Activated when a song is playing; deactivated when the song
finishes.
Activate when the Pause feature is activated;
deactivated when play is resumed.
Activated when the jukebox is started. This is the default action,
and can be used to essentially apply "decals" to the jukebox without
having to edit the skin background image. Note that this message
is never deactivated, so you cannot use this message to trigger
shutdown events, as the shutdown happens too quickly for the jukebox
to respond to.
Activated for DOSCab Jukebox, deactivated for WinCab Jukebox.
Useful if you wanted to show a different decal depending on which
version is running.
Activated when Radio Mode is started; deactivated when Radio Mode
is exited.
Activated when the play stimulator has been enabled; deactivated
when the play stimulator has been disabled.
Activated when the Mute function is used; deactivated when normal
volume is restored. This message is only sent if the actual mute
function is used, not if the volume is simply turned down to
minimum.
Activated when the user attempts to select a song when credits are
required and no credits are available. Deactivated two seconds
later.
Activated when the user attempts to select an empty song slot.
Deactivated two seconds later.
Activated when a song is selected that is already in the queue
if AllowDuplicatesInQueue is disabled in jukebox.ini. Deactivated
two seconds later.
Activated or deactivated at jukebox startup depending on the
RequireCredits setting in jukebox.ini, and activated or deactivated
as appropriate if BTN_FREEPLAY is toggled.
Activated when no songs are playing, paused, or queued. This
message is sent after the post-song delay on the last song, and it is
deactivated before the pre-song delay. It is not activated between
queued songs, only when the last queued song has played.
Activated when songs are added to an empty queue; deactivated when
the last song in the queue has started playing.
Activated when the delay period before a song starts, and
deactivated when the song starts playing. If no delay is set,
this message will activate at the beginning of a song and then
immediately deactivate.
Activated when the delay period after a song starts, and
deactivated when the post-song delay is over. If no delay is set,
this message will activate and then immediately deactivate.
Activated when the between-song delay period starts, and
deactivated when the between-song delay is over. If no delay is set,
this message will not activate at all.
If the skin is set to add multiple credits one at a time, this
message is activated while the credits are being added and
deactivated when all of the credits for that coin have been added.
Activated for each credit as it is added, deactivated a moment later.
Activated when the Skip Last Song function is available, deactivated
when the SkipLastTimeLimit timer is reached or another song is
queued or the last song is actually skipped.
Activated when the song queue is full; deactivated when the song queue
is no longer full.
See also:
MaxQueueSize.
Activated when one or more selection buttons have been pressed but not
enough to make a valid selection. Deactivated when the selection
is cleared or a valid selection is ready to be selected.
Activated when enough selection buttons have been pressed to indicate a
valid selection. Deactivated when this is no longer the case.
A command message is similar to a BTN_ message; however, they are not
sent in pairs, i.e. there is never a deactivation for them. Commands
are meant to trigger actions in the jukebox as opposed to triggering
GUI actions. These are not usually used as icon actions; they are used
internally by timers. Command messages are not sent to the GUI so
they should not be used by non-clickable icons, and clickable icons
will not appear to "press" if mapped to a command message.
If the skin is set to add multiple credits one at a
time, this command is sent once for each credit to instruct the jukebox
to increase the credit counter.
Turns to the next page of songs.
Turns to the previous page of songs.