Installing Giocoso on Raspbian for Raspberry Pi

1.0 Introduction

The Raspberry Pi single board computer is a remarkable piece of computing technology: about the size of a 2.5" solid state hard disk, the Pi 4B I'm using manages to pack in an ARM processor, 4GB RAM, gigabit Ethernet, twin USB 3 ports, twin USB 2 ports and twin HDMI outputs. It has, in short, everything required to be a capable (if slightly slow) home PC... for about £55. (That's the usual list price when the midget computers are actually in stock: they are currently in short supply worldwide right now, so prices have sky-rocketed to £150+, which makes them much less desirable as daily driver PCs). I think that's a good deal (when you can get it!) and what the Pi perhaps lacks in raw speed and CPU power, it greatly makes up for by running entirely silently: whilst you can certainly fit fans to keep things cool, a good case can keep the temperatures down entirely passively. In a music room, silence is definitely golden!

By design and default, a modern Raspberry Pi is generally kitted out with 'Raspbian' or 'Raspberry Pi OS', which is an ARM-specific port of Debian, packaged with an allegedly user-friendly front-end that makes Fisher-Price look advanced. I am not a fan of it, put it that way! On the other hand, it is lightweight enough to make the Pi feel quite 'snappy'. That maybe because it uses the LXDE desktop environment by default, rather than a heavyweight, 'conventional' desktop such as KDE.

These days, the operating system is officially called 'Raspberry Pi OS', where formerly it was known as 'Raspbian' (presumably in a nod to its Debian base). I shall use 'Raspbian' in this article, because I find the official name is too cumbersome to use repeatedly!

In any event, I downloaded Raspbian using the Raspberry Pi Imager tool, which you run on a Windows, Mac or other Linux PC. I wrote the OS image to a 32GB SD card and booted and ran everything from there: it's not as fast as doing it from a USB-attached SSD hard drive, but runs quite fluently from it anyway.

As for all my documented Giocoso installs on Linux, I ensured the operating system was as up-to-date as possible. In Raspbian's case, you do that by issuing the command

sudo apt update && sudo apt upgrade

...though the OS does an online update anyway as part of its first-boot initialisation process. However it was done, though, I ended up using kernel 5.15.32 and LXDE Version 0.99.2-4 running the X11 graphical server.

2.0 Installing Giocoso

Giocoso is installed by a script which is downloaded from this website and then executed. The usual tool for doing that is wget, run within a new terminal session, in which you type the following commands:


The initial 'cd' is to make sure you're sitting in your home folder when the download occurs -but provided you know where you are in your file system, you can download the script to anywhere to which you have read-write access:

You'll note that we are dealing with a download that's only a few kilobytes big. The specific numbers change over time, as new developments are included in the script, but we're talking no more than 5 or 6K at worst.

Once the script is downloaded, you invoke it with the command:

bash abc_installer --giocoso

As soon as the script executes, the screen will clear, the text will turn assorted shades of green and yellow (depending on your terminal's choice of colour scheme) and you'll see something like this:

The Giocoso script is fetched from my servers and then you're prompted to supply a sudo password, because we need root privileges to copy the downloaded script to your /usr/bin folder. After that's supplied, the script concludes and you're ready to run Giocoso.

Summing up then:

  • fetch the abc_installer script;
  • run it with the --giocoso argument;
  • supply your sudo password.

It's really that simple.

3.0 Running Giocoso for the First Time

Once Giocoso has been installed, you run it most simply with the bare command giocoso (though you'll see that this soon can become more complicated, with lots of run-time options being passed to the program via runtime parameters). When you launch the program for the very first time, you'll see this happen:

When first launched, Giocoso performs a software inventory on your Raspbian system and has noticed that it's missing some programs that it will need in order for itself to be able to run properly. The command needed to install those missing packages is shown in bright blue, within the red error text. Notice that the blue text wraps onto more than one line in the error message, depending on which packages you have already installed: for the installation commands to work, though, they need to be submitted as a single-line command. You can do that either by simply typing the command out manually, or by copying the the blue text into a text editor, knocking it into single-line shape there and then pasting it back into the terminal. However you choose to do it, run that blue command to fix up the missing packages:

Press [Enter] to submit those commands and everything Giocoso needs to run will be installed for you, using Raspbian's standard package management functionality. If you haven't recently used the sudo command, you'll be prompted to supply a password. On my fresh Raspbian system, I needed only to fetch around 2MB of extra software. Not exactly time-consuming!

Once the required software packages have been downloaded and installed, you can immediately try running Giocoso once more (by typing giocoso) at the command prompt:

That message only appears the first time Giocoso is run with all software prerequisites satisfied: a persistent configuration file is expected to be found in the $HOME/.local/share/giocoso folder, and when one can't be (as will always be the case on the very first run of the program), Giocoso will download a 'default' configuration file from the absolutelybaching servers and store it in that folder. You just press any key at this point in order to proceed. As soon as the default configuration file is downloaded, the screen will end up displaying something similar to this:

That wall of red error message text doesn't look too promising, does it?! In fact, however, it means Giocoso is running fine. The only thing happening at this point is that you are trying to run Giocoso in its default mode without there being a database to use to find music to play (because you haven't created it yet!), or without telling it explicitly not to use a database. This is described in more detail in the sections of this manual about Direct Play Mode and Database Play Mode. For now, the problem is easily corrected by appending a runtime parameter to the basic 'giocoso' command to formally instruct the program not to use a database for now:

giocoso --dbname=none

But if you type that command into the terminal now, you'll encounter another error:

Again, the red error text can look intimidating, but all Giocoso is saying here is: when you run me without a database, I must either be physically in a folder of music files I can play, or you must direct me to where such files can be found. In my case, I know I can find some music within my /sourcedata/music folder, so let me visit a folder there and try again:

This time, I'm sitting in a folder which clearly contains a FLAC file (and it must be a FLAC file: Giocoso won't play MP3s, OGGs, WAVs, ALACs or any other type of audio file). If I once again launch Giocoso with the giocoso --dbname=none command from before, I now get this result:

...and that's Giocoso happily playing the music, displaying the album art that's been embedded within it whilst it's at it!

Summing up, therefore:

  • On first run, Giocoso prompts for the installation of a few necessary software prerequisites;
  • Once those extra software packages are installed, Giocoso can be run a second time, at which time it will download a default configuration file
  • But it will error, because it wants to use a database that doesn't exist;
  • So you run it a third time with --dbname=none;
  • But it will error, because it can't find any music to play;
  • So you 'cd' to a folder containing a FLAC, run it a fourth time... and it will finally work

I think that makes it sound more complicated than it is, to be honest! The real point is that it takes a few goes to make Giocoso happy with its software and musical environment, but once you know about the '--dbname=none' parameter and the need to be in a folder of FLACs, it all works just fine.

4.0 Creating a Database and Music Scanning

Now that you've got Giocoso working and displaying things properly in Direct Play Mode, it's time to consider getting Giocoso to create a database of what music is available to play. That's called running Giocoso in Database Play Mode -and it's where all Giocoso's randomisation features come into play. Instead of playing the particular contents of a specific folder of music, you can ask Giocoso to scan through its database and find anything at all conducted by Karajan that lasts less than 20 minutes ... or pretty much use any other selection filters you can think of!

So, first, we need to get Giocoso to create a database and populate it with details of what music files exist. In a terminal, you do that with a variation on the command:

giocoso --createdb --dbname=my-db-name --musicdir=/somewhere/on/my/filesystem

...replacing 'my-db-name' with an actual name of the database you want to create; and '/somewhere/on/my/filesystem' with the path to the root of your music collection. Database names can be pretty much anything you want them to be -but if they contain spaces, they need to be wrapped inside double quotation marks, which can be a bit of a pain to remember to do every time you subsequently use it. I'd recommend a database name with a short, single-word, name. The default, incidentally, is simply 'music', so if you miss out the --dbname parameter by accident or design, that's the database you'll get created anyway.

The 'root of your music colleciton' folder used for the --musicdir parameter is important to get right. Giocoso will scan any number of folders 'underneath' the one provided, but will not scan upwards or sideways! In other words, supposed you stored your music like this:

  • /music/classical/Britten
  • /music/classical/Beethoven
  • /music/classical/Opera/Puccini

...then --musicdir=/music/classical would fetch all three folders of music (and any sub-folders within them). But a --musicdir=/music/classical/Opera would be blind to the existence of the Britten and Beethoven folders. Giocoso will happily descend within the Opera folder to find any number of sub-folders within it, but cannot go back 'up' a level, and discover the existence of those other two folders. So, point the parameter at a folder that's at the root of your entire music collection, not half-way through it, if you want Giocoso to be able to play everything you have collected. Also note that, as ever, if the path you want to specify contains spaces, wrap the entire path in double quotation marks. For example: "/home/hjr/My Music".

With all that in mind, here's me creating my Giocoso music database:

You'll notice from that, by the way, that the order of the runtime parameters doesn't matter: here, I've got --createdb coming after the --dbname and --musicdir parameters, but it makes no difference to whether the command will work or not! When I submit that command, this happens:

The program tells you that the database has been created almost instantly. That's because creating a database takes almost no time at all: it's the populating it that takes all the time and effort, which is what will happen next, once you press a key. Incidentally, you can confirm the existence of the database file itself by looking in $HOME/.local/share/giocoso: the database will exist as a file called <whatever database name you chose>.db. It will be pretty small, even after it's been populated, because all that's in the database is metadata about your music collection. No music files are ever copied into the database, or moved into it, for example: your music stays exactly where you put it! But the data describing that music is what the database will end up being full of... and that's just text and takes up very little space.

Anyway, here's my new database, before it's been populated with data:

As you can see, it's just 52K big at the moment, and because I've asked for a database called 'main', the database file is called 'main.db'. The filename will match the case of your dbname parameter value exactly. That is, a database called 'Main' is a completely different from one called 'main' or 'MAIN': you always need to supply --dbname in the correct case, in other words.

When you're ready then, press a key on the main Giocoso window, and it will begin to scan for music files:

As the message says, scanning for music files in a large collection can take a lot of time, though Giocoso parallelises the search as much as possible in an effort to speed things up. At this stage, the scan is simply creating a list of what music files exist. That can take a long time, depending on the size of your music collection -and there won't be any obvious indication of progress, apart from a spinning indicator. Just be patient and let the program do it's thing.

Once a complete list of music files has been prepared, Giocoso will then move on to investigating the characteristics of each music file in turn:

Here, progress will be more obvious, since Giocoso scans each discovered music file in turn for all the metadata tags it contains, it's duration and so on. All of that data it's writing into the database. Clearly, this can take a long time too -but at least you can now see progress being made, as the various music folders are visited in alphabetical order. For reference, scanning my 2TB collection of 15,000 or so recordings, over a 1Gbps network link, took just over 3 hours... so it's not exactly the speed of light, but it's not too bad, either! The fact that it took an hour longer to scan my music library on the Pi compared to even the shabbiest virtual machine I've run when documenting Giocoso on other Linux distros tells you, however, that the Pi is a bit of an asthmatic ant when it comes to processor-intensive tasks such as this one.

At the end of the scanning process, you get a statistical summary of everything that's been found:

At this point, a snapshot of your music collection has been taken and stored in Giocoso's database -which you'll recall was originally 52K big and is now:

...23MB in size. So yes, a populated Giocoso database gets significantly larger than when it's first created, but it remains fairly small, no matter how big your actual music collection happens to be, because nothing of the music itself is stored within it, just the metadata.

6.0 Database Play Mode

Once Giocoso has scanned your music collection and stored the data about it in its database, you can use Giocoso in what is termed Database Play Mode. At its simplest, you simply invoke Giocoso with the --dbname=xxxx runtime parameter, so that it knows what database you're wanting it to use. In my case, typing this command, for example:

giocoso --dbname=main

...caused this to happen:

You'll note from the top of the Giocoso window that we're in 'Database Play Mode' and using database 'Main' (Giocoso init-cases names for display purposes, but the name you supply in the --dbname parameter has to be case-aware). For some reason, Giocoso has decided to play a piece of music by Herzogenberg: I didn't ask it to do that, but Giocoso simply picked something at random, and this is what it happens to have picked.

This, in fact, is the essence of Database Play Mode: randomisation. Without other filters and 'guidance' you may provide to it, Giocoso simply picks a composer at random (each composer having an equal chance of being selected as any other, no matter how much or how little music they may have contributed to your music collection) and then picks a recording attributed (in the ARTIST tag) to that composer. You end up hearing a completely randomly-selected piece of music.

If you want to 'guide' Giocoso, so that its selections aren't completely random, you can do so by adding one or more selective runtime parameters (which are discussed at length here). Suppose you want to play a piece of randomly-selected music that's by Beethoven? This command will do it:

giocoso --dbname=main --composer=beetho

...resulting in this slightly-modified program display:

Notice how Giocoso displays your filters to you in blue, in the main part of the screen. Again, the parameter value 'beetho' has been upper-cased for display purposes -though, in fact, on this occasion, it makes no difference how you typed in the parameter value. All textual comparisons within the database are done having first forced everything (temporarily!) into upper case. You'll also spot that though I supplied the parameter value 'beetho', Giocoso has correctly found music which it knows was written by 'Ludwig van Beethoven': parameter values such as composer name are always 'wild-carded', meaning that 'bri' could match Frank Bridge as well as Benjamin Britten.

If particular performers, rather than composers, are your thing, then other runtime parameters can be fed to Giocoso. For example:

giocoso --dbname=main --comment=robles

...produces this result:

Why is something by Handel now being played in response to that request? Well, in this case, the album art gives the game away: Marisa Robles is the harpist on the recording. You'll notice back in the main part of the Giocoso display, too, that whilst Iona Brown and the Academy of St. Martin-in-the-Fields are listed as performers, so too is Marisa Robles singled out as 'harp'.

Again, you can wild-card your searches, so 'rob' would have matched Marisa Robles too... though it would also have matched 'Robin Ireland' or 'David Robertson': wild cards can be very helpful, but also result in surprises (which, in the world of making sure you don't listen to the same music over and over again is no bad thing, actually!)

I should perhaps finally mention that these sorts of runtime parameters only achieve their proper effect when you tag your FLAC files in the manner I've documented elsewhere in my 'Axioms of Classical Tagging' articles. Specifically, I used the --comment runtime parameter to find Marisa Robles because she is a performer on a recording and all the performers of a particular recording under my tagging axioms are always typed into the COMMENT tag. There is also a --performer runtime parameter, but that only searches the PERFORMER tag -and, in my system of tagging, that only contains one name, the name of the 'distinguishing artist' that makes a recording unique from any other. That means the PERFORMER tag usually contains the name of the conductor of the piece, not the singer nor the orchestra nor the harpist! If I wanted to listen to something conducted by Karajan, for example, I could certainly invoke Giocoso with the parameter --comment=karajan, but I could also use --performer=karajan, and achieve much the same results. Why duplicate in this way? Well, sometimes you get conductors who perform. Think Benjamin Britten, for example: if I wanted to hear him as a conductor, I'd say --performer=britten. If I wanted to hear him as a pianist, I'd say --comment=britten.

Anyway: this is not the place to discuss the subtleties of tagging strategies! The point to take away from here is that once Giocoso has scanned your music collection, it can play any part of it at random -or you can provide runtime parameters to guide and shape its random choices. In all cases, the program display will tell you what's been selected to play and what filters guided that choice.

7.0 Conclusion

This article was intended to get you started with Giocoso on Raspbian. To learn how to use the abc_installer script to install Giocoso; to run Giocoso in Direct Play Mode; to run it in Database Play Mode; and to fix up any album art display issues that may arise due to a lack of ImageMagick that Giocoso cannot detect. Hopefully, you've seen how easy it is to install and run Giocoso... after that, everything is simply a matter of becoming familiar with the array of things you can do with it.

For which the rest of this manual should be your guide!

[Back to Front Page]|[Giocoso on Linux]|[Giocoso on Windows]|[Giocoso on macOS]