Fedora is something of a workhorse distro, being in the same robustness and reliability stakes as Red Hat Enterprise Linux, whilst simultaneously being generally considered pretty cutting-edge, with two releases a year and thus access to very up-to-date packages. When Linus Torvalds himself uses your distro, you can be fairly sure you're doing something right, anyway! The distro comes in various formats: Workstation and Server are the two obvious ones; there are three others of more esoteric appeal. This documentation relates only to running Giocoso on the Workstation distro. That ships with a Gnome desktop, which I can't personally stand -and that's why I don't use it as my daily driver. However, other desktop environments can be installed and retrofitted to it post-install... but I haven't done that here, choosing to stick with the default environment. Ultimately, though, Giocoso doesn't care whether you're using Gnome, KDE or something whackier and niche: it's the underlying OS's selection of packages that matter, not the desktop manager.
Right in the middle of development work for Giocoso Version 2, a new release of Fedora Workstation (version 36) dropped, and I therefore switched to that newer version of Fedora for the purposes of writing these bits of documentation. However: Giocoso Version 2 runs perfectly well on Fedora 35, too.
As I do with all my Linux distros, I installed Fedora 36 on a VirtualBox VM, built with 4GB of vRAM and a 2-thread virtual CPU, plus a 40GB virtual hard disk. Before doing anything else, I began by ensuring the operating system was as up-to-date as possible. In Fedora's case, you do that by issuing the command
sudo dnf update
...and I thereby ended up using kernel 5.18.6 and Gnome 42.1, using the Wayland 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 you'll be prompted to supply a sudo password if you haven't already supplied one recently), 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:
The commands needed to install those missing packages is shown in bright blue, within the red error text. The command has been broken over multiple 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 dnf install...' 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 Fedora'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 (twice as it happens, as there are two separate installations involved). All up, on a fresh and fully-updated Fedora 36 installation, I had to install an extra 54 packages totalling around 34MB... but, obviously, your mileage may vary!
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:
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, 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 A Word About Fonts
You've just seen that Giocoso runs fine on Fedora in what's called 'Direct Play Mode' -where you are sitting in a folder containing some FLACs and directly invoke the program from there. Look closer at the album art that's displayed in the last screenshot, however:
You couldn't be expected to know it, but the font used underneath the album art picture (in this case containing the words 'Benjamin Briteen: Gloriana') is wrong. It's displaying the text perfectly legibly, but it's falling back on a system default font rather than the one actually intended. If you'd like to fix that up (and clearly, it's optional to do so!), issue this command in a terminal session:
sudo dnf install dejavu-serif-fonts
...and once that 1MB package has been installed, re-running Giocoso in the same folder as before should result in this:
The difference is subtle and, to be honest, pretty minimal: but that's an album art caption displaying as this author intended it should! Note that you can list all fonts available on your system with the command fc-list and can take a name from there and enter it into the $HOME/.local/share/giocoso/giocoso.conf persistent configuration file as the value for the CAPTIONFONT parameter and thereby achieve all manner of font effects. Here are three examples of what can be done:
...and so on. Pick extremely weird fonts, however, and you are liable to break things or at least achieve unpredictable results! So go easy on the font customisation, please 🙂
5.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:
...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:
...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 Edvard Grieg: 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.
This article was intended to get you started with Giocoso on Fedora. 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!