Upgrading Giocoso

1.0 Introduction

Upgrading to Giocoso version 2 from any previous Giocoso version 1 installation uses the same --checkver runtime parameter as you'd have used when moving between different point releases of Giocoso version 1: it's extremely easy, non-destructive and requires mere moments to complete.

In this article, I'll start with a Linux Lite installation of Giocoso 1.13 (the last version of Giocoso version 1) and show you how I end up with a fully-functioning Giocoso version 2. I'll start by showing you that Giocoso version 1 is running, via a database, thanks to the command giocoso --dbname=main, perfectly happily:

On the third line of the header area in that screenshot, you'll note the text reads 'Version 1.13'. Let's see if we can bump that up a notch!

2.0 Backing Up

Although the upgrade process is completely non-destructive, it would be prudent to take a copy of your existing Giocoso music database before starting. The database exists as a <name>.db file within the $HOME/.local/share/giocoso folder, so a simply way of backing up before we try upgrading things is to issue this command:

cp -r $HOME/.local/share/giocoso $HOME/Desktop

That takes the entire giocoso folder and all its contents, including any Giocoso databases you've created, and writes a copy onto your Desktop (pick a more suitable folder as the destination if you prefer, of course!) Should anything untoward happen to your database as a result of attempting the version 2 upgrade, you can just use a standard file browser to erase the contents of the botched .local/share/giocoso folder and to restore the good contents from this Desktop copy of the original.

3.0 Performing the Upgrade

To perform any Giocoso upgrade, including the one from version 1.x to 2.0, you issue the command:

giocoso --checkver

This produces the following screen output:

First, you are told that 'a newer version is available' and are invited to type 'y' to perform the upgrade (you can type 'n' to decline it, too, of course). If you agree to the upgrade, you are immediately prompted for your sudo password (because the upgrade needs to write the newer Giocoso executable into the /usr/bin folder). As soon as you type that in correctly, the upgrade happens within moments... and that's it! The upgrade is really a matter of a second or two of downloading and writing to /usr/bin.

If I immediately re-run that earlier giocoso --dbname=main command once again, I see this:

First, you'll notice that the header area now mentions 'Version 2.00', so we know the upgrade has occurred. The second thing you'll probably be aware of is that Giocoso 1.x's fondness for dashed horizontal lines has been replaced by Giocoso 2.00's use of solid horizontal lines. But the third thing you'll notice is that Giocoso isn't playing any music like it used to: some yellow text is being displayed instead!

This is a new feature of Giocoso version 2: it now uses a persistent configuration file to store commonly-used runtime parameters. On the first-time run of Giocoso version 2, no such persistent configuration file exists, so here the program has noticed this and is proposing to download a default one for you. Just press any key you like, the download will happen automatically (it takes only seconds to complete, if that)... and then the screen will change to display this:

This is the point at which you will meet Giocoso version 2's second new feature! It now checks the horizontal and vertical dimensions of the terminal window it's running in, and if it's any smaller than 103 columns wide by 28 lines high, it will display this warning message. It's in yellow, so it's only a warning... and if you press a key to continue, as the message tells you, then normal Giocoso music playback functionality will take place no matter whether your terminal meets the size requirements or not. However, to avoid seeing this message every time you run Giocoso in the future: edit your terminal profile and configure it to be at least 103x28:

You only have to do that once, of course. Also note that Giocoso version 1 tended to recommend a size of 106x27, so Giocoso version 2 is actually smaller in the width direction, though one line bigger in the vertical.

Whether you fix up the sizing issue and then press a key, or just press a key to ignore the matter for now, Giocoso will immediately start playing music as it has always done:

And here you see the solid horizontal lines and the Version 2.00 header text... but music playing as before.

Painless, really, wasn't it?!

4.0 Post-Upgrade Matters

The new persistent configuration file that you saw being downloaded earlier presents a couple of potential challenges. It's job is to supply values for Giocoso behaviour and configuration parameters that you then don't have to type out on the command line as double-hyphen runtime parameters as you launch Giocoso. The trouble is that, potentially, it will then provide values which you weren't expecting it to and you'll be left wondering why things are behaving as they are. Take this as an example: suppose I launch Giocoso with the simple command:


So I'm not supplying a --dbname=<something> runtime parameter. In Giocoso version 2, that will trigger this error:

Why is Giocoso saying 'I implied a database called music'? Well: since you didn't specify a --dbname parameter when launching Giocoso version 2, the persistent configuration parameter for that setting kicks in... and it is set to a default value of (you guessed it) "music". Now, you can get round this by explicitly supplying a --dbname=<something> runtime parameter; or you could edit the persistent configuration file (which you can most easily do by typing the command giocoso --editconf) and setting the SOURCEDB= parameter to a name that matches the database you've actually got. Either approach works -but fixing the configuration file value will mean you can launch Giocoso in future by typing 7 characters on the command prompt instead of at least 16!

Another example of where the configuration file can trip you up if you're new to it is shown in this screenshot:

Notice in the bottom line of text here that Giocoso is telling you that it's playing music to 'Device: Default'. Why's that? Well, it's the same issue: if you didn't explicitly launch Giocoso with a --device="something" runtime parameter, the default value from the persistent configuration file kicks in -and the default value is, indeed, 'default'. So again, either you need to keep using the --device runtime parameter explicitly, or you edit the persistent configuration file and set the DEVICE= parameter to a suitable value. Get the configuration file value right and you'll not need to specify --device as a runtime parameter ever again!

So: the short version is that you should probably run the command giocoso --editconf soon after upgrading to Giocoso version 2 and work your way through all the parameters found inside the persistent configuration file and set them to sensible values that apply to you and your particular setup, rather than the default values the configuration file is first shipped with.

Another possible corollary of the persistent configuration file is that if you used aliases in your .bashrc file to avoid having to type a bazillion runtime parameters, you might want to get rid of them. If you created an alias of (for example) giocoso="giocoso --dbname=main --device="plughw:0,1" so that you didn't need to keep specifying dbname and device parameters in version 1, those aliases will still work: but the better way of achieving the same thing in version 2 is to set SOURCEDB and DEVICE parameters in the persistent configuration file. Then the platform-specific way of specifying aliases become redundant.

5.0 A Word about Scrobbling

In version 1.x of Giocoso, when (or if!) you configured Giocoso to scrobble to Last.fm (i.e., transmit play information to that social website), it would store the encrypted keys needed to access your Last.fm account within a file, located at: $HOME/.config/giocoso-scrobbler/giocoso-scrobbler.conf.

That location has changed in version 2: the scrobbler.conf is now stored in the same folder as everything else Giocoso creates: $HOME/.local/share/giocoso.

The effect of this change is that immediately after upgrading a version 1.x Giocoso that knew how to scrobble, you'll find that version 2 will say, upon completion of its first post-upgrade play, that you haven't configured to scrobble, it can't therefore do so, and will thus quit playing any further music until you sort that out.

The solution to this is simple:

cp $HOME/.config/giocoso-scrobbler/giocoso-scrobbler.conf $HOME/.local/share/giocoso

That is, simply copy the pre-existing scrobbler.conf from its old location into the standard Giocoso configuration folder. Giocoso will find it there next time it's run and will use it to scrobble without further incident. This is a much simpler 'fix' than re-configuring Giocoso to scrobble from scratch (which you could do, but there's really no need).

6.0 Summary

Upgrading to Giocoso version 2 is therefore trivially easy: you simply run Giocoso with the --checkver runtime parameter and agree to the upgrade, and the job is done in mere seconds.

However, after the upgrade has happened, you may want to tweak your terminal profile to make sure terminal windows open with at least a 103x28 size.

You may also want to take the time to run giocoso --editconf and work your way through the persistent configuration file to set it to sensible, non-default values.

You may also want to review whether you previously created aliases in your .bashrc (or other environment profile-setting file) and whether, in light of the existence of a persistent configuration file, they are still needed.

Finally: I think you may well want to review the rest of the documentation about Giocoso version 2, so you understand what new features are available to you ...and what ones have disappeared! That's probably the task that will take you longest, after all. I give links to the crucial bits of documentation you should review below. Enjoy!

[Back to Front Page]|[New Features in Giocoso version 2]|[Summary of Runtime Parameters]|[The Persistent Configuration File]