-
Notifications
You must be signed in to change notification settings - Fork 57
/
userguide.txt
1969 lines (1484 loc) · 83.4 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.
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 'sudo ./fruitbox --cfg <file>'. fruitbox
will then look for the configuration (skin) <file>. See section
'Configuration (Skin) Files' for more detail. After the configuration
file has been read, fruitbox will load the song database file
(specified in the configuration file). If the file doesn't exist,
a new one will be created (see section 'Database Creation').
When the database has been read, fruitbox will start!
Song pages are moved using the ButtonLeft and ButtonRight keys,
and songs are selected using the select keys or cursor keys if
in joystick mode. 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...fruitbox will look
for a 'fruitbox.btn' file in the same directory as it is run
from (unless an alternative button mapping file is defined using
the '--button-map' command line option. If it finds one, it
will read the file and re-map one or more of the input control
buttons as specified in the mapping file.
4: Command Line Options
fruitbox takes the following command line parameters.
4.1: --help
Show basic help and version information.
4.2: --cfg <filename>
This option determines which configuration file (skin) is used.
4.3: --database <filename>
Use the specified database instead of the one specified in the
skin
4.4: --music-path <filepath>
Use the specified music path instead of the one specified in
the skin. Only used when the database file doesn't exist (as
specified on the command line or skin config file). Note that
the --music-path option can be specified multiple times if the
user wishes to construct the database from multiple sources.
4.5: --user-guide
Create this user-guide to file "userguide.txt" (but I guess you
already worked that one out...)
4.6: --debug-song-nums
Show select code alongside song entries
4.7: --no-database-update
Normally fruitbox will update the database if it has a modification
time earler than the contents of any of the MusicPath directories.This
option disables this check, so it is up to the user to delete
the database file in order for it to be regenerated.
4.8: --config-buttons
This option allows the user to interactively change the input
control button mappings, and creates the button mapping file
specified by the --button-map command line option (or 'fruitbox.btn'
if not specified)
4.9: --calibrate-touch
Used in conjunction with '--config-buttons' , this allows the
user to interactively specify the touch-min and touch-max values
rather than through the command line options. It will also write
these values to the button mapping file for future use.
4.10: --test-buttons
This option allows button codes to be checked without creating
a button mapping file.
4.11: --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 playing
up.
4.12: --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.13: --choose-cfg <filename>
This option allows the user to choose a configuration file (skin)
from a menu when fruitbox starts up, rather than specifying it
using the '--cfg' command line option. The <file> parameter,
should contain a list of cfg files to choose from. Each entry
takes the form 'File = <file>' (path and name of a skin's cfg
file).
fruitbox will allow the user to cycle through the list of files
using the ButtonLeft and ButtonRight keys. Any other button
will select the skin. The 'SkinName' and 'SkinDescription' values
in the skin cfg files will be used to display information about
each skin. A preview of the skin is shown if a screenshot file
exists (by default, 'screenshot.jpg' in the same directory as
the cfg file, or the name of the 'Screenshot' parameter value
in the skin configuration file). Note that screenshot files
can be generated with the '--screenshot' command line option.
4.14: --screenshot
Save a screenshot of the skin, then quit without running. The
screenshot will be written to 'screenshot.jpg' in the skin directory
by default or the value of the 'Screenshot' parameter in the
skin configuration file. This option should be used in conjunction
with the '--cfg' or '--choose-cfg' command line options.
4.15: --no-scale
Normally fruitbox will scale (resize) the skin to the display,
so no matter what it's 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.16: --button-map <filename>
Name of button mapping file (defaults to 'fruitbox.btn' if not
specified)
5: 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). 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 'Database' and '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) and Database
files with other skins.
[general]
SkinSize Size of the skin (width and height in pixels).
The skin is scaled to match the full screen size of the display
SkinName Name of the skin
SkinDescription Description of the skin
Screenshot Filename of screenshot capture
Database File name of Database file
MusicPath * File name of path to mp3 music files. Can contain sub-directories.
Ignored if the 'Database' file already exists
SortSongsBy * 'Title', 'Artist', 'Album', 'AlbumArtist', 'Year', 'Genre', 'TrackNumber', 'Publisher', 'ISRC', 'Custom', 'Random', 'Unsorted'
NoDuplicates Prevent songs being added to the playqueue if they are already in the playqueue
DuplicatesUseCredits Determines of 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'
Specifies if the first select buttons are cycled before the second
select code buttons (ColRow) or the after the second buttons (RowCol)
CustomMP3Tag Name of an MP3 ID3v2 tag the user wishes to extract to a song's 'Custom' field (i.e. "TCON" is content type)
Note: this is only used during database file *creation*
AutoSelect 'No' = ButtonSelect needs to be pressed to select song (after the select code is entered)
'Yes' = song selected immediately select code is entered
PageJump The number of screens of pages moved in one go when 'ButtonLeftJump' or 'ButtonRightJump' is pressed
SelectTimeout Timeout for select code to return to '--' after not detecting all the selection digits
SelectHoldTimeout Timeout for select code to return to '--' after song selected
AutoPageTurnTime Time between pages automatically turning (0 = no automatic page turn)
MaxPlaylistLength Maximum number of songs which can be stored in the coming up queue
LoopPlaylist 'Yes' = a song is added to the back of the play queue when it has finished playing (credits permitting)
AutoPlay 'Yes' = a random song is played if the play queue is empty and no songs are playing
AutoPlayGap The time between a random song being selected and played after the last song has finished playing
AutoGenre * Name of Genre. Pressing ButtonAuto will cycle through all AutoGenre definitions (and 'Off'
and 'Any') and only select a random song from that Genre **
PlaysPerCoin1 The number of song credits added when a coin is inserted (if all PlaysPerCoin = 0; freeplay mode)
PlaysPerCoin2 The number of song credits added when a coin is inserted (if all PlaysPerCoin = 0; freeplay mode)
PlaysPerCoin3 The number of song credits added when a coin is inserted (if all PlaysPerCoin = 0; freeplay mode)
PlaysPerCoin4 The number of song credits added when a coin is inserted (if all PlaysPerCoin = 0; freeplay mode)
SongsPerPage The number of song entries on each song page
PageMode 'Singles' or 'Albums'.
PageSize The size (width and height in pixels) of each song page
PairSongs 'No' = each song in a page 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
PageMoveStyle effect speed fading. See section 'Pages'
SongDescription * Defines (part of) the song description for the song entry (first in a pair) in the pages...
'SongTitle', 'Artist', 'AlbumTitle', 'AlbumArtist', 'Year', 'Genre', 'TrackNumber',
'Publisher', 'ISRC', 'Custom', 'PairedSongTitle', 'PairedArtist',
'PairedAlbumTitle', 'PairedAlbumArtist', 'PairedYear', 'PairedGenre',
'PairedTrackNumber', 'PairedPublisher', 'PairedISRC', 'PairedCustom'
PairedSongDescription * Defines (part of) the song description for the second song in a pair
NOTE: In Albums mode (PageMode = Albums) this determines the Album Title line
ArtistDescription * Defines (part of) the artist description in the pages (same values as 'SongDescription')
MatchedArtistDescription * 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 * Defines (part of) the extra description in the pages (same values as 'SongDescription')
SongHistoryDepth Determines the search range of number of previously played songs to ensure
no repeated songs are chosen in Auto play or Random selection.
If not specified or set to zero, fruitbox will only check for
repeated songs from within the play queue
SongLoadTime The time the song takes to load (from removing from the coming up queue to starting to play)
SongUnloadTime The time the song takes to unload (from finishing playing to the next song in the queue loading)
SongText Text style for Song title in song page. See section 'Fonts and Text'
PairedSongText Text style for the paired Song title in song page. See section 'Fonts and Text'
ArtistText Text style for Artist name in song page. See section 'Fonts and Text'
AlbumText Text style for Album name in song page. See section 'Fonts and Text'
ExtraText Text style for the extra text field in song page. See section 'Fonts and Text'
AlbumArtSize width height (in pixels)
AlbumArtOffset Offset from top left hand corner of songs page (x y in pixels)
AlbumArtAngle Angle of Album artwork in degrees (0..359)
AlbumPageLineSpacing Gap (in pixels) between song titles in the albums song pages
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'
AlbumPageMissingArtwork Filename of graphic image (bmp, png, tga, jpg, pcx) to be used if AlbumPageArtworkMode = 'Specified',
or no song artwork is found and AlbumPageArtworkMode = 'Auto'
NowPlayingArtworkMode '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
AlbumPageArtworkMode '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
[touch areas]
ButtonQuit x y width height (touch area of button, where x y = top left corner)
ButtonCoin1 x y width height (touch area of button, where x y = top left corner)
ButtonCoin2 x y width height (touch area of button, where x y = top left corner)
ButtonCoin3 x y width height (touch area of button, where x y = top left corner)
ButtonCoin4 x y width height (touch area of button, where x y = top left corner)
ButtonVol+ x y width height (touch area of button, where x y = top left corner)
ButtonVol- x y width height (touch area of button, where x y = top left corner)
ButtonRandom x y width height (touch area of button, where x y = top left corner)
ButtonSelect x y width height (touch area of button, where x y = top left corner)
ButtonSkip x y width height (touch area of button, where x y = top left corner)
ButtonPause x y width height (touch area of button, where x y = top left corner)
ButtonUp x y width height (touch area of button, where x y = top left corner)
ButtonDown x y width height (touch area of button, where x y = top left corner)
ButtonLeft x y width height (touch area of button, where x y = top left corner)
ButtonRight x y width height (touch area of button, where x y = top left corner)
ButtonLeftJump x y width height (touch area of button, where x y = top left corner)
ButtonRightJump x y width height (touch area of button, where x y = top left corner)
ButtonLeftAlpha x y width height (touch area of button, where x y = top left corner)
ButtonRightAlpha x y width height (touch area of button, where x y = top left corner)
ButtonAuto x y width height (touch area of button, where x y = top left corner)
ButtonLoop x y width height (touch area of button, where x y = top left corner)
ButtonFree x y width height (touch area of button, where x y = top left corner)
ButtonClear x y width height (touch area of button, where x y = top left corner)
ButtonMute x y width height (touch area of button, where x y = top left corner)
ButtonPowerOff x y width height (touch area of button, where x y = top left corner)
Button0 x y width height (touch area of button, where x y = top left corner)
Button1 x y width height (touch area of button, where x y = top left corner)
Button2 x y width height (touch area of button, where x y = top left corner)
Button3 x y width height (touch area of button, where x y = top left corner)
Button4 x y width height (touch area of button, where x y = top left corner)
Button5 x y width height (touch area of button, where x y = top left corner)
Button6 x y width height (touch area of button, where x y = top left corner)
Button7 x y width height (touch area of button, where x y = top left corner)
Button8 x y width height (touch area of button, where x y = top left corner)
Button9 x y width height (touch area of button, where x y = top left corner)
ButtonA x y width height (touch area of button, where x y = top left corner)
ButtonB x y width height (touch area of button, where x y = top left corner)
ButtonC x y width height (touch area of button, where x y = top left corner)
ButtonD x y width height (touch area of button, where x y = top left corner)
ButtonE x y width height (touch area of button, where x y = top left corner)
ButtonF x y width height (touch area of button, where x y = top left corner)
ButtonG x y width height (touch area of button, where x y = top left corner)
ButtonH x y width height (touch area of button, where x y = top left corner)
ButtonI x y width height (touch area of button, where x y = top left corner)
ButtonJ x y width height (touch area of button, where x y = top left corner)
ButtonK x y width height (touch area of button, where x y = top left corner)
ButtonFlag1 x y width height (touch area of button, where x y = top left corner)
ButtonFlag2 x y width height (touch area of button, where x y = top left corner)
ButtonFlag3 x y width height (touch area of button, where x y = top left corner)
ButtonFlag4 x y width height (touch area of button, where x y = top left corner)
[sounds]
InsertCoin Volume (0..100), Filename of sound effect when a coin is inserted (wav, flac, ogg)
LoadSong Volume (0..100), Filename of sound effect when a song is loading (wav, flac, ogg)
UnloadSong Volume (0..100), Filename of sound effect when a song is unloading (wav, flac, ogg)
PageMove Volume (0..100), Filename of sound effect when pages are moving (wav, flac, ogg)
InvalidSong Volume (0..100), Filename of sound effect when an invalid song choice is selected (wav, flac, ogg)
SongVolume Initial song volume (0..100)
[font] *
File Filename of a font to add to the font pool (ttf, opentype, type1, CID, CFF, fon, fnt, x11, pcf)
Height The height of the font in pixels
[page] *
Position x y (in pixels)
Angle Angle of object in degrees (0..359)
Background Filename of graphic image (bmp, png, tga, jpg, pcx) to be used as the page background
MoveDelay Delay (in video frame ticks) between left/right button press and page moving
[status] *
Size width height (in pixels)
Position x y (in pixels)
Angle Angle of object in degrees (0..359)
Contents Filename of text file describing status box contents
Output Filename of output text file containing status
Text Status box text style. See section 'Fonts and Text'
LineSpacing Gap (in pixels) between text lines in the status box
LoopVideo 'Yes' - start video from beginning after it finishes
TimerTickPeriod Time (in video frame ticks) of status box timer period
TimerOneShot 'Yes' - timer stops after one tick, 'No' - timer runs indefinitely (default)
TimerEnable '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)
[bitmap] *
Size width height (in pixels)
Position x y (in pixels)
Angle Angle of object in degrees (0..359)
File Filename of graphic image (bmp, png, tga, jpg, pcx)
HorzScale Set the bitmap horizontal size according to 'Volume' or 'NowPlayingElapsedTime'
HorzScaleMode 'Scaled' - bitmap is scaled to size, 'Clipped' - bitmap is clipped not scaled
VertScale Set the bitmap vertical size according to 'Volume' or 'NowPlayingElapsedTime'
VertScaleMode 'Scaled' - bitmap is scaled to size, 'Clipped' - bitmap is clipped not scaled
ReverseClip 'No' - bitmap is clipped bottom->top and/or right->left
'Yes' - bitmap is clipped top->bottom and/or left->right
[joystick] *
Bitmap Filename of graphic image (bmp, png, tga, jpg, pcx)
Offset x, y (offset in pixels from top left corner of joystick 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)
[touch song]
Bitmap Filename of graphic image (bmp, png, tga, jpg, pcx)
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)
** Recognised AutoGenre 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
Note that you can also define your own Genres and fruitbox will recognise these if the 'AutoGenre'
field matches the name in the MP3 (ID3v2) genre tag.
fruitbox will make every effort to choose a song from the specified AutoGenre, 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.
5.1: Time Values
Several skin parameters are specified in terms of time. The
time value 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).
5.2: 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.
5.3: 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).
The only supported format is .ogv (Vorbis + Theora). Any video
format can be converted to this format using for example ffmpeg
with the following options for specifying the video bitrate and
video picture size for better quality...
ffmpeg -i MyVideo.mp4 -b:v 2M -vf scale=640x480 MyVideo.ogv
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).
5.4: Fonts and Text
The configuration file [font] section(s) allow 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'.
Text definitions ([general] ArtistText, [general] SongText, [general]
PairedSongText, [general] ExtraText and [status] Text) parameters
have the following arguments...
<font> <colour> <alignment> <capitalise> <condense> <quoted>
<offset> <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
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'
condense : 'Yes' (wide text is horizontally squashed to fit
within max_width),
'No' no squashing is done
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 'condense' option is 'Yes')
5.5: Coin Mode
fruitbox can support upto four coin buttons. Each coin button
has it's own 'PlaysPerCoin' value, so that fruitbox can mimic
jukeboxes which have multiple coin slots, for different coin
denominations. If all four 'PlaysPerCoin' parameters are zero
(or not specified) then fruitbox will operate in free play mode.
5.6: Joystick Mode
If a [joystick] object is specified in the skin file, then joystick
mode is activated. This allows a song to be chosen using the
ButtonUp, ButtonDown, ButtonLeft and ButtonRight buttons instead
of entering the select code. Pressing ButtonSelect 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.
5.7: Touch Song Mode
If a [touch song] object is specified in the skin file, then
touch song mode is activated (only if a touch screen has been
detected). 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 page area holding the song
name, but their size and position can be adjusted by using the
'Size' and 'Offset' [touch song] parameters. The 'Bitmap' parameter
defines an image file which is displayed over the song area when
being touched.
5.8: 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 AutoPlay 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.
5.9: Albums / Singles Mode
Fruitbox has two distinct modes - Albums and Singles, specified
by the 'PageMode' parameter.
In Singles mode, each song is individually selectable, and each
page displays a number of songs (or pairs of songs), each along
with the artist name. 'ArtistText', 'SongText', 'PairedSongText',
'PairSongs' and 'SongsPerPage' configuration parameters can be
used adjust the appearance of the song details on the pages.
In Albums mode, each page shows the album title, album artist,
album cover art, and list of songs in the album (upto the SongsPerPage
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 'SongsPerPage'
configuration parameters can be used adjust the appearance of
the album details on the pages. 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).
6: Database Creation
Once fruitbox has read the skin file and found no problems, it
will try to load the music database as specified in the skin
file. The database contains details of your music; tagged and
pre-formatted to allow fruitbox to use it efficiently. If the
database file doesn't exist, then fruitbox will automatically
generate it for you, using one or more 'MusicPath'(s) as specified
in the skin file. Each MusicPath parameter must point to an
accessible file directory (for example a directory on the SD
card itself or a USB memory drive), which contains MP3 songs
(which can be in sub-directories).
Building the database file may take some considerable time if
your music library is large, but it only needs to be done once,
and subsequent start-ups of fruitbox will be very fast. If you
add or remove music from your library, fruitbox will regenerate
it automatically, providing the changes are in the same MusicPath
directory. If not, you will have to manually delete the database
filefor frtuibox to re-generate it correctly. Alternatively,
the database file 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 add or remove particular songs,
or tweak the song details, without having to re-generate the
database from scratch. Note that the song order in the database
file is irrelevant; after fruitbox has read the songs from the
database file it will sort them according to the 'SortSongsBy'
configuration parameter.
If the database file already exists, then fruitbox will ignore
the MusicPath parameter(s) in the skin file.
7: Screen Layout
The display is built using a combination of the following objects,
as defined in the skin file:
1. [page] object : a region which contains songs.
See pages 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. [joystick] object : a region containing a bitmap controlled
by the four cursor keys.
See joystick 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.
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.
7.1: Pages
Pages 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 page 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 page (in Singles mode),
or pages 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.
Pages automatically move and update their contents when the ButtonLeft
or ButtonRight keys are pressed. The look and movement of the
pages is determined by 'PageMoveStyle' parameter in the skin
file, as follows:
PageMoveStyle <speed> <effect> <fade>
<speed>
1..x = higher number = faster page 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 = pages don't fade
yes = pages fade to black
Notes:
** The 'SongDescription' and 'PairedSongDescription' configuration
parameters can be used to modify the text displayed on the song
lines of the page(s) ('PairedSongDescription' is only used if
'PairSongs' is not set to false) by setting it to 'SongTitle',
'Artist', 'AlbumTitle', 'AlbumArtist', 'Year', 'Genre', 'TrackNumber',
'Publisher', 'ISRC', 'Custom', 'PairedSongTitle', 'PairedArtist',
'PairedAlbumTitle', 'PairedAlbumArtist', 'PairedYear', 'PairedGenre',
'PairedTrackNumber', 'PairedPublisher', 'PairedISRC', 'PairedCustom'
or any user string enclosed in double quotes. Also, if multiple
'SongDescription' parameters are specified, then they are joined
together to make a single text line. For example...
SongDescription = SongTitle
SongDescription = " ["
SongDescription = Year
SongDescription = "]"
...will display the text 'Pinball Wizard [1969]' (for example)
for the song entries on each page.
*** The 'ArtistDescription' configuration parameter works in
the same way as the 'SongDescription' parameter, but affects
the artist name text in the page(s) rather than the song title
text.
7.2: Status Boxes
Status Boxes provide a very flexible way of displaying real-time
text-based information, and fixed and animated bitmaps. 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_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
The 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 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
$AUTO_GENRE
The name of the current AutoGenre that AutoPlay will select a
random song from
$PLAYS_PER_COIN1
The number of plays per coin
$PLAYS_PER_COIN2
The number of plays per coin
$PLAYS_PER_COIN3
The number of plays per coin
$PLAYS_PER_COIN4
The number of plays per coin
$VOLUME
The song volume
$SELECT_CODE
The select code
$NUM_SONGS
The total number of songs in the database
$NUM_PAGES
The total number of pages in the jukebox
$FIRST_VISIBLE_PAGE
The number of the first page visible on the display
$LAST_VISIBLE_PAGE
The number of the last page visible on the display
$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