12.3: Status Bitmaps

There are two ways of specifying bitmaps in status objects…

Using one or more ‘Bitmap’ parameters. This preloads the bitmaps on startup, so the number is limited by the GPU memory, but allows for fast switching for full-frame rate animation.

Alternatively, the ‘BitmapDirectory’ can be used. This specifies a location on the file system in which image files are stored (.bmp, .jpg, .png).

fruitbox only loads these into GPU memory when needed, so is slower, but there is no limit on the number of image files. This is more suitable for use in slide-show displays for example:

Animated GIF files can be supported by splitting the GIF file into individual files (by using ‘ffmpeg -i file.gif file%02d.jpg’ for example), including them in a [status] section with multiple ‘Bitmap’ entries, and specifying the animation speed with ‘TimerTickPeriod’.

Then in your status Contents text file include the text ‘${IF_TIMER_TICK}${DRAW_BITMAP}’

12.4: Status Videos

Status boxes can be used to display either video clips or music videos.

If the Video parameter is specified in the [status] object, any reference to VIDEO in the status Contents file variables, i.e. ${DRAW_VIDEO} will refer to the video clip specified by the Video parameter.

If the Video parameter is not specified, any VIDEO $variables will refer to the currently playing song (if it’s a video file).

12.5: Spectrum Analyser

A [spectrum] object allows an audio frequency spectrum to be displayed for the mp3 songs (not ogv videos).

Multiple [spectrum] objects can be defined. Various options allow great flexibility in the visual appearance.

For example, the user has control over the look of each of the 32 possible frquency bands, and which are visible.

12.6: Fonts and Text

The configuration file [fonts] section allows multiple fonts of different sizes to be loaded and used by different display elements. This removes the need for each text definition to load it’s own font, instead referencing a specific font type and size from the ‘font pool’.

Note that the order in which the fonts are define in the [fonts] section determines their font number, starting at 1. Font number 0 is the internal fruitbox font used for the on-screen menus etc.

Text definitions ([general] ArtistText, [general] SongText, [general] PairedSongText, [general] ExtraText and [status] Text) parameters have the following arguments…

<font> <colour> <alignment> <capitalise> <mode> <quoted> <offset (x y)> <max_width>
font : number of font from ‘font pool’ (0..)

note that the fonts in the pool are numbered in the order in which they are defined in the [fonts] section of the skin configuration file
colour : red green blue alpha (0..255)
(alpha : 0 completely transparent through to 255 completely opaque)

alignment : ‘Left’, ‘Centre’ or ‘Right’

capitalise : ‘Yes’ or ‘No’

mode :
 0 : text is displayed normally
-1 : Condense … wide text is horizontally squashed to fit within max_width
1..n : Scroll … text is scrolled at the specified speed (1 = slowest) if it doesn’t fit into max_width (See Note below)

quoted :
‘Yes’ (text is wrapped within double-quotes)
‘No’ text is unmodified

offset : x y
text position is shifted by these amounts in pixels

max_width:
The maximum width of the text. If the text is wider than this, then it will be shrunk to the maximum width (if the ‘mode’ option is -1), or scrolled within this width (if mode > 0)

Note : scrolling text is only supported for status object text (not title strip text)

12.7: FreePlay / Coin Mode

fruitbox can operate in free play or coin mode.

In freeplay mode, no coins (or credits) need to be inserted to add a song to the play queue.

In coin mode, fruitbox can support up to six coin buttons. Each coin button has its own ‘CreditsPerCoin’ value, so that fruitbox can mimic jukeboxes which have multiple coin slots, for different coin denominations.

The ‘CreditsPerCoin’ value determines how many credits are added when the coin is inserted.

The ‘CreditsPerSong’ parameter determines how many credits are used when a song is selected.

All six ‘CreditsPerCoin’ parameters are ignored if fruitbox is in free play mode.

12.8: Touch Song Mode / Button Touch Areas

Touch Song mode is activated by defining the [touch song] Bitmap parameter, and if a touchsreen has been detected (or a mouse has been detected and enabled).

This option over-rides joystick mode if that has also been defined (using the [joystick] object).

In touch song mode, the user can touch the song title areas themselves to select a song, rather than using select buttons.

Note that the song touch areas default to the title strip area holding the song name, but their size and position can be adjusted by using the [touch song] ‘Size’ and ‘Offset’ parameters.

As well as enabling touch song mode, the [touch song] Bitmap parameter specifies an image file which is displayed over the song area when being touched.

If any button assignments are specified in the [touch buttons] section, then (if a touchscreen has been detected) that area will trigger the corresponding button press event if touched.

Furthermore, if the optional image file parameter is specified, then that image will be drawn whilst that area of the display is touched, allowing simple button press animation effects.

Note : if a button area has been defined in the [touch buttons] section, and a touch screen has been detected, then that button will be automatically configured as a touch input, over-riding any mapping in the fruitbox ini file.

12.9: Mouse Mode

If the mouse is defined and enabled in the [mouse] section of the ini file, then mouse mode is activated.

This mode allows a mouse to be used to select songs in a similar way to touch mode, in that touch areas and touch song operation is activated, but responsive to the mouse pointer and left mouse button in addition to touch input.

This allows all skins designed for touch to be used without touch devices.

12.10: Joystick Mode

If a [joystick] object is specified in the ini file, then joystick mode is activated.

This allows a song to be chosen using the ‘Up’, ‘Down’, ‘Left’ and ‘Right’ buttons instead of entering the select code, and is useful for running fruitbox in arcade cabinets for example, where buttons are limited.

Pressing the ‘Select’ button will then add that song to the play queue (AutoSelect mode is disabled when joystick mode is active).

The joystick image specified is positioned in the same place as the song title being selected, and its size is calculated to fit exactly into the region containing the song title.

Specifying the ‘Size’ parameter in the configuration file allows the size to be set manually, for example if the highlighted bitmap needs to overlap the song title region.

The ‘Offset’ parameter can then be used to adjust the position of the highlighter precisely around the song title region.

12.11: Instant Play

If the InstantPlay parameter is enabled in the skin configuration file, then the playqueue is bypassed.

When a song is selected, any currently playing song is immediately stopped, and the selected song started.

This can be useful when streaming mp3s from url sources (internet radio), which effectively have an infinite duration and hence don’t naturally stop.

If the InstantPlay parameter is enabled in the skin configuration file, then the playqueue is bypassed.

When a song is selected, any currently playing song is immediately stopped, and the selected song started.

This can be useful when streaming mp3s from url sources (internet radio), which effectively have an infinite duration and hence don’t naturally stop.

12.12: Random Songs

fruitbox can play random songs in one of two ways…

1. The user pressing the ‘Random’ button
2. fruitbox selecting a random song in attract mode

In either case, fruitbox will attempt to prevent songs being repeatedly played by only picking a song

if it doesn’t appear in it’s song play history and current playqueue.

The size of the history list can be changed with the ‘SongHistoryDepth’ configuration parameter. If this is large and the number of songs in the database is relatively small, then fruitbox may not be able to quickly choose a random song which has not previously been played within the history and current play queue, so will just play a random song anyway even if it already been played recently

12.13 : Albums / Singles Mode

Fruitbox has two distinct modes – Albums and Singles, specified by the ‘AlbumMode’ parameter.

In Singles mode, each song is individually selectable, and each title strip displays a number of songs (or pairs of songs), each along with the artist name.

‘ArtistText’, ‘SongText’, ‘PairedSongText’, ‘PairSongs’ and ‘SongsPerTitleStrip’ configuration parameters can be used adjust the appearance of the song details on the title strips.

In Albums mode, each title strip shows the album title, album artist, album cover art, and list of songs in the album (upto the SongsPerTitleStrip value).

One selection will add all the songs in the album to the play queue in one go (assuming, in non-freeplay mode, there are sufficient credits). ‘AlbumText’, ‘ArtistText’, ‘SongText’, ‘PairedSongText’, ‘AlbumArtSize’, ‘AlbumArtOffset’ and ‘SongsPerTitleStrip’ configuration parameters can be used adjust the appearance of the album details on the title strips.

Also note that ‘PairedSongDescription’ is used to define the contents of the line which is associated with the ‘AlbumText’ parameter, and all of the ‘Paired*’ Description values are ignored (as these are only relevant for singles mode song pairs).

13: Screen Layout

The display is built using a combination of the following objects, as defined in the skin file:

1. [title strip] object : a region which contains songs
   See title strips section for more details

2. [bitmap] object : a region which contains a static bitmap
   This can be used for background and foregrounds for example

3. [status] object :
   A region containing status information
   See status box section for more details

4. [spectrum] object :
   A region containing an audio spectrum analyser
   See spectrum section for more details

5. [touch song] object :
   A region containing a bitmap highlighting a song name when touched.
   See touch song section for more details.

6. [touch buttons] object(s) :
   Region(s) containing a bitmap displayed when a touch button is pressed.
   See touch button section for more details.

Note that there is no limit on the number of objects which can be defined.

They are rendered to the display in the order that they are defined in the skin file.

13.1: TitleStrips

TitleStrips are the regions in the display which contain the songs. In Singles mode, song titles** are listed vertically, and shown along with the artist name.

If ‘PairSongs’ is enabled, then the songs are arranged in pairs with the artist name*** shown in between them (i.e. side A/B).

In Albums mode, the title strip contains details about the album in addition to the song list (see section ‘Albums / Singles Mode’ for more details).

Songs are sorted in the order according to the ‘SortSongsBy’ configuration parameter. Songs in each title strip (in Singles mode), or title strips themselves (in Albums mode) are assigned their own unique select code. The command line option ‘–debug-song-nums’ can be used to make these codes visible; useful when developing skins.

TitleStrips automatically move and update their contents when the ‘Left’ or ‘Right’ buttons are pressed.

The look and movement of the title strips is determined by ‘TitleStripMoveStyle’ parameter in the skin file, as follows:

TitleStripMoveStyle <speed> <effect> <fade>

<speed>
1..x = higher number = faster title strip turn (0 = instant)

<effect> …
0 = swipe horizontally
1 = swipe vertically
2 = reveal horizontally
3 = reveal vertically
4 = turn horizontally
5 = turn vertically
6 = dissolve

<fade>
no = title strips don’t fade
yes = title strips fade to black

Notes:

** The ‘SongDescription’ and ‘PairedSongDescription’ configuration parameters can be used to modify the text displayed on the song lines of the title strip(s)

‘PairedSongDescription’ is only used if ‘PairSongs’ is not set to false)

*** The ‘ArtistDescription’ configuration parameter works in the same way as the ‘SongDescription’ parameter, but affects the artist name text in the title strip(s) rather than the song title text.

Note that as well as fixed text, the *Description parameters can also contain one or more of the following reserved keywords which will be replaced by actual song details…

${SONG_TITLE}

${SONG_ARTIST}

${ALBUM_TITLE}

${ALBUM_ARTIST}

${YEAR}

${GENRE}

${TRACK_NUMBER}

${PUBLISHER}

${ISRC}

${CUSTOM_TAG}

${LENGTH}

${STRIP_CODE}

${PAIRED_SONG_TITLE}

${PAIRED_SONG_ARTIST}

${PAIRED_ALBUM_TITLE}

${PAIRED_ALBUM_ARTIST}

${PAIRED_YEAR}

${PAIRED_GENRE}

${PAIRED_TRACK_NUMBER}

${PAIRED_PUBLISHER}

${PAIRED_ISRC}

${PAIRED_CUSTOM_TAG}

${PAIRED_LENGTH}

${PAIRED_STRIP_CODE}

13.2: Status Boxes

Status Boxes provide a very flexible way of displaying real-time text-based information, fixed and animated bitmaps, video clips and sound effects.

Using the ‘Output’ parameter also allows the status information to be written to an external file to be parsed by external applications*.

Examples of status include ‘Now Playing’ information, ‘Coming Up’ song list, Select Code, Credits, etc.

Each status box defined should have a ‘Contents’ file associated with it. This is a file that contains human readable text which indicates what is drawn in the status box.

As well as fixed text, the user can also specify the following predefined variables, which represent song details and jukebox status, and also enable text and bitmaps to be conditionally drawn under many different circumstances.

The GPIO related predefined variables allow GPIO pins to be driven with high or low values under different fruitbox conditions.

* Note: outputting status to a text file can be done as well as displaying the status on the display,

or instead of (to supress the status being rendered to the display, do not define the ‘Size’ parameter (or set width and/or height to zero).

${NOW_PLAYING_TITLE}
The name of the song which is currently playing

${NOW_PLAYING_STREAM_TITLE}
The StreamTitle of the currently playing radio program

${NOW_PLAYING_STREAM_URL}
The StreamUrl of the currently playing radio program

${NOW_PLAYING_ARTIST}
The name of the artist of the song which is currently playing

${NOW_PLAYING_ALBUM}
The name of the album of the song which is currently playing

${NOW_PLAYING_ALB_ARTIST}
The name of the album artist of the song which is currently playing

${NOW_PLAYING_TRACK_NUMBER}
The track number of the song which is currently playing

${NOW_PLAYING_YEAR}
The year of the song which is currently playing

${NOW_PLAYING_GENRE}
The genre of the song which is currently playing

${NOW_PLAYING_PUBLISHER}
The publisher of the song which is currently playing

${NOW_PLAYING_ISRC}
The ISRC of the song which is currently playing

${NOW_PLAYING_CUSTOM_TAG}
The custom MP3 tag of the song which is currently playing

${NOW_PLAYING_LENGTH}
The length in mm:ss of the currently playing song

${NOW_PLAYING_ELAPSED_TIME}
The elapsed time in mm:ss of the currently playing song

${NOW_PLAYING_TIME_REMAINING}
The remaining time in mm:ss of the currently playing song

${NOW_PLAYING_ARTWORK}
The cover artwork of the currently playing song. The artwork will occupy the entire status box, and is drawn before any text. The actual artwork displayed will depend upon the value of the [general] ‘ArtworkMode’ configuration setting.

${COMING_UP_NUM_SONGS}
1The number of songs coming up in the play queue

${COMING_UP_TOTAL_TIME}
The total play time in hh:mm:ss of the songs in the play queue

${COMING_UP_TITLE}
The title of a song in the play queue. Each time this reserved word is used, it refers to the next song after the last one referenced

${COMING_UP_ARTIST}
The artist name of a song in the play queue. Each time this reserved word is used, it refers to the next song after the last one referenced

${COMING_UP_ALBUM}
The album name of a song in the play queue. Each time this reserved word is used, it refers to the next song after the last one referenced

${COMING_UP_ALB_ARTIST}
The album artist name of a song in the play queue. Each time this reserved word is used, it refers to the next song after the last one referenced

${COMING_UP_TRACK_NUMBER}
The track number of a song in the play queue. Each time this reserved word is used, it refers to the next song after the last one referenced

${COMING_UP_YEAR}
The year of a song in the play queue. Each time this reserved word is used, it refers to the next song after the last one referenced

${COMING_UP_GENRE}
The genre of a song in the play queue. Each time this reserved word is used, it refers to the next song after the last one referenced

${COMING_UP_PUBLISHER}
The publisher of a song in the play queue. Each time this reserved word is used, it refers to the next song after the last one referenced

${COMING_UP_ISRC}
The ISRC of a song in the play queue. Each time this reserved word is used, it refers to the next song after the last one referenced

${COMING_UP_CUSTOM_TAG}
The custom MP3 tag of a song in the play queue. Each time this reserved word is used, it refers to the next song after the last one referenced

${COMING_UP_LENGTH}
The length in mm:ss of a song in the play queue. Each time this reserved word is used, it refers to the next song after the last one referenced

${LAST_PLAYED_TITLE}
The name of the song which was last played

${LAST_PLAYED_ARTIST}
The name of the artist of the song which was last played

${LAST_PLAYED_ALBUM}
The name of the album of the song which was last played

${LAST_PLAYED_ALB_ARTIST}
The name of the album artist of the song which was last played

${LAST_PLAYED_TRACK_NUMBER}
The track number of the song which was last played

${LAST_PLAYED_YEAR}
The year of the song which was last played

${LAST_PLAYED_GENRE}
The genre of the song which was last played

${LAST_PLAYED_PUBLISHER}
The publisher of the song which was last played

${LAST_PLAYED_ISRC}
The ISRC of the song which was last played

${LAST_PLAYED_CUSTOM_TAG}
The custom MP3 tag of the song which was last played

${LAST_PLAYED_LENGTH}
The length in mm:ss of the song which was last played

${CREDITS}
The number of credits

${SONGS_CREDITED}
The number of songs available from inserted credits

${ATTRACT_MODE_GENRE}
The name of the current AttractModeGenre that Attract mode will select a random song from

${CREDITS_PER_COIN1}
The number of credits added when a coin is inserted

${CREDITS_PER_COIN2}
The number of credits added when a coin is inserted

${CREDITS_PER_COIN3}
The number of credits added when a coin is inserted

${CREDITS_PER_COIN4}
The number of credits added when a coin is inserted

${CREDITS_PER_COIN5}
The number of credits added when a coin is inserted

${CREDITS_PER_COIN6}
The number of credits added when a coin is inserted

${CREDITS_PER_SONG}
The number of credits used per song play

${VOLUME}
The song volume

${SELECT_CODE}
The select code

${NUM_SONGS}
The total number of songs in the database

${NUM_SEARCH_SONGS}
The number of songs from the search

${PLAYQUEUE_SPACE}
The number of empty spaces in the playqueue

${NUM_TITLE_STRIPS}
The total number of title strips in the jukebox

${FIRST_VISIBLE_TITLE_STRIP}
The number of the first title strip visible on the display

${LAST_VISIBLE_TITLE_STRIP}
The number of the last title strip visible on the display

${TOTAL_PLAYED_SONGS}
The number of songs played

${TOTAL_PLAYED_TIME}
The total time in hh:mm:ss for the number of songs played

${SET_GPIO_00_HI}
Sets the specified GPIO output high

${SET_GPIO_00_LO}
Sets the specified GPIO output low

${SET_GPIO_01_HI}
Sets the specified GPIO output high

${SET_GPIO_01_LO}
Sets the specified GPIO output low

${SET_GPIO_02_HI}
Sets the specified GPIO output high

${SET_GPIO_02_LO}
Sets the specified GPIO output low

${SET_GPIO_03_HI}
Sets the specified GPIO output high

${SET_GPIO_03_LO}
Sets the specified GPIO output low

${SET_GPIO_04_HI}
Sets the specified GPIO output high

${SET_GPIO_04_LO}
Sets the specified GPIO output low

${SET_GPIO_05_HI}
Sets the specified GPIO output high

${SET_GPIO_05_LO}
Sets the specified GPIO output low

${SET_GPIO_06_HI}
Sets the specified GPIO output high

${SET_GPIO_06_LO}
Sets the specified GPIO output low

${SET_GPIO_07_HI}
Sets the specified GPIO output high

${SET_GPIO_07_LO}
Sets the specified GPIO output low

${SET_GPIO_08_HI}
Sets the specified GPIO output high

${SET_GPIO_08_LO}
Sets the specified GPIO output low

${SET_GPIO_09_HI}
Sets the specified GPIO output high

${SET_GPIO_09_LO}
Sets the specified GPIO output low

${SET_GPIO_10_HI}
Sets the specified GPIO output high

${SET_GPIO_10_LO}
Sets the specified GPIO output low

${SET_GPIO_11_HI}
Sets the specified GPIO output high

${SET_GPIO_11_LO}
Sets the specified GPIO output low

${SET_GPIO_12_HI}
Sets the specified GPIO output high

${SET_GPIO_12_LO}
Sets the specified GPIO output low

${SET_GPIO_13_HI}
Sets the specified GPIO output high

${SET_GPIO_13_LO}
Sets the specified GPIO output low

${SET_GPIO_14_HI}
Sets the specified GPIO output high

${SET_GPIO_14_LO}
Sets the specified GPIO output low

${SET_GPIO_15_HI}
Sets the specified GPIO output high

${SET_GPIO_15_LO}
Sets the specified GPIO output low

${SET_GPIO_16_HI}
Sets the specified GPIO output high

${SET_GPIO_16_LO}
Sets the specified GPIO output low

${SET_GPIO_17_HI}
Sets the specified GPIO output high

${SET_GPIO_17_LO}
Sets the specified GPIO output low

${SET_GPIO_18_HI}
Sets the specified GPIO output high

${SET_GPIO_18_LO}
Sets the specified GPIO output low

${SET_GPIO_19_HI}
Sets the specified GPIO output high

${SET_GPIO_19_LO}
Sets the specified GPIO output low

${SET_GPIO_20_HI}
Sets the specified GPIO output high

${SET_GPIO_20_LO}
Sets the specified GPIO output low

${SET_GPIO_21_HI}
Sets the specified GPIO output high

${SET_GPIO_21_LO}
Sets the specified GPIO output low

${SET_GPIO_22_HI}
Sets the specified GPIO output high

${SET_GPIO_22_LO}
Sets the specified GPIO output low

${SET_GPIO_23_HI}
Sets the specified GPIO output high

${SET_GPIO_23_LO}
Sets the specified GPIO output low

${SET_GPIO_24_HI}
Sets the specified GPIO output high

${SET_GPIO_24_LO}
Sets the specified GPIO output low

${SET_GPIO_25_HI}
Sets the specified GPIO output high

${SET_GPIO_25_LO}
Sets the specified GPIO output low

${SET_GPIO_26_HI}
Sets the specified GPIO output high

${SET_GPIO_26_LO}
Sets the specified GPIO output low

${SET_GPIO_27_HI}
Sets the specified GPIO output high

${SET_GPIO_27_LO}
Sets the specified GPIO output low

${SET_FLAG_1_HI}
Sets the specified status flag high

${SET_FLAG_1_LO}
Sets the specified status flag low

${SET_FLAG_2_HI}
Sets the specified status flag high

${SET_FLAG_2_LO}
Sets the specified status flag low

${SET_FLAG_3_HI}
Sets the specified status flag high

${SET_FLAG_3_LO}
Sets the specified status flag low

${SET_FLAG_4_HI}
Sets the specified status flag high

${SET_FLAG_4_LO}
Sets the specified status flag low

${NO_DRAW}
Supresses drawing of the status object

${SET_VISIBLE}
Makes the status object visible

${SET_NOT_VISIBLE}
Makes the status object invisible

${DRAW_BITMAP}
Draw user defined bitmaps, as specified by the Bitmap parameter. The bitmap will occupy the entire status box, and is drawn after any text. If multiple bitmaps are defined, they will be drawn in turn, each time the ${DRAW_BITMAP} keyword is executed. Bitmaps remain visible until a ${UNDRAW_BITMAP} command is executed.

${DRAW_RANDOM_BITMAP}
Draw a random user defined bitmap, chosen from the specified Bitmap parameters.

${UNDRAW_BITMAP}
Undraw the bitmap

${DRAW_VIDEO}
Draw the video

${UNDRAW_VIDEO}
Undraw the video

${START_VIDEO}
Start video playing

${STOP_VIDEO}
Stop video playing

${PAUSE_VIDEO}
Pause video playing

${UNPAUSE_VIDEO}
Un-pause video playing

${STOP_TIMER}
Stop the status TimerTick timer

${START_TIMER}
Start the status TimerTick timer

${RESET_TIMER}
Reset the status TimerTick timer

${PLAY_SOUND}
Play the sound as defined by the Sound parameter

${STOP_SOUND}
Stop the sound as defined by the Sound parameter

${IF_FREEPLAY}
Activates the text following it if Free Play mode is enabled

${IF_NOT_FREEPLAY}
Activates the text following it if Free Play mode is disabled

${IF_NO_CREDITS}
Activates the text following it if no credits are available

${IF_ANY_CREDITS}
Activates the text following it if credits are available

${IF_SONG_PLAYING}
Activates the text following it if a song is currently playing

${NOT_SONG_PLAYING}
Activates the text following it if no song is currently playing

${IF_ATTRACT_PLAYING}
Activates the text following it if a song is currently playing via attract

${IF_NOT_ATTRACT_PLAYING}
Activates the text following it if no song is currently playing via attract

${IF_FILE_PLAYING}
Activates the text following it if the song is currently playing is a local mp3 file

${IF_NOT_FILE_PLAYING}
Activates the text following it if the song is currently playing is not a local mp3 file

${IF_VIDEO_PLAYING}
Activates the text following it if the song is currently playing is a video

${IF_NOT_VIDEO_PLAYING}
Activates the text following it if the song is currently playing is not a video

${IF_STREAM_PLAYING}
Activates the text following it if the song is currently playing is a streaming (internet radio) song

${IF_NOT_STREAM_PLAYING}
Activates the text following it if the song is currently playing is not a streaming (internet radio) song

${IF_SONG_LOADING}
Activates the text following it if a song is currently loading

${IF_NOT_SONG_LOADING}
Activates the text following it if no song is currently loading

${IF_SONG_UNLOADING}
Activates the text following it if a song is currently unloading

${IF_NOT_SONG_UNLOADING}
Activates the text following it if no song is currently unloading

${IF_ANY_COMING_UP}
Activates the text following it if any songs are coming up

${IF_NONE_COMING_UP}
Activates the text following it if no songs are coming up

${IF_SONG_COMING_UP}
Activates the text following it if there is another song in the play queue. This is different to the ${IF_ANY_COMING_UP} keyword because it refers to the next coming up entry rather than the complete play queue

${IF_ATTRACT_MODE}
Activates the text following it if Attract mode is enabled

${IF_NOT_ATTRACT_MODE}
Activates the text following it if Attract mode is disabled

${IF_LOOPQUEUE_MODE}
Activates the text following it if Loop mode is enabled

${IF_NOT_LOOPQUEUE_MODE}
Activates the text following it if Loop mode is disabled

${IF_TIMER_HI}
Activates the text following it if the status timer is high. The value of ‘TimerTickPeriod’ for the status object in the configuration file determines the rate at which the timer toggles between high and low. i.e. TimerTickPeriod = 30 means the timer will be high for 30 video frames, then low for 30 video frames, repeating indefinitely

${IF_TIMER_LO}
Activates the text following it if the status timer is low

${IF_TIMER_TICK}
Activates the text following it when the status timer ticks (each tick occurs every TimerTickPeriod video frames

${IF_MUTE}
Activates the text following it when the song volume is muted

${IF_NOT_MUTE}
Activates the text following it when the song volume is not muted

${IF_TITLE_STRIP_MOVING}
Activates the text following it when the song title_strips are moving

${IF_NOT_TITLE_STRIP_MOVING}
Activates the text following it when the song title_strips are not moving

${IF_PLAYQUEUE_EMPTY}
Activates the text following it if the play queue is empty (includes currently playing song)

${IF_NOT_PLAYQUEUE_EMPTY}
Activates the text following it if the play queue is not empty (includes currently playing song)

${IF_PLAYQUEUE_FULL}
Activates the text following it if the play queue is full (includes currently playing song)

${IF_NOT_PLAYQUEUE_FULL}
Activates the text following it if the play queue is not full (includes currently playing song)

${IF_STEREO}
Activates the text following it if the current song is stereo

${IF_NOT_STEREO}
Activates the text following it if the current song is not stereo

${IF_PAUSED}
Activates the text following it if the current song is paused

${IF_NOT_PAUSED}
Activates the text following it if the current song is not paused

${IF_INSTANT_PLAY}
Activates the text following it if Instant Play mode is set

${IF_NOT_INSTANT_PLAY}
Activates the text following it if Instant Play mode is not set

${IF_INVALID_CHOICE}
Activates the text following it if the last song selection was invalid

${IF_NOT_INVALID_CHOICE}
Activates the text following it if the last song selection was not invalid

${IF_DUPLICATE_CHOICE}
Activates the text following it if the last song selection was a duplicate choice

${IF_NOT_DUPLICATE_CHOICE}
Activates the text following it if the last song selection was not a duplicate choice

${IF_VISIBLE}
Activates the text following it if the status object is visible

${IF_NOT_VISIBLE}
Activates the text following it if the status object is invisible

${IF_FLAG_1_HI}
Activates the text following it if the specified status flag is high

${IF_FLAG_1_LO}
Activates the text following it if the specified status flag is low

${IF_FLAG_2_HI}
Activates the text following it if the specified status flag is high

${IF_FLAG_2_LO}
Activates the text following it if the specified status flag is low

${IF_FLAG_3_HI}
Activates the text following it if the specified status flag is high

${IF_FLAG_3_LO}
Activates the text following it if the specified status flag is low

${IF_FLAG_4_HI}
Activates the text following it if the specified status flag is high

${IF_FLAG_4_LO}
Activates the text following it if the specified status flag is low

${END_IF}
Marks the end of a text section playing by the preceding $IF_

${ELSE}
Complement to previous $IF condition

${IF_ANY_BUTTON_PRESSED}
Activates the text following it if any button is pressed

${IF_NOT_ANY_BUTTON_PRESSED}
Activates the text following it if any button is not pressed

${IF_BUTTON_QUIT_PRESSED}
Activates the text following it if the specified button is pressed

${IF_NOT_BUTTON_QUIT_PRESSED}
Activates the text following it if the specified button is not pressed

${IF_BUTTON_COIN1_PRESSED}
Activates the text following it if the specified button is pressed

${IF_NOT_BUTTON_COIN1_PRESSED}
Activates the text following it if the specified button is not pressed

${IF_BUTTON_COIN2_PRESSED}
Activates the text following it if the specified button is pressed

${IF_NOT_BUTTON_COIN2_PRESSED}
Activates the text following it if the specified button is not pressed

${IF_BUTTON_COIN3_PRESSED}
Activates the text following it if the specified button is pressed

${IF_NOT_BUTTON_COIN3_PRESSED}
Activates the text following it if the specified button is not pressed

${IF_BUTTON_COIN4_PRESSED}
Activates the text following it if the specified button is pressed

${IF_NOT_BUTTON_COIN4_PRESSED}
Activates the text following it if the specified button is not pressed

${IF_BUTTON_COIN5_PRESSED}
Activates the text following it if the specified button is pressed

${IF_NOT_BUTTON_COIN5_PRESSED}
Activates the text following it if the specified button is not pressed

${IF_BUTTON_COIN6_PRESSED}
Activates the text following it if the specified button is pressed

${IF_NOT_BUTTON_COIN6_PRESSED}
Activates the text following it if the specified button is not pressed

${IF_BUTTON_VOLUP_PRESSED}
Activates the text following it if the specified button is pressed

${IF_NOT_BUTTON_VOLUP_PRESSED}
Activates the text following it if the specified button is not pressed

${IF_BUTTON_VOLDOWN_PRESSED}
Activates the text following it if the specified button is pressed

${IF_NOT_BUTTON_VOLDOWN_PRESSED}
Activates the text following it if the specified button is not pressed

${IF_BUTTON_RANDOM_PRESSED}
Activates the text following it if the specified button is pressed

${IF_NOT_BUTTON_RANDOM_PRESSED}
Activates the text following it if the specified button is not pressed

${IF_BUTTON_SELECT_PRESSED}
Activates the text following it if the specified button is pressed

${IF_NOT_BUTTON_SELECT_PRESSED}
Activates the text following it if the specified button is not pressed

${IF_BUTTON_SKIP_PRESSED}
Activates the text following it if the specified button is pressed

${IF_NOT_BUTTON_SKIP_PRESSED}
Activates the text following it if the specified button is not pressed

${IF_BUTTON_PAUSE_PRESSED}
Activates the text following it if the specified button is pressed

${IF_NOT_BUTTON_PAUSE_PRESSED}
Activates the text following it if the specified button is not pressed

${IF_BUTTON_UP_PRESSED}
Activates the text following it if the specified button is pressed

${IF_NOT_BUTTON_UP_PRESSED}
Activates the text following it if the specified button is not pressed

${IF_BUTTON_DOWN_PRESSED}
Activates the text following it if the specified button is pressed

${IF_NOT_BUTTON_DOWN_PRESSED}
Activates the text following it if the specified button is not pressed

${IF_BUTTON_LEFT_PRESSED}
Activates the text following it if the specified button is pressed

${IF_NOT_BUTTON_LEFT_PRESSED}
Activates the text following it if the specified button is not pressed

${IF_BUTTON_RIGHT_PRESSED}
Activates the text following it if the specified button is pressed

${IF_NOT_BUTTON_RIGHT_PRESSED}
Activates the text following it if the specified button is not pressed

${IF_BUTTON_LEFT_SCREEN_PRESSED}
Activates the text following it if the specified button is pressed

${IF_NOT_BUTTON_LEFT_SCREEN_PRESSED}
Activates the text following it if the specified button is not pressed

${IF_BUTTON_RIGHT_SCREEN_PRESSED}
Activates the text following it if the specified button is pressed

${IF_NOT_BUTTON_RIGHT_SCREEN_PRESSED}
Activates the text following it if the specified button is not pressed

${IF_BUTTON_LEFT_SORT_PRESSED}
Activates the text following it if the specified button is pressed

${IF_NOT_BUTTON_LEFT_SORT_PRESSED}
Activates the text following it if the specified button is not pressed

${IF_BUTTON_RIGHT_SORT_PRESSED}
Activates the text following it if the specified button is pressed

${IF_NOT_BUTTON_RIGHT_SORT_PRESSED}
Activates the text following it if the specified button is not pressed

${IF_BUTTON_ATTRACT_PRESSED}
Activates the text following it if the specified button is pressed

${IF_NOT_BUTTON_ATTRACT_PRESSED}
Activates the text following it if the specified button is not pressed

${IF_BUTTON_LOOPQUEUE_PRESSED}
Activates the text following it if the specified button is pressed

${IF_NOT_BUTTON_LOOPQUEUE_PRESSED}
Activates the text following it if the specified button is not pressed

${IF_BUTTON_FREEPLAY_PRESSED}
Activates the text following it if the specified button is pressed

${IF_NOT_BUTTON_FREEPLAY_PRESSED}
Activates the text following it if the specified button is not pressed

${IF_BUTTON_CLEARQUEUE_PRESSED}
Activates the text following it if the specified button is pressed

${IF_NOT_BUTTON_CLEARQUEUE_PRESSED}
Activates the text following it if the specified button is not pressed

${IF_BUTTON_MUTE_PRESSED}
Activates the text following it if the specified button is pressed

${IF_NOT_BUTTON_MUTE_PRESSED}
Activates the text following it if the specified button is not pressed

${IF_BUTTON_0_PRESSED}
Activates the text following it if the specified button is pressed

${IF_NOT_BUTTON_0_PRESSED}
Activates the text following it if the specified button is not pressed

${IF_BUTTON_1_PRESSED}
Activates the text following it if the specified button is pressed

${IF_NOT_BUTTON_1_PRESSED}
Activates the text following it if the specified button is not pressed

${IF_BUTTON_2_PRESSED}
Activates the text following it if the specified button is pressed

${IF_NOT_BUTTON_2_PRESSED}
Activates the text following it if the specified button is not pressed

${IF_BUTTON_3_PRESSED}
Activates the text following it if the specified button is pressed

${IF_NOT_BUTTON_3_PRESSED}
Activates the text following it if the specified button is not pressed

${IF_BUTTON_4_PRESSED}
Activates the text following it if the specified button is pressed

${IF_NOT_BUTTON_4_PRESSED}
Activates the text following it if the specified button is not pressed

${IF_BUTTON_5_PRESSED}
Activates the text following it if the specified button is pressed

${IF_NOT_BUTTON_5_PRESSED}
Activates the text following it if the specified button is not pressed

${IF_BUTTON_6_PRESSED}
Activates the text following it if the specified button is pressed

${IF_NOT_BUTTON_6_PRESSED}
Activates the text following it if the specified button is not pressed

${IF_BUTTON_7_PRESSED}
Activates the text following it if the specified button is pressed

${IF_NOT_BUTTON_7_PRESSED}
Activates the text following it if the specified button is not pressed

${IF_BUTTON_8_PRESSED}
Activates the text following it if the specified button is pressed

${IF_NOT_BUTTON_8_PRESSED}
Activates the text following it if the specified button is not pressed

${IF_BUTTON_9_PRESSED}
Activates the text following it if the specified button is pressed

${IF_NOT_BUTTON_9_PRESSED}
Activates the text following it if the specified button is not pressed

${IF_BUTTON_A_PRESSED}
Activates the text following it if the specified button is pressed

${IF_NOT_BUTTON_A_PRESSED}
Activates the text following it if the specified button is not pressed

${IF_BUTTON_B_PRESSED}
Activates the text following it if the specified button is pressed

${IF_NOT_BUTTON_B_PRESSED}
Activates the text following it if the specified button is not pressed

${IF_BUTTON_C_PRESSED}
Activates the text following it if the specified button is pressed

${IF_NOT_BUTTON_C_PRESSED}
Activates the text following it if the specified button is not pressed

${IF_BUTTON_D_PRESSED}
Activates the text following it if the specified button is pressed

${IF_NOT_BUTTON_D_PRESSED}
Activates the text following it if the specified button is not pressed

${IF_BUTTON_E_PRESSED}
Activates the text following it if the specified button is pressed

${IF_NOT_BUTTON_E_PRESSED}
Activates the text following it if the specified button is not pressed

${IF_BUTTON_F_PRESSED}
Activates the text following it if the specified button is pressed

${IF_NOT_BUTTON_F_PRESSED}
Activates the text following it if the specified button is not pressed

${IF_BUTTON_G_PRESSED}
Activates the text following it if the specified button is pressed

${IF_NOT_BUTTON_G_PRESSED}
Activates the text following it if the specified button is not pressed

${IF_BUTTON_H_PRESSED}
Activates the text following it if the specified button is pressed

${IF_NOT_BUTTON_H_PRESSED}
Activates the text following it if the specified button is not pressed

${IF_BUTTON_I_PRESSED}
Activates the text following it if the specified button is pressed

${IF_NOT_BUTTON_I_PRESSED}
Activates the text following it if the specified button is not pressed

${IF_BUTTON_J_PRESSED}
Activates the text following it if the specified button is pressed

${IF_NOT_BUTTON_J_PRESSED}
Activates the text following it if the specified button is not pressed

${IF_BUTTON_K_PRESSED}
Activates the text following it if the specified button is pressed

${IF_NOT_BUTTON_K_PRESSED}
Activates the text following it if the specified button is not pressed

${IF_BUTTON_L_PRESSED}
Activates the text following it if the specified button is pressed

${IF_NOT_BUTTON_L_PRESSED}
Activates the text following it if the specified button is not pressed

${IF_BUTTON_M_PRESSED}
Activates the text following it if the specified button is pressed

${IF_NOT_BUTTON_M_PRESSED}
Activates the text following it if the specified button is not pressed

${IF_BUTTON_N_PRESSED}
Activates the text following it if the specified button is pressed

${IF_NOT_BUTTON_N_PRESSED}
Activates the text following it if the specified button is not pressed

${IF_BUTTON_O_PRESSED}
Activates the text following it if the specified button is pressed

${IF_NOT_BUTTON_O_PRESSED}
Activates the text following it if the specified button is not pressed

${IF_BUTTON_P_PRESSED}
Activates the text following it if the specified button is pressed

${IF_NOT_BUTTON_P_PRESSED}
Activates the text following it if the specified button is not pressed

${IF_BUTTON_Q_PRESSED}
Activates the text following it if the specified button is pressed

${IF_NOT_BUTTON_Q_PRESSED}
Activates the text following it if the specified button is not pressed

${IF_BUTTON_R_PRESSED}
Activates the text following it if the specified button is pressed

${IF_NOT_BUTTON_R_PRESSED}
Activates the text following it if the specified button is not pressed

${IF_BUTTON_S_PRESSED}
Activates the text following it if the specified button is pressed

${IF_NOT_BUTTON_S_PRESSED}
Activates the text following it if the specified button is not pressed

${IF_BUTTON_T_PRESSED}
Activates the text following it if the specified button is pressed

${IF_NOT_BUTTON_T_PRESSED}
Activates the text following it if the specified button is not pressed

${IF_BUTTON_U_PRESSED}
Activates the text following it if the specified button is pressed

${IF_NOT_BUTTON_U_PRESSED}
Activates the text following it if the specified button is not pressed

${IF_BUTTON_V_PRESSED}
Activates the text following it if the specified button is pressed

${IF_NOT_BUTTON_V_PRESSED}
Activates the text following it if the specified button is not pressed

${IF_BUTTON_W_PRESSED}
Activates the text following it if the specified button is pressed

${IF_NOT_BUTTON_W_PRESSED}
Activates the text following it if the specified button is not pressed

${IF_BUTTON_X_PRESSED}
Activates the text following it if the specified button is pressed

${IF_NOT_BUTTON_X_PRESSED}
Activates the text following it if the specified button is not pressed

${IF_BUTTON_Y_PRESSED}
Activates the text following it if the specified button is pressed

${IF_NOT_BUTTON_Y_PRESSED}
Activates the text following it if the specified button is not pressed

${IF_BUTTON_Z_PRESSED}
Activates the text following it if the specified button is pressed

${IF_NOT_BUTTON_Z_PRESSED}
Activates the text following it if the specified button is not pressed

${IF_BUTTON_POWER_OFF_PRESSED}
Activates the text following it if the specified button is pressed

${IF_NOT_BUTTON_POWER_OFF_PRESSED}
Activates the text following it if the specified button is not pressed

${IF_BUTTON_FLAG1_PRESSED}
Activates the text following it if the specified button is pressed

${IF_NOT_BUTTON_FLAG1_PRESSED}
Activates the text following it if the specified button is not pressed

${IF_BUTTON_FLAG2_PRESSED}
Activates the text following it if the specified button is pressed

${IF_NOT_BUTTON_FLAG2_PRESSED}
Activates the text following it if the specified button is not pressed

${IF_BUTTON_FLAG3_PRESSED}
Activates the text following it if the specified button is pressed

${IF_NOT_BUTTON_FLAG3_PRESSED}
Activates the text following it if the specified button is not pressed

${IF_BUTTON_FLAG4_PRESSED}

Activates the text following it if the specified button is pressed

${IF_NOT_BUTTON_FLAG4_PRESSED}
Activates the text following it if the specified button is not pressed

The variables beginning ${IF_*}, ${IF_NOT_*} and ${ELSE} are used to conditionally display or ignore the text in the config file which follows it, upto the next ${END_IF} (or end of the line).

Note that IF conditions cannot span lines in the text file (unless the line ends with the ‘\’ line concatentation character).

Variables which do not begin with ${IF specify dedicated jukebox status such as song names, etc.

Each line in the Contents file corresponds to a unique line in the status output, and are therefore treated separately.

A single line in the status object can be split across multiple lines in the Contents file, to aid readability.

If a line ends with the ‘\’ character, then it is joined with the following line, allowing long and/or complex expressions to be split across multiple lines, but treated as one line entry.

Each status box can also include images for cover art for the currently playing song, and other user defined bitmaps.
Any image will be scaled to cover the entire status box.

Hint: For best performance, it is advisable to limit the number of $ variables in a status box. It is better to group status variables together depending upon when they change; for example try not to mix status which changes regularly (like now playing elapsed time) with status that doesn’t change regularly (such as ‘coming up’ status) in one status box.
This is because the entire contents of a status box is re-drawn if just one element changes.

14: Sound Effects

Sound effects can be added in status objects by using the Sound parameter.
These are then referenced in the status Contents file using the ${PLAY_SOUND} and ${STOP_SOUND} variables.

This flexibility allows sound effects to be played under many different conditions, such as … button presses, song loading/unloading, coin insertion, title strip movements, song selections, etc.

15: Status Flags

Four status flags allow for inter-status communication and user triggered status events.

Each status flag can be set high or low from button presses (toggle) and/or status $variables.
The values of the flags can be read in status objects, allowing support for functionality such as…

1. Inter status communication:

for example one status object could toggle a flag with a certain timer tick period which could then be detected in a different status object with a different timer tick period. This would allow status to “time-out” after being started from a different timer period (or a button press).

2. Button invoked status display:

The ‘Flag*’ buttons can be used to turn on and off status information.

In addition to the above, the DynamicEnableFlag parameter in some display objects can be used to directly enable or disable any dynamic parameters the object has.

16: GPIO Input/Output

fruitbox can use the GPIO pins for both input and output:

When a button is defined which uses a GPIO pin, the GPIO pin is automatically configured as an input, with an internal pullup resistor. You then just have to ensure that the hardware button is connected between this GPIO pin and GND. Both normally-open and normally-closed switches are supported (fruitbox will auto-detect the type on power-up, so ensure no buttons are pressed when fruitbox is started).

When a ${SET_GPIO*} variable is encountered in a status object Contents file, the specified GPIO pin is automatically configured as an output.

Note that if the same pin is defined in both the button mapping file and a status object, then input will take precedence over the output, hence the status output will not work.

The fruitbox developer assumes no responsibility for any damage caused to the Raspberry Pi or connected hardware due to the use of the GPIO pins from fruitbox, so please make sure you choose your GPIO pin assignments carefully 😉