1.0 Operating System Support
The Giocoso Version 3 installation process is now fully-automated and does everything required to make the program work properly (previous versions would detect what needed to be done to get things running but then ask you to issue the necessary commands, manually). The installer also notices if an earlier version of Giocoso is already present on the system and, if so, backs it up, converts it to Version 3 format and makes it immediately available to the new program version.
Giocoso on Linux
Giocoso runs on all major Linux distros: my basic rule of thumb is to take the top 20 distros listed on Distrowatch's Page Hit Ranking at the start of major program development and make sure the resulting Giocoso runs fine on all of them. I then add in a sprinkling of other distros that appeal to me for one reason or another, even if they don't seem terribly popular, according to Distrowatch! Since most distros are actually derived from other, 'parent' distros (Mint, for example, is a variant of Ubuntu, as Manjaro is of Arch), we can construct a 'support matrix' for what Giocoso runs on, based on the principle 'family', as follows:
| Arch Family | Debian Family | Ubuntu Family | Fedora Family | openSUSE Family | ARM Family |
|---|---|---|---|---|---|
| Arch | Debian | Ubuntu | Fedora | openSUSE Leap | Raspberry Pi OS |
| Manjaro | Devuan | Linux Mint | Nobara | Tumbleweed | Manjaro on Pi |
| EndeavourOS | Linux Mint Debian Edition | Pop! OS | Ultramarine | GeckoLinux | Ubuntu on Pi |
| Garuda Linux | Peppermint OS | Linux Lite | |||
| Bluestar Linux | MX Linux | Zorin OS | |||
| AntiX Linux | Elementary OS | ||||
| KDE Neon | |||||
| Tuxedo OS |
The last column there is a bit of a stretch: ARM is a CPU architecture, not a distro family... but the point is that Giocoso will run on those Linux distros that are able to be installed on ARM chips used in the Raspberry Pi 4 (the 3 and 5 variants of that device have not been tested, however).
You will note that each name in that table is hyperlinked: follow the links to specific Giocoso installation notes, describing any quirks and workarounds needed to get Giocoso running on that distro. I will mention ahead of time that almost all members of the Debian family give superb Giocoso results. Almost all members of the Ubuntu family give very good Giocoso results. The Arch family gives mixed results, as does the Fedora family, though they can be worked around. The worst results were all from the openSUSE family: for the most part, they can be worked around, but GeckoLinux is a bit of a shocker: wildly inconsistent outcomes, depending on your choice of desktop environment, and with multiple points of breakage. Avoid Gecko, basically, if at all possible!
All distros should be fully updated (by you!) with their latest security and software patches before you even start to install Giocoso.
Giocoso on Windows
Any of the above distros running on Windows 10 or 11, via the WSL2 (Windows Subsystem for Linux, version 2), should also work without drama (though only Ubuntu-on-Windows, Debian-on-Windows and Manjaro-on-Windows have actually been tested at length). You will first need to install WSL2, for which this article may be helpful. After that, you can go ahead and install different distros 'within' Windows and, once they are running, you can follow the standard Giocoso installation process (see Section 2 below) to get Giocoso running. After that, you should see the Windows installation notes for some specific tweaks and workarounds that will be needed to get Giocoso working well on this Linux-on-Windows platform.
Unsupported Operating Systems
Please note that Giocoso Version 3 drops support for being installed on anything to do with Apple Macs or Solus (a weird Linux distro that doesn't even have xterm in its repositories, which seems to me like trying to fly an aeroplane without any wings). It is possible that Giocoso Version 3 will run on Macs, but I have expended precisely zero effort in checking to see whether it does or not, and don't propose to do so in the future. If you would like to buy me some Apple hardware using M2 or M3 CPUs, then I'll revisit that decision, but until then, I'm unable to do anything meaningful in the Apple realm.
Giocoso 3 is also technically unsupported on Windows 11, in the sense that whilst it runs perfectly fine on my various Windows 11 installations, I don't actually own any hardware that is officially supported for running Windows 11 itself. I can't really say I support running Giocoso Version 3 on an operating system that I cannot myself get official support for!
2.0 Installing Giocoso
The basic installation procedure for any supported operating system is
wget doco.absolutelybaching.com/gioinst
The installer is small (around 20KB) , so it will take hardly any time to download it. Once the installer has been downloaded, you launch it in the same folder you saved it to, with the command:
bash gioinst
You will first see a screen warning you that the installer will make quite a few changes to your system, if you let it:
You need to type 'y' (and then press [Enter]) to proceed. If you type anything else, the installer will terminate without having touched your system at all.
2.1 Software packages needed for Giocoso to work
To start with, the Giocoso installer will check for the presence of various packages on your system and will seek to install any that it finds to be missing. You can usually just let it do it's thing at this point, but if you are interested, here are the packages/programs that Giocoso deems essential to install:
- sqlite3 (a database)
- ImageMagick (an image processing program)
- ncurses (a program that allows command-line interfaces to look a bit more like graphical interfaces)
- grep (a text processing program)
- libsixel (a program which allows pictures to be displayed inside a terminal)
- util-linux (a program that allows for the generation of universally unique identifiers, or UUIDs)
- fontconfig (a utility for managing fonts) bc (a computational library that allows Bash to do floating point arithmetic)
- fmt (a tool allowing text messages to be wrapped across a terminal with proper formatting)
- xdotool (a utility allowing command-line management of window placement and sizing)
- xdpyinfo (a utility for determining the current screen resolution)
- flac (the library that allows FLAC audio files to be read and understood)
- ffmpeg (an audio player)
- xclip (a little utility allowing command line management of the clipboard)
- nano (a simple text editor)
- curl (a command line tool for fetching files across the Internet)
- xterm (a terminal emulator or console window)
- dialog (a program that allows programs to draw GUI-like message boxes, file selectors and so on)
If having any of those installed on your system gives you cause for concern, type 'n' when the installer prompts you and give up on the idea of installing Giocoso altogether: the program cannot run without all of them being present, I'm afraid.
2.2 A Word About Fonts
In addition to the above packages, Giocoso 3 also installs two open source fonts to allow it to display itself in a known, good manner. These are Space Mono and Libre Baskerville. Space Mono is used to display the main program and its menus; Libre Baskerville is used to create the 'caption labels' that appear underneath displayed album art. The fact that these fonts are auto-installed for you does not mean that you are required to use them when running Giocoso, though: the program's functionality isn't affected by its mere appearance, after all.
However, if you choose to use non-supplied fonts, you may well find that when album art is displayed, it messes around badly with the program display:
Now, you can always fix these display glitches (the over-sized album art, for example, can be adjusted in the Administration menu, Option 3, by setting the 'Size of album art when displayed' option to new values). The more fundamental point is, however, that if you use the Giocoso-supplied fonts, things should look fine without any fiddling whatsoever.
2.3 Version 2 Database Conversion
If the Giocoso Version 3 installer detects the presence of Giocoso Version 2, then it will attempt to bring across a copy of your Version 2 database(s) to the new installation. It also applies some minor structural modifications to these copies of the prior version databases. The process is described in some detail here, but the short version is that the process ought to be non-destructive and go without incident. However, it's code, code can have bugs... and in any case, it might be an alternate Thursday with a blue moon: you are strongly recommended to back up your Giocoso Version 2 databases before attempting to install Version 3, even though the Version 3 installer will take backups anyway.
3.0 Getting Started, post-Install
Once Giocoso is installed, you can launch it by (a) clicking on the launcher provided on the Desktop (some distros require you to 'trust' or 'mark as executable' the launcher before it will work); or (b) clicking the option provided somewhere in the main menu, which is usually to be found under 'Multimedia' or (depending on distro) 'Sounds & Video'. The main program display should then appear:
Operation of the program beyond this point is hopefully self-explanatory: the Play Music menu lets you, er, actually play music (!); the Database Management menu lets you create a music database and then add new recordings to it over time; the Reporting menu lets you query your music database and generate reports from it, such as how many recordings you own, what proportion of them you've played and so on; the Administration menu lets check for program updates or re-configure the persistent configuration file, and similar tasks; whilst the Control menu lets you send 'messages' to another, music-playing session, telling it to pause/resume, stop playback immediately, stop playback when the current recording ends and so on.
The usual way to really get started with the program would be, though not necessarily in this order:
- Administration -> Create/Edit the Configuration File
- Database Management -> Create a music database
- Play Music -> Play music with defaults
The underlying issue here is that you need (a) to have a database listing all the FLACs you possess; and (b) to have Giocoso configured to open that database by default; and (c) only when the configured database name matches the database you've created can you then play music using it. This means:
If you're coming from Giocoso Version 2, you already have a database (that's been migrated across for you) whose name might not be 'music'. In this case, you skip the 'create database' step entirely and instead edit the configuration file so that its default database is the same name as the Version 2 database that's been migrated across. Once the configuration file knows the name of your pre-existing database, you can skip straight to the playing music stage.
If you're completely new to Giocoso, though, you won't have an existing database at all, so the configuration file's default value of 'music' is as good as anything else -with the only proviso being that a database of that name doesn't actually exist yet! So, in this situation, you'd skip the editing the configuration file stage of proceedings and move straight into creating a new music database, which you'd make sure to name 'music' as you do so. Again, once the configuration file's default name matches the actual name of a database that physically exists, you can move on to playing music.
Lastly, if you are new to Giocoso but want to create a database that isn't called 'music', you'd have to create the database first using whatever name you like, then configure the configuration file to make that new database the default, and only when the two match can you finally move on to playing music with it.
Beyond that quick-start approach, however, you should read the relevant pages elsewhere in the user manual for an exploration (and explanation!) of the rest of the program's functionality,
4.0 Conclusion
Summarising things as compactly as I can, then:
- Read your distro's specific installation notes, to see if there are any pre- or post-installation steps you'll need to take
- Fully update your distro, so that it's using the latest packages and patches
- If you're already running Giocoso Version 2, read the upgrading steps article and follow them
- wget doco.absolutelybaching.com/gioinst
- bash gioinst
- Launch Giocoso and make the configured default database name match whatever database already exists, or that you have created.
If you are coming from Giocoso Version 2, there's one extra step to add to that lot:
- When you are happy that Giocoso 3 is running successfully, clean out the $HOME/.local/share/giocoso folder and the /usr/bin/giocoso.sh script: in other words, delete all traces of Giocoso Version 2
I hope all your Giocoso Version 3 installations work successfully and that you get up-and-running with the new program quickly and painlessly!
[ User Manual Home ]