Installing Giocoso

Giocoso has been extensively tested on the following 'main stream' Linux distros (the links take you to distro-specific installation notes and observations):

• Arch
• Debian
• Ubuntu
• Fedora
• openSUSE Leap
• openSUSE Tumbleweed
• RaspberryPi OS

If your chosen distro is based on one of these 'parent' distros, then Giocoso will likely work on it, too. Thus, in the Arch family, Giocoso has been tested to work on Manjaro, EndeavourOS, Garuda Linux and Bluestar Linux. In the Debian family, Devuan, Linux Mint Debian Edition, Peppermint OS, MX Linux and Antix Linux have all been confirmed to work. Practically everything based on Ubuntu is known to work: Linux Mint, Pop!OS, Zorin OS, Tuxedo OS and several others have been given the intensive testing treatment. Not many distros are based on Fedora, but Nobara and Ultramarine are all known to be fine. And so on.

If you are running Windows 10 or 11 on a 64-bit CPU, you can install the Windows Subsystem for Linux, Version 2 (WSL2) and, within that environment, install a Linux distro of your choice: at that point, though your main OS is Windows, you'll be able to install and run Giocoso in the context of WSL2 as successfully as if you were running the equivalent Linux distro as your main OS. You will first need to install WSL2, for which this article may be helpful. After that, you can follow the standard Giocoso installation process (see Section 2 below) to get Giocoso running. You might also want to consult the Windows-specific installation notes for some tweaks and workarounds that will be needed to get Giocoso working well on this Linux-on-Windows platform.

I should add that Giocoso 3 is 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! Nevertheless, I have installed it on Windows 11 on officially-unsupported hardware and it ran perfectly well. Whether that will always be the case, I cannot say: you're basically on your own with Windows 11!

Giocoso does not support running on anything to do with Apple. Neither will it work on the Solus Linux distro.

The basic installation procedure for any supported operating system is, in a new terminal session:

wget software.bbritten.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.

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.

Giocoso runs in a terminal session that is ideally at least 103 columns wide and 28 tall. Your choice of default font to use in such a terminal session will determine how Giocoso appears. It can look like this:

…or like this:

…or, if you really decide to pick unfortunate choices of default font and font-size, this:

From that last example in particular, you can see that injudicious font choice (or font-size choice) can really mess with Giocoso's display, with the program logo over-writing or colliding with the line drawing characters. To mitigate against this, Giocoso installs a few open source fonts whose existence can then be relied on to produce acceptable-looking program display. The main one is Luxi Mono: choose that as your terminal's default font at 12-point size and Giocoso is more or less guaranteed to display things correctly. The program shortcuts that the Giocoso installer places on your desktop and in your start menu are pre-configured to use Luxi Mono 12-point for their display, too, so they are auto-configured to display things correctly 'out of the box'.

If you choose to use different fonts, that's fine too: but you may have to play around with point sizes to get an acceptable program display.

Also note that the Giocoso installer will install the Libre Baskerville font (another open source font, so no licensing issues arise). This is a non-monospaced font (so has nothing to do with the program display in a terminal session), but is instead used to create the 'caption labels' that appear underneath displayed album art. The use of this font is hard-coded and cannot be changed.

A final factor to consider that will affect program display is the size of the album art that Giocoso will display as each new recording starts. This is configurable in the Administration menu, Option 2:

The default size is 320 (meaning that images will be displayed with a width of 320 pixels). You can increase or decrease this as the mood takes you, but don't expect the results to look very good if you over-size things:

Use of Giocoso may need a little bit of finagling at the start, in order to get these sorts of visual issues sorted. In general, however, if you're displaying Giocoso in a 103×28 terminal with a default, monospaced font that's 12px in size and with album art dimensions set to 320px, you will probably have zero display problems.

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 select and play music; the Database Management menu lets you create a music database and then add new recordings to it; 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. The Pro menu is where advanced networking functionality resides (for example, pausing a play of music in your listening room and resuming it in the garden shed!).

Use the left- and right-arrow keys to select a menu option and have its various options displayed. You can also tap the letter corresponding to the relevant menu: 'R' jumps you to the Reporting menu, for example; 'D' gets you directly to the Database Management menu, and so on. Once any given menu is displayed, tap the number shown against a menu item to select that item. For example, tap '2' when the Play Music menu is selected to perform a 'play music from selection filters' operation.

The usual way to get started with the program would be, though not necessarily in this order:

• Database Management → Create a music database
• Administration → Create or Edit the Configuration File
• 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 default database name matches the database you've actually created can you then play music using it.

By default, Giocoso is configured to expect the existence of a database called music. If you therefore start by creating a database of that name, Giocoso will be fine: as soon as a database of that name is populated with details of the music you own, you'll be able to use Giocoso to play it. If you want to name your database something else, that's OK too: use the Database Management menu to create it, then use the Administration menu to adjust the configuration file to use that distinctively-named database as the default and then you'll be able to play music.

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.

Summarising things as compactly as I can, then:

1. Read your distro's specific installation notes, to see if there are any pre- or post-installation steps you'll need to take
2. Fully update your distro, so that it's using the latest packages and patches
3. wget https://bbritten.com/software/giocoso-installer.sh
4. bash giocoso-installer.sh
5. Launch Giocoso and create a new database. If it's called “music”, play music immediately. If it's called something other than “music”, alter the configuration file to use the non-default-named database instead and then play music

I hope all your Giocoso Version 3 installations work successfully and that you get up-and-running with the new program quickly and painlessly!

[ Back to Giocoso Home Page ]