Installing Giocoso on Manjaro

1.0 Introduction

Manjaro has been, for many years, my own personal distro of choice (with occasional bouts of infidelity that were swiftly rectified!). It offers all the power of Arch, but presented in a user-friendly manner, with most software packages you could ever want to use being readily and easily available. It makes for a fine platform on which to run Giocoso, basically, and there will be zero issues arising when you attempt to do so!

For the purposes of this article, I built a new VirtualBox virtual machine, using 4GB of vRAM and a 2-thread virtual CPU, plus a 40GB virtual hard disk and proceeded to install Manjaro+KDE and the Plasma desktop, using the full ISO available from the Manjaro website. That said, the choice of desktop is irrelevant from Giocoso's perspective: it will run perfectly fine with any of their other desktop environment options, too.

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

sudo pacman -Syu

...and I thereby ended up using kernel 5.15.48-1 and KDE Plasma 5.24.5, using 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:

Here, Giocoso has performed a software inventory on your Manjaro system and decided 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. The command has been broken over two lines, though, and you'll need to type it in as a single line ...or you could copy the blue text, paste it into a text editor, knock it into a single-line version there, then copy-and-paste it back into the terminal. However you choose to do it, you need to submit that 'sudo pacman...' command now, before we can go any further:

Press [Enter] to submit those commands and everything Giocoso needs to run will be installed for you, using Manjaro's standard package management functionality. If you haven't recently used the sudo command, you'll be prompted to supply a password and, as you see above, you'll be asked to confirm the installation of any packages before any changes are made to your system. You'll note, too, from the above screenshot that the software requirements are fairly minimal (in my case, around 3MB).

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, this time I 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 will perform a software inventory and prompt for the installation of missing packages
  • Once those extra software packages are installed, Giocoso can be run a second time and it will then download a default, persistent configuration file
  • As soon as the persistent configuration file has been downloaded, Giocoso will error out, because the default configuration tells it to use a database that doesn't yet exist
  • So you run it a third time with --dbname=none
  • But it will error yet again, because it can't find any music to play in the folder you're working in
  • So you 'cd' to a folder containing a FLAC, run it a fifth 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 under 2 hours... so it's not exactly the speed of light, but it's not too bad, either!

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 upper-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 Karl Hartmann: 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 in 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 Dittersdorf 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 Manjaro. To learn how to use the abc_installer script to install Giocoso; to run Giocoso in Direct Play Mode; and finally to run it in Database Play Mode, with and without filters to 'guide' the randomisation process. 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]|[Back to Installing on Linux]