-
Notifications
You must be signed in to change notification settings - Fork 13
/
userguide.txt
2343 lines (1731 loc) · 120 KB
/
userguide.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1: Introduction
Welcome to fruitbox, a customisable, Retro MP3 Jukebox for the Raspberry Pi.
fruitbox attempts to emulate the operation of classic jukeboxes, by providing a music player which operates
on the principle of presenting songs on title strips, in which the user can select a song by turning
through pages of title strips, and selecting individual songs by entering a unique code for that song,
which is then entered into a play queue.
The look and feel of fruitbox is provided by 'skins', which are human readable text files which can be
created and modified by the user to create an almost infinite number of different jukebox styles.
fruitbox provides many customisable features, which are described in the 'Configuration (Skin) File'
sections of this user guide. A very brief (and by no means exhaustive) summary of its capabilities are...
-> MP3 or OGV (video) playback
-> MP3 playback from local files or URL streams (internet Radio)
-> Singles or Albums mode
-> Coin or Freeplay mode
-> Controls easily mappable to keyboards, USB controllers, GPIO, mouse or touch screens
-> Random song play (attract mode) with preview and fade effects
-> Output of Jukebox status via GPIO and/or text files for external status
-> Generation of title strip images for printing
fruitbox is free for non-commercial use. If you enjoy using fruitbox, and would like to encourage future
development, please consider making a donation to the author at https://paypal.me/rpifruitbox
2: Starting Up
fruitbox is intended to be run directly from the command line for maximum performance.
See section 'Command Line Options' for startup options.
3: Operation
To run fruitbox, from the command line goto the installation directory and type ./fruitbox
fruitbox will then read the skin list in the [skins] section of the fruitbox.ini file and present you
with a skin chooser to allow you to select your skin (unless there's only one skin defined in the [skins]
section. The skin chooser can be bypassed if you want to load a particular skin immediately by using
the '--skin' command line option and specifying a skin configuration file directly. For example ...
./fruitbox --skin skins/Wurly/fruitbox.cfg
See section 'Configuration (Skin) Files' for more detail about the contents of these files. After the
configuration file has been read, fruitbox will create the song database by searching through the MusicPath
directories (see section 'Database Creation'). When the database has been read, fruitbox will start!
Song title strips are moved using the 'Left' and 'Right' buttons, and songs are selected using the select
keys. Once a song is selected, it is added to the play queue. If no song is playing, the song at the
top of the play queue is 'loaded', played, and then 'unloaded'.
Control inputs (buttons) can be re-defined via an on-screen menu or direcrly editing the [buttons] section
of the fruitbox ini file.
4: Command Line Options
fruitbox takes the following command line parameters...
4.1: --help
Show basic help and version information.
4.2: --version
Reports the version number.
4.3: --skin <filename>
This option determines which skin (configuration file) is used. If omitted, then fruitbox will use the
[skins] section in the ini file to determine which skin to use. If more than one skin is defined in
the [skins] section, then fruitbox will allow the user to choose a skin from an on-screen menu.
4.4: --ini <filename>
Name of initialisation file (defaults to 'fruitbox.ini' if not specified). This file contains all the
non-skin specific fruitbox parameters.
4.5: --music-path <filepath>
Use the specified music path instead of the one specified in the skin or ini files. Note that the --music-path
option can be specified multiple times if the user wishes to construct the database from multiple sources.
4.6: --user-guide
Create this user-guide to file "userguide.txt".
4.7: --debug-song-nums
Show select code alongside song entries.
4.8: --no-database-refresh
Normally fruitbox will refresh the database if any database files (fruitbox.db) have a modification time
earler than the contents of the directories they are in. This option disables this check, so it is up
to the user to delete the database file(s) in order for them to be refreshed.
4.9: --force-database-refresh
Normally fruitbox will refresh the database if any database files (fruitbox.db) have a modification time
earler than the contents of the directories they are in. This option overrides this check, and always
refreshes the database file(s). This is useful if the user for example changes anything which is created
or used when the database is created (i.e. CustomMP3Tag).
4.10: --load-playlist <filename>
Loads a playlist file and populates the play queue with the songs in it; fruitbox will begin playing
the songs after it has started up.
4.11: --save-playlist <filename>
When fruitbox exits (by the user pressing the 'Quit' button), this option saves the contents of the play
queue (and currently playing song) to the specified file. This can subsequently be loaded back into
fruitbox using the '--load-playlist' command line argument. The playlist file contains a list of song
filenames which can easily be edited by hand to modify the playlist as required.
4.12: --dump-title-strips
This option causes every title strip to be written to a unique png image file. fruitbox will then quit
without running. If fruitbox is used in a real jukebox which has real (paper) title strips and not on-screen
ones, then this can be used to generate the title strips with real song data for printing out. The user
can modify the style and contents of the title strips in the usual way using skin parameters. In order
to supress the displaying of the actual title strips on the screen, you can just set the "Visible" flag
of each title strip to "No".
Note that the --dump-title-strips option must be used in conjunction with a specified skin (--skin option)
since the title strips are defined in the skin.
4.13: --display-size <width> <height>
This option specifies the size of the display that fruitbox creates when starting up. If not specified,
then the display size is auto-detected. The display size does not have to be the same as the skin size,
as fruitbox will scale the skin size to match the display size.
4.14: --no-scale
Normally fruitbox will scale (resize) the skin to the display, so no matter what its size, it will always
fit exactly. This option turns off the scaling so the skin will be shown at its original size (useful
for debugging skin designs). The skin will be centered on the display. If the skin is smaller than
the display then the skin will be surrounded by a black border, but if the skin is larger than the display,
the outer edges of the skin will not be visible.
4.15: --rotate <angle>
This option allows the display to be rotated by <angle> degrees. Please note that if using a touch based
skin, this will affect operation of the touch co-ordinates and the skin may have to be modified.
5: Initialisation File
When starting up, fruitbox looks for an initialisation file (default 'fruitbox.ini') in the same directory
it is run from, which contains settings which are not skin-specific. The command line option --ini can
be used to specify an alternative ini file. If no ini file is found, it will be created, and you can
manually edit it later. The following list shows each parameter in each section. Note that some of
these parameters can also be changed directly from the main menu (accessible via the 'Menu' button).
Note that entries marked with a '*' means that these groups / parameters can be defined multiple times.
Note also that if a touchscreen is detected and the [touch screen] section is not defined (or incomplete),
the touch screen calibration is automatically run.
[general]
MusicPath * <filename> of path to music files (mp3, ogv, m3u, pls). Can contain sub-directories.
CustomMP3Tag <name> of an MP3 ID3v2 tag the user wishes to extract to a song's 'Custom' field (e.g. "TCON" is content type)
Note: this is only used during database file *creation*
MaxPlayQueueLength <number> Maximum number of songs which can be stored in the coming up queue
LoopPlayQueue <yes|no>
Yes : a song is added to the back of the play queue when it has finished playing (credits permitting)
Note this option is ignored if the [general] NoDuplicates parameter is enabled in the skin configuration file
IgnoreArtistPrefixThe <yes|no>
Yes : ignore 'The ' beginning word in artist names
SongHistoryDepth <number> Determines the search range of number of previously played songs to ensure
no repeated songs are chosen in Attract mode or Random selection.
If not specified or set to zero, fruitbox will only check for
repeated songs from within the play queue
SongHistoryIncludeUserSelection <yes|no> User selection is included or excluded from the history search
SongVolume <volume> Initial song volume (0..100)
SongVolumeStep <step> Song volume step (0..100) (amount changed for VolumeUp / VolumeDown)
ReplayGain <none|track|album> (automatic gain adjustment - requires MP3 ReplayGain tag data)
FreePlay <yes|no>
Yes : Credits/coins are not required to add a song to the play queue
CreditsPerCoin1 <number> of song credits added when a coin is inserted
CreditsPerCoin2 <number> of song credits added when a coin is inserted
CreditsPerCoin3 <number> of song credits added when a coin is inserted
CreditsPerCoin4 <number> of song credits added when a coin is inserted
CreditsPerCoin5 <number> of song credits added when a coin is inserted
CreditsPerCoin6 <number> of song credits added when a coin is inserted
CreditsPerSong <number> of song credits required to play one song
MenuColour <r> <g> <b> Modify the on-screen menu colour
MenuBackgroundColour <r> <g> <b> <a> Modify the on-screen menu background colour
SkinChooserTimeout <time> [ticks|seconds|minutes|hours] time before skin chooser starts current skin if no choice made
A value of zero or not defined disables timeout
[attract mode]
Enable <yes|no>
Yes : a random song is played if the play queue is empty and no songs are playing
Choice <random|sorted>
Determines if the songs in attract mode are selected randomly or in the order in which they are sorted
Interval <time> [ticks|seconds|minutes|hours] The time between a random song being selected and played after the last song has finished playing
MaxVolume <0 to 100> Maximum volume of attract mode song (with respect to current volume level)
FadeIn <time> [ticks|seconds|minutes|hours] Length of fade in time of attract mode song (0 = no fade in)
FadeOut <time> [ticks|seconds|minutes|hours] Length of fade out time of attract mode song (0 = no fade out)
FadeInPosition <time> [ticks|seconds|minutes|hours] Start time of attract mode song
FadeOutPosition <time> [ticks|seconds|minutes|hours] Stop time of attract mode song
SkipLoad <yes|no>
Yes : attract mode songs don't invoke load / unload sequences
[skins]
File * <filename> of skin configuration file
[buttons]
Quit <name> of button (quit fruitbox)
Coin1 <name> of button (insert coin)
Coin2 <name> of button (insert coin)
Coin3 <name> of button (insert coin)
Coin4 <name> of button (insert coin)
Coin5 <name> of button (insert coin)
Coin6 <name> of button (insert coin)
VolUp <name> of button (change volume)
VolDown <name> of button (change volume)
Random <name> of button (select random song)
Select <name> of button (play selected song)
Skip <name> of button (stop current song)
Pause <name> of button (pause/unpause currently playing song)
Up <name> of button (joystick selector)
Down <name> of button (joystick selector)
Left <name> of button (move title_strips/joystick selector)
Right <name> of button (move title_strips/joystick selector)
LeftScreen <name> of button (move title_strips by 'ScreenJump' amount)
RightScreen <name> of button (move title_strips by 'ScreenJump' amount)
LeftSort <name> of button (move title_strips by last 'SortSongsBy' value)
RightSort <name> of button (move title_strips by last 'SortSongsBy' value)
AttractMode <name> of button (toggle Attract mode)
LoopQueue <name> of button (toggle Loop mode)
FreePlay <name> of button (toggle Freeplay mode)
ClearQueue <name> of button (empty play queue)
Mute <name> of button (volume mute)
PowerOff <name> of button (power off)
Select0 <name> of button (song selection)
Select1 <name> of button (song selection)
Select2 <name> of button (song selection)
Select3 <name> of button (song selection)
Select4 <name> of button (song selection)
Select5 <name> of button (song selection)
Select6 <name> of button (song selection)
Select7 <name> of button (song selection)
Select8 <name> of button (song selection)
Select9 <name> of button (song selection)
SelectA <name> of button (song selection)
SelectB <name> of button (song selection)
SelectC <name> of button (song selection)
SelectD <name> of button (song selection)
SelectE <name> of button (song selection)
SelectF <name> of button (song selection)
SelectG <name> of button (song selection)
SelectH <name> of button (song selection)
SelectI <name> of button (song selection)
SelectJ <name> of button (song selection)
SelectK <name> of button (song selection)
SelectL <name> of button (song selection)
SelectM <name> of button (song selection)
SelectN <name> of button (song selection)
SelectO <name> of button (song selection)
SelectP <name> of button (song selection)
SelectQ <name> of button (song selection)
SelectR <name> of button (song selection)
SelectS <name> of button (song selection)
SelectT <name> of button (song selection)
SelectU <name> of button (song selection)
SelectV <name> of button (song selection)
SelectW <name> of button (song selection)
SelectX <name> of button (song selection)
SelectY <name> of button (song selection)
SelectZ <name> of button (song selection)
Flag1 <name> of button (toggle status flag)
Flag2 <name> of button (toggle status flag)
Flag3 <name> of button (toggle status flag)
Flag4 <name> of button (toggle status flag)
Menu <name> of button (fruitbox menu)
Search <name> of button (song search/filter)
Mouse <name> of button (mouse select)
Screenshot <name> of button (take screenshot)
[touch screen]
Enable <yes|no>
Yes : touch screen control is enabled
TopLeft <x> <y> (the touch co-ordinates for top left of touch display)
BottomRight <x> <y> (the touch co-ordinates for bottom right of touch display)
[mouse]
Enable <yes|no>
Yes : mouse control is enabled
Bitmap <filename> of graphic image (bmp, png, tga, jpg, pcx)
Size <width> <height> (in pixels)
Angle <angle> of object in degrees (0..359)
Tint <r> <g> <b> <a> (modify the objects colour)
HorizontalFlip <yes|no> flip object horizontally
VerticalFlip <yes|no> flip object vertically
HotSpot <x> <y> (offset in pixels from top left corner of mouse pointer which corresponds to the click position)
Sensitivity <0.0 .. > sensitivity of mouse movement (1.0 nominal, higher is more sensitive)
HideAfter <time> [ticks|seconds|minutes|hours] (Hide inactive mouse pointer after this time. 0 = don't hide)
[joystick]
Enable <yes|no>
Yes : joystick control is enabled
DisableTitleStripFlip <yes|no>
Yes : Title Strip flipping is prevented using left/right in joystick mode
Bitmap <filename> of graphic image (bmp, png, tga, jpg, pcx)
Size <width> <height> (in pixels)
Angle <angle> of object in degrees (0..359)
Tint <r> <g> <b> <a> (modify the objects colour)
HorizontalFlip <yes|no> flip object horizontally
VerticalFlip <yes|no> flip object vertically
Offset <x> <y> (offset in pixels from top left corner of joystick highlight in song title region)
6: Skin Selection
If fruitbox is run with the --skin <file> command line option, that skin will be immediately loaded and
used. If no --skin option is specified, fruitbox will invoke the skin chooser for you to select a skin
from the list of skins specified in the [skins] section of the ini file. If the [skins] list contains
only one entry, then the skin chooser is not invoked and the skin immediately loaded, in the same way
as if it were specified from the --skin command line argument.
7: Database Creation
Once fruitbox has read the skin file and found no problems, it will try to load the music database.
The database is built from multiple 'fruitbox.db' files which are created in each sub-directory in the
MusicPath(s) which contain music files (mp3, ogv, m3u, pls). Each fruitbox.db file contains a list of
music files in that directory, along with their extracted metadata (mp3 tags). If fruitbox finds music
files without an accompanying fruitbox.db file, it will create a fruitbox.db file in that directory.
This may take some time as fruitbox extracts the metadata from the music file(s), but only needs to be
done once, so subsequent fruitbox start-ups will be much faster. If fruitbox detects that an existing
fruitbox.db file has been modified earlier than the directory it is in (for example if music files have
been added or removed), it will automatically refresh the fruitbox.db file (unless the --no-database-refresh
command line option is specified).
MusicPath(s) can be specified in one of three places; fruitbox ini file, skin configuration file or --music-path
command line option(s). They can be defined in more than one place, but the --music-path option overrides
the skin configuration file, which in turn overrides the fruitbox ini file.
The database files can be edited by hand in a standard text editor if you have small changes to make
or are feeling brave! This can be useful if you wish to tweak the song details, without having to re-generate
the database from scratch. Note that the song order in the database files are irrelevant; after fruitbox
has read the songs from the database files it will sort them according to the 'SortSongsBy' configuration
parameter(s).
7.1: MP3 File Support
During database creation, any file in the MusicPath (or sub-directories) with .mp3 extension will be
added to the database. fruitbox will extract the mp3 metadata tag values (title, artist, album, etc.)
from the files and store these details in the database files for faster subsequent start-up of fruitbox.
7.2: Video (OGV) File Support
fruitbox can play video files if they are in ogv format (Vorbis + Theora). During database creation,
any file in the MusicPath (or sub-directories) with .ogv extension will be added to the database. fruitbox
cannot extract metadata from the ogv files, so will extract the artist and song title name from the filename
if the filename (excluding .ogv extension) has the format "Artist - Title", and set all other fields
(album, genre, etc) to Unknown. The user can subsequently edit the database file to manually add meaningful
names to the unknown fields.
Any video format can be converted to ogv format using for example ffmpeg with the following options for
specifying the video bitrate and video picture size...
ffmpeg -i MyVideo.mp4 -b:v 2M -vf scale=640x480 MyVideo.ogv
NOTE: ffmpeg versions above 4.1 onwards seem to cause corruption of the video. It is recommended
to use ffmpeg version 4.0.2 (or older) ... see: https://www.videohelp.com/software/ffmpeg/old-versions
Since the video decoding process is quite CPU intensive, it is recommended that a Quad core Pi is used
(Model 2 or 3) with a good PSU (at least 2 Amps) when running fruitbox and skins with video content,
and the display resolution is kept low (less than 1024x768).
7.3: MP3 Stream (Internet Radio) Support
fruitbox can play mp3 files sourced from url streams (internet radio). During database creation, any
file in the MusicPath (or sub-directories) with .pls or .m3u extensions will be added to the database.
For .m3u files, fruitbox will first extract the Artist and Title names from the #EXTINF entries (if in
the format "Artist - Title"). For .pls files, for each File* entry, fruitbox will first extract the
Title from it's corresponding Title* entry.
For both .m3u and .pls files, fruitbox will request the ICY Header from the stream server (during database
creation) and, if available, assign the icy-name to the Title name, and the icy-description to the Artist
name. During playback of mp3 streams, fruitbox will extract ICY (SHOUTcast) metadata to display real-time
StreamTitle information (ie. currently playing song).
Note: .pls and .m3u files for internet radio stations can be found on the internet. A good source is
https://www.internet-radio.com/
8: Input Control Buttons
The fruitbox input controls can be modified via the Controls menu. By default, the buttons are mapped
to keyboard keys (see section 'Default Buttons'), but each key can be re-mapped to any of the following...
1. Keyboard key
2. GPIO input pin
3. USB game controllers (joystick stick / button)
4. Region on touch screen
For touch screen buttons, the touch areas are defined in the skin file itself, using the [touch buttons]
section, because these are skin-related. If any buttons are defined in the skins' [touch buttons] section
and a touch screen is detected, the user-defined mapping for that button is ignored and set to touch
input.
8.1: Default Buttons
The button controls are mapped to the following keyboard keys by default, but can be re-mapped to other
keyboard keys, GPIO inputs, USB game controllers or touch screen inputs defined in the fruitbox ini file.
Keyboard Key fruitbox button Description
--------------- ------------------- --------------------------
LEFT : Left .............. Move title strips left
RIGHT : Right ............. Move title strips right
[ : LeftScreen ........ Move to previous screen
] : RightScreen ....... Move to next screen
, : LeftSort .......... Move to prev sort section*
. : RightSort ......... Move to next sort section*
UP : Up ................ Move song selection up (joystick mode only)
DOWN : Down .............. Move song selection down (joystick mode only)
0 to 9 / A to Z : Select0..SelectZ .. Song selection
ENTER : Select ............ Select song
F1 : Coin1 ............. Insert coin
F2 : Coin2 ............. Insert coin
F3 : Coin3 ............. Insert coin
F4 : Coin4 ............. Insert coin
F5 : Coin5 ............. Insert coin
F6 : Coin6 ............. Insert coin
F7 : Flag1 ............. Toggle status flag 1
F8 : Flag2 ............. Toggle status flag 2
F9 : Flag3 ............. Toggle status flag 3
F10 : Flag4 ............. Toggle status flag 4
SPACE : Random ............ Select random song
BACKSPACE : Skip .............. Skip (stops currently playing song)
; : Pause ............. pause (pauses/unpauses currently playing song)
' : AttractMode ....... Toggle Attract Mode
F11 : LoopQueue ......... Toggle Loop mode
F12 : FreePlay .......... Toggle Free Play mode
DELETE : ClearQueue ........ Clear all songs in play queue
= : VolUp ............. Song volume up
- : VolDown ........... Song volume down
LEFT CTRL : Mute .............. Mute / Unmute song and sound effects
RIGHT CTRL : Screenshot ........ Take Screenshot
FORWARD SLASH : Search ............ Search Filter Menu
TAB : Menu .............. Main Menu
ESC : Quit .............. Quit fruitbox
SYSRQ : PowerOff .......... Power off Raspberry Pi
* The sort sections start with a new letter of the alphabet corresponding to the last SortSongsBy value.
For example, if the last SortSongsBy = Artist, and the currently displayed artists begin with 'B', then
pressing 'LeftSort' will move to the screen which contains the first title strip which contains the first
Artist beginning with the letter 'A'.
The 'Screenshot' button is used to capture the screen, and write the image to 'screenshot.jpg' in the
skin directory by default or the value of the 'Screenshot' parameter in the skin configuration file.
8.2: Touch Screen and Mouse Support
If a touch screen is detected and the skin is designed to support touch input, then fruitbox can use
the touch screen to accept button presses. Song selection by pressing the song title within the title
strips themselves can also be supported. The [touch screen] section in the fruitbox ini file defines
the calibrated touch co-ordinates for the detected touch screen. If no calibration values are present
in the ini file, fruitbox will automatically run the touch screen calibration on start-up. To run touch
screen calibration again, simply delete the [touch screen] section in the fruitbox ini file, or select
'Calibrate Touchscreen' through the Main menu 'Controls' option.
If no touch screen is detected but a [mouse] is defined in the fruitbox ini file, then if a mouse is
connected it can be used instead of a touch screen, using the touch defined areas in the skin file.
Parameters in the [mouse] section of the ini file can be used to modify the look and behaviour of the
visible mouse pointer.
9: On-screen Menus
Buttons 'Menu' and 'Search' provide access to on-screen menus. Each menu can be controlled directly by
touch if a touchscreen is installed, or via the buttons or mouse if not. For mouse or touch operation,
an on-screen keyboard is displayed, otherwise the mapped fruitbox buttons are used. In the latter case,
the Left and Right keys are used to choose the menu option(s), any other button will select it. After
selection, the value can be changed by using left/right (boolean or numeric values), or buttons '0' to
'9' and 'A' to 'Z' for strings. For string entry, 'Left' is used to delete the last character and 'Right'
is used to insert a space. Any other button will exit the editing mode.
9.1: Main Menu
The main menu gives access to Global Settings, Button Configuration, Software Update, About information,
and Power Off.
9.2: Search Menu
The search menu allows the user to filter out songs in the database, in order to find specific songs.
Several filter fields are provided, and entering text into a field causes fruitbox to search for songs
containing text within that criteria. For example...
If the text 'Bea' is entered into the Artist field, then fruitbox will only display Artists whose name
contains 'Bea' (so for example, 'The Beatles', 'The Beach Boys', 'Bronski Beat', etc.). If more than
one field contains text, then all non-empty fields must be satisfied for the song to be displayed (i.e.
Artist : Bea and Year : 1965, will only display songs if the Artist name contains 'Bea', and they are
from 1965). Hint: entering for example '198' into the Year field will display all songs from the 1980s.
10: Troubleshooting
Poor graphics performance is usually caused by not allocating enough memory to the GPU. If the display
is very sluggish, or is corrupted / flashing white, quit fruitbox and check for any 'GetError_0x505'
messages. These messages mean the GPU hasn't got enough memory to create the graphics in video memory,
so has to use (slower) CPU memory instead. To fix this, change the Raspberry Pi memory split using the
Advanced Options in the raspi-config (type 'sudo raspi-config' from the command line). 256M is recommended
for the GPU, but more may be needed if the skin contains lots of large graphics objects.
11: Hints and Tips
Automatically run fruitbox on power up
--------------------------------------
To run fruitbox automatically on power up, add the following lines to /etc/rc.local :
cd <directory where fruitbox is installed>
./fruitbox --skin <your cfg file>
Automatically mount USB memory stick on power up
------------------------------------------------
If your music is stored on a USB memory stick, you can automatically mount the USB memory stick at boot
time by typing the following commands:
sudo mkdir -p /mnt/usb
sudo nano /etc/fstab
When inside the nano editor, add the following line at the end of the table...
/dev/sda1 /mnt/usb vfat defaults,nofail 0 0
Save (Ctrl-O), then Quit nano (Ctrl-X). Then in your fruitbox ini file, set the 'MusicPath' parameter
to '/mnt/usb/'
Quick fruitbox style change using USB memory sticks
---------------------------------------------------
As a general tip, you can store the configuration file on a USB memory stick along with the music, and
run fruitbox using the command './fruitbox --skin /mnt/usb/fruitbox.cfg'. That way, you could have a
complete jukebox look and feel with specific music all self-contained on the USB stick, so then all you
need to do to change jukebox styles and music collections is to swap USB sticks...
Let's Rock!
If you wish to design your own skins, please read on...
12: Configuration (Skin) Files
Configuration files (skins) define the look and feel of fruitbox. A configuration file is a human-readable
text file containing a list of parameters and their values. Parameters are grouped into sections, where
each section is defined by its name enclosed in square brackets, followed by the parameter list for that
section. The order of sections is not important except when the section refers to a display object,
in which case the order of the sections determines the render order on the display.
A parameter is defined by specifying its name, followed by its parameter value(s). The parameter name
and values can be separated by whitespace, = or :. Parameter values can be strings, numeric decimal
values, or boolean values (true, false, enable, disable, on, off, yes, no, 0, 1).
Parameter values in <> brackets are compulsory, and those in [] are optional.
Comments can be included in the configuration file by prefixing any comment text with the '#' character.
The following list shows all the possible parameters for each section. If a parameter is not specified
in the configuration file, fruitbox will use a default value.
Note that entries marked with a '*' means that these groups / parameters can be defined multiple times.
Note: filenames for 'MusicPath' parameters have file paths relative to the directory fruitbox was run
from, whereas filenames for all other parameters (sound files, bitmap files, status text files, font
files) have paths which are relative to the directory the configuration file itself is in. This allows
configuration files and their associated content files to be kept together, but easily share common MusicPath(s)
with other skins.
[general]
SkinSize <width> <height> Size of the skin (in pixels).
The skin is scaled to match the full screen size of the display
SkinName <name> of the skin
SkinVersion <version string> of the skin
SkinDescription * <description> of the skin
Screenshot <filename> of screenshot capture
MusicPath * <filename> of path to music files (mp3, ogv, m3u, pls). Can contain sub-directories.
SortSongsBy * <title|artist|album|albumArtist|year|genre|trackNumber|publisher|ISRC|custom|random|unsorted> [Descend|Ascend]
optional [Descend|Ascend] is sort direction (Ascend if not specified)
NoDuplicates <yes|no> Prevent songs being added to the playqueue if they are already in the playqueue
Note enabling this option disables the [general] LoopPlayQueue parameter
DuplicatesUseCredits <yes|no> Determines if a selected song which is already playing or in the queue (duplicate song)
uses up a credit
SelectButtons * List of characters for the select code for the button presses
SelectButtonsSequence <rowcol|colrow>
colrow : SelectButton sequences are cycled in order they are defined
rowcol : SelectButton sequences are cycled in reverse order they are defined
AutoSelect <yes|no>
No : Select button needs to be pressed to select song (after the select code is entered)
Yes : song selected immediately select code is entered
InstantPlay <yes|no>
No : selected song is queued in the coming up list
Yes : selected is immediately played (and any currently playing song is stopped)
ScreenJump <number> of screens of title strips moved in one go when 'LeftScreen' or 'RightScreen' button is pressed
SelectTimeout <time> [ticks|seconds|minutes|hours] Timeout for select code to return to undefined after not detecting all the selection digits
SelectHoldTimeout <time> [ticks|seconds|minutes|hours] Timeout for select code to return to undefined after song selected
TitleStripAutoTurnTime <time> [ticks|seconds|minutes|hours] Time between title_strips automatically turning (0 = no automatic title strip turn)
AttractModeGenre * <name> of Genre. Pressing AttractMode button will cycle through all AttractModeGenre definitions (and 'Off'
and 'Any') and only select a random song from that Genre **
SongsPerTitleStrip <number> of song entries on each song title strip
AlbumMode <yes|no>
Yes : Songs are grouped and selected by Album
No : Songs are selected individually
TitleStripSize <width> <height> (in pixels) of each song title strip
TitleStripBackground <filename> [genre]
Filename of graphic image (bmp, png, tga, jpg, pcx) to be used as the title strip background
Optional Genre string is name of genre specific title strip background
PairSongs <yes|no|dual>
No : each song in a title strip is listed with its artist line
Yes : two songs are displayed (above and below) the artist line only if they are by the same artist
Dual : two songs are displayed (above and below) the artist line regardless of artist
TitleStripMoveStyle <effect> <speed> <fading>. See section 'TitleStrips'
SongDescription <string> defining the song description for the song entry (first in a pair) in the title_strips.
Can contain a mixture of fixed text and reserved keywords
See 'TitleStrips section' for details.
PairedSongDescription <string> defining the song description for the second song in a pair
NOTE: In Albums mode ([general] AlbumMode = yes) this determines the Album Title line
ArtistDescription <string> defining the artist description in the title_strips (same values as 'SongDescription')
MatchedArtistDescription <string> used instead of 'ArtistDescription' if the artists of the songs in a pair are the same
(or the second song in a pair is absent)
ExtraDescription * <string> defining the extra description in the title_strips (same values as 'SongDescription')
Note that each entry must have a corresponding "ExtraText" entry
SongLoadTime <time> [ticks|seconds|minutes|hours] the time the song takes to load (from removing from the coming up queue to starting to play)
SongUnloadTime <time> [ticks|seconds|minutes|hours] the time the song takes to unload (from finishing playing to the next song in the queue loading)
SongText <font> <colour (r g b a)> <alignment> <capitalise> <mode> <quoted> <offset (x y)> <max_width>
Text style for Song title in song title strip. See section 'Fonts and Text'
PairedSongText <font> <colour (r g b a)> <alignment> <capitalise> <mode> <quoted> <offset (x y)> <max_width>
Text style for the paired Song title in song title strip. See section 'Fonts and Text'
ArtistText <font> <colour (r g b a)> <alignment> <capitalise> <mode> <quoted> <offset (x y)> <max_width>
Text style for Artist name in song title strip. See section 'Fonts and Text'
AlbumText <font> <colour (r g b a)> <alignment> <capitalise> <mode> <quoted> <offset (x y)> <max_width>
Text style for Album name in song title strip. See section 'Fonts and Text'
ExtraText * <font> <colour (r g b a)> <alignment> <capitalise> <mode> <quoted> <offset (x y)> <max_width>
Text style for the extra text field(s) in song title strip. See section 'Fonts and Text'
Note that this must be defined for each definition of "ExtraDescription"
AlbumArtSize <width> <height> (in pixels)
AlbumArtOffset <x> <y> Offset from top left hand corner of songs title strip (in pixels)
AlbumArtAngle <angle> of Album artwork in degrees (0..359)
AlbumModeLineSpacing <gap> (in pixels) between song titles in the albums song title_strips
NowPlayingMissingArtwork <filename> of graphic image (bmp, png, tga, jpg, pcx) to be used if NowPlayingArtworkMode = 'Specified',
or no song artwork is found and NowPlayingArtworkMode = 'Auto'
AlbumModeMissingArtwork <filename> of graphic image (bmp, png, tga, jpg, pcx) to be used if AlbumModeArtworkMode = 'Specified',
or no song artwork is found and AlbumModeArtworkMode = 'Auto'
NowPlayingArtworkMode <none|embedded|folder|specified|logo|a>
none : don't show artwork,
embedded : use image in MP3 file,
folder : use 'folder.jpg' in song directory,
specified : use MissingArtwork image,
logo : use fruitbox logo,
auto : use embedded/folder/missing/logo if available
AlbumModeArtworkMode <none|folder|specified|logo|auto>
none : don't show artwork,
folder : use 'folder.jpg' in song directory,
specified : use MissingArtwork image,
logo : use fruitbox logo,
auto : use folder/missing/logo if available
[fonts]
File * <filename> <height> font to add to the font pool (ttf, opentype, type1, CID, CFF, fon, fnt, x11, pcf)
[title strip] *
Visible <yes|no> (makes the object visible or invisible)
Position <x> <y> (in pixels)
Clip <x> <y> <width> <height> (in pixels)
Angle <angle> of object in degrees (0..359)
MoveDelay <delay> (in video frame ticks) between left/right button press and title strip moving
MoveReverse <yes|no> reverse the direction of the title strip movement
HorizontalFlip <yes|no> flip object horizontally
VerticalFlip <yes|no> flip object vertically
Tint <r> <g> <b> <a> (modify the objects colour)
[status] *
Visible <yes|no> (makes the object visible or invisible)
Size <width> [dynamic] <height> [dynamic] (in pixels)
Position <x> [dynamic] <y> [dynamic] (in pixels)
Clip <x> [dynamic] <y> [dynamic] <width> [dynamic] <height> [dynamic] (in pixels)
Angle <angle> [dynamic] of object in degrees (0..359)
Tint <r> [dynamic] <g> [dynamic] <b> [dynamic] <a> [dynamic] (modify the objects colour)
DynamicEnableFlag <1..4> enable dynamic parameters using status flag 1..4
HorizontalFlip <yes|no> flip object horizontally
VerticalFlip <yes|no> flip object vertically
Contents <filename> of text file describing status box contents
Output <filename> of output text file containing status
Text <font> <colour (r g b a)> <alignment> <capitalise> <mode> <quoted> <offset (x y)> <max_width>
LineSpacing <gap> (in pixels) between text lines in the status box
LoopVideo <yes|no> start video from beginning after it finishes
TimerTickPeriod <time> (in video frame ticks) of status box timer period
TimerOneShot <yes|no>
Yes : timer stops after one tick
No : timer runs indefinitely (default)
TimerEnable <yes|no>
Yes : timer initially enabled (default)
No : timer initially disabled)
BitmapDirectory <location> of image files (bmp, jpg, png)
Bitmap * <filename> of graphic image (bmp, png, tga, jpg, pcx)
Video <filename> of video clip (ogv)
Sound <filename> of sound effect (wav, flac, ogg) <volume (0..100)> [loop (Yes|No)]
[bitmap] *
Visible <yes|no> (makes the object visible or invisible)
Size <width> [dynamic] <height> [dynamic] (in pixels)
Position <x> [dynamic] <y> [dynamic] (in pixels)
Clip <x> [dynamic] <y> [dynamic] <width> [dynamic] <height> [dynamic] (in pixels)
Angle <angle> [dynamic] of object in degrees (0..359)
Tint <r> [dynamic] <g> [dynamic] <b> [dynamic] <a> [dynamic] (modify the objects colour)
DynamicEnableFlag <1..4> enable dynamic parameters using status flag 1..4
HorizontalFlip <yes|no> flip object horizontally
VerticalFlip <yes|no> flip object vertically
File <filename> of graphic image (bmp, png, tga, jpg, pcx)
[spectrum] *
Visible <yes|no> (makes the object visible or invisible)
Size <width> [dynamic] <height> [dynamic] (in pixels)
Position <x> [dynamic] <y> [dynamic] (in pixels)
Clip <x> [dynamic] <y> [dynamic] <width> [dynamic] <height> [dynamic] (in pixels)
Angle <angle> [dynamic] of object in degrees (0..359)
Tint <r> [dynamic] <g> [dynamic] <b> [dynamic] <a> [dynamic] (modify the objects colour)
DynamicEnableFlag <1..4> enable dynamic parameters using status flag 1..4
HorizontalFlip <yes|no> flip object horizontally
VerticalFlip <yes|no> flip object vertically
Bitmap <filename> of band(s) graphic image (bmp, png, tga, jpg, pcx)
Band * <number (0..31)> [gain (1.0 nominal)] [offset (x y)] [tint (r g b a)] of visible frequency band
Note: the tint is applied in addition to the global [spectrum] Tint
Mode <scaled|clipped|position> bitmap draw mode
Channel <left|right|both>
Decay <value> speed of peak decay (0=instant)
[touch song]
Bitmap <filename> of graphic image (bmp, png, tga, jpg, pcx).
Image to overlay on title strip song name when touched
Note: Defining this parameter will enable touch song mode
Offset <x> <y> (offset in pixels from top left corner of song touch highlight in song title region)
Size <width> <height> (in pixels). If not specified the size will be set to cover the song title exactly
Angle <angle> of object in degrees (0..359)
HorizontalFlip <yes|no> flip object horizontally
VerticalFlip <yes|no> flip object vertically
Tint <r> <g> <b> <a> (modify the objects colour)
[touch buttons]
Quit <x> <y> <width> <height> [bitmap] (touch area of button, optional bitmap to draw when touched)
Coin1 <x> <y> <width> <height> [bitmap] (touch area of button, optional bitmap to draw when touched)
Coin2 <x> <y> <width> <height> [bitmap] (touch area of button, optional bitmap to draw when touched)
Coin3 <x> <y> <width> <height> [bitmap] (touch area of button, optional bitmap to draw when touched)
Coin4 <x> <y> <width> <height> [bitmap] (touch area of button, optional bitmap to draw when touched)
Coin5 <x> <y> <width> <height> [bitmap] (touch area of button, optional bitmap to draw when touched)
Coin6 <x> <y> <width> <height> [bitmap] (touch area of button, optional bitmap to draw when touched)
VolUp <x> <y> <width> <height> [bitmap] (touch area of button, optional bitmap to draw when touched)
VolDown <x> <y> <width> <height> [bitmap] (touch area of button, optional bitmap to draw when touched)
Random <x> <y> <width> <height> [bitmap] (touch area of button, optional bitmap to draw when touched)
Select <x> <y> <width> <height> [bitmap] (touch area of button, optional bitmap to draw when touched)
Skip <x> <y> <width> <height> [bitmap] (touch area of button, optional bitmap to draw when touched)
Pause <x> <y> <width> <height> [bitmap] (touch area of button, optional bitmap to draw when touched)
Up <x> <y> <width> <height> [bitmap] (touch area of button, optional bitmap to draw when touched)
Down <x> <y> <width> <height> [bitmap] (touch area of button, optional bitmap to draw when touched)
Left <x> <y> <width> <height> [bitmap] (touch area of button, optional bitmap to draw when touched)
Right <x> <y> <width> <height> [bitmap] (touch area of button, optional bitmap to draw when touched)
LeftScreen <x> <y> <width> <height> [bitmap] (touch area of button, optional bitmap to draw when touched)
RightScreen <x> <y> <width> <height> [bitmap] (touch area of button, optional bitmap to draw when touched)
LeftSort <x> <y> <width> <height> [bitmap] (touch area of button, optional bitmap to draw when touched)
RightSort <x> <y> <width> <height> [bitmap] (touch area of button, optional bitmap to draw when touched)
AttractMode <x> <y> <width> <height> [bitmap] (touch area of button, optional bitmap to draw when touched)
LoopQueue <x> <y> <width> <height> [bitmap] (touch area of button, optional bitmap to draw when touched)
FreePlay <x> <y> <width> <height> [bitmap] (touch area of button, optional bitmap to draw when touched)
ClearQueue <x> <y> <width> <height> [bitmap] (touch area of button, optional bitmap to draw when touched)
Mute <x> <y> <width> <height> [bitmap] (touch area of button, optional bitmap to draw when touched)
PowerOff <x> <y> <width> <height> [bitmap] (touch area of button, optional bitmap to draw when touched)
Select0 <x> <y> <width> <height> [bitmap] (touch area of button, optional bitmap to draw when touched)
Select1 <x> <y> <width> <height> [bitmap] (touch area of button, optional bitmap to draw when touched)
Select2 <x> <y> <width> <height> [bitmap] (touch area of button, optional bitmap to draw when touched)
Select3 <x> <y> <width> <height> [bitmap] (touch area of button, optional bitmap to draw when touched)
Select4 <x> <y> <width> <height> [bitmap] (touch area of button, optional bitmap to draw when touched)
Select5 <x> <y> <width> <height> [bitmap] (touch area of button, optional bitmap to draw when touched)
Select6 <x> <y> <width> <height> [bitmap] (touch area of button, optional bitmap to draw when touched)
Select7 <x> <y> <width> <height> [bitmap] (touch area of button, optional bitmap to draw when touched)
Select8 <x> <y> <width> <height> [bitmap] (touch area of button, optional bitmap to draw when touched)
Select9 <x> <y> <width> <height> [bitmap] (touch area of button, optional bitmap to draw when touched)
SelectA <x> <y> <width> <height> [bitmap] (touch area of button, optional bitmap to draw when touched)
SelectB <x> <y> <width> <height> [bitmap] (touch area of button, optional bitmap to draw when touched)
SelectC <x> <y> <width> <height> [bitmap] (touch area of button, optional bitmap to draw when touched)
SelectD <x> <y> <width> <height> [bitmap] (touch area of button, optional bitmap to draw when touched)
SelectE <x> <y> <width> <height> [bitmap] (touch area of button, optional bitmap to draw when touched)
SelectF <x> <y> <width> <height> [bitmap] (touch area of button, optional bitmap to draw when touched)
SelectG <x> <y> <width> <height> [bitmap] (touch area of button, optional bitmap to draw when touched)
SelectH <x> <y> <width> <height> [bitmap] (touch area of button, optional bitmap to draw when touched)
SelectI <x> <y> <width> <height> [bitmap] (touch area of button, optional bitmap to draw when touched)
SelectJ <x> <y> <width> <height> [bitmap] (touch area of button, optional bitmap to draw when touched)
SelectK <x> <y> <width> <height> [bitmap] (touch area of button, optional bitmap to draw when touched)
SelectL <x> <y> <width> <height> [bitmap] (touch area of button, optional bitmap to draw when touched)
SelectM <x> <y> <width> <height> [bitmap] (touch area of button, optional bitmap to draw when touched)
SelectN <x> <y> <width> <height> [bitmap] (touch area of button, optional bitmap to draw when touched)
SelectO <x> <y> <width> <height> [bitmap] (touch area of button, optional bitmap to draw when touched)
SelectP <x> <y> <width> <height> [bitmap] (touch area of button, optional bitmap to draw when touched)
SelectQ <x> <y> <width> <height> [bitmap] (touch area of button, optional bitmap to draw when touched)
SelectR <x> <y> <width> <height> [bitmap] (touch area of button, optional bitmap to draw when touched)
SelectS <x> <y> <width> <height> [bitmap] (touch area of button, optional bitmap to draw when touched)
SelectT <x> <y> <width> <height> [bitmap] (touch area of button, optional bitmap to draw when touched)
SelectU <x> <y> <width> <height> [bitmap] (touch area of button, optional bitmap to draw when touched)
SelectV <x> <y> <width> <height> [bitmap] (touch area of button, optional bitmap to draw when touched)
SelectW <x> <y> <width> <height> [bitmap] (touch area of button, optional bitmap to draw when touched)
SelectX <x> <y> <width> <height> [bitmap] (touch area of button, optional bitmap to draw when touched)
SelectY <x> <y> <width> <height> [bitmap] (touch area of button, optional bitmap to draw when touched)
SelectZ <x> <y> <width> <height> [bitmap] (touch area of button, optional bitmap to draw when touched)
Flag1 <x> <y> <width> <height> [bitmap] (touch area of button, optional bitmap to draw when touched)
Flag2 <x> <y> <width> <height> [bitmap] (touch area of button, optional bitmap to draw when touched)
Flag3 <x> <y> <width> <height> [bitmap] (touch area of button, optional bitmap to draw when touched)
Flag4 <x> <y> <width> <height> [bitmap] (touch area of button, optional bitmap to draw when touched)
Menu <x> <y> <width> <height> [bitmap] (touch area of button, optional bitmap to draw when touched)
Search <x> <y> <width> <height> [bitmap] (touch area of button, optional bitmap to draw when touched)
Mouse <x> <y> <width> <height> [bitmap] (touch area of button, optional bitmap to draw when touched)
Screenshot <x> <y> <width> <height> [bitmap] (touch area of button, optional bitmap to draw when touched)
** Recognised AttractModeGenre values are...
Blues Classic Rock Country Dance
Disco Funk Grunge Hip-Hop
Jazz Metal New Age Oldies
Other Pop R&B Rap
Reggae Rock Techno Industrial
Alternative Ska Death Metal Pranks
Soundtrack Euro-Techno Ambient Trip-Hop
Vocal Jazz+Funk Fusion Trance
Classical Instrumental Acid House
Game Sound Clip Gospel Noise
AlternRock Bass Soul Punk
Space Meditative Instrumental Pop Instrumental Rock
Ethnic Gothic Darkwave Techno-Industrial
Electronic Pop-Folk Eurodance Dream
Southern Rock Comedy Cult Gangsta Rap
Top 40 Christian Rap Pop / Funk Jungle
Native American Cabaret New Wave Psychedelic
Rave Showtunes Trailer Lo-Fi
Tribal Acid Punk Acid Jazz Polka
Retro Musical Rock & Roll Hard Rock
Folk Folk-Rock National Folk Swing
Fast Fusion Bebob Latin Revival
Celtic Bluegrass Avantgarde Gothic Rock
Progressive Rock Psychedelic Rock Symphonic Rock Slow Rock
Big Band Chorus Easy Listening Acoustic
Humour Speech Chanson Opera
Chamber Music Sonata Symphony Booty Bass
Primus Porn Groove Satire Slow Jam
Club Tango Samba Folklore
Ballad Power Ballad Rhythmic Soul Freestyle
Duet Punk Rock Drum Solo A Cappella
Euro-House Dance Hall Goa Drum & Bass
Club-House Hardcore Terror Indie
BritPop Negerpunk Polsk Punk Beat
Christian Gangsta Rap Heavy Metal Black Metal Crossover
Contemporary Christian Christian Rock Merengue Salsa
Thrash Metal Anime JPop Synthpop
Abstract Art Rock Baroque Bhangra
Big Beat Breakbeat Chillout Downtempo
Dub EBM Eclectic Electro
Electroclash Emo Experimental Garage
Global IDM Illbient Industro-Goth
Jam Band Krautrock Leftfield Lounge
Math Rock New Romantic Nu-Breakz Post-Punk
Post-Rock Psytrance Shoegaze Space Rock
Trop Rock World Music Neoclassical Audiobook
Audio Theatre Neue Deutsche Welle Podcast Indie Rock
G-Funk Dubstep Garage Rock Psybient
Off Any Unknown
Note that you can also define your own Genres and fruitbox will recognise these if the 'AttractModeGenre'
field matches the name in the MP3 (ID3v2) genre tag.
fruitbox will make every effort to choose a song from the specified AttractModeGenre, but is constrained
by the song history and number of songs available to choose from. If it cannot choose a song
in a reasonable time, it will play any song.
12.1: Dynamic Parameter values
Dynamic parameter values (specified as [dynamic] in the above parameter descriptions), are optional values
which extend the usefulness of the parameter. They can be applied to the Position, Size, Clip, Angle
and/or Tint of displayable objects, and are used to modify the parameter value in real-time. The format
of the dynamic value field is "[max_value mode <param>]". Note the square brackets must be specified
in order for the dynamic values to be recognised. The parameter value will change between the initial
value and the 'max_value'. How the value changes is given by the 'mode', which can be one of the following
strings :
${RANDOM}
${TIMER_TICK}
${VOLUME}
${FIRST_VISIBLE_TITLE_STRIP}
${LAST_VISIBLE_TITLE_STRIP}
${NOW_PLAYING_ELAPSED_TIME}
${SONG_LOAD_POSITION}
${PLAYQUEUE_OCCUPANCY}
${SPECTRUM_BAND}
${LEFT_SPECTRUM_BAND}
${RIGHT_SPECTRUM_BAND}
Examples...
Size = 100 [200 ${VOLUME}] 150
...will create an object whose horizontal size ranges from 100 to 200 depending upon the volume, and
whose vertical size is fixed at 150.
Position = 100 150 [250 ${SPECTRUM_BAND} 2]
...will create an object whose horizontal position is fixed at 100, and whose vertical position ranges
from 150 to 250 depending upon the value of the audio spectrum frequency band number 2
Tint = 100 150 75 [255 ${RANDOM}] 200
...will create an object whose tint values red, green and alpha elements are fixed at 100, 150 and 200
respectively, but whose blue element randomly changes between 75 and 255 in real time.
12.2: Time Values
Several skin parameters are specified in terms of time. The (integer and fractional) time value can
be appended with "ticks", "seconds", "minutes" or "hours" (defaults to ticks if no units are specified).
"ticks" refers to the number of video frame ticks. So for example at 60Hz, a time value of 120 equals
2 seconds. When starting up, fruitbox will detect the video display and print out the frame rate (along
with the resolution). Specifying the time in ticks is useful for animation, which is synced to the video
display, but otherwise it is recommended to use conventional time units for non display parameters (for
example SongLoadTime) which means the time is not dependant upon the video frame rate, which can vary
depending on which display device is connected and how it's configured.
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