Frequently Asked Questions - Convergence Jukebox Version 0.4 and Conference Jukebox 2
By Brad Fortner Dec 3, 2017
What is Convergence Jukebox?
Convergence Jukebox is open source Python based software that has been written in Python 2.7 to emulate a “retro” style jukebox. The type of jukebox that was popular in bars, restaurants and recreation areas during the 1950’s and 60’s. The Convergence Jukebox source code is distributed from its GitHub page to encourage others to further modify the software, adapt it to other platforms and to add features. More details at http://bit.ly/1PabZRZ and http://bit.ly/1Z0OghL.
How did Convergence Jukebox come about?
Written from scratch starting in 2012 by Brad Fortner of Convergence Communications, Convergence Jukebox plays properly formed ID3 tagged mp3 media. The Jukebox can be controlled for “personal” use by your computer keyboard but is better operated with a USB keypad such as a Pi Engineering USB keypad. Its output resolution is modifiable allowing it to connect to inexpensive computer, laptop or TV displays with its “retro look and feel”. It can even be connected to bill, coin or card acceptors such as a WeaveFuture Coin Acceptor via USB for “pay to play” situations.
What is Convergence Jukebox 2?
On May 16, 2017 Convergence Jukebox 2 was released which built upon original source code but switched from a Tkinter based GUI to one constructed using Kivy. Convergence Jukebox 2 is the “go forward” software which is subject of ongoing development.
Why the split between the 0riginal Convergence Jukebox and Convergence Jukebox 2?
When trying to package the original Convergence Jukebox programs into stand-alone executables many problems were encountered resulting in a convoluted mix of software to bootstrap versions for Windows and Raspberry Pi. From what the author could tell much many of the packaging problems were caused by use of the Tkinter gui.
A decision was made to redesign the gui around more modern gui software. Kivy was chosen for this given its cross platform capabilities include Android and IOS. Hence Convergence Jukebox 2’s gui is Kivy based, operating in the exact same manner as the original gui while maintaining compatibility with Convergence Jukeboxes mp3 player.
At some point in the future the two programmes that make up Convergence Jukebox 2 (convergencegui.py and convergenceplayer.py) can be merged into a single program (convergencejukebox.py) that can be packaged for use on Windows, Mac, Linux, Android and IOS environments.
How is Convergence Jukebox 2 licenced?
Convergence Jukebox 2 is written in Python allowing it to be cross platform. It is licensed with a GNU V3 General Public License that guarantees end users (individuals, organizations, companies) the freedoms to run, study, share (copy), and modify the software. It’s perfectly suited as a Jukebox software base for the Maker community as it can be easily modified and adapted.
What are the features of Convergence Jukebox 2?
Information on Convergence Jukebox features can be found at http://bit.ly/1Jqiwvg. Instructions on how to access those features are explained later in this FAQ with most of the original functionality between the original Convergence Jukebox software and Convergence Jukebox 2.
Where do I get the Python source code for Convergence Jukebox from?
The source Convergence Jukebox software both original and Convergence Jukebox 2 can be downloaded via its GitHub site.
Is there a Windows.exe available so I can try and use Convergence Jukebox without being a Python programmer?
Yes but only for the original Convergence Jukebox. The original Convergence Jukebox was frozen with many crude workarounds. It was never successfully packaged into a Windows installer. It is available as a self extracting winzip file that does not require you to have Python 2.7 installed your Windows computer. It can be downloaded from here. The installation will run out of the box as it contains 80+ public domain mp3’s in the associated music directory by following the instructions below;
To install the original Convergence Jukebox software on your Windows computer;
a) Download the Convergence Jukebox For Windows.exe program and run it.
b) You can press the Unzip button and Convergence Jukebox will install at c:\convergencejukebox\. For the purposes of this FAQ this will be known as the default directory.
You can browse to a directory location you want to install Convergence Jukebox and then press Unzip.
c) next navigate to the default c:\convergencejukebox\ directory.
d) click on convergencejukebox.exe to launch the program.
f) to exit Convergence Jukebox press the esc key.
My convergencejukebox.exe installation has stopped running, won’t load or is displaying an error sign. What should I do?
Be sure that you are starting the program by clicking on convergencejukebox.exe to start the program.
If problems persist this usually occurs because one of the programs files or databases has become corrupted. The fastest solution is to delete all .txt and .pkl files found in the default c:\convergencejukebox directory and rerun Convergence Jukebox by clicking on the convergencejukebox.exe program. This will recreate all the required housekeeping files for Convergence Jukebox, rebuild a fresh database of your songs and the Jukebox will start operating playing when it’s finished.
If the above doesn’t work one of the main .exe programs has become corrupted. If you're using the windows.exe version (ie convergencejukebox.exe) uninstall Convergence Jukebox via Windows control panel and download and install a fresh installation.
I’ve downloaded the and written the Convergence Jukebox .img file for Raspberry Pi to an 8 gig SD card. What do I need to know about it.
Not much. When you boot your Raspberry Pi it will automatically start playing Creative Commons music that’s been placed on it from http://freemusicarchive.org. The music was chosen because it’s free to distribute and the ID3 tags associated with them are properly formed.
If you wish you can edit the Convergence Jukebox Python Code directly on your Raspberry Pi once the disk is running. The Python Files are found in the /home/pi/python/jukebox subdirectory.
To add, change or remove the music on your Raspberry Pi Jukebox start by consulting the “Making The Most Out Of An MP3 Library For Use With Convergence Jukebox” guide so you can properly form your ID3 tags for Convergence Jukebox.
I want to run the Convergence Jukebox Python code. How do I run it?
The version currently posted operates on both Windows and Linux platforms. Convergence Jukebox is initiated by first running the convergencejukebox.py file. It starts by checking that the device has a 720p (1280 * 720) resolution available. It then ensures a /music subdirectory is in place containing some MP3 files so the Jukebox will start right out of the gate. It then runs convergenceplayer.py
convergenceplayer.py is the second program in the sequence and it is the mp3 player engine. It builds a database of the music in the /music subdirectory, adds a number of other supplemental pkl and txt files --some required for the GUI-- and then starts playing the music. Once the music starts playing it runs convergencegui.py
convergencegui.py is the third program run. It provides a Tkinter GUI overlay and the user interaction. In the release Convergence Jukebox is set to run only at 720P (1280 by 720 resolution). This is because it was designed to run on cheap readily available monitors and the current Tkinter interface is programmed to that resolution.
Several Windows OS exe's are employed to start the various Python programs. I've included both the exe's and Autohotkey scripts in the repository. I know this is a kludge. These will disappear over time as I learn more about how to run multiple python scripts.
For the Linux version a .bat file called gui_launch_pi.bat launches the GUI. Please note that I tried several different ways of doing this including using OS (it froze the player) and subprocess (it froze the GUI). Using the .exe and .bat the program at least works...
If you're further developing this code you can run those three .py programs in the order described manually and they will work.
I want to run the Convergence Jukebox Python code on OSX, will it run?
To the best of my knowledge the Python code should run on all operating systems. No work has been done yet to test it on OSX.
My convergencejukebox.py has stopped running, won’t load or is displaying an error sign. What should I do?
Ensure that you are starting the program by clicking on convergencejukebox.py to start the program. As explained elsewhere in the FAQ it’s the first program that needs to run in order for Convergence Jukebox to operate.
If problems persist this usually occurs because one of the programs files or databases has become corrupted. These are the .txt and .pkl files that get written to the Convergence Jukebox default directory during operation. The fastest solution is to delete all .txt and .pkl files found in the defualt c:\convergencejukebox\ directory and rerun Convergence Jukebox by clicking on the convergencejukebox.py program. This will recreate all the required housekeeping files for Convergence Jukebox, rebuild a fresh database of your songs and the Jukebox will start operating playing when it’s finished.
If the above doesn’t work one of the main .py programs has become corrupted. Download and run a fresh version from the Convergence Jukebox GitHub site.
How do I control Convergence Jukebox?
to exit Convergence Jukebox - press ESC
add credits - press x
navigate screen(s) - press up, down, left, and right arrow keys
select song - press spacebar, mouseclick or touch screen
Selection Sort In Convergence Jukebox 1 -
Artist sort - press A
Title sort - press T
Selection Sort In Convergence Jukebox 2 - press / (forward slash). It toggles between Artist sort and Title sort with each press.
jump to Artist or Title starting with A, B or C - press a multiple times
jump to Artist or Title starting with D, E or F - press d multiple times
jump to Artist or Title starting with G, H or I - press g multiple times
jump to Artist or Title starting with J, K or L - press j multiple times
jump to Artist or Title starting with M, N or O - press m multiple times
jump to Artist or Title starting with P, Q or R - press p multiple times
jump to Artist or Title starting with S - press s
jump to Artist or Title starting with T, U or V - press t multiple times
jump to Artist or Title starting with W, X, Y or Z - press w multiple times
Why is the keyboard layout the way it is for personal use?
Convergence Jukebox has been programmed as “Retro Jukebox” that has minimal controls. The Jukebox can be controlled for “personal” use by your computer keyboard but as you may understand it is better operated with a USB keypad such as a Pi Engineering USB keypad. The Pi Engineering keypad is desirable because of its rugged engineering, its ability to be programmed to emulate standard keyboard keys and its ability to embed key labels on to specific keys This is the layout for the keypad which better explains the keyboard controls.
If you're unhappy with the personal keyboard controls as programmed, under Convergence Jukebox licensing you can fork and the Convergence Jukebox Python code from the Convergence Jukebox GitHub site and add your own features --such as a more suitable keyboard control layout -- to the code. You will find the keyboard bindings at the end of the convergencegui.py code. Good luck and please share….
The Pi Engineering Keypad is expensive. Are their any alternatives?
Yes. The original Convergence Jukebox was programmed by a conventional USB Numeric Keypad of which there are many available for under $15.00. It turned out to be a messy hack employing Autohotkey to program the keypad and inkjet printing the key overlays on removable sheets that stretched over the actual keypad. It worked satisfactorily as a personal device but it was ditched because the the keypad would not stay locked in numlock mode during reboots.
Convergence Jukebox is telling me my Computer does not have the required resolution. What can I do?
How do I add music to Convergence Jukebox?
Music is added to convergence Jukebox by placing MP3’ with properly formed ID3 tags into the (default) c:\convergencejukebox\music\ subdirectory and restarting the software. The subdirectory acts as a watch folder of sorts and will rebuild your song database when it senses a change to the number of files in its music subdirectory during a reboot.
I’ve changed the mp3’s in my (default) c:\convergencejukebox\music\ subdirectory and have restarted the software. Convergence Jukebox is not detecting the change and rebuilding the database. How do I force the software to sense the change and rebuild its database?
Convergence Jukebox will rebuild your song database when it senses a change to the number of files in its music subdirectory during a reboot. The primary reason it does work is because the MP3 file count is the same. (ie. you removed as many MP3 files as you added) So to Convergence Jukebox the file count is still the same. By adding or deleting one MP3 file the software will detect the the change on a restart and will rebuild the database.
To answer the question and force a rebuild of the song database delete the file_count.txt file located in the (default) c:\convergencejukebox\ directory and restart the software. Convergence Jukebox will sense that the file is missing and rebuild the database from scratch. Once the complete database is rebuilt Convergence Jukebox will start up as normal.
What is the limit on the number of MP3’s I can place on Convergence Jukebox?
We believe Convergence Jukebox has an unlimited mp3 library size. It’s more limited by hard drive and memory size. Your hard drive can obviously fill up with MP3’s and the larger the library of MP3’s, the more memory Convergence Jukebox will require to operate. I operate a Windows 7 version containing 10,000 mp3 files which runs fine on an HP MINI 210 PC that contains an Atom N450 processor, 1024 MB of memory and a 160.0 GB hard drive. As well I’ve tested Convergence Jukebox on a Raspberry Pi Zero with well over 8000 mp3’s and it operated flawlessly
What are the minimum hardware requirements for Convergence Jukebox?
Convergence Jukebox has been authoured in Python 2.7 to operate on minimal hardware. Convergence Jukebox is primarily an MP3 player with software added on top of it to make it perform like an old style jukebox. MP3 players, like the Apple Nano, require very little hardware. Convergence Jukebox is more limited by hard drive and memory size. Your hard drive (or storage device) can obviously fill up with MP3’s and the larger the library of MP3’s, the more memory Convergence Jukebox will require to operate.
How do I change the name of the jukebox?
The name of the Jukebox that appears at the top of the Jukebox Arch on the Convergence Jukebox Gui can be changed in the convergencegui.py code. Locate the jukebox_name variable in current_song_display_updater().
During a database build Convergence Jukebox suddenly stops and the program crashes. What’s causing this and how can I stop it from happening?
The cause can be from MP3’s that are not properly formed but it is usually caused by MP3 ID3 tags that contain unicode characters. It can be as simple as a Mötley Crüe MP3 being processed. Notice the letters ö and ü in Mötley Crüe. They are unicode variants on ASCII’s o and u. There may also be unicode buried in the MP3’s ID3 tag that you don’t see.
Python 2.7 does not natively support Unicode characters. Recent code changes have been added to Convergence Jukebox to deal with the issue. The code deletes mp3 files containing Unicode before the file is processed by Convergence Jukebox. However if Unicode slips through, Convergence Jukebox will crash when the file gets appended to the song database. The fix (for now) is to remove MP3’s containing unicode characters from the Convergence Jukebox music subdirectory and delete the file_count.txt file located in the (default) c:\convergencejukebox\ directory. Restart the Convergence Jukebox software and it will rebuild a new database.
What can I do to play MP3’s that contain unicode characters or exhibit other problems?
You can remove the unicode characters and ensure your MP3’s are fully formed. To do this please consult the Making The Most Out Of An MP3 Library For Use With Convergence Jukebox guide It will assist you in removing Unicode characters, creating MP3’s with consistent volume levels, validating the consistency of your MP3 files and standardizing MP3 titles so you can better manage a growing collection.
Can I shut off the Random Play?
Not in its current release. Convergence Jukebox was designed to be a background music player that allows users to select their own music using credits. You can program what gets played randomly via Convergence Jukebox’s Genre features. Under Convergence Jukebox licensing you can fork and the Convergence Jukebox Python code from the Convergence Jukebox GitHub site and add your own features --such as no random play-- to the code. Good luck and please share….
What is the Convergence Jukebox Genre feature and how does it work?
The Genre feature allows one to tag each song (must be on the comment fields of both the ID3v1 and ID3v2 tags) with a Genre that can be given a priority when Convergence Jukebox builds its random list. This allows one to play jazz tunes all afternoon and switch to modern rock or pop music in the evening. The way that Convergence Jukebox is constructed, users have complete control over genre names, random playback of a single genre as a priority or priority random playback of mix of up to five genres. The genre_flags.txt field found in the default c:\convergencejukebox\ directory controls the genres that Random List prioritizes.
Why does Convergence Jukebox use the comment field as opposed to the Genre field in it’s Genre feature?
It’s complicated. To start ID3 genre tags are a series of informal standards. There is no de facto genre name list or standardization on how a musician is assigned to a genre. Even worse, using the MP3 ID3 genre tag there is no real method to assign more than one genre to a recording.
Adding to the complexity is that hsaudiotag, which is the Python library employed by Convergence Jukebox to read MP3 ID3 tags, is not clear on how it reads them. Experimentation reveals that hsaudiotag reads fully formed ID3v2 tags using its auto wrapper. Experimentation has also shown that hsaudiotag is more dependable in reading ID3 tags if all ID3v1 tags are either removed or if all ID3v1 tags are duplicated --as best one can-- within the MP3 file.
To answer the question it turns out the comment field in ID3v2 is unlimited in size by the specification so it provides enough space to not only add a number of genres, but the ability for the user to create genre names for themselves. Hence the rationale for using the comment field. More on this in the Making The Most Out Of An MP3 Library For Use With Convergence Jukebox guide.
If you're unsatisfied with this why not fork the Python code from the Convergence Jukebox GitHub site and add your own feature --such as reading the genre field (hsaudiotag supports reading the genre tag) or perhaps both-- to the code. You’ll find the relvant code in the convergenceplayer.py code in the song_list_generator(). Good luck and please share….
How can I ensure a specific song never gets played randomly by Convergence Jukebox?
By adding the tag norandom to the comment field on a properly formed ID3v2 MP3, Convergence Jukebox will play that mp3 during Random Play. Whenever a Random List is generated --either during a reboot or by the introduction of a genre-flags.txt file-- all the norandom tagged songs bypassed are written to the log.txt file in the the default c:\convergencejukebox\ directory. The only way to play an mp3 marked norandom is through credit play.
Where can I find the Convergence Jukebox log file and what does it record?
The Convergence Jukebox log file is found in the default c:\convergencejukebox\ directory. Its filename is log.txt. It records times when Convergence Jukebox is started or rebooted, logs each song it plays noting date, time, artist, song name, and whether is was random (ends with a 0) or credit play (ends with a 1). The log notes songs that are tagged norandom when a random list is generated. As well the log notes songs that were deleted from the music folder because of detection on Unicode or missing artist and title ID3 tag information.
I’ve noticed that Convergence Jukebox rarely plays the same song twice. Why is that?
The player engine Convergence Jukebox has been designed to play each song in it one time. After it’s played it’s removed from Random Play until another Random Play list is built either by reboot, the introduction of a new genre-flags.txt file or all the songs in the jukebox library are played and a new random list is regenerated recycling all the songs back into Random Play. When someone selects a song via credit play, it’s automatically removed from Random Play. Also Convergence Jukebox does not allow for multiple plays of the same song on the upcoming selected song list. Once the name of a song is no longer on the upcoming list it can be played again via credit play. All of this means that a person monitoring Convergence Jukebox all day won’t tire of the same songs being played over and over again unless it’s being programmed by an individual via credit play.
What is credit play and can I make Convergence Jukebox coin operated?
Convergence Jukebox was designed to accommodate pay per play situations. This is known as credit play. Hence to select songs that you want to hear, their must be credits available. For personal use credits are added to the Jukebox by pressing the x key on the keyboard. Credit plays are displayed under UPCOMING SELECTIONS and are played as a priority over Random Play songs. Upcoming songs will start as soon as the current random play song ends.
If you wanted to set up a pay per play situation you could employ a coin or card acceptor such as a WeaveFuture Coin Acceptor via USB which has been tested and proven to work with Convergence Jukebox. The WeaveFuture Coin Acceptor works by activating the x key on Convergence Jukebox once it accepts a coin. It does this via a USB connection to the Convergence Jukebox computer and its own windows based interface software that allows you to program the appropriate key for the coin acceptor to activate.
More on coin operation…
In December 2017 a patch was added to the original version of Convergence Jukebox bringing it up to version 0.4. If you’re having trouble getting a coin machine functioning directly with Convergence Jukebox run coinreader.exe. It’s a python program that waits for the <x> key to be pressed. When it’s run coinreader.exe creates a file called credits.txt with 0 value. When coinreader.exe reads an <x> generated from a WeaveFuture Coin Acceptor it adds a credit the credits.txt file.
What’s the credits.txt file all about?
Convergence Jukebox 0.4 now searches for a credits.txt file. If it senses the file it looks for a change to credits.txt 60 times per minute. When it senses an update the credits are are reflected immediately on the GUI. If no credits.txt file is found Convergence Jukebox acts exactly like it did in version 0.3. When a credit is used it’s subtracted from the credits.txt file and the Jukebox screen is updated.
Why does the Convergence Jukeboxes GUI lose focus with coin operation?
There is a well known bug in Windows 7, 8 and (possibly) 10, where running multiple programs causes a certain amount of focus stealing. If this is occuring run the gui_on_top.exe program which will force focus on the Convergence Jukebox GUI.
Given the number of programs involved how do I run Convergence Jukebox in an automated fashion on Windows?
We use the free version of WinPatrol that allows one to delay the start times of all programs when the computer is booted. On our HP MINI 210 PC that contains an Atom N450 processor, 1024 MB of memory (ie. a slow pc by today's standards) we start;
Why can’t I select a song on the last Convergence Jukebox screen?
It’s a bug in the original version but has been fixed in Convergence Jukebox 2.
When I quit Convergence Jukebox my screen resolution has changed. How do I stop that from happening?
Press the esc <escape> key to exit Convergence Jukebox. Prior to quitting the software will reset your computer to its former screen resolution.
What are the known bugs, shortfalls and future additions being considered for Convergence Jukebox?