Lyrics Jukebox

Detailed program features

Basics

Lyrics Jukebox does not require installation, you can simply run the program. All necessary files are included, except for the Internet radio function, which requires the VLC player.
This allows it used as a portable music player with all data on a removable drive.

The program is free (and contains no advertisment or promotions) and does not require an Internet connection (except for radio streaming, of course).

Since Lyrics Jukebox is developed for a small screen, where an extensive settings dialog would be difficult to handle; the mode of operation is determined by a configuration file, in which the settings are changed manually.
By default, the program expects this configuration file with the name Lyrics_Jukebox.config to be in the same directory as the program file. If a different configuration file is to be used, the path/name can be specified as a start argument. Details on how to change the settings and all configuration parameters are described on the Configuration page.

Operating modes

Note: As is common in most operating systems, the following examples use / as the path separator. For Windows, you can use a \ instead.

Lyrics Jukebox can be used in various ways. In general, you can choose whether the program plays music continuously, using the jukebox to select tracks and check what music is available, or whether the jukebox is launched after the program starts and only plays the tracks selected there.
The provided standard configuration starts the program in playback mode and the jukebox can be switched on and off.

Below are some suggestions for possible operating modes and the corresponding configuration entries.

1. Simple player without lyrics display or jukebox
   You can achieve this with SimplePlayer=on.
2. Playing an M3U playlist
   To do this, enter path/filename for PlayList,
   for example PlayList=Playlists/Partymusic.m3u
3. Play directory content (optionally with or without subdirectories)
   To do this, enter path/filename for MusicDir,
   e.g. MusicDir=Music/Classic
   The ReadSubDirs parameter determines whether subdirectories are read.
4. Simple Play
   Shuffle=off
   SmartShuffle=off
5. Simple shuffle play
   Shuffle=on
6. Advanced shuffle play with no repetitions
   Shuffle=off
   SmartShuffle=on
7. Shuffle play with adjustable frequency
   The playback frequency of individual tracks can be defined in a list
   RatingList=path/filename (see Configuration for list structure).
   If you want, you can you can get a rotation of tracks like some radio stations, but it is better not to exaggerate.
   How much effect the rating entries have depends on the total number of songs:
   
   • If the rating is positive, additional playlist positions for that track will be evenly distributed throughout the active playlist (the program tries to avoid repetitions of artist or title). A value of +3 results in three additional tracks, which is of course more noticeable for a few pieces than for many.
   • If the rating is negative, the track will be skipped randomly, e.g. -2 means that the track will only be played every third time on average.
8. A playlist without paths or with incorrect paths can be imported
   OldPlayList=path/filename
   This can also be combined with Shuffle play or a previously loaded playlist; the imported playlist is always placed at the beginning. When it's finished, it automatically switches to the internal playlist, whether that's set to random or a pre-loaded list.
   To import such a list, all the titles in it must be known, i.e. they must either be in the specified music directory (if the music from MusicDir is used) or be present in the playlist (if PlayList is used). Missing tracks are omitted and there is a brief warning during the import of the OldPlayList.
9. Scrolling text
   For small screens, a large ticker with information about the track can be displayed LargeIntro=on
   This parameter causes the year, artist and title to be displayed as scrolling text a few seconds after the start of a song.
   In radio mode, the transmitted name of the currently playing track is then displayed as soon as it changes.
10. To support stage performances ("on-stage"), you can wait before each new track
    PauseBeforeTrack=on
    The music then starts when the space bar or the pause button on the user interface is pressed.
11. Operation as a jukebox, where only the selected tracks are played
    JukeboxOnly=on
    This parameter means that the jukebox function cannot be switched off.
12. Operation as a party jukebox which, if no one selects a track, switches to Shuffle play or a playlist after a desired time period.
    JukeboxTimeout=60
    for example, causes the music to resume automatically after one minute.
13. Operation as Internet radio
    The VLC player is used, which must therefore be installed.
    The streaming URLs of the Internet radio stations are contained in a text file which you can modify as you wish. Each line contains a URL and the stations are offered in the order in which they appear in the program.
    RadioStations=path/filename
    The radio function icon is only present if the list of radio stations is available and the VLC player was found on startup. It must be installed in its usual location or its path must be specified in the VLC executable configuration entry.
    If required, it is started and controlled via Telnet.
14. Operation in window or full screen mode
    Fullscreen=on
    activates full-screen mode. If the switch to windowed mode is disabled, the program can only be terminated with Ctrl-C. This is the best setting when used as a jukebox because guests cannot access the operating system's user interface.
    When running in windowed mode, you can scale to full screen and return with Alt-Enter. However, the content displayed differs from the Fullscreen setting as the window content is enlarged to screen size.
    Drag&Drop is supported when operating in windowed mode. You can drag in music or lyrics files or playlists onto the program window, the tracks will be cached and queued, similar to the Search or Jukebox option.

Further settings

• Fonts, window and font size
  For unsynchronized and synchronized song lyrics, a font can be defined with TxtFont and LRCFont. If the font selected for LRC texts is not suitable for all languages, a separate font can be assigned to certain languages using LanguageFonts.
  Set the desired window size withDisplayWidth and DisplayHeight. The program always starts with these values. You should then adjust the font size to the window or display size using LRCFontSize and TxtFontSize.
• Loading music files into RAM
  The PreLoadMusic parameter controls whether the active song is played directly from storage or loaded into RAM beforehand. Playing from RAM has two advantages: There are no interruptions from delayed file reading, and the ID3 tags are removed, preventing interference noise caused by incorrect synchronization.
• Network activities and update search
  In the default configuration, Lyricsjukebox does not establish network connections to destinations outside of your computer.
  When using the internet radio function, Lyricsjukebox connects to the VLC server on Localhost via Telnet. The connection to the radio station is then established by the VLC media player.
  You can use the CheckForUpdate parameter to ask LyricsJukebox to check for a updated version on this website. If you activate this update search, LyricsJukebox tests if there is an Internet connection at the launch by briefly establishing a connection to a Google server (this is a function of the programming language being used), then it will load the download page via HTTP, check the version number and display a message about an updated version for 12 seconds if required.
  On the Mac and Linux, the programs Lyrics_Jukebox and its service component Lyrics_Jukebox_Service exchange data via UDP. Normally a local firewall should not block this data, but if necessary, allow access to the UDP ports 61802 and 61803.

Basic Operating Instructions

Lyrics Jukebox can be operated with a mouse or touchscreen.
The semi-transparent control elements become visible when the screen is tapped or clicked. They disappear again ten seconds after the last operation. If a keyboard is available, they can also be removed by pressing the Esc key.
Most control functions are also available as keyboard shortcuts; the assignment of the functions to the keys is listed on the Operation page. These keyboard controls are also used for remote control.

Status icons

On the right side of the screen below the play time, four symbols indicate different operating statuses of Lyrics Jukebox.

• The jukebox indicates the jukebox mode. If it is displayed, the program switches to jukebox title strip selection after the end of the last played song.
• The radio indicates the usage of the Internet radio function.
• The crossed-out loudspeaker is displayed when the mute function is activated.
• The small Previous button indicates that you have returned to the list of recently played tracks by pressing the Previous button. This list is kept because the normal internal playlist does not know which tracks have been inserted using the search function or the music box selection. The Previous button can therefore also be used to access the additional tracks that have been played.
  To exit this list immediately and return to normal song rotation, press and hold the forward button for 1.5 seconds.

Troubleshooting

In case of any errors, you canactivate the display of additional diagnostic messages by using the ShowMessages configuration entry. This will report various internal program activities, allowing you to gain a better understanding of the processes. For example, these messages also help to determine which is the highest sensible value for the frequency in the Frequency parameter. If the frequency is set too high, messages like "2 events omitted" are constantly displayed. These messages are normal during activities such as switching to the next track or any operating procedures, but they should only occur occasionally while playing music.

Other

• Lyrics Jukebox currently only supports MP3 files. Other audio file formats are not supported yet, although music based on ffmpeg would not be problematic. However, I first want to teach the program to read other tag formats like Vorbis comments.

• For MP3 files with a variable bitrate that do not contain a Xing header, the exact duration of the track is not available to the program. If the associated text is just a text file without timestamps, then the appropriate timing is not assigned to each line and the scroll speed is usually too slow. Additionally, the effectiveness of the position slider will not always be as precise as expected. If this is bothersome in some cases, you can add the Xing header to the music file using a suitable program, such as foobar 2000 or MP3 Diags.

• Lyrics Jukebox was written in the Hollywood multimedia scripting language, which allows for straightforward cross-platform programming. The executable program essentially consists of a Lua core that executes Lua bytecode. Of course, the convenience of development comes with drawbacks, as interpreted languages produce slower results than compiled languages. However, the resulting code is essentially fast enough for what is needed. Minor disadvantages are noticeable when switching to the next track, because a number of activities are required (reading tags, loading and rescaling cover images, reading text, loading music files into memory, creating graphic layers for the large scrolling text if necessary). Especially on the Raspberry, switching from one track to another takes significantly longer than on a fast PC.

• I don't know yet whether I'll try to design a suitable settings dialog for the configuration at some point, because I'm happy with the way it is.
  

• When listening to the radio, I've occasionally been curious whether the music track currently playing is available in my collection. Therefore, everytime the transmitted track changes, Lyrics Jukebox searches its playlist for the name, and if it is found, a green dot appears on the right. However, this only works for radio stations that do not broadcast the title too intricately.