BBritten.com - softwares:giocoso

changelog - [Giocoso Version 3.38 - No current scheduled date]

hjr (hjr@undisclosed.example.com) — 2026-04-01T09:06:19+00:00

Giocoso Version 3 Changelog

The Changelog will record code changes to the release version of Giocoso Version 3 as they are themselves scheduled and, eventually, released.

Changes are listed in reverse chronological order (i.e., the most recent releases appear first).

For the most part, the main user manual for Giocoso will not be updated to take account of program changes that the Changelog details. You need to read the user manual in conjunction with this Changelog to get a full understanding of the current program functionality and its capabilities.

Sometimes, I may go back and modify the user manual when changes appear to me to represent significant differences from the way the program was behaving when the documentation was originally written, but this is definitely not guaranteed.

Giocoso Version 3.38 - No current scheduled date

Fix: Last release introduced a logo picture size parameter, governing the size of the 'Beethoven with Headphones' image and defaulting it to 220×220 pixels. On reflection, that is probably much too big for most standard monitor displays, so this release changes the default to 110×110 pixels. It remains possible, of course, to set it to any square size you like: it's just the default size which changes.

Code modification: Of no practical difference at all, the pieces of code which ensure new shell scripts are downloaded during updates of existing installations has been moved from one shell script to another. It works in exactly the same way as before, but is just differently located.

Giocoso Version 3.37 - March 31st, 2026

Enhancement: The report on composers not played in past 60 days (Reporting menu, Option A) has been enhanced slightly with an additional column showing the number of days. since that composer's last play (previously, only a last-played calendar date was shown: this is now also converted into a 'number of days since now' display).

Bug-fix: There has long been an ARTSIZE parameter to control how large album artwork embedded into a set of FLACs should be displayed as music plays. It is expressed as a single number (say, 580) which is then treated as an instruction to resize the artwork to be displayed at 580 pixels wide by 580 pixels tall. Poor syntax implementation meant, however, that the resizing was not performed correctly in both dimensions, but only in one. That has now been fixed. You will still end up with square imagery, sized in both dimensions to the one number of pixels specified in the configuration settings and with (deliberately!) no regard for aspect ratios; it will just now be done correctly!

Enhancement: Two new persistent configuration parameters have been added to the configuration screen options: “Program Logo size” (defaults to 220 pixels) and “Program Logo position” (defaults to 0). This last parameter is entered as a negative [to move left] or positive [to move right] integer. For example, an entry of “-2” means 'position the logo two characters to the left of its programmed starting position'. These parameters have been necessitated by the realisation that Retina and non-Retina displays render things very differently… and what looks perfect on my iMac looks awful on my Lenovo laptop! Tweaking these two parameters allows you to make the program look good no matter the screen you're running on.

Minor Enhancement: The software licence is now viewable within a dialog form, rather than with the less utility.

Significant Enhancement / Bug-fix: The logic for doing default searches of music to play (Option 1 on the Play Music) has been significantly revised. As explained in this blog piece, there was a bit of a logic bomb lurking in Giocoso's random selection code. By ranking per-composer recordings before deciding whether any recording qualified, on configured selection grounds, to be played, Giocoso was making it very hard for an eligible recording to be actually selected. The code change now makes all eligible recordings capable of selection, meaning that Giocoso will now more easily find a diverse set of qualifying recordings to play. In plain English, Giocoso's random selection was previously failing to find things to play when it could and should have because it was doing things in a logically over-restrictive way. Now, that won't be the case.

Modification: The Pro menu used only to be visible if you'd configured the IP address of a MySQL database that was acting as a Pro database. Now, the Pro menu item is visible all the time, no matter what you've configured… but you won't actually be able to move into the Pro menu unless your configuration is set to point to a Pro database. In other words, if you are sitting on the top 'Administration' item, you'll always see something labelled “Pro”. If you haven't configured a Pro server, however, if you tap the right-arrow button you will jump over the Pro menu item and land on 'Quit'. Tap the left-arrow key and again you'll jump over the Pro menu and land back on 'Administration'.

Modification/Bug-fix: Some menus have more than 9 items (for example, Reporting, which had items A and B in addition to nine numbered items). Those extra items were inadvertently assigned letters which conflict with the top-menu items: for example, tapping 'A' to produce the 'Composers not played in past 60 days' report conflicted with the 'A' for Administration menu move. That has now been resolved by making sure 10th and subsequent items do not use letter shortcuts that conflict with anything else. An altogether worse bug was that if you ever landed on the Pro menu, no other top menu options worked: you could tap 'D' to jump to the Database Management menu and absolutely nothing would happen! That has now been fixed.

Enhancement: The Administration menu gets a new Option 8: Change the program colour scheme. This brings up a form that lets you assign colour numbers to each of the Giocoso program display elements and thereby change the look of the program to something that suits you better than the defaults I designed it with:

Here, for example, I'm saying I want the Program logo and boilerplate text to appear bright red, rather than it's default 'normal cyan'. The result would be a rather garish confection like this:

Giocoso is thus brought into line with all my other software programs and now thereby caters to those users who don't use jet-black terminal emulator colour profiles.

Giocoso Version 3.36 - March 18th, 2026

Bug-fix: Giocoso is written in the United Kingdom, where we expect numbers to be written as “1.43”, using a full-stop as the decimal point. Trouble is, anyone using Giocoso in Europe (for example) would expect that to be written as “1,43” with a comma as the decimal point. European operating systems presented with “1.43” will declare it to be an invalid number and mayhem results. This has recently come to light as an example of UK small-mindedness (and my inability to think globally) as a result of a user in Germany (or at least, using a German locale on a Tuxedo OS) encountering an 'invalid number' error when trying to implement Giocoso's ReplayGain functionality. This has now been corrected, by forcing Giocoso to use a locale in which full-stops are regarded as 'correct', no matter what the wider operating system may think. My thanks to Helmut for the bug report and working with me to confirm the nature of the problem and success of the fix. If users in other non-UK lands have equally exotic number representation issues, this fix should resolve it for them too.

Bug-fix: Tiny issue, but the Aggregate Statistics report mentioned 'Stat' in one section and 'stat' in another: the inconsistency in capitalisation has now been resolved.

Bug-fix: When reporting a completed play to the Giocoso Pro database, macOS would not identify itself correctly, resulting in the os_type column in the GLOBAL_PLAYS table remaining blank. It now reports 'macOS xxxxx' correctly, where the 'xxxxx' bit will be 'Tahoe', 'Sequoia', 'Sonoma', 'Ventura' and so on.

New Feature: MacOS can now do PulseAudio playback. That is, you can run Giocoso on your desktop iMac or Mac Mini and have the audio play via some other PC anywhere on your network. It's a bit fiddly to configure (article incoming!!), but so long as your Mac has the environment variable PULSE_SERVER set, and has a version of ffmpeg installed that works with PulseAudio, and there's a remote PC configured to act as a PulseAudio server, then you press play on the iMac and the sound comes out via a Debian box or an Arch PC.

New Feature: Not specific to macOS at all, but a consequence of me tinkering with the code required to achieve PulseAudio playback generally, even on Linux: there is a new configuration parameter:

This is under the 'text entries' parameters: PulseAudio Server IP Address is the IP address of the PC to which you wish your music playback to be directed over the network. It works in conjunction with the later (and long-existing) yes/no parameter to Force the use of PulseAudio:

In all earlier releases of Giocoso, if you set 'force PulseAudio' to yes, the server to which audio would be sent would be dictated by whatever you had manually remembered to set with the PULSE_SERVER environment variable before you even launched Giocoso. Now, the IP address you set for the new 'PulseAudio IP Address' will override any environment variable you may have set. Note that if you type an invalid IP address entry into this new parameter field, it is ignored: type “192.168.137.876”, for example, and no valid PulseAudio server will have been specified at all.

Also note that if you set a valid value for the Server IP address, but do not also set 'force PulseAudio' to yes, then the IP address is ignored: audio being transmitted over the home network requires both parameters to be set, not just one. New documentation for this feature is being prepared: PulseAudio is a complex subject! The new parameters do allow, however, for a powerful desktop PC to be the 'playing PC', but for sound to be heard coming out of a relatively trivial Raspberry Pi that happens to be hooked up to your DAC, amplifier and speakers! Being able to modify the IP address 'inside' Giocoso also makes it convenient to broadcast audio to a variety of 'player PCs' dotted around your house. If you need music playing in your greenhouse, you can set the IP address to 192.168.0.52; you come back inside and need music in your kitchen, just adjust the IP address to 192.168.0.76 and hit 'play' once more… Sort of like a Sonos multi-room capability, but without the huge cost or proprietariness!

Significant New Feature: A minimal player mode has been created:

This is essentially a cut-down Play menu that lets you initiate a 'default play' only: no filtered search allowed, no playing music directly in a folder, etc., etc. You get a standard, randomised search for something to play that depends on what you've configured in your persistent configuration file (and which requires the full-blown Giocoso interface to modify). Once play has been initiated, the display changes to this:

You get to see information about the music playing but you don't get any album art or play duration/countdown data as you would in the full-blown Giocoso interface: this is for kicking off music playback using a mobile telephone or tablet, on a remote device, over ssh. Usually such terminal emulators don't handle graphics display in-terminal at all, so the lack of graphics components in this display is completely deliberate. The lack of a countdown timer is more a function of the lack of space on such terminal displays, to be fair!

This new player mode essentially takes the place of Mgiocoso, which is now therefore deprecated (it's still there for now and works as ever it did, but it will be removed in a future version). The new feature is enabled by running the command minig.

New Feature: Related to this new mini-player mode, the “Set up PulseAudio Server details” allows you to configure up to five 'audio sinks':

Free-form text labels are paired with IP addresses (and stored in the local Giocoso database as the table PULSESINKS). These can then be used when taking the new mini-player option 1, to select a PulseAudio sink to 'play to':

If your Giocoso installation is configured to use PulseAudio, whatever server/sink you select on this screen overrides the one exported as the PULSE_SERVER in your shell environment and the one configured in the new Giocoso persistent parameter file, for the purposes of music playback initiated by the mini-player. In other words, there's a hierarchy of specifying which PulseAudio server receives this Giocoso's audio stream: the PULSE_SERVER environment variable, over-ridden by the new configuration parameter setting, over-ridden by this mini-player setting.

Note that if you don't set 'force the use of PulseAudio' to 'yes' in the main configuration file, it won't matter what PulseAudio server you pick here: playback will always be directed to the local machine on which the miniplayer is running. Only when PulseAudio is forced will the server selection kick in and direct playback to whatever sink/server you've specified.

Bug-fix: On the Reporting menu, Option A is said to list 'Composers not played in the past 60 days'. The report then went on to list composers not played in the past 120 days. The report code has been adjusted to match what the menu says it will list!

Changed Feature: This is possibly a bug-fix too! I've long known that if your terminal didn't use a jet-black background then the Giocoso program logo would appear awkwardly in the terminal:

The issue is simply that I put that logo together in some art package or other from 'components' lying about the place without a lot of thought… and it's black background thus got 'baked' in-place for evermore, meaning it sticks out like a sore thumb when your terminal background isn't jet black to match. It's not exactly a show-stopper, but it's less than great for light-background terminals and the like. So: welcome to the new, almost-completely text-based logo:

I am not a fan of ASCII art, but at least it keeps everything completely text-based and thus truly independent of the terminal background. Other terminal colour schemes work well, too:

But some will still be a disaster -but not for particularly logo-related reasons:

This is not the logo looking odd but the entire colour scheme of the terminal working against Giocoso's choice of text colours. The only fix for that remains choosing a different terminal colour profile, I'm afraid!

Giocoso Version 3.35 - February 22nd, 2026

Bug-fix: Reports were re-coded carefully to work on macOS in Version 3.34… provided you were using Giocoso Pro features! If you were only using a local database, then some of the reports would have failed to display properly. Now fixed: all reports run perfectly on macOS in both local and Pro modes.

Enhancement: A new Report (Option A on the Reporting menu) has been created that lists all composers who haven't been played within the past 120 days (an arbitrary cut-off point, I'll admit): these might be composers you want to force playback for.

Enhancement: Further improvements in code to make Giocoso a first-class macOS citizen! A specific example: being able to tap the 'B' key on any menu and have Sqlitebrowser launch, if that program is already installed. You could do that only on Linux before, but now it works on macOS, too.

Significant Enhancement: Giocoso's reporting capabilities have been overhauled. All reports now output as HTML to your system's default browser, with polished and responsive formatting. For example:

Enhancement: You now no longer have to remember that Pro table names have a global_ prefix when doing Advanced SQL Reporting (Reporting menu, Option 5). In previous versions, you had to know that when querying in global mode, it was “select * from global_plays”, but in local mode it's just “select * from plays”. Similarly, you had to know whether you were supposed to be querying global_recordings or just recordings. That's all handled for you now: if you query “global_plays” when in non-Pro mode, your query will be silently re-written to mention “plays”. Likewise, querying “recordings” or “plays” when in Pro mode, your SQL will be silently re-written to refer to “global_recordings” or “global_plays”. The short version is that if all your queries mention just “plays” and “recordings”, they'll work no matter which reporting mode you're in.

New Feature: A new configuration parameter has been created to allow you to specify your preferred browser in which to open Giocoso reports:

The new parameter is the last one on the first page: Preferred browser. If you leave this field blank, Giocoso will use whatever your system's default browser is. If you specify a name here, however, as I have done, then that will be the browser Giocoso uses instead (if it exists). If you name a browser that doesn't exist (for example, you accidentally type “fyrefox”) then Giocoso will fall back to using the system's default browser instead. This flexibility means that the new reporting functionality might produce results like this:

…or like this:

It's the same data, just presented by (in the first case) Firefox and (in the second) w3m browsers: the option to keep things within the terminal window is still there, in other words. Incidentally, w3m has become a dependency of Giocoso's: it will attempt to install it as part of its own install, though if it cannot do so for one reason or another, reporting capabilities will not be compromised.

New Feature: A new selection filter has been added to the form you see when you take the Play Music menu, Option 2:

The new filter says “Find me composers who haven't been played in X number of days and play some of their music for me”. It is an unusual filter in one sense because it negates every other filter you may have set on the form. That is, it cannot be combined with any of the other filters: if you set the 'play me long-unplayed composers' filter and the 'where the maximum duration is 60 minutes', you will get long-unplayed composers' music however long it plays for. The maximum duration filter will be silently ignored (and so will any other filter you may have set).

Enhancement: A new “timeout” parameter has been applied to all attempted connections to a Pro database (when one is in use, obviously). If your network was dodgy or you accidentally specified the wrong IP address for the Pro database, Giocoso would keep locking up and being unresponsive for up to around 10 seconds, until the database connection attempt failed (ask me how I know!). A new “connection-timeout” of 1 second has been applied to all attempts at connecting to a Pro database, so there is now only a momentary wait before the connection fails. This doesn't much help you, of course, in the sense that not being able to connect to a Pro database rather spoils the fun of using Giocoso Pro: nothing works! But at least your system doesn't now just appear to hang for no apparent reason.

Enhancement: A streamlined upgrade procedure has been implemented. It's simpler and faster than before.

There has been quite a flurry of new Giocoso releases lately: that's largely a function of the fact that I've been getting it to work on macOS and, in the process, tidying up quite a few long-standing irritations. I think it fair to say that this phase is now over: I will certainly keep releasing new versions as the need arises (and bugs are pointed out to me!) but, as of right now, I'm fairly convinced that Giocoso is working as I want it to, on all the platforms I need it to, and I don't, therefore, anticipate very many new releases in the immediate future.

Giocoso Version 3.34 - February 8th, 2026

Enhancement/New Feature: Giocoso has acquired ReplayGain playback capability. ReplayGain is a standard way of describing how much to boost an audio signal by at playback time, dynamically, with the information stored in special metadata tags. If enabled in the program configuration settings, Giocoso will now read the REPLAYGAIN_ALBUM_GAIN tag and apply the value it has been assigned to increase the playback volume by that amount. For example, when shown this set of FLACs:

…Giocoso will automatically play the music back with a +10.73dB volume boost (although it applies a hard cap, so that only a boost of +7.5dB will take place: this avoids making too dramatic a volume change to something the recording engineer presumably mastered excessively quietly for a reason).

To support the new functionality, the Administration menu, Option 2 Create or Edit the Configuration file gets a new option:

The parameter takes a value of yes or no: no is the default. If set to yes and if the first FLAC in a folder contains a REPLAYGAIN_ALBUM_GAIN metadata tag, then the appropriate volume boost will be dynamically applied. If set to no or there is no REPLAYGAIN_ALBUM_GAIN tag, then no dynamic volume boost will take place.

Playback of music will now show whether ReplayGain is being applied or not:

The last line of descriptive text on the left of the screen will say 'ReplayGain Applied: None“ if no REPLAYGAIN_ALBUM_GAIN tag exists or if the new configuration parameter is set to a value of “no”.

Note that ReplayGain uses a completely different acoustic model than simply boosting a FLACs audio to its maximum loudness without distortion. As a result, if you've previously volume boosted your FLACs using Semplice's 'real' mode, you may well now see this happen when playing those FLACs in Giocoso:

That ”-0.18 dB“ Replay “gain” tells you that the physical FLAC has been boosted to a non-distorting loudness that ReplayGain considers too loud. That's absolutely fine: it doesn't mean the physical volume boost has done any harm to your FLACs. They are simply too loud for ReplayGain's taste (which is hard-coded to think that an 89dB volume is just fine).

Minor Enhancement: The mgiocoso script now displays what ReplayGain (if any) has been applied for playback of the currently-playing FLAC:

If no ReplayGain is being applied, the line will display a value of “none”.

Interface Change: The program display has been modified slightly during playback of music, as you've seen in the above screenshots. The composition details are now delineated apart from the 'recording details/history' part of the display. A new “days since last played” item of data also makes an appearance (which will also display an approximate conversion into a years-since-last-played figure, if it's been more than 365 days), as well as the new ReplayGain data.

Minor Bug Fixes: Various fixes to code have been implemented to allow Giocoso to run on the latest versions of macOS running on Apple Silicon chips and using Homebrew packages to satisfy software dependencies. In particular, it was discovered that the default ImageMagick installation on these more modern Macs could not do text manipulation and would trigger Giocoso to fail in ugly ways. That is all now handled by the Giocoso installation script and by subtler code dealing with the production of the 'caption bar' under any album art that is displayed during playback. On macOS, album art captions are now always coded to use the built-in Palatino font.

Bug Fixes: The Reporting menu, Options 6, 7, 8 and 9 had a bug in them that prevented reports from displaying at all on macOS (because they used a Linux-ism to open the reports in the system's default browser). That has now been resolved and those reports will now also open in macOS' default browser, too.

Enhancement: Not that anyone would really notice, but the code controlling the playback of music has been re-factored to make maintenance easier in the future.

Major Enhancement: Mgiocoso is Giocoso's optional “control panel”: you run it on a mobile device, for example, to be able to send control commands to a playing Giocoso session (i.e., tell it to pause, resume, autostop or terminate etc). If you need the functionality (such as being able to see precisely what is playing on a headless Raspberry Pi that's playing away in a drawer), it's a nice tool. It was written in a hurry, however, and the display 'flashed' repeatedly every 5 seconds as the thing re-checked what the playing session was doing. The whole thing has now been re-written to be much more intelligent about when it updates its display. It also acquires “ReplyGain” and “Days since last play” data in its display. Mgiocoso now runs properly on macOS, too:

Enhancement: If you are running in Pro mode, a fast refresh to pick up new recordings has always triggered a complete re-build of the Pro server's copy of the recordings table. This means you discover 3 new recordings locally… but then have to endure loading 17000 records to the Pro server over the network! The new feature in this release of Giocoso is that fast refreshes only load the newly-discovered recordings to the remote database. If it happens that the global database knows about recordings that no longer exist in the local database (perhaps because you moved them to a different physical path or re-tagged them) then the fast refresh process now also deletes out the 'unwanted' recordings from the global database, thereby keeping local and remote databases 'in sync'. The result is a considerably faster remote data load. Full local refreshes still completely re-load the remote database, of course.

Giocoso Version 3.33 - January 1st, 2026

Minor Enhancement: The font size used to generate the captions for display under the album art display when music is playing has always been fixed (at 14 or 16pt, depending on certain factors). On high-resolution screens or when Kitty graphics are used to do the artwork display, this is problematic: the caption text tends to come out much too small when you start increasing the display size of the artwork itself. This is now not the case. Giocoso will now take the configured artwork display size (for example, 500, meaning “500px x 500px), divide by 100 (i.e., 5 in this case) and multiply by 4 to give a final text size of 20pt. Change the artwork size to, say, 600×600 and the caption text point size will become 24pt (i.e., 6*4). This seems to yield acceptable results on all manner of screen resolutions and with varying artwork size configurations. On a related note, the caption panel itself was also always previously fixed at 45 pixels tall: that looks absurdly small when album art is displayed at sizes of 600 or more pixels. Accordingly, it too is now sized dynamically to be as wide as the album art work and as tall as 10% of that. That is, if you set album art to display at 600 pixels, the caption bar will be 600 pixels wide and 60 tall; set a size of 475 and the caption bar will be 475×47 and so on.

The difference is subtle, but apparent:

Here's the before-shot, when caption bar height and text point size were fixed:

…where I think we can agree that the two-line caption under the album art is a bit spidery, a tad small and quite hard to read. And here's the revised version:

…where the caption is taller, the text is in a larger font and it's all a bit more legible.

Bug Fix: From the screenshots above, you'll notice that Giocoso, when running on macOS, was not doing a very good job at presenting the 'Selection 2 of 2' data in the top right-hand corner of the program display. There, you'll see it padding the first number with zeroes and the second with spaces …and padding with enough spaces or zeroes to represent a 5-digit number in each case. Not a good look …and entirely down to the variables involves being treated as strings, not numbers. This has now been corrected, and Giocoso on macOS displays the counts much more appropriately:

Minor Enhancements: Other minor tweaks and improvements to the way Giocoso installs and runs on macOS have been made, in light of further testing on more modern OS releases, and with due regard to the difference between the way Homebrew and MacPorts work.

Significant Enhancement: Screen redrawing has always been fairly slow, such that on less powerful computers (such as Raspberry Pi, or old Intel hardware) the screen could seem to 'flash' annoyingly when, for example, you tapped along the top menu options (from Play to Database to Reporting, for example). Sometimes, screen refreshes were so slow to occur that you'd be able to see escape sequences (such as “^[[C”) displayed on the screen as menu navigation took place, making things very ugly indeed. Accordingly, the screen redrawing code has been completely overhauled and now the program responds much more cleanly and swiftly to events that trigger screen redraws. The result is that even on low spec hardware, Giocoso now 'flashes' very infrequently and the random appearance of escape sequences on screen should almost never occur. This is achieved basically by replacing calls to the external “tput” utility with a pure Bash approach that keeps everything within the one Bash session, resulting in much less context switching on the CPU, and hence a swifter-feeling interface.

Bug Fix: The new handling of Kitty graphics in Version 3.32 introduced a logic error which prevented the display of the program logo properly under many non-kitty-related conditions. Now fixed: the logo should display properly in all terminals that support in-terminal display of either sixel or kitty graphics.

Bug Fix: I recently increased my 'timebar' parameter from 720 hours (basically, 30 days) to 1440 (60 days). If I play Mahler on January 1st, he can't be played again until March 1st, give or take, unless especially exempted. Unfortunately, I'd forgotten that back in the dim mists of time, I couldn't conceive why anyone would ever want to bar a composer from being replayed beyond 999 hours: any time bar submitted larger than that limit was automatically set to a paltry 6 hours… which is why I suddenly started hearing Bruckner and Perti just days after having played them! In this version, the upper limit on the time bar has been completely removed. One of 1000 hours or above will work just fine… though, bear in mind, a huge time bar will potentially leave you with very few candidate composers for the next play!

Enhancement/Bug Fix: On macOS, support for running Giocoso in Pro mode was extremely hit-and-miss. If you were using a very old version of MariaDB client to talk to your Pro Server (as you would if you had installed MariaDB via MacPorts on old hardware) then connections to the Pro server would fail to be established. That's because Giocoso really expects you to be using a modern client and thus be aware of the –skip-ssl component of a database connection string. Ancient versions of MariaDB had no idea what ssl connections to a database were and therefore choked on that –skip-ssl parameter: no Pro for them! If you manually removed that bit of the connection string to avoid this, but were using a modern version of MariaDB on more modern hardware, the MariaDB client would again choke, this time because failure to mention –skip-ssl would stop the database connection being made. The new version includes code which checks whether your MariaDB client understands ssl connections at all: if it does, it tells it to skip using them; if it doesn't, it simply doesn't mention them. All macOS Giocoso Pro connections thus work correctly, no matter how you installed your MariaDB client or how modern or old it is. This conceivably benefits ancient Linux distros too, though I've never met one in the wild with client software as old as it is on my iMac!

Enhancement/Bug Fix: On macOS, when using a 'Magic Mouse', accidental swipes left/right on the mouse would produce a trail of visible escape characters and garble the main Giocoso program display. Some of those escape characters could also be interpreted to mean 'launch Sqlitebrowser' or 'Enable/Disable Autostop', meaning it wasn't just visually annoying but could also affect program functionality: it was very annoying, basically! That is now fixed. New user-input handling code means that mouse (or trackpad) swipes are completely ignored and new ttype control means that the escape characters generated by such swipes are not echoed across the screen.

Giocoso Version 3.32 - December 11th, 2025

General code tidying: Giocoso uses Bash script code developed over 5 years and several different versions of Bash. A lot of old Bash-isms therefore persisted and needed updating. For example, the syntax to do if statements (e.g., if [ “$var” == “some-string” ]; etc etc) could usefully be updated to use the double-square-bracket technique, which then no longer requires variable or string quoting (so if [[ $var == some-string ]]; etc etc). Another example is where you do conjoined tests: instead of if [[ $a == some ]] && [[ $b == text ]], it's cleaner to do if [[ $a == some && $b == text]], where the concatenation takes place inside the single set of double-brackets. Such code tidying should make zero difference to functionality, but makes the code somewhat easier to read and maintain and brings coding consistency to the program.

Minor Enhancement: When playing music, Giocoso now blanks out the program's graphical logo before overlaying the currently-playing album art on top. In the previous Giocoso version, depending on your precise choice of album art, you could see the extreme left-edge of the program logo appearing underneath the displayed album art. That won't now happen.

Minor Bug Fix: If your graphics hardware is ancient, Giocoso could emit the following error when using the 'B' key to launch the Sqlitebrowser database querying tool: MESA-INTEL: warning: Haswell Vulkan support is incomplete […] Some incorrect rendering might occur because the selected Vulkan device […] doesn't support base Zink requirements. This error message would appear to garble the main Giocoso program display, as it would be printed in black text, causing apparently blank lines to over-write parts of the terminal. The error would not appear at all if the PC running Giocoso had more modern graphics hardware: I'm using a 2014 Mac Mini, with an integrated Intel HD Graphics 5000 chipset, which is now obviously too ancient to cope with the way its Linux Mint 22 now renders things. The bug fix is that Giocoso now traps those errors so that the display is no longer garbled. Sqlitebrowser continues to launch and display correctly regardless.

Bug Fix: Sometimes, Giocoso could forget a configured minimum duration. Your configuration file might be saying “only play recordings that are at least 20 minutes long” and Giocoso would go and randomly select a 6 minute-long recording to play. Now fixed: the configuration file is re-read for every select performed, ensuring that a value for minimum duration is always correctly applied.

Bug Fix: The calculation of the 'rechashvalue' for a played piece of music could be wrong if the composition or composer name contained a single quote (e.g., Vincent d'Indy). This would mean that the program display would claim that there were 'Previous plays: 0' for that recording, even though there were plenty of them. Now fixed: the program computes the rechashvalue correctly and thus is able to get an accurate count of previous plays, no matter if apostrophes are present or not.

Minor Enhancement/Functionality Change: If you are running Giocoso with pop-out art enabled (perhaps because in-terminal graphics are not supported), you might close that pop-out window and thus lose 'sight' of what music you're listening to. The new feature is that you can press the “Z” key (or lower-case 'z') at any time to re-display the standalone album art. If it's already being displayed, the existing window is killed off and a new one launched; if the window has already been closed, a fresh one is simply opened. There was once a menu option under the Administration menu (option 6: 'Re-display Album Art in pop-out window') that was intended to achieve the same sort of thing, but it's now been made redundant, so that option has disappeared. Other menu items in the Administration menu have been re-numbered accordingly.

Minor Enhancement/Bug Fix: Sometimes when quitting Giocoso, the terminal might get 'stuck' and appear unresponsive. You'd type things at the command line, but you wouldn't see what you were typing being echoed back to the terminal. It would look like you were typing nothing at all. Giocoso now performs a 'reset' on quitting, which restores full functionality to the terminal: what you go on to type will display normally.

Major Enhancement: For various reasons, Konsole and other terminals that used to display in-terminal graphics have stopped doing so on specific distros. As described here, the technical issue is whether a terminal emulator supports sixel graphics. Many do not and the ones that do often have to have that support 'compiled in' for it to work properly… and several distros choose not to do that, either! An alternative way of displaying graphics in-terminal is to use the 'kitty graphics protocol': some terminals support that when they don't support sixel graphics. Accordingly:

A new configuration option is provided to 'Use Kitty Graphics for in-terminal graphics display'. The default value is 'no'.
If nevertheless set to 'yes', the program logo and album art are then displayed using kitty graphics, rather than sixel graphics. If your terminal supports it, album art should then be displayed appropriately.
The way kitty graphics displays things is heavily dependent on your choice of terminal and terminal font. Use the configuration parameter 'Size of album art when displayed' to make the kitty display bigger or smaller to suit.

As a result of this change, the kitty terminal has become an installation dependency for Giocoso. You don't need to use it for anything else, but it needs to be present on the system to provide this new and alternative graphics display capability. If you are installing Giocoso afresh, then Kitty will be automatically installed; if you are merely upgrading to the new version of Giocoso, you'll need to install Kitty yourself: sudo apt install kitty or sudo zypper install kitty and similar commands, depending on distro, will achieve the necessary.

Note that kitty graphics are notably 'blockier' than sixel graphics, so kitty is not the default display technology: it's there for when sixel graphics fail!

Significant Bug-Fix: A horrible logic error on my part in Version 3.30 completely screwed up the application of the 'Time Bar'. When you take the Play Music menu, Option 1 Giocoso's random selection of music to play is meant to take your value for the 'Hours before composer eligible for second play' configuration parameter and prevent playback of further music by any composer who's had something played within that number of hours. So, say you set the parameter to “240”, then if Composer A's “Symphony No. 1” is played on the 1st of the month, nothing else by that composer can be played until the 11th of the month (because 240 hours is 10 days, so he's blocked from random selection using the default music selection process for 10 days). Unfortunately, my logic flaw was to apply the time bar to the recordings eligible for a second play, not the composer! This meant that if Solti's recording of Beethoven's fifth took place on December 1st, Bernstein's recording of anything by Beethoven was still eligible to be played on the 2nd December, despite a 10-day time-bar allegedly being set on anything by Beethoven. Mea culpa. This has now been fixed and works as intended and as previously advertised.

Significant Enhancement: The way the Exempts file is processed has also changed, to make it more efficient. A composer listed in the Exempts file is explicitly exempted from *any* configured time bar. If the configuration file says 'don't re-play a composer until at least 240 hours has elapsed', then a Mahler symphony played on December 1st precludes anything else by Mahler from being played until December 11th (10 days later, 240 hours being 10 days). But if Mahler is also listed in the Exempts file, then that time bar is not applied to Mahler, so something by him could (not 'will') be played on December 3rd, say. In a previous release, this exemption was applied to the whole pool of candidate composers, so that if (say) Britten (time-barred), Bax (also time-barred) and Mahler (exempted) were all randomly selected as candidate composers for the next play, the Mahler exemption was applied to Britten and Bax as well. The exemption is now done 'cleanly' and only affects the explicitly-exempted composers. In this example, both Britten and Bax would now still be time-barred for 10 days, and Mahler would not be.

Enhancement: The Giocoso installer has been re-written to be somewhat more elegant to view and efficient to use. It has also had new support for installing onto AlmaLinux and Rocky Linux (both free clones of Red Hat Enterprise Linux). The existing support for installing onto Raspberry Pi OS (sometimes called “Raspbian”, as it's a derivative of Debian) has been re-worked and some kinks ironed out. The Pi 4 is now a first class platform on which to run Giocoso, rather than being something of an afterthought! Note that the Giocoso installer will now quit without doing anything if it detects that your system has pending updates: previously, Giocoso charged ahead and performed a full system update for you… but there are obvious issues with doing that, so now it won't be quite so cavalier! You won't be able to install Giocoso until and unless you've fully updated your system, even so: but such an update is left as a matter for you to deal with.

Enhancement: Support for running Giocoso on macOS has been re-introduced. The installer now detects the presence of macOS and responds appropriately (though note: you'll need to have pre-installed Homebrew or Macports yourself for the install to succeed). Giocoso then runs successfully on macOS -though there are still currently some rough edges and there is no support at all for pausing a music play.

Giocoso Version 3.31 - April 10th, 2025

Minor bug-fix: The program display could become garbled (with mysterious blank lines seemingly over-writing the proper display elements at random) because of an inappropriate use of the 'ps' program. That has now been fixed.

Giocoso Version 3.30 - March 7th, 2025

A huge update, warranting another version jump (to Version 3.30, direct from 3.20). Please note that upgrading to this version requires special steps and cannot be performed by using the in-program 'check for updates' option as would normally be the case.

Significant New Feature: The release of 'Giocoso Pro'. A new configuration option allows a local Giocoso session to be pointed at a remote MySQL database. Subsequent plays of music will be recorded in the local database and the remote database. This means multiple devices will be aware of all music played on any of them. Filters to 'play me previously unplayed music' will therefore now correctly not start playing music which this device hasn't played before but that one has played previously. Reports will now be generated from the remote database, including data from plays made on all devices, not just the local one. An entirely new 'Pro' menu allows you to initialise a remote MySQL database and export a local PLAYS table to it. In case anyone is wondering: no, having a 'Pro' version doesn't mean money is charged or functionality compromised. 'Giocoso Pro' is still completely free of charge to use and full functionality is available to every user, without caveats or reservations. The 'Pro' name arises simply because working with MySQL is generally considered to be 'proper database administration territory', and thus rather harder and more nerdy to do than using the local database Giocoso originally used. Pro features are entirely optional: if you don't want them, you can switch them off (and back on!) at will.

New Feature: Added a new 'hotkey' option. Pressing 'F' (or 'f', upper or lower case being irrelevant) during music playback launches the system's default file manager in the currently-playing recording's folder. If Britten's Peter Grimes was playing, for example, and I tapped 'f', Dolphin (the KDE default file manager) would open in (for me) /sourcedata/music/classical/B/Benjamin Britten/Peter Grimes (Britten - 1958). If you notice a cataloguing error as a piece of music plays, this helps you get to the music file(s) involved quickly for editing and correction. Different distros and desktop environments will open the relevant folder in whatever file manager is configured to be their default. Note that the program display does not indicate that 'f' is a valid keypress that will do something: you just have to know it's there as an option!

New Feature: Another new hotkey option is available during music playback: if you press 'K' or 'k', and there is a file called 'booklet.pdf' in the folder being played, then it is opened in your system's default PDF reader. It's intended to help you easily access the digital versions of CD booklets that you have (hopefully!) stored within the same folder as the FLAC files ripped from the CD. If no such file exists, nothing happens: booklets in non-PDF format or not literally called 'booklet.pdf' won't be opened. Note that the program display does not indicate that 'k' (or 'K') is a valid keypress that will do something: you just have to know it's there as an option. Be aware that 'K' tapped when music is not playing does something completely different (recalling prior advanced SQL selections, a function that is shown on the main menu display).

Enhancement or possible feature removal: Due to popular demand, the 'scrolling logo' has been removed: whether that counts as 'feature removal' or an enhancement is a matter of opinon! Instead the program starts up instantly with a new graphical logo:

Enhancement: For new installations, the Luxi Mono font is now the default. Upgrades won't pick up this change automatically, however: the font can be downloaded here, for free. Install it using your distro's standard font installation tools: until you do, the program display may be garbled as your terminal application attempts to approximate a font it doesn't actually know how to draw.

Enhancement: Fast database refreshes now clear out entries in the RECORDINGS table which are found to no longer exist on disk. Previously, if you moved a recording from /orchestral to /symphonic (say), the fast refresh would have picked up the 'new' recording in the /symphonic folder, but the old entry for the same recording in its /orchestral folder location was not cleared out (you needed a full refresh to do that). Now, it will be.

Enhancement: The various ways of searching for music to play have been significantly tweaked to better deal with situations where folders the database thinks exist actually don't, or where folders that exist turn out not to contain playable FLACs. Consider a play list you created 8 months ago: it consists of a listing of hard disk folders that may all now no longer exist at those specific locations. The new search code handles these sorts of issues rather more gracefully than before. One significant side-effect: if your search returns many candidate folders, there'll be a potentially significant wait for the candidate folders to be checked for existence and the presence of FLACs within them. A new progress counter lets you know how far the file checking has got. If you tighten your selection criteria, so that fewer folders are considered candidates, you can speed up this folder checking considerably.

Enhancement: The default music search (Option 1 on the Play Music menu) has been substantially re-written to make it a faster and more bullet-proof batch process. The old default search picked one composer and then tried to find music by that composer to play; if it failed to find a suitable recording, it would discard its first composer selection and try again. This would involve a lot of trips to the database before you happened to get lucky and find a suitable recording to play. This does not work well if the database is at the other end of a network cable! Now, therefore, Giocoso selects a batch of all eligible composers; then it selects a batch of all eligible compositions; then it limits them down to the size of your 'Number of plays per cycle'. A bit of filtering ensures that within a play cycle, the same composer can't be picked more than once. Sometimes, this will mean that there won't be 10 plays per cycle: if there aren't enough candidate recordings by unique composers, the cycle will end early. No matter: a new default search will enable a new cycle to be constructed from new candidates …and away you go once more.

Removed Feature: Because default search now operates on a 'batch select' basis, the “maximum number of searches before giving up” parameter is no longer used: you get your 10 (or whatever) candidate recordings selected in one go: either you get a result, or you don't, but there's no 'having another go, over and over' as there used to be. That's simply because that's the way SQL works: if it didn't return anything this time, there's no point re-submitting it and hoping you get a different result! The parameter has accordingly been removed from the Administration menu, Option 2 screens and, if already present in the configuration file, is simply ignored. Any update to your configured parameters made by taking the Administration menu, Option 2 will trigger the removal of the parameter if it's found in the active configuration file.

Removed Feature: The Database Management main menu Option 8 : Pull remote database to be primary has been removed. That menu option provided rudimentary functionality allowing one Giocoso instance to become aware of plays made by another, but it was clunky and awkward to use. The new Giocoso Pro functionality renders this mechanism entirely redundant and is therefore completely removed from the program.

Modified Feature: Pressing [Enter] on a main menu item triggers the first option within that menu. If the “Play Music” menu is active, for example, pressing [Enter] triggers the “Play music with defaults” option, as though the user had typed '1'. This was a feature introduced in Version 3.20. In Version 3.30, it is modified: it doesn't work with the Administration menu, nor with the new Pro menu, though it continues to work for all other menus. The reason for this change is simply that Play Music, Database Management and Reporting menus don't actually do anything 'dangerous' when you take their first options… but the Administration menu first option triggers a software update (which might not be convenient or wanted) and the Pro menu first option threatens to re-create a Giocoso Pro database server from scratch, which potentially involves data destruction! If you really want to do either of those things, you now need to type in the relevant menu option number: pressing [Enter] on those two menus (often by accident!) now no longer does anything.

Modified Feature: The aggregate statistics report has always reported on 'Average number of plays per day'. That has now been modified to be 'Average number of plays per day in past year': the underlying query now only looks at 'today minus 365 days'. It seemed pointless to average your plays over (potentially!) a decade or more, as if the figure would be meaningful.

New Feature: In Version 3.12, the ability to create notes about a currently-playing recording was introduced. This capability remains as-was, but the new feature in Version 3.30 is that, if the program is operating in 'Pro mode', notes are now stored in the globally-shared database, not as a single text file stored on the local playing device. Global Notes, as the feature is called, only permits one note per recording, but a note can be added to at will, as often as you like, and can be up to 4GB in size. When adding a note, you tap the 'n' key (as in previous Giocoso versions) and the nano editor opens automatically. When saving the text file, it's stored back into the Pro database, where it can then be accessed for read-only purposes by any other Giocoso Pro client device. Global notes are displayed within the main Giocoso program window in a simple, GUI-like text file display tool. Non-Pro notes made prior to this release are still stored on local disk, but are no longer accessible through Giocoso for as long as the program runs in Pro mode.

Changed Feature: The syntax for doing command-line database refreshes has been clarified (i.e., changed!). You need to check your crontab to ensure it is submitting things in the correct way. The syntax is now: /usr/bin/giocoso3.sh music_database_name /some/dir/of/music --fullrefresh (or --fastrefresh if that's the refresh mode you're wanting to use). Basically, you invoke Giocoso with three arguments: database, music folder and the full or fast refresh type switch, in that order.

New Feature: If you operate in 'Pro mode', one client device can pause the playback of a recording and a different client device can resume that same recording from where the first got to (give or take a second), a feature called Global Pause/Resume. If you are listening to some Wagner in the listening room late in the evening and fancy completing the opera propped up in bed on the laptop, Giocoso Pro features now let you do exactly that: music can now follow you around the house and to different devices at will.

Bug Fix: If one Giocoso session is playing music, a second session is not supposed to be able to initiate music playback. The test to check for this condition was broken by the changes introduced in Version 3.20, however. The new release implements the correct check once more, thus again making a second session unable to start music playback when another session is already engaged in it.

Bug Fix: The “Selection: X of Y” counter did not increment the 'X' component of the play count in any play mode except the default. If you did a play by 'selection filter' or an 'advanced SQL selection' or a 'play from a playlist', the 'X' was always stuck at 1 (a bug introduced in Version 3.20, sadly). Now fixed: it increments by 1 every time a recording completes a play no matter which play mode you're using.

Bug Fix: When manually creating a new playlist, previous Giocoso versions would pre-populate it with the last-played recording (if there had been one), rather than creating it genuinely blank. That now doesn't happen: the Play Music menu, Option 7 now always creates completely-blank playlists.

Minor Enhancement: The Database Management menu, Option 6: Backup a local database now displays a message explaining where the new local database backup can be found on your file system.

Minor Enhancement: The Database Management menu, Option 7: Optimise a local database now tells you the before and after sizes of the database on disk, so you can see something has actually been achieved by the optimisation process. If there's no size difference, before to after, then you're told that too.

Minor Enhancement: If you press 'B' on any menu, Giocoso tries to launch the sqlitebrowser tool for managing local, Sqlite databases. If that tool has not been installed on your system, however, the 'B' key simply appeared to do nothing in earlier Giocoso versions: now a message will be displayed explaining that for 'B' to do anything, you have to manually install sqlitebrowser first.

Minor Enhancement: When editing the configuration file (Administration menu, Option 2), if you pressed [Cancel] half-way through the editing process, the entire configuration file would revert to default values, losing any non-defaults you may have previously set. Now, cancelling at any point aborts the entire editing process and restores things to the way they were before you started editing anything. Instead of reverting to defaults, you revert to the configuration file values you began with, in other words.

Minor Enhancement: When producing advanced SQL reports (Reporting menu, Option 5), the panel in which you type your query will now remember the last query you typed, so won't ever open blank except on the first time of use. Any previous query displayed can be edited to become a new query (which will then be remembered for the next time of use). A previous query can also simply be wiped, so that a new query can be typed in ab initio. An additional refinement to the way advanced SQL queries work is that you don't return to the main program menu after each query: the query form remains open for typing/editing and re-submitting until such time as you explicitly press [Cancel].

Minor Enhancement: When creating a database for the first time, Giocoso runs off to the proposed 'root of the music collection' folder provided by the user and checks whether any FLACs are stored within that folder hierarchy. In previous versions, it performed a complete count of FLACs before deciding whether the proposed folder was a 'good' one or not. That was a bit of over-kill, in the sense that you only really need to find one FLAC in the folder structure to know the folder choice was legitimate. New in Version 3.30, therefore, as soon as one FLAC is found, the counting process stops, resulting in significantly faster progress towards actually processing/analysing the FLACs. The database creation process speeds up as a result.

Please note: This indicates the end of the 3.2x line of Giocoso. Entries above this are for version 3.3x and higher.

gioinstall - [2.0 Installation]

hjr (hjr@undisclosed.example.com) — 2026-03-31T10:59:44+00:00

Installing Giocoso

1.0 Operating System Support

There are four levels of support for installing Giocoso onto assorted Linux distros and other operating systems, as follows:

Tier 1: Used by me daily, on real hardware, extensively tested, guaranteed to work
Tier 2: Used by me infrequently, only in virtual machines, lightly tested, tested extensively in the past, things will almost certainly work
Tier 3: Hardly ever used by me and then only in virtual machines. No testing done, unless specific issues are reported, but has worked in the past just fine, so things ought still to work, too
Tier 4: Thought to work, and tested to work in the past, but you're really on your own.

Putting specific, named distros into each tier goes as follows:

Tier 1: AlmaLinux 9 and 10; Raspberry Pi OS, Fedora, Linux Mint, Apple macOS
Tier 2: Debian, EndeavourOS, Ubuntu
Tier 3: OpenSuse Leap & Tumbleweed, GeckoLinux, Arch, Manjaro, Garuda Linux, Devuan, Linux Mint Debian Edition, Peppermint OS, MX Linux, AntiX Linux, Pop! OS, Linux Lite, Zorin OS, Elementary OS, KDE Neon, Tuxedo OS, Nobara, Ultramarine
Tier 4: Windows

Every listed distro did run Giocoso perfectly at some time in the past and, if the distro developers haven't messed around with core libraries too much, they should still work. However, only those distros in Tier 1 will receive extensive real-world testing from Version 3.32 and up. Other distros will receive either light-touch testing to make sure most things seem to work fine (Tier 2), or will only be tested on-demand by users reporting specific problems (Tier 3). I've provided some distro-specific notes and gotchas elsewhere.

Apple became a Tier 1 operating system when I decided at the end of January 2026 to invest in a brand new Apple Silicon iMac. It's now my principle desktop operating system and, as my daily driver, is going to be the platform on which I test things out most thoroughly. I also have access to a couple of old Apple iMacs (from 2015 and 2012) that use Intel CPUs and can only run modern versions of the operating system thanks to Open Core Legacy Patcher: their 'officially supported' operating systems end with Catalina and Monterey respectively. Accordingly, Giocoso will be a Tier 1 supported application on only Catalina, Monterey and whatever OS version runs on a 2024 iMac (Tahoe, probably). All other OS versions will be Tier 4 support: definitely do-able and definitely done and documented: but you're essentially on your own.

Windows is a bit of a special case, because it probably runs Giocoso just fine… but I have no means of knowing that for sure. Windows 10 reached end of Microsoft's official support back in October 2025, so all the hardware I have running Giocoso on Windows 10 is now no longer representative of anything supported by the operating system's own manufacturer. Windows 11 is, of course, fully supported by Microsoft -but I literally have no hardware that is officially supported for running it. I can hack Windows 11 onto a bunch of spare hardware, but it will be an unsupported and unrepresentative platform. The principle, however, is that if you get Windows running the Windows Subsystem for Linux (WSL2) then you can install one of the supported distros on that (for example, Ubuntu or Fedora) and Giocoso will run perfectly well in that environment. So, it's not that Giocoso won't run on Windows: it's just that I now expend zero development effort proving it does so. Any issues arising as you try to run it are therefore really yours to resolve. I will certainly offer advice and help if asked, but it will be merely on a 'best efforts' basis. In the meantime, I have written installation instructions for Windows 11 here.

Giocoso does not work on the Solus Linux distro.

2.0 Installation

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

wget https://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.

At the end of the installation, when you first run Giocoso, you may find the program display garbled (it is equally possible you won't!). If you do, just visit the Administration menu, take Option 2 to “edit the configuration file” and then press [Enter] through the various options (without changing any of them, really) until you return to the main program display: you should find all visual glitches gone (though you may need to go back into the configuration options to adjust the size of the program logo: it defaults to being 220×220 pixels in size and that might be too large on standard 1080p resolution displays).

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 and Display Sizes

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.

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 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.

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
wget https://software.bbritten.com/gioinst
bash gioinst
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 ]