BBritten.com - softwares:giocoso

adminmenu

Anonymous (anonymous@undisclosed.example.com) — 2025-11-27T12:23:34+00:00

The Administration Menu

The Administation menu contains options which, in sum, represent a bit of a mish-mash of functionality!

Most of it bears on how the program behaves or goes about the business of selecting music to be played. Other options are concerned with setting the program up correctly to work with your system's audio hardware or involve resetting that audio hardware when needed. Another very important option allows you to check for whether I've released newer versions of the software and to have them automatically downloaded and applied to your system if so.

Links to a detailed description of each menu option are listed below:

| Back to Software Home | Giocoso 3 Home Page |

changelog

Anonymous (anonymous@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.

controlcmd

Anonymous (anonymous@undisclosed.example.com) — 2025-12-11T10:01:39+00:00

Controlling Music Playback

The general 'philosophy' of Giocoso is that listening to classical music is a pleasure -but that it's a pleasure to be taken seriously. That's why Giocoso doesn't 'do' tracks: you don't listen to mere parts of whole compositions in the concert hall (on the whole), so you shouldn't be doing that in your music listening room at home, either. It's also why Giocoso doesn't encourage you to skip through recordings; or repeat them; or pause them: if you don't do it in public, you shouldn't be getting into the habit of doing those things in private, either.

That said, listening to a twenty minute symphony without pause or break is one thing; but even the most devout classical music fan is going to struggle listening through 4 hours of Götterdämmerung without a break every now and then! So… yes, somewhat belatedly, Giocoso acquired 'controls' that allow you to pause, resume, repeat and stop playback. These controls are displayed at the bottom of the program display area whenever music is playing (see the first screenshot below). Versions of Giocoso prior to Version 3.13 contained the same options in a dedicated 'Control Menu', but that disappeared in Version 3.13, since the 'bottom control menu' completely replaces it.

An entirely standalone package (called Mgiocoso) was introduced in Version 3.04: it only displays and processes the same set of playback control options on behalf of a second, music-playing Giocoso session. In Version 3.11, Mgiocoso was launched automatically every time Giocoso itself ran, by default (though it was configurable). In Version 3.13 and above, however, since all the music playback controls are now displayed as selectable options from the music playback screen itself, the need for Mgiocoso to control another, music-playing Giocoso session is thereby severely diminished. Mgiocoso thus reverts to being off by default -though it still retains its usefulness as a way for a space-constrained device (such as a smartphone) to control a music-playing session running on a remote PC. The documentation below assumes you are using Giocoso Version 3.13 or higher, at any rate.

The Controls

Playback controls appear within the main Giocoso window (from Version 3.13 and on) at the bottom of the main program display as soon as music playback commences:

The control options shown in this 'bottom menu' are hopefully self-explanatory. Each is invoked by tapping the letter associated in yellow with each option. That is, type 'A' for 'Autostop', 'S' for 'Skip' and so on. Take note that it's 'x' for Exit, not E, though! Also be aware that the case of the letters you type is irrelevant: type A or a, and Autostop will be engaged regardless, for example.

Taking each option in turn, then:

Autostop: If you launch Giocoso with the 'Number of plays per cycle' Persistent Configuration parameter set to (say) 10, but after the 2nd recording you need a break, you can take the autostop option to tell the playing session to complete the recording it's already playing, but not to start any new play after that. The currently-playing recording thus completes normally and will be recorded in the Giocoso database as a successful 'play'.
Terminate: If you take this option, Giocoso will immediately cease playback of the currently-playing recording and will not attempt to play anything else subsequently. No attempt to complete the playback is made: the music just stops abruptly. A terminated play thus hasn't completed successfully and is therefore not recorded in Giocoso's database as a play at all: you don't get partial brownie points for almost-finishing listening to something!
Pause/Resume: This option tells a playing Giocoso session to immediately pause the recording it's playing. If a recording has already been paused, however, then the message is interpreted as an instruction to resume playback (from the precise moment where playback had previously reached). The pause/resume option is thus a 'toggle switch'. Using it for the first time triggers a pause, using it a second time releases the pause and triggers resumption of playback; using it a third time again pauses playback… and so on, ad infinitum. Please note: As at December 2025, the Pause option will not be displayed (or be operational) on macOS. That platform handles audio processes very differently than Linux, so the usual way of pausing/resuming a music-playing process simply doesn't work correctly on macOS. A fix is in the works…
Skip: This option tells a playing Giocoso session to immediately cease playback of the currently-playing recording, but to then pick something new to play afterwards (assuming that 'plays per cycle' is set to a number higher than 1 and that 'unused' plays in that cycle exist). A skipped recording doesn't count as a successful play, so isn't recorded in Giocoso's database. A skipped recording also 'consumes' one of the plays in a cycle. If you've said, 'play 10 recordings one after the other' (by setting 'Number of plays per cycle' to 10) and you're currently on play number 4 in that cycle… then a skip command stops the 4th playback and triggers Giocoso to start playing the 5th. If you were on play number 10 and issued a skip, then as there is no 11th play to be had in a cycle, all playback ceases when this 10th recording is stopped in its tracks. Skip is thus similar to 'terminate', except that Skip will play new music after the current play's termination, if possible, whereas Terminate just stops everything in its tracks.
Repeat: This option tells a playing Giocoso session to repeat the currently-playing recording once it has reached its natural conclusion. Nothing about the current play is interrupted or altered in any way; once it has finished, however, the same recording will get played again, in its entirety, from beginning to end. If you are in a 10-play cycle, however, and request the 10th recording to be played again, the repeat will not happen, because that would be an 11th play in the cycle: there have to be spare 'plays' to accommodate the repeat, basically. Repeated plays are recorded in the database. A repeat request only lasts for the 'lifetime' of the currently-playing recording. That is, if you're playing a symphony, it will repeat …and as the symphony starts its second play, the repeat option is turned off automatically, so the same symphony will only play twice. You can, of course, re-use the Repeat option to trigger a third play at any time the second play is underway (and so on, until no more plays of any sort are possible).
Volume: This option opens the ALSA volume control panel, allowing you to increase or decrease the volume of the music being played back. Please note that the ALSA volume control is an entirely separate utility that Giocoso merely 'runs' for you. How you use it and how you configure it are really subjects beyond the scope of this document: Google for the term alsamixer, however, and you should find third-party documentation that can help. An example might be this page. I have nevertheless included some notes about it below.
Notes: This option invokes a text editor and pre-populates it with details of the recording that's playing. The idea is that you can then just type freely anything you like by way of observations about the composition generally or that recording specifically. The text editor that launches when you take this control option will be that which is specified by your system's EDITOR environment; if that's not set at all, then nano is the default editor of last resort. Again, you'll need to know how to use your default text editor (and, specifically, how to save your edits with it), but that is another subject beyond the scope of this particular documentation.
Exit: Functionally, this option performs the same thing as 'Terminate' but, once that part's complete, it will then quit Giocoso completely.

Autostop, Repeat and Pause/Resume are all toggle commands. That is, you can use them once to initiate some action in a playing Giocoso session -but, so long as you do it swiftly enough, you can also use the same option again to reverse the earlier command. This is explicitly true of pause/resume: one press of menu Option 5 triggers playback pause; a second press of the same option reverses that; a third press would re-initiate a pause and so on, ad infinitum. It is also true of the other commands mentioned: a request to stop all playback after the present recording ends (i.e., an Autostop) can be reversed by sending another Autostop request; likewise, a request to repeat the currently-playing recording can be revoked by sending the same request a second time.

Options in the bottom control bar will highlight when they're first taken; toggle options will remain highlighted until they are toggled back off. Thus, you might end up with a display like this:

…which indicates that all three options, Autostop, Pause and Repeat have been taken at some point. If you were then to withdraw the request to 'repeat' the play, you'd press the R button once more:

…and now two of the options remain toggled on, but the Repeat option is now toggled back off.

The non-toggle options will be highlighted briefly for as long as it takes for Giocoso to process them. Terminates and Skips are pretty instantaneous in operation, though, so it's unlikely you'll ever see them highlighted for long.

Non-Listed Controls

Two options are not shown on the control menu. They nevertheless work in precisely the same fashion as the others, as follows:

Launch Mgiocoso: tap the letter 'M' (or 'm', of course) and this triggers Giocoso to launch a new Mgiocoso session/window. If one already exists, it is killed off and a new one is launched to replace it. If no existing Mgiocoso session exists, a brand new one is launched.
Launch Sqlitebrowser: tap the letter 'B' (or 'b' of course) and this will cause the Sqlitebrowser third-party SQL query tool to be launched, if it has been installed (by you!). If the package hasn't been installed, then tapping B will achieve nothing. Note that Giocoso checks whether the package has been installed, but doesn't itself trigger its installation if it detects that it hasn't been. Be warned that each new tap of the 'B' key will trigger the automatic and forceful destruction of any existing Sqlitebrowser windows before a new one is opened: if you had any complex SQL queries typed in the first session, they will be unceremoniously lost when that window is auto-closed.

ALSA Volume Control

I mentioned above that the alsamixer utility can be used to control the output volume levels used for each audio device detected on the system, assuming that your system is using ALSA as its sound server in the first place. If you're using Pipewire or other sound servers, it may not work at all. It also won't do anything if, for example, your audio output is a toslink optical out: the light is either on or off, not dimmer or brighter! Even if you use non-optical digital outputs, they're either on or off, so again, varying the signal strength to achieve volume alteration is a non-starter. Optical or digital outputs are brilliant for isolating your amplifier from electrical noise and for when a capable external DAC (digital to analogue converter) does a better job of signal processing than your PC's built-in one… but abandon any thought of using software volume control if you go these routes: a good remote control for your amplifier will be what you're after!

If you are using a non-digital audio output and the ALSA sound server, however, then you can indeed use alsamixer to adjust music playback volume by software alone. Alsamixer controls one device at a time: you press F6 to obtain a list of all audio devices and select one. Once a device has been selected to be the 'active device', you can increase or decrease the volume of that device using the up- and down-arrow cursor keys.

As you know, of course, you tell Giocoso the audio device you want a music signal to be sent to by setting the 'Audio device to use as default output' parameter in the Persistent Configuration file, accessed via the Administration menu, Option 3. That parameter defaults to a default of, er… 'default': if that's still true for you, then taking this ALSA Volume Control menu option will cause alsamixer to open to the 'master channel' by default -which may or may not be the one you need to adjust the volume of, depending on your hardware specifics.

If you have set Giocoso's audio device parameter to something more specific than 'default', it will usually be to a named device in the format plughw:x,y …and if that's what your Giocoso is set to, then taking the ALSA Volume Control menu option will cause alsamixer to open with the device with device index x pre-set as the active channel (i.e., the first number after the 'plughw:' bit will be treated as though it were the device index). Again, that might or might not be the correct device to alter the volume of, depending on your specific circumstances.

If Giocoso opens alsamixer with the 'wrong' audio device set as active, for whatever reason, remember you can always press F6 to get a pop-up list of all devices, from which you can select the correct one instead.

Here is my current music room PC configuration, for example:

In the Administration menu Option 3, I've said 'plughw:2,0' is my audio device. So when I then take the Control menu Option 6, I see this:

That tells you that alsamixer has opened with the E30 'item' set as the active device. I happen to know that's correct: I play my music via a Topping E30 Digital-to-Analogue converter. So, I can increase that device's volume with the up-arrow:

…or lower it with the down-arrow:

But if I didn't know what 'E30' was, how would I know? Well, press F6:

The blue pop-up dialog lists all known audio devices on this PC: you can see most of them relate to audio output via assorted HDMI ports… definitely not something I'd want to control the volume of, since they're not what's plugged into my amplifier! However, if it turned out that starting with the 'E30' device was incorrect, I could just select one of the other devices and up- and down-arrow for that device instead.

You quit out of the alsamixer interface by pressing the ESC ('escape') key: you should be returned to Giocoso's own Control menu.

Now, suppose you hadn't the faintest clue how to configure Giocoso to use the correct audio device:

Here, you see me having set the default audio device for Giocoso as 'plughw:62,0'. That will mean alsamixer would try to open with device '6' as the controlled device (Giocoso only passes the first character of the first device number to alsamixer, so 92 would be passed as '9' and so on)… but as no such device actually exists, that's going to get quite messy:

As you can see, alsamixer tries manfully to tell you that device 6 doesn't exist… but it's getting a bit cluttered on-screen at this point, because Giocoso cannot control the way alsamixer displays its messages. The Giocoso menu is actually working fine, despite appearances, so tapping 'p' at this point, for example, would re-display the Play Music menu and tidy up all the messy messages.

In short:

if your Giocoso default audio device is configured to 'default', alsamixer will open the 'master' audio channel, which may or may not allow you to set the volume correctly. Try pressing F6 and selecting another listed device and altering the volume of that if the master device is not what is needed
if your Giocoso default audio device is correctly configured to a numbered plughw device, then alsamixer should open that device and volume control on it will probably work correctly, assuming you're using the ALSA sound server technology at all in the first place. Again, use the F6 trick to select another device if it doesn't seem to work
if your Giocoso default audio device is incorrectly configured to mention a hardware device number that doesn't actually exist… then invoking alsamixer will result in an error and the Giocoso menu will appear a bit scrambled. Fix your Persistent Configuration file with Administration menu Option 3 before trying to get this ALSA Volume Control option working once more!

You can always adjust the volume using whatever standard controls your distro gives you, entirely outside of Giocoso's purview, of course: this control option is only provided as a possible convenience, whereby volume can be achieved entirely within the context of Giocoso program operation. You don't have to use it if you don't want to, or if it's giving incorrect results.

| Back to Software Home | Back to Giocoso Documentation Home |

customvis

Anonymous (anonymous@undisclosed.example.com) — 2025-12-03T19:50:30+00:00

Visual Appearance Customisations

Giocoso Version 2 had a veritable plethora of options that could be set in the Persistent Configuration File to control the visual appearance of the program display -the colour of text used, and so on. Most of those options have gone in Giocoso Version 3, at least in a form that is readily settable and re-configurable.

On the other hand, Giocoso Version 3 uses the dialog utility to draw a lot of its visual components, so provided you are prepared to tinker with dialog's own configuration files, you can still tweak Giocoso's visual appearance to dramatic effect.

Here I'll list a few of the simpler colour/visual tweak customisations it's possible to do to knock Giocoso Version 3 into a shape you're happy with.

1.0 Colour Constants

The Persistent Configuration file is generally edited by taking the Administration menu Option 2. However, the file is merely a text file and it contains some parameters which are not exposed or made editable by that particular menu option. For example:

Here I've opened the file in the Kate text editor that is generally standard on KDE-using distros, but I could have opened it in any available text editor. The file is, of course, found in $HOME/.local/share/giocoso3/txt/giocoso.conf. The key parameters to worry about in this context are those appearing on line 6 of the file: the 'colour constants'. The colour names shown here must not be altered, because otherwise Giocoso will break badly. But the numbers assigned to those names can be fiddled with at will: they are the ANSI colour codes and the entire set of them is visible here:

You can see the configuration file says 'RED=1'… and the ANSI color chart confirms that 1 is indeed red. There is nothing, however, to stop you setting RED=9 and achieve a brighter, pinker red… or set it to 13 and get a purple instead. Thus, the 'normal' Giocoso program display looks like this with the default colour constants:

…but if I set the constants to this:

YELLOW=226 RED=9 BLUE=104 CYAN=130 GREEN=220 NORMAL=176 WHITE=128

…and then re-launch Giocoso, it will now appear like this:

All sorts of other graphical nightmares are made by possible by fiddling the colour constants in this way, as you can no doubt imagine!

2.0 XTerm Colours

Giocoso tends to run inside an XTerm terminal: if you use the program launcher that the Giocoso installation procedure creates for you, it will contain a launch command such as:

/usr/bin/xterm -bg black -fg green -geometry 103x28 -fa 'Space Mono:style=Regular' -fs 12 -ti 340 -tn xterm-256color -e giocoso3.sh

…which is certainly pretty nasty, but basically says 'launch xterm at a certain size, using a certain font, and then run the giocoso3.sh shell script within it'. Rather crucially, however, it also contains a “bg” command, which sets the background terminal colour and an “fg” command, which sets the default foreground terminal colour. Note that not all implementations of xterm support these parameters, so you'll have to experiment! If your xterm does support setting foreground and background colours in this way, though, you can edit the launcher command to specify any of the possible foreground and background colours, by name. Available colours are:

black
blue
green
yellow
cyan
white
magenta
red

If you set -bg magenta -fg blue within the launcher command, therefore, you can end up with this sort of nightmare:

I'm not saying I'm recommending this approach, in case that wasn't obvious! I'm just saying that extensive control over Giocoso Version 3's appearance is possible, if you are prepared to fiddle enough with the launcher command and Giocoso's own colour constants. The interaction between them can be quite tricky to predict ahead of time, though, so extensive experimentation is probably required!

3.0 Dialog Colours

No matter how ghastly a colour scheme you've managed to cook up using the techniques mentioned in Sections 1 and 2 above, the moment you take a Giocoso option that invokes the display of a dialog box of some kind, the program's colours will immediately switch to those configured for use by the Dialog utility. For example, here's my weird choice of colours (in a vaguely sane terminal colour scheme!) from a couple of screenshots ago:

…but the second I take Option 2 on the Play Music menu, which triggers the display of a music selection filter form, I see this:

That black/white/grey/blue/red colour scheme is that belonging to the dialog utility and is immune from colour changes you may make to Giocoso or XTerm. In fact, it's controlled by its own, entirely independent, configuration file: $HOME/.local/share/giocoso3/txt/abgiodialog.conf. It's simply a text file and can thus be edited in any standard text editor. It contains a bazillion lines such as:

screen_color = (WHITE,BLACK,ON)
shadow_color = (BLACK,BLACK,ON)
dialog_color = (BLACK,WHITE,OFF)
title_color = (GREEN,WHITE,OFF)
border_color = (WHITE,WHITE,ON)
button_active_color = (WHITE,RED,ON)
button_inactive_color = dialog_color
button_key_active_color = button_active_color
button_key_inactive_color = (RED,WHITE,ON)
button_label_active_color = (WHITE,RED,ON)
button_label_inactive_color = (BLACK,WHITE,ON)

…and hopefully you can see where the red, green, white and black colours are being configured.

This is a pretty hard file to understand or edit intelligently, I'll warn you in advance: the key thing to spot is that each dialog display element is described with a foreground, background and highlight combo. Hence, the default colouration of all dialogs invoked by Giocoso (governed by the 'screen_color' parameter) is to have a black background, white foreground text, and the white will be bright-white, because highlighting has been set 'ON'. Armed with this little knowledge, therefore, it's possible to replace colour names and see what effect such replacement has on things. If you're going to fiddle with this, I'd strongly recommend only changing one colour/parameter at a time, though!

Available colour names for the dialog utility are: black, red, green, yellow, blue, magenta, cyan and white.

Thus, by merely editing the first of the dialog configuration options to read:

screen_color = (WHITE,YELLOW,ON)

…you can achieve this thing of beauty:

Again: I'm not recommending you should actually do this! I'd rather you spent your time listening to music instead, of course… but the capability to tailor these things is definitely there.

| Back to Software Home | Back to Giocoso Documentation Home |

dbmenu

Anonymous (anonymous@undisclosed.example.com) — 2025-12-04T17:43:46+00:00

The Database Management Menu

The music database is central to the way Giocoso works. It contains listings of what FLAC files exist and where on the hard disk they can be found. The Giocoso database does not however store the FLAC files themselves. Think of it as an directory of FLACs, rather than as a jukebox of them.

So central to the workings of Giocoso is this 'database of FLACs', creating one is actually compulsory: even plays of music sourced directly from the hard disk (see Play Menu Option 3) have to be recorded in Giocoso's 'history of plays' table. Accordingly, the very first thing you should do after installing Giocoso is to create a new music database (see Option 1).

Part of the database creation process is to point Giocoso in the direction of your FLAC music files collection: for each FLAC the program discovers, the database will capture and record data extracted from the tag metadata you've (hopefully!) added to your FLACs, such as the composer, the performers, the recording date, the genre and so on. The presence of this metadata within a fairly small database is what makes it possible for Giocoso to randomly select 'all choral works by Haydn that were recorded by Thomas Beecham' (for example): the data is readily accessible and searchable and database randomisation techniques can be applied to it very easily. It's much easier doing it that way than, for example, having to freshly analyse every FLAC every time you think you might want to play it!

This means, however, that after once creating the music database, you need to keep its contents up-to-date. If you had acquired 15 new CDs, ripped them and added them to your collection, you'd better tell Giocoso about that: the program cannot select to play that which it doesn't know to exist, after all.

The music database is used, too, every time a recording plays: Giocoso records the fact of a completed 'play' in its database, along with the associated metadata for that recording. In this way, a history of your plays is built up over time. A play history can be a mere curiosity (as in, 'wow: I didn't realise the last time I played Adolphe Adam was over a year-and-a-half ago'); it can also be useful, in the sense of 'play me choral music by Haydn conducted by Beecham that I've never played before'. Without a play history to scan, that last clause of your requirements cannot be answered.

Being able to create, protect, query and refresh the music database is thus a core Giocoso function: and the Database Management menu is how you go about doing all those things.

Links to a detailed description of each menu option are listed below:

Create a music database

Fast Scan for new recordings

Full Scan all recordings

Select & use a different database

Import plays to a database

Backup a database

Optimise a database

| Back to Software Home | Back to Giocoso Documentation Home |

giocoso

Anonymous (anonymous@undisclosed.example.com) — 2026-03-19T08:30:11+00:00

Giocoso Version 3 : The FLAC Player

User Manual Index

1.0 What is Giocoso?

Giocoso Version 3 is a gapless, trackless, optionally-randomising command-line FLAC player, intended primarily for the playback of digital classical music, on Windows and Linux.

Which is a bit of a mouthfull! So let's break that down a bit:

Gapless: Giocoso plays one FLAC file after another without detectable pause between them, so if you have three movements of a string quartet that are supposed to flow into each other without a break, Giocoso will play that as a continuous stream of music without silence between the movements. Most media players these days can do 'gapless playback', but some do it better than others. Giocoso does it properly.

Trackless: Giocoso plays entire folders of music as though they were one composition (which, if you follow my axioms of classical tagging, they should be!) If a “Symphony No. 5” folder happens to contain four files, because the CD they were ripped from regarded the four movements of the symphony as separately-indexed tracks, Giocoso doesn't care: it simply plays all four files in sequence before declaring the symphony as a whole complete. No other music players I can think of behave quite like this! The reasoning is simply that you don't go to a classical music concert and walk out of the concerto after just the first movement -or walk in to it after the first two movements have played just so you can listen to the nice tune in the third movement! Giocoso pays classical music the respect it deserves: composers wrote entire compositions, not 'tracks' or 'movements' that can be ripped from their context and played standalone.

Optionally Randomising: Giocoso can be instructed to play specific pieces of music (for example, 'play Peter Grimes' or 'play Fantasia on a Theme of Thomas Tallis'). But it can also be asked to 'play a choral work', or 'play something by Beethoven': in which case, the choice of which specific choral work or Beethoven piece will be a matter of random chance. In this randomised-play mode, you can supply additional filters so that the 'degree of freedom of choice' the randomiser will exercise can be limited: for example, 'Play me Choral works by Prokofiev that last between 30 and 50 minutes'.

Command Line: Giocoso has been written to get out of the way and not consume too many computing resources. It therefore runs within a simple terminal session, with instructions given to it by selecting variously numbered menu options. As a concession to making things look 'pretty', Giocoso will by default display the album art associated with the composition it's playing at any given time (assuming you've remembered -or bothered!- to tag the music files with that album art in the first place). Even this can be turned off, however.

FLAC Player: Classical music deserves being listened to in excellent audio quality. This means that playing music files which are encoded as MP3, OGG or other lossy audio formats, where some of the music signal is thrown away in order to achieve smaller file sizes on disk, is not of any interest to Giocoso at all. It cannot see such files, much less play them. The only audio format that Giocoso sees, understands and plays is FLAC -the Free Lossless Audio Codec. There are other lossless audio formats in existence of course, such as lossless WMA or the Apple Lossless Audioc Codec (ALAC): but these are or were proprietary, generally tied to a specific operating system platform (WMA=Windows, ALAC=Mac, for example) and may be patent-encumbered. Only FLAC fits the bill, as its name suggests, of being open source, freely available on all platforms, and widely supported.

Classical Music Player: To be honest, Giocoso plays FLACs and couldn't care whether a particular FLAC was composed by Johann Sebastian Bach or Madonna: it makes neither moral nor artistic judgments in that regard! There's nothing intrinsically that makes Giocoso only a classical music player, in other words. However, it has been deliberately designed to talk the language of composers and compositions, not albums and tracks -so the music it is most tailored to play correctly is classical music that has been properly tagged with metadata describing composers, performers, compositions and movement titles. The fact that it plays gaplessly and tracklessly also means its playback model most closely resembles that of the classical music concert hall.

Windows, macOS, Linux and ARM: Giocoso is fundamentally merely a Bash shell script, orchestrating the work of other programs such as metaflac, ImageMagick and ffmpeg. Any computing platform that can run Bash and those extra programs is therefore a suitable platform on which to run Giocoso. Windows 10 and up provides the Windows Subsystem for Linux that allows it to run full-fat Linux 'within' the standard Windows desktop paradigm, so can be persuaded to run Giocoso with little difficulty these days. The Raspberry Pi, despite using ARM CPUs rather than x86-based ones, runs all sorts of Linux distros with success, so it's a usable platform on which to run Giocoso, too. MacOS is slightly tricker: at heart, it's Unix (BSD) with a proprietary user land. It can therefore run Giocoso natively, provided certain Linux-y software environments are provided to it beforehand.

Another way of describing what Giocoso means to me is simply this: it's a personal 'radio station' for classical music, capable of playing a 'wall' of constantly-varied classical music on a wide variety of platforms and PCs. It helps me discover obscure corners of my music collection that I would otherwise miss (thanks to its randomisation features) and plays a series of whole compositions without me having to intervene to make it do so.

2.0 Why Giocoso?

Linux and Windows are not exactly short of software for playing digital music files! From programs such as VLC, Foobar2000 or the weirdly-named DeaDBeef, there is a media player to cater for, apparently, everyone's whims and wishes. So why bother writing a new one? Because none of the media players on any of the platforms I've mentioned were, I think, designed with classical music in mind and thus none of them were entirely 'right' for me and my classically-inspired requirements. Some of these requirements I've already touched on in Section 1, but they perhaps bear repeating a little here!

2.1 Tracks

Every software music player I know of displays and works with 'tracks'. Here's DeaDBeef playing some Brahms, for example:

Is the display here of any usefulness? To some extent, yes: it's good to know that Brahm's Symphony No. 3 consists of four movements, and it's nice to know each movement's general tempo marking. You could get that information from Wikipedia, of course, or even (perish the thought, I realise) a book! But you can't deny that seeing the information here, within your music player, is convenient.

So no, it's not the display of track information that bothers me. It's the fact that this display invites 'selective clicking' on the individual tracks -or, in other words, partial plays of things, rather than the entire composition that Brahms intended you listen to. UK readers will recognise what I'm talking about if I mention 'Radio 3 v. Classic FM'; Australian readers will similarly spot the similarity of approach if I say '2MBS FM v ABC Classic FM'. The one tends to play whole compositions without interruption; the other tends to play just 'the good bits', without taxing its audience too much :)

Now, it's your music and you listen to what and how you like, I suppose -but to my mind, a music player that encourages or invites bad listening habits is not to be recommended! If you take your classical music even slightly seriously, in other words, I don't think you should want to be distracted or tempted by the existence of 'tracks' -and hence my desire to write a trackless music player.

2.2 Optionally Randomising

Over the years, I have got into the bad habit of over-playing some composers and under-playing others. There's nothing morally wrong with doing that! We have favourites, of course, and there's no harm in indulging ourselves with our favourites, whether that's favourite food, favourite drinks or favourite music! But over-doing the favouritism means you miss out on a chance to experience new things and -perhaps- develop new favourites. For a wider musical experience, in other words, I wanted a music player that would make me listen to composers who were not on my list of favourites. Essentially, that meant taking the choice of what to listen to out of my hands -and for that, I needed a music player that would choose to play compositions at random for me, regardless of who had written it. Giocoso's ability to randomise its plays was thus a crucial and key reason for writing it in the first place.

Of course, there are times when I want to choose, specifically, what to listen to: if I feel like a run-through of Bernstein's Candide, I should be able to listen to it and not have the music player randomly select some Mozart instead! So, the ability to not randomise when required was also important to me.

But even when I say, “I want to listen to some Britten”, it would be quite handy if the music player would take me at my word and only play Britten's music… but which specific bit of Britten it decides, by more random selection. In other words, I'm after a spectrum from 'totally random' through 'random within a specified preference' all the way to 'not random at all: I'll tell you what to play'. Giocoso fits these requirements, but I don't know of another player that comes close to doing so. So that's another reason why I felt 'writing my own' was required.

2.3 Work with the Metadata

Most other software music players will happily display the metadata tags you embed in your FLAC files when first ripping them from CD, but few seem to be able to work with that metadata. In other words, though I've carefully tagged all my music with composer, composition and performer names, it can be difficult to find a software music player that will easily and consistently let me say 'please find me something composed by Bernstein (and not just conducted by him)'. It is undoubtedly true that a lot of players will let you search for the word 'Bernstein', but they tend to search 'greedily', returning results where the search term can be found in any tag, not just the ones you care about in the moment.

So, for example, the Strawberry music player will certainly let me search for the word 'Bernstein':

…but why are works by Copland, Berg, Milhaud, Mahler and Wagner appearing in that list? Because Bernstein conducted those recordings, even if he didn't compose them! Now, it's possible with Strawberry and other players I know of to fix this by adding some 'search syntax' to proceedings:

By using the search term 'Composer:Bernstein', you force Strawberry to inspect only the 'composer' tag, and that obviously works to narrow things down nicely. Great! So what's the problem? Well, the problem is that this 'tag:value' search syntax is the way Strawberry does it, but it's not the way all players do it: different music players use different syntax to achieve the same outcome. Here, for example, is how Foobar2000 deals with this situation:

Just typing 'Bernstein' into the filter window (at the bottom of the screen) certainly gets anything with a 'Bernstein' tag somewhere… but this is the original Strawberry result again: it's finding things Bernstein conducted, not just composed. Foobar's syntactical trick to narrow things down to just the stuff he composed is this:

You can see that you have to change the filter text to be in the form of 'field HAS <some value>' or 'field IS <something>' and so on: the syntax is not exactly difficult, but it's different to that used by Strawberry (and other players) and something else to have to remember -and in Foobar2000's case, if you don't type the HAS or IS in upper-case, it won't work at all. It's fiddlier than it ought to be, put it that way! Making you change your search term in order to alter what tags will be inspected by the search seems counterintuitive to me, anyway.

Giocoso Version 3's approach to this is as follows:

By typing the search term against the 'Composer Name' filter, I ensure Giocoso is only looking for music files tagged as having been composed by Bernstein. It's going to ignore anything just conducted by Bernstein and, as a result, the playlist Giocoso generates from this search looks like this:

…and there's not a dose of Mahler or Bartók in sight!

If I fill in the search filter this way instead:

…now I'm asking Giocoso to look for any recording where Bernstein is listed as one of the performers (perhaps as pianist, but most commonly he's going to be the conductor). The playlist this search produces looks as follows:

Same search term, but very different results, with lots of pieces by non-Bernstein composers -simply because Giocoso makes it easy to specify which tags, precisely, you want to search through at any time by merely altering the placement of the search term within the filter screen. The search term itself doesn't change; merely the location where you type it -and there's no weird syntax to get right to ensure the search works, either!

I wanted a music player, in other words, that understood how I'd tagged my music and would work with that tagging strategy to enable meaningful musical discovery possible. Giocoso puts metadata filtering front-and-centre in what it does, and it does it without having to remember syntactical tricks that are different from the tricks used by other players. The meaning of a search filter in Giocoso is given simply by its position on a human-readable form, not because of special keywords and syntax surrounding it.

2.4 Statistics

I am quite fanatical about keeping track of what I've listened to, who my most-listened-to composers are, and so on. Few music players I'm familiar with allow you to build up readily-accessible statistics about your listening habits. Transmitting your play history to Last.fm can certainly help in this regard -but some people might not be too keen on sharing their play histories with the rest of the world in the way that scrobbling does! I therefore wanted a music player that would build up a local play history that could be interrogated and used for analysis of a flexible and extensible nature. As it happens, I then decided to publish this statistical data to my own website in ways which allow easy, graphical visualisation of what I've been listening to: see, for example, this page.

I certainly realise that not every classical music listener is going to find this sort of data helpful or even interesting -but I wrote Giocoso to at least provide this data to those for whom it might prove useful.

2.5 Summary

Given all of the above points, the short version is simply this: none of the software music players on Linux or Windows with which I am familiar (and there are lots of them!) met all of these specific needs which I was aware I had -and that's why Giocoso exists! If any of these points ring a bell with you, then you're definitely the target market for Giocoso -and I think you'll find it useful, too.

3.0 Is Giocoso for Everyone?

With all the above in mind, I hope it's clear that Giocoso isn't intended as a general purpose music player that everyone will find appropriate! Whilst music can be pure entertainment, to be sampled and dabbled in, like a plate of petits fours, Giocoso doesn't expect you to be listening to music that way! It plays without interruption; it doesn't display pretty visualizations on your computer screen whilst it's doing it; it puts sound quality above hard disk space; it expects you to have tagged your music files 'properly'; and it expects you to own your music, rather than be streaming it (Giocoso, in fact, has no streaming capabilities at all, except over a local network). It doesn't have to be classical music that you're listening to, but Giocoso was written expecting it to be. If you're the kind of listener that loves classical and jazz, for example, I think you'll find Giocoso a good fit for playing the classical part of your music collection… but I have no idea how well or ill it works with Jazz. I am pretty certain, however, that it won't play well with “pop music”, however that might be defined.

Fundamentally, Giocoso is written in the belief that not all music is nails, so not all music players should be hammers! It is a tool tailored for playing certain kinds of music in a particular kind of way. If you don't fit its model, it's not going to fit your requirements, therefore.

4.0 What's with the name?

As a classical music fan, you will probably already know that the word giocoso is a tempo indication that means ‘lively, humorous, joyful’ or, particularly, ‘playful’. I couldn’t think of a better name for something designed to ‘play’ my music collection in a way that brings me joy and makes music choices for me that are always fresh and lively.

gioinstall

Anonymous (anonymous@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 ]

giopro

Anonymous (anonymous@undisclosed.example.com) — 2025-12-09T14:08:02+00:00

Giocoso Pro

“Giocoso Pro” is the name I gave to a set of extensions to basic Giocoso functionality that permit multiple playing devices to access a single, shared database of recordings and plays. That's it. There's no cost involved in switching these features on: it's not as if there's 'freebie, cheapie, Giocoso' and then 'pay to drive the gleaming, clever Pro version'. Everything Pro is available to every user of perfectly standard Giocoso, too. In fact, Pro features are switch off-and-on-able at will. The only factor in deciding whether you want to use the Pro features is: do I have multiple computers playing the same set of recordings, and if the bedroom laptop plays something at night, I'd like reports from my downstairs main PC to know about those plays the next morning.

A special 'Pro' menu appears when you enable Pro functionality (and disappears if you turn that functionality back off at any point). The links below step you through the various options of that Pro menu. There's also an introductory essay introducing you to the architectural and practical underpinnings of the Pro features, and a couple of essays on how you go through the necessary prerequisite of building a special Giocoso Pro Server.

Giocoso Pro Concepts

Building a Giocoso Pro Server on Non-Arch Linux

Building a Giocoso Pro Server on Arch Linux

Running Giocoso Pro with MySQL rather than MariaDB

The Pro Menu

| Back to Software Home | Back to Giocoso Documentation Home |

hotkeys

Anonymous (anonymous@undisclosed.example.com) — 2025-12-10T18:00:16+00:00

Hot Keys

“Hot keys” are alpha-numeric keys you can tap at various points when using Giocoso to achieve various things or invoke particular bits of functionality. You will see all sorts of hot keys indicated in the main Giocoso program display, of course: when you're playing music, for example, the bottom of the screen displays this sort of thing:

…which tells you precisely what tapping the A, T, P and S keys do. The top of the screen similarly displays options for selecting the Play Music, Database Administration, Reports and so on menus. These are obvious hot keys.

In this short article, however, I'm not interested in listing hot keys which are clearly indicated and explained on the main program displays in this way. Rather, I want to list the “hidden” hot keys which do things, but for which no indication is given even for their mere existence!

As of Giocoso Version 3.32, therefore, these hidden hot keys are:

M - Launches the Mgiocoso control panel application
G - Launches a secondary non-music-playing instance of Giocoso (so you can reports, for example, whilst music is playing in the initial session)
B - Launches the Sqlitedbbrowser program (to query and manage a local, Sqlite database) if it has been installed on your system. Giocoso checks for its presence and launches it if it knows it's been installed. If it happens, tapping 'B' simply brings up a message advising you to install the program yourself. You'll need to use your distro's innante package management features to accomplish that (on Ubuntu, for example, a simple sudo apt install sqlitebrowser will usually do the trick).
V - Invokes the ALSA volume mixer, allowing you to alter playback volume (or alter left/right balance etc)
Q or X - Quits Giocoso immediately, without going via a menu option first
F - Only available during music playback. If music is playing, the 'F' key opens your system file manager in the folder that the playing music comes from (so you can, for example, open the booklet PDF that you might store in the same folder as the FLACs)
K - Only available during music playback. If music is playing, the 'K' key will search through the currently-playing folder for a file called 'booklet.pdf' and, if present, will open it in your system's default PDF reader. If no such file exists, then the K key does nothing at all, and no warnings are given.

Note that all hot keys are case-insensitive. Whether you tap 'K' or 'k', for example, is irrelevant: the function the key performs will be invoked just as successfully either way.

| Back to Software Home | Back to Giocoso Documentation Home |

linux

Anonymous (anonymous@undisclosed.example.com) — 2025-12-29T18:03:05+00:00

Linux Quirks and Notes

1.0 Introduction

The main instructions for installing Giocoso on Linux are to be found in the main, parent article. Some distros will have odd 'quirks' that need addressing before the 'standard install steps' can work, however, and that's what will be documented here.

Obviously, too, issues can arise depending on the desktop environment you choose to use, rather than the distro: the default terminal emulator used by some DEs will work fine with Giocoso… and then sometimes they won't! Those sorts of quirks and issues are also discussed here.

2.0 General Album Art Display Issues

Giocoso likes to display album art whenever music is playing and, by default, it likes to display that album art within the terminal emulator in which Giocoso itself is running. To do that, Giocoso uses what are called “sixel graphics”: if your chosen terminal emulator supports sixel graphics, you'll get album art; if not, you won't. Unfortunately, some terminals that used to support sixel graphics have recently stopped supporting it.

For example, here is a screenshot from Debian 13 running KDE Plasma and with Giocoso running in that desktop environment's default terminal emulator, Konsole:

So, Konsole (version 25.04) is quite happy to display sixel graphics. But here's Endeavour OS using KDE Plasma and again running Giocoso in Konsole (version 15.12),

Notice that the music playback is working just fine… but there is no album art on display. Somewhere between April and December of 2025, the Konsole developers stopped compiling the terminal with sixel graphics support. Endeavour OS being a rolling distro based on Arch, its packages are always being kept bang up-to-date and it has therefore picked up the newer version without sixel graphics whereas 'solid, stable' Debian hasn't (yet).

This is not just a KDE/Konsole issue, however. On most distros, the Giocoso installer will leave a launcher icon for Giocoso on your desktop. Double-click on that and Giocoso will launch within the uxterm terminal emulator. Here's Debian running Giocoso in that:

The little 'X' icon in the top left-hand corner of the display shows you that this is uxterm: the presence of album art tells you that Debian's version of uxterm has no problem with sixel graphics. Again, on Endeavour OS that same scenario produces this result:

You'll have to take my word for it that that's still Giocoso running inside uxterm, because the 'X' icon has been over-written by Giocoso's own icon. But it is uxterm, this time being unable to display album art.

I hasten to add that this is not a Debian v. Endeavour OS issue. It's not even a KDE v. Gnome or any other desktop environment issue. It all depends on how up-to-date your terminal emulation software is and whether its developers have compiled in support for sixel graphics or not …and that can affect any distro and any default terminal application. Here, for example, is Giocoso running on Endeavour OS inside the Gnome Terminal:

…and again, there's no in-terminal album art. In this case, however, the result of using Gnome Terminal on Debian would be exactly the same: that particular terminal has never supported sixel graphics, to my knowledge.

The issue is therefore one that can affect different distros and different terminals in a slightly unpredictable way. There are a couple of workarounds available to you, however. One is to stop relying on sixel graphics and instead switch to using kitty graphics, which was a capability introduced to Giocoso in version 3.32. You do that by taking the Administration menu, Option 2 and switching the last of the yes/no parameters, Use kitty graphics for in-terminal display, to a value of yes. Do that and Giocoso will attempt to draw in-terminal graphics using a protocol that many terminal emulators that don't do sixel graphics support natively. Here's Konsole in Endeavour OS, for example, after switching on the option to use kitty graphics:

…and, as you can see, Konsole suddenly has no problem displaying album art once more. If you try using kitty graphics in a terminal that doesn't support that protocol, however, the results will be ugly:

That's Gnome Terminal once more: it doesn't support kitty or sixel graphics!

If you find yourself in a Gnome desktop environment, therefore, you won't find that simply switching Giocoso to using kitty graphics resolves the dilemma. Instead, you'd really need to switch to using the Kitty Terminal, which Giocoso has installed as a dependency since version 3.32: it should be accessible from your standard distro's start menu. Kitty graphics don't have to be used within the Kitty terminal emulator (as the example of kitty graphics working in Konsole showed earlier), but obviously the Kitty Terminal is designed to understand the kitty graphics protocol from the get-go, so it's a reliable fall-back option.

On macOS, I find I need to install the WezTerm terminal emulator (which understands sixel graphics) and not enable the use of kitty graphics. WezTerm is also available for Linux, provided your distro supports the use of Flatpack packaged applications.

Another alternative (though one I find less than satisfactory) is to not use in-terminal display of album art at all: the Administration menu, Option 2 also gives you a chance to set a parameter to 'Display album art in its own window', which is a much simpler proposition, involving no particular graphics protocol dependencies: that option will work on every distro, desktop environment and operating system without a drama.

In Summary: It's not whether Giocoso is working correctly or not; it's not whether you're using a particular OS, distro or desktop environment: it's entirely down to different terminals having different capabilities 'baked in' by their developers and ensuring that Giocoso is configured to exploit those capabilities once you understand what they are.

Konsole used to handle sixel graphics; the latest versions now only seem to handle kitty graphics. Gnome terminal doesn't seem to handle anything these days. Xterm (and uxterm) have variable support for sixel graphics, depending on distro, but zero support for kitty graphics. Whether Giocoso correctly displays album art in-terminal is thus a bit of a lottery, but on all platforms there are a choice of terminals (Kitty and WezTerm, for example) that can handle things properly.

macos

Anonymous (anonymous@undisclosed.example.com) — 2026-02-03T21:24:50+00:00

Installing Giocoso on macOS

1.0 Introduction

For several years, the best I could do by way of offering support for running Giocoso on macOS was to say, “It probably works fine, but I can't really say for sure” because all my Apple hardware dated from 2012, 2014 or 2015. My various iMacs and Mac Minis thus all used Intel hardware and were severely restricted in what versions of macOS they could run without adding the complication of using the Open Core Legacy Patcher to the mix.

From the end of January 2026, however, that is no longer true. I still have all those Intel Macs, so I can test Giocoso on those and their assorted old versions of macOS… but I now own an M4 iMac and can therefore attest that Giocoso installs and runs on Apple Silicon just fine and that the latest version of macOS (Tahoe, at the time of writing) works perfectly fine with the latest version of Giocoso (version 3.34 at the time of writing).

For this reason, running Giocoso on Apple's hardware is now Tier 1 support territory: it is, in fact, my new daily driver and I can therefore state with confidence not merely that it ought to work but that it very much does work.

There are a couple of caveats, though: Giocoso does not, because it cannot, work precisely the same on macOS as it does on Linux. In particular, the way that macOS handles audio is quite different from the way Linux does it, to the point that freezing the music playback process certainly halts music playback, but when you resume, the player will attempt to 'catch up' to clock time, with disastrous results. Accordingly, pausing and resuming music playback doesn't work on macOS. Giocoso won't even show you the option to pause/resume if it detects macOS is in use. A completely different approach is needed to implement a pause/resume functionality on macOS which may happen in a future release… but might well not!

That said, the basic principle of getting Giocoso to run on macOS is, essentially, to install a quasi-Linux 'userland' of tools and utilities, thus creating an environment Linux-y enough for Giocoso to cope. There are two possible ways of doing that: by using Homebrew or MacPorts as a quasi-package manager.

Homebrew supports only newer macOS releases (basically, Sonoma, Sequoia and Tahoe). It will work on older releases, but with quirky glitches and errors that have to be worked around. On those older releases, too, Homebrew tends to compile things from scratch, which works eventually but takes ages to complete: one install on Catalina took over 6 hours to finish! I really wouldn't recommend Homebrew installs unless you're running newer macOS versions on decent hardware, therefore.

MacPorts supports older macOS releases very well (and the newer ones, too) and its installs are relatively quick in all cases. I would certainly recommend the MacPorts approach to running Giocoso, therefore.

However, it's not a free choice: if you've ever used Homebrew before, you must not switch to using MacPorts, nor vice versa. It's one or the other, but software mayhem awaits anyone trying to use both.

So, if you've used neither package manager before, I'd recommend MacPorts, especially for older macOS releases. If you've used one or other before, you must continue to use that manager now. Anything older than Monterey is really a problem for Homebrew installations, however, so if you can avoid that, I'd strongly recommend you to do so.

Anyway, if macOS is detected, Giocoso's installer will prompt you to tell it which package manager it should use.

This documentation will thus chart two paths forward: one, the Homebrew approach; the other, the MacPorts one. Pick one and only one! In both cases, however, you end up with a system that is capable of running Giocoso, so the two paths merge thereafter for the purposes of running and using Giocoso. My recommendation remains, however, that the MacPorts approach is simpler and faster (and better tested!)

2.0 Installing Homebrew

Before we can install Homebrew, we need to install all the command line utilities that allow software to be compiled. In a terminal window, type the command:

xcode-select --install

Once that install has completed, type:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

That will download the Homebrew software itself and install it: respond appropriately to any prompts put to you. At the end of the Homebrew installation, you'll see a message that tells you to type three convoluted commands that put Homebrew in your system's path. Mine were:

echo >> /Users/hjr/.zprofile
echo 'eval "$(/usr/local/bin/brew shellenv)"' >> /Users/hjr/.zprofile
eval "$(/usr/local/bin/brew shellenv)"

Obviously, yours won't say “hjr”! Also note that later versions of Homebrew install into /opt/homebrew rather than /usr/local/bin/brew, so on those versions (e.g., Tahoe) make sure you run the commands as Homebrew itself tells you to, because it will get the paths and username correct.

At this point, you will need to install a couple of pieces of critical software that are needed just to obtain the Giocoso installer, let alone to run it. I also suggest that you manually install a few other packages, largely because (a) I've had errors when the Giocoso installer tries to do the same; and (b) a couple of these packages can take literally 5 or 6 hours to compile (though I will note that Homebrew installs on more modern versions of macOS are much quicker than that. I think it better that you see that happening for that length of time, rather than sit staring at an apparently 'stuck' Giocoso installer attempting to do the same things. Get the pain out of the way early, rather than experience it during the Giocoso install, in other words. Type these commands one at a time, in the order shown, bearing in mind that the first one might take nearly six hours to complete on older hardware:

brew install wget bash wezterm fd flac ffmpeg xterm dialog freetype xquartz
brew postinstall openssl
brew postinstall llvm

Those last two commands may or may not be needed: if they are, Homebrew will tell you in its output. Read it carefully and follow its instructions. On Tahoe, for example, neither command was needed: back on Monterey, both were. It depends on how up-to-date your version of macOS is, basically.

2.1 Installing ImageMagick

Installing ImageMagick with Homebrew is a problem, partly because they have changed the way the software is configured over time, so your results will vary depending on what version of the brew 'bottles' you manage to pull down (which will depend on your version of macOS, of course). It's also a pain to do on seriously old versions of macOS: on Catalina, for example, a 'brew install imagemagick' failed with the error “Failed to download resource libzip (1.11.4)”.

So, the path here is a little treacherous. Let's take it step by step: first, try issuing the vanilla command:

brew install imagemagick

…all lower-case and with a 'k' on the end of the program name. If that appears to succeed, type this command:

magick --version

You will see a response similar to this:

Version: ImageMagick 7.1.2-13 Q16-HDRI aarch64 23522 https://imagemagick.org
Copyright: (C) 1999 ImageMagick Studio LLC
License: https://imagemagick.org/license/
Features: Cipher DPC HDRI Modules OpenMP 
Delegates (built-in): bzlib cairo fontconfig freetype gslib heic jng jp2 jpeg jxl lcms lqr ltdl lzma openexr png ps raw rsvg tiff uhdr webp xml zip zlib zstd
Compiler: clang (17.0.0)

So, first the response means ImageMagick is installed and functional. But a crucial feature needs to be visible on that “Delegates (built-in):” line. If it doesn't mention fontconfig and freetype then you've installed (through no fault of your own) a version of ImageMagick that can handle artwork but cannot handle text. Which is an absolute disaster for Giocoso!

So, if your output does mention freetype and fontconfig, you have installed ImageMagick correctly and can proceed to the next step.

If you output fails to mention them, however, you now need to issue these two commands:

brew uninstall imagemagick
brew install imagemagick-full

ImageMagick-full is a differently-compiled version of ImageMagick that definitely does include linkages to fontconfig and freetype. So, when that installation has completed, you should be able to do a magick –version and see those two packages mentioned in the Delegates line of output at last.

There's just one slight problem: Homebrew installs the imagemagick-full package into a completely non-standard folder that won't be searched by your system by default. So, once you've confirmed that font-aware ImageMagick is installed correctly, type this command:

sudo nano /etc/paths

At the top of whatever is already present in that file, add the line:

/opt/homebrew/opt/imagemagick-full/bin

Then quit your terminal: I mean, really quit it, not just close it down: right-click the launcher and select 'Quit' from the context menu). Or open a new terminal and select Terminal → Quit Terminal from the top menu.

So, that's two scenarios: (1) installing plain imagemagick works and gives you font support; (2) installing vanilla imagemagick works but fails to give you font support, so uninstalling it and installing imagemagick-full, plus adjusting the /etc/paths file.

The third scenario is that (1) failed with nasty-looking error messages. If that happens, do this in a new terminal session:

cd
cd Downloads
wget https://imagemagick.org/archive/binaries/ImageMagick-x86_64-apple-darwin20.1.0.tar.gz
tar -xzf ImageMagick-x86_64-apple-darwin20.1.0.tar.gz
sudo mv ImageMagick-7.0.10 /usr/local/ImageMagick

sudo nano /etc/paths
At the top of the file, add a new line reading: /usr/local/ImageMagick/bin
sudo cp -R /usr/local/ImageMagick/lib/* /usr/local/lib
sudo cp -R /usr/local/ImageMagick/bin/* /usr/local/bin

Verify this old binary version works as intended with:

magick -version

…and, again, make sure you see some sort of response that mentions fontconfig and freetype.

Now, just to add icing on the cake: Giocoso will actually try to install both the imagemagick and the imagemagick-full packages onto your system. That might mean you end up with both present on the one system -and then the problem becomes which one will Giocoso try to use by default. That depends on the content of your /etc/paths file. If you list /opt/homebrew/bin (or the 'standard' Homebrew binaries folder) above the weirder /opt/homebrew/opt/imagemagick-full/bin folder, then it'll be the imagemagick binary that gets found first when Giocoso asks to use it. If you list the 'weird' folder above the 'standard' one, Giocoso will find and use the -full version first.

So, here's a worked example (using Homebrew on Tahoe, a bang up-to-date scenario): I've got both imagemagick and imagemagick-full installed, thanks to Giocoso. Here's my paths file:

hjr@Howards-iMac ~ % cat /etc/paths 
/opt/homebrew/bin
/opt/homebrew/opt/imagemagick-full/bin
/usr/local/bin
/System/Cryptexes/App/usr/bin
/usr/bin
/bin
/usr/sbin
/sbin

So which version will get used first? In this case, it'll be the “imagemagick” one:

hjr@Howards-iMac ~ % magick --version
Version: ImageMagick 7.1.2-13 Q16-HDRI aarch64 23522 https://imagemagick.org
Copyright: (C) 1999 ImageMagick Studio LLC
License: https://imagemagick.org/license/
Features: Cipher DPC HDRI Modules 
Delegates (built-in): bzlib heic jng jpeg lcms ltdl lzma png tiff webp xml zlib zstd

Notice that the Delegates line doesn't mention fontconig: Giocoso will break in this environment, rather horribly, with warnings about not being able to read assorted fonts. So let me edit my /etc/paths to this:

/opt/homebrew/opt/imagemagick-full/bin
/opt/homebrew/bin
/usr/local/bin
/System/Cryptexes/App/usr/bin
/usr/bin
/bin
/usr/sbin
/sbin

Quit Terminal and re-launch and I'd hope that you would now expect the -full version of imagemagick to be found and used, right? Wrong!

hjr@Howards-iMac ~ % magick --version
Version: ImageMagick 7.1.2-13 Q16-HDRI aarch64 23522 https://imagemagick.org
Copyright: (C) 1999 ImageMagick Studio LLC
License: https://imagemagick.org/license/
Features: Cipher DPC HDRI Modules 
Delegates (built-in): bzlib heic jng jpeg lcms ltdl lzma png tiff webp xml zlib zstd

Still the font-less version! The reason this happens is because Homebrew is too damned clever for its own good! It modifies another file which trumps the contents of the /etc/paths file: $HOME/.zprofile:

 hjr@Howards-iMac ~ % cat .zprofile
 eval "$(/opt/homebrew/bin/brew shellenv zsh)"

That “eval” line has the effect of bumping the ordinary Homebrew binaries to the front of the path, whatever /etc/paths may say. We therefore need to modify that file by adding the line:

export PATH="/opt/homebrew/opt/imagemagick-full/bin:$PATH"

…to the end of the file. That manually forces the -full version to the front of the path once more. Save the edited .zprofile, then quit terminal once more and launch a new one:

hjr@Howards-iMac ~ % magick --version
Version: ImageMagick 7.1.2-13 Q16-HDRI aarch64 23522 https://imagemagick.org
Copyright: (C) 1999 ImageMagick Studio LLC
License: https://imagemagick.org/license/
Features: Cipher DPC HDRI Modules OpenMP 
Delegates (built-in): bzlib cairo fontconfig freetype gslib heic jng jp2 jpeg jxl...

Bingo! We have fontconfig support at last.

I wish I could simplify this for you, but it is tricky and it all depends on the age of your operating system and the specific version of Homebrew you're using. If you are very lucky, a vanilla imagemagick install will have font support and will be at the front of the path by default: the simultaneous existence of an imagemagick-full install won't matter, because it's in a location that no-one will search for and Giocoso doesn't need.

On more recent Homebrew and macOS versions, however, both versions will be present and the vanilla imagemagick will not have font support, which will break Giocoso. You therefore need to manipulate system paths to make the -full version searchable and discoverable and thus the one that Giocoso will use.

This is definitely the sort of low-level shenanigans that Unix and Linux administrators eat for breakfast. It's unlikely to be appealing to a lot of Mac users, but there it is!

2.2 Add Homebrew Binaries to Path

Assuming you finally get the correct response from ImageMagic, you need to make sure that the /etc/paths file knows how to find all the Homebrew binaries the Giocoso installation will pull in as dependencies. You do that with the command sudo nano /etc/paths and your job is to put the path to the Homebrew bin folder at the top of the list if it's not already there. This is again a version-dependent thing. On the latest macOS Tahoe, for example, Homebrew puts all the executables it installs into /opt/homebrew/bin and that's not in the paths listed in this file. On Monterey, though, Homebrew used to install into /usr/local/bin …and that is already present in /etc/paths (probably!).

So, first determine where your Homebrew bin is: for example, type:

which bash

…and you should see a path returned to you. On Tahoe, I see a response of:

/opt/homebrew/bin/bash

…which tells me that “/opt/homebrew/bin” is definitely the right location. Failing that, cd to /usr/local/bin and see if you can ls any of the executables you've been installing.

Once you've worked out the correct path, add that path to the top of the list of paths in /etc/paths, unless it's already present:

Here, /usr/local/bin was already present and I'm just adding the Tahoe-esque version above it. The order in which lines appear is important: you want Homebrew's bin folder to be first in the list, otherwise when Giocoso says “use Bash as my shell”, it will discover the built-in Apple version which is from the early 2010s and is grossly out of date. Giocoso will break horribly when that happens. Listing Homebrew's folder first makes sure the Bash version 5.x+ is picked up instead… and then things will work!

Once those installations are complete, you'll be free to download the Giocoso installer and run it… for the which, see Section 4 below! For now, close the terminal you were using to install these packages and open a brand new one to do the Giocoso install: that way, new paths and installations are fully picked up by the new terminal session.

3.0 Installing MacPorts

Before we can install MacPorts itself, we need to install the various command line utilities that MacPorts will expect to find on the system: these are programs that, for example, compile source code into executable binary packages. Fortunately, this is quite easy to do.

Simply open a terminal and type the command:

xcode-select --install

A graphical dialog will ask you if you really want to install the command line tools:

Click [Install] and agree to the ludicrously long licence agreement that appears. A lengthy download of the relevant software then takes place, ending with this:

Once those tools are installed, you need to obtain an appropriate version of MacPorts: different releases of macOS need different instances of the MacPorts software. At the time of writing (December 2025), these were the latest os-dependent releases available:

Check the Macports website for the actual versions current at the time you want to install. There are versions available for macOS releases earlier than Sierra, but installing Giocoso on such ancient operating systems is definitely not supported at all, so be my guest but you're on your own for them!

Once you've downloaded the correct package for your operating system, visit your Downloads folder in Finder and double-click the pkg file to launch the installation wizard:

Click your way through the wizard, agreeing to the inevitable licence, and choosing an appropriate hard drive to install onto:

You'll be prompted for your administrator password and then the software installation will begin. Once it's complete, you'll be asked whether to move the downloaded MacPorts package to the bin or keep it: either answer is fine, but you won't need to install MacPorts again, so you might as well bin the package!

Next you will need to add the MacPorts path to your system's PATH variable: you do that by typing the command:

sudo nano /etc/paths

At the very top of the file, before all other listed folder names, add the line:

/opt/local/bin

…and then save the modified file. It is important this new path appears first in the file, because that determines the order in which macOS searches for executables -and we want the MacPorts executables to be found before macOS's built-in ones. Only in this way can we be sure, for example, that the MacPorts version of Bash is used in preference to macOS's ancient version of Bash (which won't be able to run Giocoso properly).

You make this change of path variables take effect by closing your existing terminal window and opening a new one.

Once that's all done, you need to install a couple of software packages before you can attempt to install Giocoso. Just type the command:

sudo port install wget bash

You'll see MacPorts proposing to install a bunch of related software besides those two packages:

When prompted, say 'y' to continue. The software installation will be relatively swift, and will end with a wall of text that you can safely ignore:

Once you see that, your system is ready to install Giocoso. Be sure to close your terminal again at this point and open a new one: if you don't, you'll be trying to launch the Giocoso installer in a terminal that only knows about the existence of the ancient, built-in version of Bash, which won't work. Only a freshly-opened terminal will notice that you've just installed a Version 5+ copy of Bash and make use of it.

4.0 Installing Giocoso

Now you're ready to install Giocoso, you first need to obtain the installation script itself. That's easily done in a terminal, with the command:

wget software.bbritten.com/gioinst

To launch the downloaded script, you then just type the command:

bash gioinst

That should immediately trigger the following display:

This text just warns you that an assortment of software is about to be installed on your system and some configuration changes will be made. You can back out at this point, by tapping 'n', and nothing at all will have changed on your PC… but if you tap 'y', the installer will proceed. You'll first be asked to supply the sudo password, so that the installer script can obtain the root privileges it needs to do its work. Once you supply that, you'll see this bit of text:

This is quite a crucial prompt to get right. Giocoso can use either Homebrew or MacPorts to install the software it depends on …but it's vital that it shouldn't use the package manager that's inappropriate for your system. If you've installed Homebrew, Giocoso mustn't try to use MacPorts and, of course, the opposite also applies. Your job is therefore to tap 'h' or 'm' to tell the installer which package manager to use during the installation process. Make sure you pick the right one, or mayhem will ensue!

As soon as you've selected the correct package manager, the screen will change to this sort of thing:

This part of proceedings can take quite a while (potentially a very long time if you're using the Homebrew package manager): be patient and let it do its thing! Eventually, the screen will change to this:

With the software prerequisites dealt with, the installer will now download Giocoso itself: just click OK (or press [Enter]) to move on to that next step:

This part of the process will speed by pretty quickly: Giocoso's bits and pieces are measured in kilobytes, not gigabytes! When they've all been downloaded, you'll be prompted once more to begin a verification process, where the installer computes a hash sum for the things it has downloaded and compares those hash values to ones this website thinks ought to be true:

If any mismatches are detected, the installer will try to download the various components again, hopefully with a better result. One way or another, however, you'll end up seeing this:

And that's it! Giocoso is now successfully installed and can be immediately launched by typing the command giocoso into a terminal, though the results might not be ideal:

You will note that, running in the standard macOS terminal, the colour scheme used by Giocoso doesn't really work very well, with grey text that's practically impossible to read! We'll sort this out shortly, but for now the point is that Giocoso is installed and works!

5.0 WezTerm to the Rescue!

Appearing in all the wrong colours is not the default terminal's only failing: you'll soon find out that it is not able to display album artwork inside itself, either. Technically, Giocoso displays artwork using the “sixel graphics” protocol… and that protocol has to be support (i.e., 'compiled in') to any terminal application for it to work. The default macOS terminal doesn't do that, so in-terminal graphics are a no-no.

If you are using MacPorts, therefore, I recommend you run the following command:

sudo port install wezterm

…which will install the WezTerm terminal emulator, which does know how to render sixel graphics. It should appear in the Launchpad display as a black square with a blue “$W” in it. There's no need to do this now if you're using Homebrew, because I included the command to install that way back in Section 2 anyway.

WezTerm will tend to want open by default using a small window with small fonts: I suggest you would want to change that up a bit. The way you do that is to issue these commands:

cd
nano .wezterm.lua

Paste into the new file the following:

local wezterm = require 'wezterm'
local config = wezterm.config_builder()
config.initial_cols = 103
config.initial_rows = 28

config.colors = {
    -- The default text color (green is dark green, lime is bright green)
    foreground = 'lime',
    -- The default background color
    background = 'black', 
}

config.font = wezterm.font("Courier New", {weight="Regular", stretch="Normal", style="Normal"})
config.font_size = 16

wezterm.on('format-window-title', function(window, pane, tabs, panes, config)
    return "Giocoso : The Classical Music Player"
end)

return config

Save the modified file. Hopefully, most of this is self-explanatory: it tells WezTerm to open at an initial 103 columns by 28 rows; to use the built-in Courier font (more on this below) at 16pt size, and to auto-launch Giocoso when it itself launches. With these parameters configured, launch WezTerm by clicking its icon in the Launchpad:

That's a rather pleasing display, I think.

Be aware that Giocoso supplies a font it thinks you might want to use instead of the 'Courier New' one I've mentioned in the above configuration file: Luxi Mono. It can be found in the /Users/hjr/.local/share/giocoso3/art folder (the “hjr” bit is my username: substitute in your own, obviously!), as a file called luximr.ttf. Double-click that to launch the Apple Font Book utility which lets you install it:

Once the font has been installed, re-edit the .wezterm.lua file and replace the name “Courier New” with “Luxi Mono”, leaving all other text unchanged, and save the file. You should see the existing terminal update itself to display the new font:

The new font is slightly serif (the characters have little hooks at their tips and so on) and not quite as spidery as Courier New… but the choice of font is, ultimately, up to you.

If you now take the Database Management menu, Option 1 you'll be able to create a database of what music files exist on your system. After that, you'll be able to take the Play Music menu, Option 1 and have some of it start playing to you:

…music with in-terminal display of album art!

6.0 Final Graphical Tweaks

The last thing you might want to consider is creating a proper program launcher for Giocoso that looks like it belongs to Giocoso and not Wezterm! Here, for example, is my dock:

You'll note that the second icon in from the left is, indeed, something that looks like it might want to launch Giocoso. How do you achieve that?

Well, first open Finder and visit the Application section: there you'll find a MacPorts folder (assuming you've used MacPorts to install everything, of course):

Inside that folder, you'll find the icon used to launch WezTerm:

Right-click that icon and select 'Copy' from the context menu; then click back to the Applications section and right-click and select 'Paste': you'll now have a WezTerm icon in the 'root' of the Applications folder:

Right-click this new icon and select 'Rename' from the context menu and then change the text label for the icon to 'Giocoso':

Now comes the slightly tricky bit to describe! Right-click the new 'Giocoso' icon and select 'Get Info' from the context menu. That will open up an information panel about the executable associated with the icon. Keep that open whilst, back in Finder, you select 'Go → Go to Folder…' from the top menu: for the path to go to, type /Users/hjr/.local/share/giocoso3/art (replacing 'hjr' with your own username, of course):

Your job now is to click-and-drag the giocosoico.png from the art folder in Finder on top of the tiny '$W' icon in the top left-hand corner of the Giocoso Info panel. Drop the png on top of the existing icon and you should see both the little and big icon at the bottom of the Info panel change:

Now you can close the Info panel down. In the Finder window, you can now double-click the new Giocoso icon to launch WezTerm. That will put the running application-with-Giocoso-icon into your dock: right-click it to say 'Keep in Dock' and then drag it to where you want to see it in future. Bingo: you now have a proper-looking application launcher that will allow you to run Giocoso easily within a terminal emulator that knows how to display album art properly.

A couple of additional notes of caution and advice. First: earlier versions of macOS (think: Catalina, especially) do not allow you to drag .png files onto the Info panel as I've described here. On those versions, you first have to convert the .png supplied by Giocoso to a .icns format and then drop that version of the artwork onto the Info panel's little icon placeholder. I use this free on-line converter to do that. Point the site to the .local/share/giocoso3/art/giocosoico.png file, click convert, then download the converted file. Drag that to the Info panel and you can delete the download afterwards.

Second: if you used Homebrew to install Giocoso, you won't find WezTerm inside a MacPorts folder: it will be directly in the Applications section of Finder. The same technique applies, however: copy it, paste it, rename it, re-icon it.

7.0 Giocoso Pro Complications

Giocoso Pro is an extension to the basic Giocoso functionality of playing local music files: it allows a Giocoso instance to consult a remote database of what music files exist to determine what to play. This remote database is a MariaDB or MySQL database and thus your local Giocoso installation needs MariaDB or MySQL client software to talk to it.

Such a client has, in fact, been installed for you automatically, as part of the standard Giocoso installation. The trouble is that macOS probably won't know how to find it! Worse, what it should be hunting for changes depending on whether you use MacPorts or Homebrew as your installation package manager. For me, using MacPorts, the correct executable ended up being found in /opt/local/lib/mariadb/bin and was called mysql, even though Giocoso only ever installs the MariaDB client.

Sidenote: On my brand new M4 iMac, I did the Homebrew install and MariaDB was located correctly, first time of asking: just type mariadb in a terminal session and if it returns a message about 'ERROR 2002 Can't connect to local server', you're in business and need read no further in this section.

The key point to make is that Giocoso expects to find either a “mariadb” or a “mysql” executable in /opt/local/bin. Chances are that this is not where Homebrew or MacPorts put it, however! Therefore, we need to do some slight of hand to make it so: in a terminal, type the command:

sudo ln -s "/opt/local/lib/mariadb/bin/mysql" "/opt/local/bin/mariadb"
sudo ln -s "/opt/local/lib/mariadb/bin/mysql" "/opt/local/bin/mysql"

That creates a link between a placeholder called “mariadb” in the correct location to the actual executable in the weird and deeply-nested place that MacPorts put it. A functionally-identical link is also established between a placeholder called “mysql” in the right place to the actual executable. That means whether Giocoso issues “mysql” commands or “mariadb” ones, it will always find that actual executable.

With those links in place, you should be able to type the plain command:

mariadb

..or:

mysql

…and, in either case, get the same response:

ERROR 2002 (HY000): Can't connect to local MySQL server through socket '/opt/local/var/run/mariadb/mysqld.sock' (2)

Don't worry about the apparent error: that's just a consequence of not trying to connect to a specific database for now. The point is, if MariaDB or MySQL is producing error messages, the program has been found and is running: if you can find the program, so can Giocoso… and that means Pro functionality becomes possible.

Be warned: I could not install MariaDB on Catalina via Homebrew. I was able to brew install mysql-client, but that then leaves a MySQL client trying to talk to my MariaDB Giocoso Pro server: not a combination I support or approve of! For such an old version of macOS, I suppose it was foolish to imagine Homebrew being reliable (remember: Homebrew is only supported for recent OS releases; it's MacPorts that works on ancient versions), so this is not a failing that is likely to trip you up, but it's another factor to bear in mind when considering whether to go the Homebrew or MacPorts route.

8.0 Conclusion

I've personally installed Giocoso 3.32 on (a) Catalina; (b) Big Sur; (c) Monterey; (d) Sonoma, (e) Sequoia and (f) Tahoe. The older versions were using Intel chips; Tahoe uses the Apple Silicon M4 chip, so Giocoso is known to work on most macOS versions released since 2019 and on both major CPU architectures.

Speaking generally, MacPorts is the way to go to get Giocoso's prerequisites/dependencies installed if you are using anything earlier than Sonoma; conversely, Homebrew is a reliable way forward if you're using Sonoma onwards. Catalina is pushing it, though ultimately gets there. Everything else is most plain sailing, using the appropriate package management technology for the OS version.

As a final flourish, I give you parting screenshots of my assorted real-world Giocoso-on-Mac installations:

Catalina, 2.7GHz, 8GB RAM (via Homebrew and MacPorts)

Big Sur, 1.4GHz, 4GB RAM (via MacPorts)

Monterey, 3.1GHz, 16GB RAM (via MacPorts)

Ventura, 1.4GHz, 4GB RAM (via Homebrew and Macports, using Legacy Core Patcher)

Sonoma, 2.7GHz, 8GB RAM (via MacPorts, using Legacy Core Patcher)

Sequoia, 2.7GHz, 8GB RAM (via Homebrew, using Legacy Core Patcher)

Tahoe, ~4.4GHz, 16GB RAM (via Homebrew, M4 iMac)

| Back to Software Home | Back to Giocoso Documentation Home |

minig

Anonymous (anonymous@undisclosed.example.com) — 2026-03-20T18:25:54+00:00

Minig : The Giocoso Mini Player

1.0 Introduction

Starting with Giocoso Version 3.6, Giocoso ships with the ability to run in “minimal mode”: a stripped-down Play Music menu that allows you to initiate randomised playback from an interface that is width-constricted, such as a mobile telephone:

Taking the 'Play Music' menu option on this screen is exactly equivalent to taking Option 1 on the standard Play Music menu in full-blown Giocoso: you get the 'default' music selection that results from applying parameters specified in your persistent configuration, excludes and exempts files, randomly-ordered.

This mini-mode Giocoso is invoked by typing the command:

minig

…at the command line. The intent is that you might do this whilst connected to a music-playing PC over ssh, on your mobile (cell) phone. You thereby acquire the ability to start and control playback of music, remotely.

With this scenario in mind, the mini player deliberately avoids displaying any form of album art or other in-terminal graphics since doing so generally results in this kind of garbled display:

The mini player therefore only displays textual data related to the music being played, like this:

As music plays, the usual sort of 'play control' menu options are available at the bottom of the screen: Autostop (to allow the current play to continue but prevent progress thereafter to any new play); Terminate (to immediately halt the current play and to not progress to any other play, either); Skip (to immediately halt the current play but to progress to the next play, if any are available); and Repeat (to allow the current play to continue to completion and then to begin playing it again from the start). Play controls you would see when the full-fat Giocoso plays music (such as Pause, Volume and Notes) are not available in mini-mode.

Note that the mini player doesn't just initiate music playback: if you have already begun playing music in full-fat Giocoso on server X, then connecting to server X and running minig will show you what music is already playing:

Here, for example, you see that some Gabrieli is playing in full-fat Giocoso on the left; the mini player has then been launched on the right: it immediately displays the details of what is already being played, rather than giving you the option to initiate music playback. The mini player's music play controls still function, however: if you press Autostop in the mini player, the Autostop option in the main player will light up, for example.

The only thing to really note about the mini player in this 'control mode' (as opposed to it being the playback initiator) is that the play controls are not persistent or interactive: if you tap 'Repeat', for example, the mini player's 'Repeat' option will not stay highlighted, though the one in the main player will. In similar fashion, if the main player stops playing one piece of music and starts playing a new piece, the mini player's display will not update to reflect this: it will continue to display the details of the original recording only: you would need to tap 'x' to quit the mini player and re-launch it to see the details of the new recording being played.

Another feature of this 'control mode' functionality: if you take the mini player's “Skip” option, you'll trigger the main player to terminate the current music playback and start the configured countdown before play of a new recording begins. That causes the mini player to return to the main menu (since there is no music playing whose details it can display). It will remain at this main menu, even though the main player moves on to playing something new: again, the point is that in control mode, the mini player is not interactive with the main player. That's why the mini player has an Option 3: Refresh screen menu item. Tap '3', and the mini player's display will update to display the details of the new recording that the main player has begun to play.

2.0 Pulse Audio Configuration

Remember the situation the mini- layer was invented for: initiating or controlling music playback from a Giocoso-enabled computing device via a handheld device. In that context, where control is separate from the thing doing the actual playing, it makes sense that the controller should be able to direct the player to send its music to wherever the controller wants it to, rather than to the device on which the player is actually running.

Imagine this scenario: you have a music-playing PC in a dedicated listening room, attached to a good DAC, amplifier and speakers. Today, however, you want to sit out in your garden and thus require music to sound out from the garden shed (it happens!). The garden shed is equipped with an ancient PC that can barely run anything usefully… but it happens to be connected to an amplifier and speakers. In this case, therefore, you want the listening room PC to send its audio signal not to the DAC, amplifier and speakers to which it is directly connected but over the network, to the garden shed PC: it is playing in the listening room, but it is sounding in the shed!

This is functionality that comes with a technology called PulseAudio (and its newer, backward-compatible equivalents, such as PipeWire). Giocoso has always been “PulseAudio capable”, but the mini player extends this capability to making it trivially easy to select any of multiple 'audio sinks' to which music playback can be directed. (An “audio sink” in this context is simply a fancy way of referring to “the device that does the sounding of music, even if it's not doing the playing”)

2.1 Setting up PulseAudio Server Details

The Giocoso mini player comes with Option 2 : Set up PulseAudio Server details which, when taken, reveals this sort of screen:

The screen allows five pairs of “Sink Name” and “Associated IP Address” to be entered: the name can be anything you like but will be truncated to 14 characters long upon saving. The IP addresses have to be valid IP addresses to be meaningful! When submitted, these entries are written to a table in the local Giocoso database, called PULSESINKS, with columns identifier (the textual data) and ipaddress (the associated IP address).

You don't have to fill in all five available sinks: I've shown five for explanatory purposes but in fact only ever direct my music to either the bedroom or the summerhouse, so in reality, I'd only ever fill in two sinks.

Note, however, that if the mini player is going to be run on a one of the PCs that you also listen to music on directly then it should be entered as its own possible sink. In other words, I also listen to music in the listening room: if this mini player is running on the listening room PC, I'll need the ability for the listening room PC not only to direct audio to the bedroom or summerhouse but also to itself… otherwise, I won't be listening to much in the listening room in future!

2.2 Selecting a PulseAudio Server

Once you've created a set of PulseAudio sinks and their associated IP addresses, you can select one of them using the mini player's Option 1: Select a PulseAudio Server menu item:

On this screen, all configured sinks will appear with a set of empty brackets next to them. One of the sets of brackets will have an asterisk in them: that is the currently configured PulseAudio Sink (that is, the one mentioned in the full-fat Giocoso's Administration menu, Option 2:

You can see here that I've pre-configured IP address 91 to be my 'default sink' and from the earlier mini player screen, you can see that the .91 address is, indeed, associated with my listening room PC. However: it's a nice sunny day and I want to have music play from the listening room out to my garden: so, on the mini player, I've highlighted the 'Summerhouse Pi' item by up- and down-arrowing to it. Once it's highlighted, press the Space Bar:

Now the asterisk jumps to the 'Summerhouse Pi' item, indicating that it's been selected. Press [Enter] to confirm. Immediately, the mini player screen will update to show the change in selected sink:

Were you to go into the full-fat Giocoso's administration menu, option 2 once more, you'd see the newly-selected audio sink had also been changed there. The mini player selection changes the main Giocoso's persistent configuration file settings, therefore.

All this now means that if you were to initiate play from either the mini player (by tapping the 'P' key) or from the main Giocoso play menu, the resulting audio stream would “sound out” on the .116 computer: and the birds and I would be happy!

There is just one catch before the pigeons and I can be truly satisfied in the sun: it isn't enough only to select a PulseAudio sink to play to. You also must tell the main Giocoso's configuration file that it must use PulseAudio to distribute its audio via PulseAudio in the first place. That's done with another of the persistent configuration file settings:

Here, the “Force the use of PulseAudio” configuration item has been set to yes (it defaults to a 'no' value). Only when this says 'yes' and a PulseAudio server's IP address has been configured using either the main Giocoso program or the mini player will music be played on one PC and sounded out on another.

3.0 Conclusion

The mini player is not all to do with PulseAudio: it's there as a remote control for 'proper' Giocoso, allowing you to repeat, skip, terminate and autostop plays already begun with the main player, but via an ssh session and a mobile phone. In this mode of operation, the mini player takes over most of the functionality of mgiocoso.

In addition to controlling existing plays, however, the mini player can do something mgiocoso never could: initiate default, randomised plays by itself.

Only in a third, subsidiary mode of operation can the mini player be used to setup a group of PulseAudio 'sinks' and then direct plays of music that it initiates to one of them, over the network, provided you've already configured PulseAudio on all appropriate computing devices. Doing that necessary configuration of PulseAudio servers can actually get quite tricky and is beyond the scope of this particular piece of documentation, though additional documentation helping you achieve it is in preparation.

| Back to Software Home | Back to Giocoso Documentation Home |

playmenu

Anonymous (anonymous@undisclosed.example.com) — 2026-01-23T20:04:03+00:00

The Play Music Menu

Giocoso is, first and foremost, a classical music player… so the Play Music menu is pretty much the meat-and-potatoes of the entire program! Almost all the options found on this menu will initiate music playback (the exceptions are a couple of menu options that deal with playlist housekeeping matters).

The various music-playing menu items controls what music Giocoso will play, by altering the source of the music it knows about. Most commonly, Giocoso will use a music database to tell it what FLAC files exist and where they can be found on disk: Giocoso will query that database and pick one of those files to play, more-or-less at random. However, you can also make specific queries of that database using your own selection criteria and Giocoso will then play the results of your queries. Finally, you can simply 'point' to a folder of music on your hard disk and tell Giocoso to 'play that', which it will then do, quite happily.

Whenever you make a manual selection of music to play, you can store the results of that selection into a text file called a playlist. Playlists can then also become a source of future Giocoso play selections. Since a playlist is simply a text file, you can create your own playlists in a simple text editor and feed that to Giocoso as a source of plays, too.

I must emphasis, however, that practically nothing on the Play Music menu will work until you have created a music database: if you haven't already created a database, therefore, please skip to the Database Management menu options to do that first! Also: please note that there can only be one Giocoso session playing music at a time, though you are free to launch multiple Giocoso sessions to do other things (like running reports or editing the Persistent Configuration file) whilst another is playing music. Most of the menu options on the Play Music menu will simply be silently inoperative if acting on them would cause two sessions to start playing music at the same time. Indeed, if you launch a second Giocoso session after one is already playing music, the entire Play Music menu will be off-limits: no menu items at all will be displayed.

Links to a detailed description of each menu option are listed below:

Play music with defaults

Play music from selection filters

Play music in specified folder

Play music by advanced SQL selection

Play music from a playlist

Resume a Global Play

Create or edit a playlist

Delete old playlists

An additional note about how Giocoso can play back music using ReplayGain technology is found here.

| Back to Software Home | Back to Giocoso Documentation Home |

probuild1

Anonymous (anonymous@undisclosed.example.com) — 2026-02-18T18:47:04+00:00

Build A Giocoso Pro Server

1.0 Introduction

A Giocoso Pro Server is simply a PC (or virtual PC) that runs a copy of the MySQL database (or MariaDB). Such a computer does not need to be particularly powerful or well-resourced: a single CPU, 1GB RAM and (say) 40GB of hard disk space should be more than adequate, though of course more of any of these things is always welcome!

Since it is a server, there is no need for a fancy graphical desktop to make things look 'nice': a Linux distro that provides the bare minimum of computing capabilities whilst managing to run the database is all that is really required: so Arch, or Ubuntu Server or Fedora Server are ideal candidates, because they ship 'out-of-the-box' without GUI bells and whistles. Personally, my Giocoso Pro Server runs in a FreeBSD jail, so not even Linux is a necessity!

A fixed IP address for networking purposes is a good idea (servers need to be contacted by client machines, so it's a good idea for the server to stay fixed at a known address, rather than to dynamically wander around the place!) but it is not a requirement that the server has to be able to see your music collection, either directly or via a storage sharing technology (such as NFS or SMB). The Giocoso clients will inform the server about what music exists: the server itself doesn't need to be able to confirm the details.

I've written a separate article on how to build a Giocoso Pro server using Arch, because the Arch installation process itself is so unusual, compared to any other distros you might want to use. In this article, I'll be using Fedora Server 41 specifically -but the principles demonstrated work on any non-Arch distro you're likely to want to use. The basic story is:

Install your operating system using defaults
Download a preparation script from this website
Run the preparation script
Confirm things are working
Check your clients can access the new server

2.0 Install your Operating System

I'm building a virtual machine in which to install Fedora Server: I've deliberately configured it with fairly minimal resource settings:

Anything vaguely similar in physical hardware capabilities would suffice just as well: before I built my FreeBSD Jail, I was using a 2011-vintage Dell desktop PC with an Intel i3 CPU, 4GB of total RAM and a 60GB solid state hard drive as a test platform, and it worked fine.

As far as the operating system installation went, I ran with all the defaults proposed:

Specifically, I chose automatic disk partitioning and the default Fedora Server software selection. The one thing I did manually intervene on was the networking: by default, it's configured with DHCP, which makes life convenient but means your server is assigned an IP address dynamically and in a way that means the address could change every time the server is rebooted. Changing IP addresses makes life hard for clients wanting to find the server! Therefore, I assigned a static IP address, as follows:

Now, the specific addresses you see here are mine, appropriate to my home network setup. They are unlikely to apply to your environment. Here is not the place to explain the basics of home networking, but if you aren't sure what entries to make for your own Giocoso Pro Server, please read <a href=“http://absolutelybaching.com:81/music-articles/how-to-rip-an-sacd/”>Section 2.3 (“The Home Network”) of my article on doing SACD ripping, where I explain network addresses in some detail.</a>

I also clicked the IPv6 Settings tab in the above screenshot and set the 'Method' to 'Disabled': your Giocoso Pro Server is not going to need to know how to handle IPv6 connections!

Fedora's installation prompts for the creation of a non-root user account: you should take the opportunity to do that:

You also get the opportunity to enable or disable the root account:

I chose to leave the root account disabled. It would be like that in Ubuntu Server, for example, without even asking you about it …and isn't a bad thing to do in any distro. Provided there is a non-root administrator account created (as you can see my 'hjr' account will be), you can always exercise root powers via the magic of the sudo command, so there's no need to ever actually be root directly.

They're really all the things you need to consider at operating system installation time: non-root user account, fixed IP address, standard/default disk partitioning and software selections. After that, you just click the 'Begin installation' button and sit back and wait. It took about 10 minutes for the O/S installation to complete for me.

When the installation completes, reboot the machine and log in as the non-root administrator user you created earlier:

As you see, you end up at no-frills command line prompt… just what servers are supposed to look like!

The only other order of business at this point is to stop the machine being called “localhost”, which is what Linux calls things that don't have 'proper' host names. Some operating system installers allow you to specify a proper hostname as part of their installation wizard, but Fedora doesn't. So lLet's fix that the manual way, like so:

sudo hostnamectl set-hostname giocosopro

I'm assigning the name 'giocosopro' here, but you can pick any single-word name of your fancy. You'll need to log out and then log back in to have the change picked up and applied:

Apart from that, though, you're now running a server that can become a Giocoso Pro server… we just need to make that bit happen next!

3.0 Update the O/S & run the Giocoso Pro Installation Script

Before we do the Giocoso Pro bit, it's a good idea to make sure all the software on your new server is as up-to-date as it can be. If you don't do this manually now, the Giocoso Pro installer will do it for you anyway, but it's nice if that script doesn't have to take hours to complete! Getting the updates done now means the Giocoso installer will have to do much less of the heavy lifting later. At the command prompt, therefore, type the command:

sudo dnf update

On Ubuntu or Debian, you'd type 'sudo apt update && sudo apt upgrade'; on Arch it would be 'sudo pacman -Syu'; on OpenSuse, 'sudo zypper update' and on FreeBSD, 'pkg update'. All do the same thing: inspect the software on the system, fetch updates to all of it from across the Internet, then apply it. On Fedora, my update was not terribly big:

…but it depends on how recently a particular version of your server's operating system was released or refreshed as to precisely how much software will need to be downloaded and applied.

Once your operating system has been updated, type this command:

wget software.bbritten.com/pro

If you get told 'command not found', you'll first need to install the wget program itself (this happens commonly on Debian-based distros, for example): sudo dnf install wget would be the command on Fedora; sudo apt install wget on Debian and Ubuntu; sudo zypper install wget on OpenSuse and pkg install wget on FreeBSD.

You can confirm the script has downloaded correctly, like so:

The exact size of the script will vary over time, so don't place too much reliance on specific numbers: the point is simply that you can see the downloaded file. It's a shell script, which means it's fundamentally merely a text file. You're welcome (indeed, encouraged) to open the file in a text editor to check its contents and make sure it doesn't do nefarious things. A suitable command might therefore be less pro. Just tap the letter 'q' to quit the less program when you're satisfied with the script's contents.

When you're ready to launch the pro script, just type:

bash pro

You will immediately be prompted for your sudo password (i.e., the password of the non-root account you're operating under). Depending on how long the script runs for, you may be prompted for the sudo password more than once: just type it in whenever prompted.

The script does the following things to your server:

Updates all its software (which shouldn't do much, if you've just done the job manually anyway!)
Installs MariaDB database software (equivalent to installing MySQL)
Enables MariaDB to restart automatically whenever the server reboots
Configures MariaDB to accept network connections
Opens the MariaDB default port (3306) in any running firewall
Runs the mysql_secure_installation script to tighten up the default security within MariaDB
Creates a new MariaDB database, called “giocoso3” and a user to own and administer it, also called “giocoso3”, with a password of “giocoso3”

It should all generally whizz by at a rate of knots without too much drama. Debian doesn't install sudo by default, so there are some root passwords required to get it to the point of using sudo, I'm afraid: this means that Debian-based distros will generally prompt for the root password multiple times before it finally prompts for the sudo password. Stay aware of which one it's asking for at any given time.

Please note that on FreeBSD, you will probably get an error about 'bash not found', so you'll have to do a pkg install bash before you can run the bash pro command.

4.0 Post-Installation Checks

Once the pro script has run its course, it's probably wise to run a few checks, just to make sure everything worked as intended.

4.1. Is the MySQL Configuration File correctly set to accept network connections?

The MySQL database needs to be configured to 'bind' to a network address, and not just to localhost connections. The pro script should have done that for you, but it's best to be sure. The relevant configuration file is either /etc/mysql/my.cnf or /etc/my.cnf, depending on distro (Fedora and OpenSuse use the /etc/my.cnf location; most other platforms use /etc/mysql/my.cnf. Just cat the file and check the results:

You need to see a 'mysqld' section at the end of the file, together with a bind address that reads your server's actual IP address, not a '127.0.0.1' placeholder. If you see something similar to the above, your MySQL server is configured to accept connections from across the network, which is what we want to see.

4.2. Is the Firewall port 3306 open?

This can be tricky to do in a bit of distro-agnostic documentation, because different distros use different firewalls, if they use a firewall at all by default. Thus, the specific commands to check the status of the firewall on any given distro might well vary. On Fedora Server, the firewall software is called firewalld and 'firewall-cmd' commands are used to query and control it.

To check if a firewall is running at all, issue the command:

sudo firewall-cmd --state

If it returns with a reply of running, then you know that there is< a firewall in use and that therefore it needs to permit MySQL traffic through. To check that the MySQL port is open for network traffic, therefore, then issue this command:

sudo firewall-cmd --query-port=3306/tcp

That will either return 'yes' or 'no'. If it returns yes, you're in business and need do no more. If it returns no, however, then you need to manually force the port open with the commands:

sudo firewall-cmd --permanent --add-port=3306/tcp
sudo firewall-cmd --reload

A re-run of the 'query port' command should then return a 'yes' reply.

On Ubuntu Server, the firewall software is called ufw so the command to check if port 3306 is open is:

sudo ufw status

If you get a little table of results when issuing that command, you should be good to go. OpenSuse apparently uses the firewalld firewall, just as Fedora does …so the above commands should work on that distro, too. Debian is a law unto itself, so on that distro you'd issue the command

sudo nft list ruleset

If a bunch of code comes back that lists 'dport 3306' within curly braces, you're probably good to go!

4.3. Is there a Giocoso3 Database?

The last thing to check on the server is whether the script correctly created a giocoso3 database for you. Issue the command:

sudo mysql

At the new prompt that then appears, type:

show databases;

Be sure to include that trailing semi-colon, which is the delimiter that tells the database engine your command 'ends here'. You should see something like this:

You can see the name 'giocoso3' shown in the little list of databases there: that means the script has done its job correctly. Type the word quit to get back to the normal command prompt.

4.4 Final Checks from Clients

One final check is probably worth performing: can your client devices actually see and connect to the new Giocoso Pro server? To check that, you'll need a client device onto which the MySQL server client software has been installed. Explaining how to do that in detail is outside the scope of this article, but in brief:

Arch: sudo pacman -S mariadb
Debian: sudo apt install mariadb-client
Ubuntu: sudo apt install mariadb-client
OpenSuse: sudo zypper install mariadb-client
Fedora: sudo dnf install mariadb

Assuming the client software has been installed, switch to using one of those client devices and in a new terminal session type the command:

mariadb -u giocoso3 -pgiocoso3 -h 192.168.137.187 -D giocoso3 --skip-ssl

…which means “connect to a database called 'giocoso3', as a user called 'giocoso3' and with a password of 'giocoso3' (notice there's no space between the -p and the password!)”. The specific IP address you use should be whatever your new Giocoso Pro Server is using, of course. The username and password are, however, hard-coded and fixed.

The response should be something like this:

You'll notice that I threw in a 'show tables;' command there -the result was 'empty set', because no tables actually exist within this database as yet, but the fact that the command produce a response of any sort at all indicates that remote connections to the server are working as intended. To create appropriate tables is the job of the Giocoso Pro initialisation process, which is launched from within Giocoso itself… and which is resolutely outside the scope of this particular article! For now, it's sufficient to know that you've got a working Pro server that is able to be used by Giocoso clients successfully.

5.0 Final Notes on Security and the Pro Script

The Pro script aims to automate the setup of a MySQL server on Arch, Debian, Devuan, Fedora, OpenSuse, Ubuntu and FreeBSD. It may work on distros derived from those 'parent distros', but I haven't tested them and I can't vouch that anything will work in such environments. Generally speaking, you don't want to be setting up dedicated database servers on 'niche' distros anyway: I've never seen Oracle installed on Peppermint Linux or Garuda Linux, for example! Stick to the mainstream 'parent' distros, though, and you should be OK.

That said, I'm disclaiming all responsibility at this point! You run the Pro script at your own risk. I haven't wrapped it in layers of error detection and robustness, for example. I've tested it on virtual machines running fresh installs of the latest versions of the various distros mentioned (latest at the time of writing that is, being mid-February 2025) and it does what I expect it to do on all of them. If you run it on a server you're already using for other things, who knows what the results might be. If a pre-loved server is your intended platform, therefore, I would recommend you reading the Pro script and working out what it does… and then doing those same things yourself, manually… and carefully!

Finally, please note that the MySQL database the Pro script creates (and which Giocoso Pro expects) is not secure and isn't intended to be secure. It's administrative user is giocoso3, password giocoso3, and he has complete authority to create or destroy everything in the giocoso3 database. There's no subtlety about that and it's entirely by deliberate design: a Giocoso Pro database is not meant to be as secure as Fort Knox. It's intended for internal use in a home network environment, without access to the wider world via the Internet, so any potential threat to it is entirely inside your own home. Knowing the credentials involved potentially gives your miscreant children the ability to screw with the Giocoso global database …but it's expected that this is a problem you'll resolve in whatever way seems appropriate to you! Just be warned that you should not attempt to change the giocoso3 username or password. That combo of credentials is hard-coded throughout Giocoso's code, so changing it on the database will definitely break things, badly.

In conclusion:

Start with a vanilla, fresh server installation
Fully update your server's operating system
wget software.bbritten.com/pro
bash pro
Check your firewall allows traffic on port 3306

…and then go configure your client devices to point to and make use of the new Giocoso Pro Server's database.

| Back to Software Home | Back to Giocoso Documentation Home | Back to Pro Menu |

probuild2

Anonymous (anonymous@undisclosed.example.com) — 2025-12-10T10:49:10+00:00

Build A Giocoso Pro Server With Arch Linux

1.0 Introduction

Giocoso Pro is the name given to a MySQL (or MariaDB) database that provides details of what music files exist and what plays of them have taken place, shared amongst all your computing devices that might be involved in playing classical music. It is a very lightweight implementation of a relational database, with just two tables and not a lot of relations between them! Running such a database therefore requires very little in the way of hardware resources: it's recommended to have a dual core CPU, 2GB of RAM and 20GB of hard disk space, though more of any of these resources is always handy

Since it is a server, there is no need for a fancy graphical desktop to make things look 'nice': a Linux distro that provides the bare minimum of computing capabilities whilst managing to run the database is all that is really required -and that makes Arch an ideal distro for implementing Giocoso Pro, because it starts out about as barebones an operating system as it's possible to get. You choose what to add to it (not much, as it turns out!) and the end result remains extremely minimalist, yet fully functional. As such, this article sort-of reproduces my earlier article on how to build an Arch desktop, but simplifies things dramatically, as no desktop environment is involved.

2.0 The Basics

I built what follows in VMware Workstation as a virtual machine, with:

4096 MB of virtual RAM
2 virtual CPUs
20GB virtual hard disk

Those are above-minimum specs and I could certainly have halved the RAM allocation without too much drama. It's still fairly lightweight, however. If I were doing this on one of the spare physical machines I have sitting around in my loft, my 2011-vintage Dell desktop PC with an Intel i3 CPU, 4GB of total RAM and a 60GB solid state hard drive would work perfectly well.

It is configured to use bridged networking, as it will need to be able to connect to the Internet -and, of course, as a Giocoso Pro machine, client music-playing devices will want to be able to connect to it!

I obtained my Arch Linux installation medium from here, specifically the archlinux-2025.01.01-x86_64.iso file, via the torrent link provided on that page.

3.0 Getting Started

When you first boot your PC or virtual machine, you'll see this boot menu:

The top menu option is the correct option to take: either let the automatic boot countdown time itself out or press [Enter] to accept the top menu selection. This will trigger the display of a pile of unintelligible messages, at the end of which you are somewhat unceremoniously dumped at a command prompt, logged in as root:

Everything from this point on consists of typing some textual commands in order to get the operating system installed on your computer -and ensuring you type them correctly!

4.0 Initial Steps

4.1 Keyboard Selection

Arch assumes you are using a standard US keyboard. If that's not true for you, you'll need to tell it what keyboard you're actually using. Type the following command:

ls /usr/share/kbd/keymaps/**/*.map.gz | less

…and a long list of available keyboard mappings will be displayed, one page at a time (tap 'q' to quit back to the command prompt at any time). Read the list carefully until you see the one you need. The bit you need to take note of is the last part of the file name, but ignoring the “.map.gz” extension. So, a Spanish keyboard would probably be listed under 'es' for 'España'; an Italian one under 'it' and so on. The standard UK Qwerty keymap is listed as 'uk.map.gz', so lopping off the extension, you arrive at plain 'uk'. Knowing that, issue the loadkeys command:

loadkeys uk

You can then tap some keys on your keyboard to validate that you've selected the correct keymap.

4.2 Prepare the Hard Disk

You next need to know what hard disk(s) you've got and onto which one you'll be installing the operating system. Type the command:

fdisk -l

…and you'll see output such as this one:

This tells me I have one real hard disk (ignore things called /dev/loop…) called /dev/sda: I can tell that's the 'right' device identifier because the display tells me it's 20GB big, which is the hard disk size I was expecting. You replace '/dev/sda' in everything that follows with the device identifier that is displayed for your hard disks.

Knowing the device identifier for your hard disk, we now need to parttition it and write a file system onto it. The command to do that is:

fdisk /dev/sda

That takes you into the fdisk utility where it unhelpfully sits there prompting you to type a 'command' of some sort. These are issued by typing individual letters. The key sequence you need to supply now is as follows:

n
p
[Enter] [Enter] [Enter]
w

That creates you a new primary partition, accepting the defaults for its size and location on the disk, and writing those configuration details to disk, so they actually take effect: congratulations, you now have a new partition on the hard drive, called /dev/sda1 (notice the '1' gets appended to the base device identifier, to indicate that it's the first partition (and the only one, as it happens) on this disk. Once the partitioning is complete, you could do another fdisk -l to confirm that a numbered partition is listed in the output.

Assuming it is, you now need to format it (and I'm only going to use the very unexotic ext4 file system to do so), using the command:

mkfs.ext4 /dev/sda1

That command should complete relatively quickly and at this point you now have a usable hard disk onto which we can install the Arch operating system and software itself.

We finish up this stage of proceedings by mounting the new hard drive partition into a folder, allowing us to write to it by directing things 'into' that folder. The command to do that is simply:

mount /dev/sda1 /mnt

…and this means that if we were to store or write anything into /mnt, we'll be writing onto the physical hard drive we've just formatted.

4.3 Installing the Operating System

The command to fetch the operating system files from the Internet and copy them into /mnt is:

pacstrap /mnt base linux linux-firmware nano sudo make wget gcc binutils bc networkmanager inetutils man coreutils

That triggers a lot of activity:

Around 600MB of files are now downloaded from the Internet and written into various sub-folders within the /mnt folder. The process should be entirely automatic, so be patient and just let the process complete in its own good time. Should your network connection fail for any reason, don't panic: just re-issue the same pacstrap command again once normal network service has been resumed. The process will pick up from where it last reached.

4.4 Post OS-Installation Configuration

At this point, your new operating system is downloaded and installed, but is fundamentally not usable and won't even boot correctly. We need to tweak some things before you can turn the raw install into a usable operating system.

The first thing we need to do is create an fstab so that the new OS knows what drive(s) it's got to mount in the first place. Issue this command:

genfstab -U /mnt &gt;&gt; /mnt/etc/fstab

That's the 'live' Arch system writing into the contents of the /mnt folder, so that what it sees as /mnt/etc/fstab will, eventually, become the new system's actual /etc/fstab.

Everything else we need to tweak cannot really be written 'into' the new operating system from 'outside' like this, however. Instead, we actually have to sort-of 'go into' /mnt and do everything from within that system. The command to do that is:

arch-chroot /mnt

You'll see the start of the command prompt changes to reflect the fact that you are now 'in' /mnt, as though it were your root folder. There are bunch of fairly low-level commands we must now issue to get things 'right'. First, we ought to set the new system's time zone correctly. To find out what time zones even exist, type the command:

timedatectl list-timezones | less

Once you've found one that seems suitable (I'm going for 'Europe/London'!), tap 'q' to quit the listing and then type the command:

timedatectl set-timezone Europe/London

Next, we need to say what 'locale' our system should use. In my case, I want to say I'm using UK currency, date and time conventions and also using the UTF-8 character set (I need the ability to type the occasional umlaut, or cedilla, given I listen to a lot of classical music by European composers!). So:

nano /etc/locale.gen

That document lists every possible locale: your job is to find the one you want and to remove the hash from the start of the line so that it is uncommented. In my case, I'm looking for en_GB.UTF-8 (English, Great Britain, UTF-8 characterset). Once uncommented, press Ctrl+X to quit and then tap 'y' to save when prompted, finishing with a final [Enter] to accept the proposed file name. With one locale un-commented in this way, type the command:

locale-gen

…and you should see confirmation that the correct locale has been generated.

If you had to change your keyboard settings right at the start of proceedings (see Section 4.1 above), then you should configure that keyboard change now, too:

nano /etc/vconsole.conf

…and type in:

KEYMAP=uk

(or whatever keymap you chose back in Section 4.1).

The new operating system now needs to know about its network identity. So, issue this command:

echo stravinsky > /etc/hostname

…to set your new device's hostname to 'stravinsky'. If you want a different name, be my guest and supply it instead -but make sure you replace all future mentions of 'stravinsky' in this article with whatever alternative name you decided upon!

Now, finish things off with:

nano /etc/hosts

Into this mostly-empty file, append the following information:

127.0.0.1 localhost
::1 localhost
127.0.1.1 stravinsky.dizwell.home stravinsky

Of course, replace 'stravinsky' with your actual choice of hostname. Also note that 'dizwell.home' is my home network's 'domain name': you'd have to change that to whatever you use in your home network, too. Save the edited file.

4.5 Configure Some Users

We're nearly done! We should now set a password for our root user, with the command:

passwd

Type something memorable and complicated twice, when prompted. Don't forget what you supply at this point! Now we move on to creating a non-root user, who I'm calling 'hjr', but substitute in whatever feels more appropriate for you! The commands to give are:

useradd -m -G wheel hjr
passwd hjr

The first command creates a user called 'hjr' and makes him a member of the 'wheel' group for reasons which will shortly become apparent! The second command sets a new password for the new user: follow the prompts and type in a suitable password, twice.

Lastly, type these commands:

export EDITOR=nano visudo

This will open up the sudoers file inside the nano text editor. Your job is to find the line which reads %wheel ALL=(ALL:ALL) ALL and remove the '#' character from the start of that line, so that the line becomes a real, operative one rather than just being commented-out. Press Ctrl+X to exit the editor when ready and then tap 'y' when asked whether you want to 'save the modified buffer': this exit+save is how the edited file will get saved back to disk safely. The new line in the sudoers file means that anyone who is a member of the 'wheel' group can now exercise sudo powers (and thus be the equivalent of root). From the way I created the 'hjr' user earlier, you can see this means that if I log in as hjr, I should be able to issue sudo commands without trouble.

4.6 And finally...

We are almost done!! We just need to make sure that the new operating system knows how to bootstrap itself at boot time. That's done with the commands:

pacman -S grub
grub-install /dev/sda
grub-mkconfig -o /boot/grub/grub.cfg

That installs a boot loader called 'grub', makes it take note of the /dev/sda device that was initialised way back in Section 4.2 and creates a boot configuration which enables the new operating system to boot correctly in future.

At this point, the only thing left to do is to ensure the new PC's network connection comes up properly on subsequent reboots. Issue this command:

systemctl enable NetworkManager.service

And with that done, you can quit the chroot environment we entered earlier and ask for your new PC to reboot:

exit
reboot

You should end up at a command-line login prompt, at which point you can log in as yourself (in my case, as 'hjr').

5.0 Installing Giocoso Pro

Now that you have a working Arch server, it's time to install Giocoso Pro onto it. This basically means downloading a script from this website which (a) installs the MariaDB relational database program; and (b) creates and configures a database suitable to act as a shared Giocoso database. The process, once launched, should be mostly automated: the occasional prompt to supply your password at various points may arise, but otherwise it should be fairly painless.

So, first obtain the Giocoso Pro installation script by typing the command:

wget https://software.bbritten.com/pro

You then run that script, once it's been downloaded, with the command:

bash pro

The script will produce a lot of output, similar to this:

Most of the output can be safely ignored: the key thing to watch out for is that you should see reference to 'mariadb': that's the clue that MariaDB is being installed and configured for you. Once MariaDB is running and configured appropriately, all that is needed is a reboot of the entire server to ensure that MariaDB really does come back up and running automatically afterwards, so type:

reboot

When your PC comes back, log in as yourself and type:

sudo mariadb

…followed by:

show databases;

If MariaDB really is running correctly, you should see this sort of thing:

Notice in the list of databases that there is one called 'giocoso3': that's the proof you need that your Giocoso Pro server is ready to accept connections from client devices. You can then just type exit to get back to a standard command prompt.

6.0 Final Checks from Clients

One final check is probably worth performing: can your client devices actually see and connect to the new Pro server? The way to test that is to switch to using one of those client devices, onto which you've previously installed the MariaDB client software. This command should be typed in a terminal session launched on one such device:

mariadb -u giocoso3 -pgiocoso3 -h 192.168.137.188 -D giocoso3 --skip-ssl

…which means “a user called 'giocoso3' and with a password of 'giocoso3' (notice there's no space between the -p and the password!) wishes to connect to the MariaDB Server running on host 192.168.137.188 and connect to the database called 'giocoso3'”. The response should be something like this:

7.0 Conclusion

Building an Arch server is not particularly hard, but it is fiddly! There are quite a lot of commands to type, all of which are important, all of which demand being typed in correctly

Once built, however, turning the barebones server into a Giocoso Pro server is a simple matter of downloading the appropriate script and launching it. After that, a simple couple of checks performed both on the server itself and on the client devices that hope to make use of it will hopefully demonstrate that you're in business for running Giocoso in shared database mode.

| Back to Software Home | Back to Giocoso Documentation Home | Back to Pro Menu |

proconcepts

Anonymous (anonymous@undisclosed.example.com) — 2025-12-09T14:08:25+00:00

Giocoso Pro Concepts

1.0 High-level Overview

Giocoso Pro is an entirely free and optional addition to standard Giocoso's functionality. It enables a local installation of Giocoso (what is termed hereafter a 'Giocoso client' or 'client device') to push its recordings and plays data to a remote server or PC hosting a special kind of Giocoso Pro database. The Pro databases uses the MySQL database engine (though see Section 12 below for more details regarding the database engine actually in use on any given computing device).

The point of doing that is to enable the client's play history to be shared out to other Giocoso clients: in this way, plays made on a laptop in the bedroom at night are visible to the desktop PC that is used throughout the day, or vice versa. Reports and statistics produced by any Giocoso client will therefore accurately reflect the nature of the music played by all clients, not just the reports and statistics that could be derived from a client's local Giocoso database (which is only ever aware of the plays made on that specific device). The Pro database doesn't replace the local database: that's still there, present on every device; it is, however, an 'aggregation' of lots of local databases. Its play history is thus comprehensive, not device-specific.

Diagrammatically, you might imagine a Giocoso Pro implementation looking a bit like this:

Here we have two client PCs (one could be a laptop, another a single-board computer, whatever: the specifics don't matter!). Each client device is part of a single home network and can therefore access a shared storage device (here labelled a NAS, but it could simply be a third PC's hard disk shared out via SMB or similar), which contains the home's digital music collection. Thus each PC can play network-accessible music files.

Their non-Pro database of what is playable and what has been played is stored on each client's internal hard disk, local to each device and only really accessible by the Giocoso software installed on each specific PC.

It's important to notice that no data passes directly between the client PCs: in earlier versions of Giocoso, there was a mechanism for one client to pass a copy of its local database to another, but that was clumsy and prone to error, so has been removed from Giocoso Version 3.30 and above. The current situation is as shown above: the Giocoso clients do not talk to each other at all, but each talks to a single, jointly-accessible Pro server.

Giocoso Pro is the addition of the bit you see in the top right of the diagram: a new server, labelled 'Pro Server', is visible to the two client devices across the network. It runs a database of recordings and plays, so each client PC can access that Server-based database to store data about recordings and plays that the other client can immediately see (and add to as needed). Note that the Pro Server here is not accessing the NAS device: a Pro Server doesn't need access to the music collection itself. It knows about what digital music files exist and where they can be found because the clients tell it, not because it works it out for itself.

Since each client can see the same Pro server as the other(s), what one client writes there, the other can immediately read intelligibly. If the first client says “There's a Beethoven symphony stored in folder X”, because 'X' is a folder on the shared NAS device, that's going to be true for the second client too. And if the second device says, “I played a Mozart concerto found in folder Y”, the first client will immediately know precisely what concerto was played because it too can see 'folder Y'. In short: what one device can see, all others can see too.

For this diagram to work as a matter of practical reality, you need to do three things:

Build a Giocoso Pro Server
Install a MySQL client on each client device
Switch on Pro features for each client device

Separate instructions for building a Giocoso Pro Server are are provided elsewhere, but it basically involves installing MySQL server and then running a special configuration script that is downloaded from this website.

If you were performing a completely fresh installation of Giocoso Version 3.30 or above then the MySQL client software would be automatically installed as part of Giocoso's software prerequisite checks. However, upgrading to Version 3.30 from an earlier Giocoso release doesn't trigger this important software installation -so I've provided separate documentation that explains how to do the job manually, if you have to.

Finally, switching on Pro features for a client device is simply a matter of setting three new persistent configuration options: I'll discuss the details of this immediately below.

2.0 Switching Pro Client features on

After installing or upgrading a client's Giocoso version to 3.30 or above, the Administration menu, Option 2: Create or Edit the Configuration file can be used to edit the local persistent configuration file:

Three new configuration options are provided, as shown: a MySQL IP Address and Port number, and a 'local folder prefix'. A fourth new option asks whether this is a primary device or not: we'll see how that works in Section 5 below. A fourth parameter (“Is this a primary device”) determines whether a local database refresh also updates the Pro server's database: primary devices do, non-primary ones don't.

For now, it's important to know that Pro features are turned on by setting a value for the MySQL Server IP Address parameter. If it is blank (as shown above, and as it will be by default) then all Pro features are turned off. The IP address needs to be the IP address of the server running MySQL that has already been configured to act as a Giocoso Pro database. That will vary, depending on your own home network setup and configuration -but the client PC definitely needs to be able to connect to it over the network. Note that the IP Address parameter has to be a raw IP address, not a hostname that is resolved into an address via a DNS server or a hosts file. Giocoso checks any entry here at the point of submission and will blank out anything that is not submitted in the form a.b.c.d, where a, b, c and d are all numbers between 0 and 255. However, Giocoso does not check that the IP address entered actually exists on your network or is contactable by the client PC …or that, even though it's contactable, whether or not a MySQL database can be reached at the address. So: typing in a nonsensical IP address will generate an error; but typing in a sensible address that happens not to exist won't generate a thing -though all attempts to play some music after making such an entry will fail.

The default MySQL port number (i.e., the port on which the MySQL listens out for remote connections) is 3306, and the configuration options screen will have this entered by default. Without an IP address entry, however, the presence of a port number here will not switch on Pro features. It is generally unlikely that you would ever want to configure a Giocoso Pro server to use a non-default port, so the default provided here to client devices is probably not going to need to change… but if you do elect to use a non-default port, here's where you tell the client what you've done. Note that if you are running an internal firewall, you need to open it to allow traffic through on whatever port is configured here, otherwise the port will be considered closed and network communications will not be able to flow between clients and server.

It is critically important when enabling Pro functionality in a Giocoso client device that you specify a valid value for the 'Local folder prefix' parameter, and I'll discuss that in some detail next.

3.0 File Storage Locations

The Pro database contains a global_recordings table which will contain data about all the recordings that any client device might want to play. It's important to realise, however, that the Pro database only stores a location to a digital file, not the file itself. It follows that if this global_recordings table is to be shared between multiple clients, then the recording location has to be applicable to, and valid for, all clients.

Imagine the scenario, therefore, where the shared NAS device on which your digital music files exist stores its music at, say: /mnt/bulkdata/music/classical/… and in lots of sub-folders within that basic path. You make this NAS location available to all your network client devices via file-sharing technologies such as SMB or NFS. Each client device then maps this network-accessible folder to a local mountpoint… and the problem is that different clients might mount the network location to very different mountpoints.

For example, my desktop happens to be the 'source of truth' for all digital music in my house, so it finds music at /home/hjr/Music. My main listening PC happens, for historical reasons, to map the NAS folder to /sourcedata/music. My laptops, unconstrained by history, tend to map the same NAS folder to /netmusic.

The problem is that the Pro database must respond to queries from all these devices about 'where do I find Beethoven's Symphony No. 5?' and provide a response that works for all of them. If it replied 'at /home/hjr/Music/Beethoven/Symphonic/Symphony No. 5', that would make my desktop PC happy, but would be completely wrong for my main listening PC and my laptops. Indeed, if it ever answered with a full path, the path would have to be identical on all client devices for it to work for all of them… and constraining things that way would defeat the intended purpose of making Giocoso 'device independent'.

So what Giocoso Pro does is to store, in the global database, only the part of the path which genuinely does apply to all client devices. This is called the folder suffix. Each client device then prepends the part of the path which makes the file suffix work for that specific device: this is called the folder prefix. So, for example, imagine I have these devices and paths:

* Main PC:  /home/hjr/Music/Beethoven/Symphonic/Symphony No. 5
* Laptop: /netmusic/Beethoven/Symphonic/Symphony No. 5
* Listening PC: /sourcedata/music/Beethoven/Symphonic/Symphony No. 5

…then I hope it's obvious that /Beethoven/Symphonic/Symphony No. 5 would be valid for all my client devices and thus be a suitable folder suffix, and the /home/hjr/Music, /netmusic and /sourcedata/music parts of the paths must therefore be valid device-specific folder prefixes.

Here's the completed configuration screen for my main PC, therefore:

When the global, shared Pro database tells my main PC to play “/Beethoven/Symphonic/Symphony No. 5”, therefore, my PC automatically sticks “/home/hjr/Music” onto the front of that and thus searches my hard disk for the complete path of /home/hjr/Music/Beethoven/Symphonic/Symphony No. 5… and will be successful in accessing that complete path. Different devices can look in paths that make sense to them, too, because they'll be configured with different folder prefixes, each one appropriate to each specific device. In this way, Giocoso Pro ensures device independence yet provides single, centralised responses to 'what recordings exist?' queries.

Incidentally, note that it doesn't matter if you enter your local folder prefix with a trailing slash or not: Giocoso Pro treats “/home/hjr/Music/” identically to “/home/hjr/Music” (without the trailing slash).

4.0 Consequent Changes to the local installation

When you switch Pro features on for a client devices by configuring a Remote MySQL Server IP Address, the behaviour of the local client installation changes significantly, as follows:

All options on the Play Music menu that have to do with selecting things to play (except for the 'play music in specified folder') now source their selections from the shared Giocoso Pro database, over the network
Numbered options on the Play Music menu have changed position to accommodate the new Global Resumption feature (see Section 10 below). Options 6 and 7, to do with using playlists, are now Option 7 and 8, and global resumptions are handled by a new Option 6.
During plays of music, the 'n' key now invokes the 'Global Notes' mechanism (see below, Section 9), not the local one.
When a play concludes, it is still recorded in the local plays table; it is then copied to the remote, Pro database. In other words, the local plays table continues to be a complete record of what this specific device has played.
Playlists created before Pro features get enabled are still valid and can be played perfectly fine in Pro or local mode, though only on the device on which they were created.
All options on the Database Management menu continue to reference the local database: if you create a database, it's a local one; if you fast or full-scan refresh a database, it's the local database that is being refreshed (but see below); if you backup or optimise a database, these are operations that only affect the local database… and so on.
As just stated, any fast or full scan database refresh is always of the local database… but if Pro mode has been enabled and the local configuration file has declared this device to be a 'primary device' (i.e. “Is this a Primary Device?” is set to 'yes'), then Giocoso will perform a full push of the local recordings table to the remote, shared database after the local database has been brought up to date. If a primary device refreshes its local device, it will eventually update the global database -and, at that point, all Giocoso devices will be aware of (and can play) any new recordings discovered by the refresh operation.
The reporting menu can use either the local database as its source or the remote, shared database: but it can't use both at the same time. Option 9 on the new Pro menu allows you to switch sources back and forth, between local and remote mode.
If reporting is done in Pro mode, then all output from the Advanced Reporting by SQL function (Option 5) will open in your system's default browser.
Nothing in the Administration menu changes meaning or functionality
A new Pro menu is accessible. This allows a client to wipe the remote recordings table and to re-populate it ab initio. It also allows you to produce a couple of 'aggregated statistics' reports, whereby you can see which devices are playing how-much music and what operating systems they're using to do so.
Configured parameters that affect music search (e.g., setting a maximum and/or minimum duration, or setting the unplayed works or under-played composers flags on) still affect searches performed by that device but by no other device.

It's important to note that Pro features can be switched on and off, at will. You do so by supplying or removing an entry for the 'Remote MySQL Server IP Address' configuration parameter (accessible via the Administration menu, Option 2). If you switch them on, all the changes mentioned above immediately kick in. If you switch them back off, then everything reverts to the way Giocoso behaved before remote databases were even a thing: plays revert to being sourced from the local recordings table and completed plays continue to be stored in the local plays table, for example.

5.0 Are All Clients Equal?

Conceptually, all Giocoso clients have access to the same collection of digital music files (though the specifics of the paths needed to get to them might vary, as previously discussed), so each is as equally well-equipped to talk to the remote Pro database as any other. However, the file prefix/suffix business does affect the answer to the 'are all clients equal' question!

Suppose you have one PC whose folder structure to get to the music files is: /sourcedata/music/classical/A/Aaron Copland… and another PC has /netmusic/classical/A/Aaron Copland… Further suppose that the first PC has its file prefix set to '/sourcedata/music/classical' and the second to '/netmusic'. Can you see that this is now a problem, because if the first PC does a full refresh, it will strip its prefix from the paths it ends up uploading to the Pro database. So a recording found in (say) “/sourcedata/music/classical/A/Aaron Copland/Ballet/Billy the Kid” would be stored by the first PC with the file suffix “/A/Aaron Copland/Ballet/Billy the Kid”. That's not an issue for the first PC next time it wants to play that recording: it takes its prefix and adds it to the suffix and ends up with “/sourcedata/music/classical/A/Aaron Copland/Ballet/Billy the Kid”… and that's completely correct. The trouble starts when the second PC tries to play the same recording: it will do the 'prefix+suffix' trick and go looking for a recording in “/netmusic/A/Aaron Copland/Ballet/Billy the Kid”… and the “/classical” sub-folder name is entirely missed out. Net result: the second PC won't be able to find the relevant recording.

Of course, if you then let the second PC do a full refresh, its results would be written up to the Pro database… and now all the paths would be wrong for the first PC, because again the prefix+suffix equation ends up producing the wrong result.

Wekk, the real fix for this is to sort out the prefix definitions so that they correctly result in suffixes that apply to all devices. In this case, /sourcedata/music and /netmusic would work, resulting in suffixes of '/classical/A/Aaron Copland…'; so would /sourcedata/music/classical and /netmusic/classical which would result in suffixes of '/A/Aaron Copland…'. Either alternative would result in a prefix+suffix combo that would work for both PCs.

So that's the correct fix for this sort of situation: ensure your prefixes are configured for every device that uses Giocoso so that the re-constructed full paths are always right, for every device.

There's always the risk, however, that you'll not quite manage to do that correctly for one or other device you casually add to your network… and if that ever happens, you'll wake up one morning unable to play anything on all your other devices because the new device has clobbered the file suffixes stored in the Pro database as a result of a scheduled full refresh! Ask me how I know! Therefore, an option in the Administration menu, Option 2: Create or Edit the Configuration File allows you to declare that 'this device is, yes, a Primary Device'. A “primary device” uploads new data to a Pro database whenever it performs a local database refresh; a non-primary device will only refresh its own local database: there won't be a subsequent push of recordings data to the Pro Server. Practically, this means it is the primary device's choice of file prefix/suffix that becomes the one that all other devices then have to work with.

Now: there's nothing to stop you declaring all your client devices as primary: Giocoso isn't keeping count and doesn't care if you arrange for every local device to upload its database scans to the Pro database. There's no harm in things working this way: if you've got your file suffixes and prefixes sorted out correctly across all devices then any device's updates won't disrupt the suffixes stored in the Pro database and thus won't break any other device's ability to play music. It would be a lot of unnecessary writing to the Pro database, of course, since whatever recordings one device discovers to exist will be exactly the same recordings that every other device would discover! But you could certainly configure things this way if you wanted. This again implies that, conceptually, all client devices are as equal as each other. Practically, however, it makes more sense to declare one device the sole primary device on the network: its music discoveries become the truth for all other devices and writes to the Pro database are therefore kept to a minimum. Other, non-primary, devices simply read the results of the primary device's work, but don't add to them.

Bear in mind, too: the Pro menu, Option 4: Push Recordings to remote database is there to allow any client device to push its local recordings table to the remote Pro Server database, under manual control. The 'primary-ness' of a device only affects whether it automatically pushes its recordings to the remote database every time it locally refreshes. It's also true that you can re-designate a primary device as a non-primary one, and promote a non-primary one to be primary as your needs and requirements dictate. It's not a set-and-forget option, incapable of modification.

But to the question that heads up this section, the answer is: yes and no, it depends! Conceptually, all devices are capable of being exactly equal to any other. Practically, however, it makes sense to declare one device to be a little more equal than the others, so that it's version of 'what music exists' is the one that the others use, rather than having to work it out for themselves.

6.0 Do Clients need a local database any more?

Since all clients, once Pro features are enabled, get their 'source of plays' from the Pro server; and since they write their 'history of plays' to the same Pro server, it's a reasonable question to ask whether or not the local Giocoso database is necessary any more on client devices. The answer to that is unequivocably: yes.

There are a number of reasons for this. First and most important: when a play concludes, as was mentioned in Section 3.0 above, the details of the play are first written to the local database and only then copied to the Pro one. If there is no local database, that first write would fail, messily.

Secondly, the Pro database is a summation or aggregation of multiple local databases, not a replacement for any of them. Thirdly, and related to the prior point: the network might go down and if it does, it should be possible to continue using Giocoso in local mode. Once connections to the Pro database are available again, fine: the stuff that took place locally should be push-able to the Pro database by way of catch-up (that's what the Pro menu, Option 2: Push plays to global database is for, after all). If there were no local record of plays made, that sort of catch-up wouldn't be possible; and if we instead said 'make the Pro database the only one that clients use', Giocoso would be rendered unusable the second the network or the Pro server itself failed. Putting point 3 in a different way, then: we don't want a single point of failure to render Giocoso unusable; having a local database we can read from and write to means we don't have to take that risk.

Finally, as has been mentioned previously, Pro mode is switchable: you can turn it off and on. If you didn't have a local database, you couldn't do that usefully.

So: in short, you must have a local database when you want to run in Pro mode. Get your local database created and populated first, and then turn on Pro mode to unlock the new features it provides, whilst still having a usable local installation should it prove necessary.

It is technically true that only one client device needs to do a scan for music files and thus populate the local recordings table, before pushing this to the Pro database. That's because all other clients will thereafter be told what music to play and what location it can be found in by the Pro database: a local recordings table is therefore not needed to perform that function (and one could be created easily enough should Pro-mode ever be turned off). But this 'lack of necessity' definitely does not extend to the local plays table. If you want to play music on a Giocoso client device, it must have access to a local plays table… which means a local database is a necessity, at all times.

7.0 Definition of Uniqueness

In Pro mode, the definition of a unique recording is the COMPOSER tag plus the COMPOSITION tag, conjoined: this is called the RECHASHVALUE. The definition of a unique play is COMPOSER+COMPOSITION+PLAY_DATE: this is called the PLAYHASHVALUE. In both cases, in Pro mode, the uniqueness of a composition or a recording are derived from the tag data stored within FLACs themselves. If you modify the composer or composition metadata associated with a FLAC after it has been added to your Giocoso database, then it will appear as a new recording when ultimately transferred across to the shared Pro database.

This is very different to the way old-school Giocoso (and current, but non-Pro, Giocoso) works. In non-Pro mode, it is the full path to a FLAC on the hard disk which defines uniqueness (called the DIRNAME in both the plays and the recordings tables). If you were to move a FLAC from a folder called /orchestral to one called /symphonic, for example, then this would look like a new FLAC to non-Pro Giocoso… but since the composer and composition tags didn't change, it won't look like a new recording to Giocoso in Pro mode.

The significance of this is that some Giocoso behaviours depend on the definition of 'what constitutes a unique recording'. If you are asking to play unplayed recordings, for example, then the test in non-Pro mode is 'does this recording's full path (i.e., DIRNAME) appear in the PLAYS table?' In Pro mode, however, the definition is 'does this recording's RECHASHVALUE appear in the GLOBAL_PLAYS table?'. Going back to that previous example, then, it becomes obvious that in non-Pro mode a physical move of a file will make Giocoso think the file is new and thus unplayed …but if neither the composer nor composition tags were modified, Giocoso running in Pro mode will know the file has been played before, because the physical move won't have changed the file's RECHASHVALUE. This means not only music selection can change between Pro and non-Pro modes (recordings one thinks are previously-played might look unplayed to the other) but the reporting on things like 'how many recordings are unplayed' will vary between the two modes, too.

8.0 Table and Column Definition Changes

In standard Giocoso, non-Pro mode, you would query the RECORDINGS and PLAYS tables. When Giocoso is running in Pro mode, however, you will query the almost-equivalent GLOBAL_RECORDINGS and GLOBAL_PLAYS tables. The GLOBAL_ tables are functionally equivalent to their non-global equivalents, but there are actually quite considerable internal differences between RECORDINGS/GLOBAL_RECORDINGS and PLAYS/GLOBAL_PLAYS, some of which have been mentioned above, but which I'll re-iterate here.

In RECORDINGS and PLAYS, every record is uniquely identified by an automatically-assigned ID number. Every new full scan of recordings (Database Management menu, Option 3) completely wipes the RECORDINGS table and potentially assigns different IDs to the same recording than it had before. Accordingly, the ID is really a meaningless piece of data in RECORDINGS (it is less volatile in the PLAYS table, however, since that is never wiped).

In GLOBAL_RECORDINGS, the unique identifier is RECHASHVALUE. This is an MD5 hash string which is directly derived from the COMPOSER and COMPOSITION metadata tags found within the digital music file itself. In the GLOBAL_PLAYS table, the unique identifier is PLAYHASHVALUE, which is another MD5 hash string derived directly from the COMPOSER and COMPOSITION tags, plus the date and time of the conclusion of the specific play. Since these hash values are derived from metadata, they are genuinely invariant unless the metadata associated with a digital music file is actually changed.

I've also already mentioned that non-Pro RECORDINGS and PLAYS tables used a column called DIRNAME to store the full path to the location of a digital music file; in Pro mode, the GLOBAL_RECORDINGS table has a column called FILESUFFIX and this stores only the device-independent part of the path that locates any given digital music file. The non-Pro PLAYS table also stores the DIRNAME when a play concludes: in Pro mode, the GLOBAL_PLAYS table merely stores the RECHASHVALUE of a recording, without any indication of the physical location of the file(s) just played. Both PLAYS and RECORDINGS and their Pro equivalents go on to store the GENRE, COMMENT, PERFORMER and DURATION of each recording or play, so there is no change there.

Finally, the GLOBAL_PLAYS table stores the name of the client device doing the music play, and the details of the operating system it is running, in columns called DEVICENAME and OS_TYPE. There are no equivalents of this data in non-Pro mode.

Being aware of these details is important when it comes to constructing Advanced SQL play requests (Play Music menu, Option 4) or Advanced SQL reports (Reports menu, Option 5). If, for example, you had previously wanted to play previously-played masses by Haydn, you might have submitted a query such as:

composer='Joseph Haydn' and genre='Choral' and composition like '%missa%' and dirname in (select dirname from plays)

In Pro mode, that same query would have to be re-written as:

composer='Joseph Haydn' and genre='Choral' and composition like '%missa%' and rechashvalue in (select rechashvalue from global_plays)

Note the change from testing 'dirname' to 'rechashvalue' and the change of table name from 'plays' to 'global_plays', for example. These changes are not applied automatically for you: there's a reason this stuff is called 'Pro'… you're deemed to understand what's needed to construct valid SQL statements!

9.0 Global Note-taking

Since Giocoso Version 3.12, it's been possible to tap the 'n' key as a recording plays and thereby open up a text document (called classical_music_notes.txt, stored in $HOME/.local/share/giocoso3/txt) where you can type in assorted notes and observations. This facility remains unchanged in Version 3.30, but if you switch on Pro features, the new 'Global Notes' feature is invoked instead.

“Global Notes” means that a new table is created in the Giocoso Pro database, called (somewhat unimaginatively!) GLOBAL_NOTES. It is queried when the 'n' key is tapped: either existing notes for the currently-playing recording are found in the global database, in which case they are opened in nano for editing; or no existing notes for the current recording are found, in which case nano is opened with a new document that is blank:

In either case, you can just start typing your notes and observations as before. You will note that the text wraps when needed, but not particularly nicely (see, for example, the way 'from the trumpets and drums' wraps in the above screenshot on line 3 of the main text): it is a basic text editor that's being used for its simplicity and ubiquity, not because it handles long lines of text particularly well! Once you're done writing, the edited text is saved (by pressing Ctrl+X) and, at that point, it is written back to the Pro database: no copy of the text is stored locally, at all. Once nano closes, Giocoso returns back to the 'now playing' screen, which continued to run in the background for as long as you were editing text.

Note that any local notes you may have made before enabling Pro features are not transferred across to the global database. They remain accessible in the local classical_music_notes.txt file, but transferring them across to the global database is a manual job.

The GLOBAL_NOTES table consists of only two columns: rechashvalue as the unique key, identifying the work for which the notes are provided; and notes -which is a long text field, accepting up to 4GB of input (which should be sufficient for most recordings, I think!)

Global notes can be viewed by taking the Pro menu, Option 8. Dialog screens display first all the composers for whom notes have ever been made; you select one and then every recording associated with that composer for which notes exist. You select one from the list and then the note text is displayed in a quasi-graphical form, like so:

Notes displayed in this way are read-only.

10.0 Global Pause and Resume

When Giocoso clients operate in 'Pro' mode, if music playback is ever paused, data about what recording was being listened to and the point to which playback had reached is written back to the Giocoso Pro database (into a table called GLOBAL_PAUSESTATUS). If playback is resumed on that original client device, the previously-created playstatus record is deleted. The playstatus table therefore only contains data about recordings that have been, and still are, paused.

Whilst playback remains paused on the first Pro client device, therefore, it's possible for another Giocoso Pro client device to use the contents of the playstatus table to start playback itself, of the same recording, from the point to which the first device had reached. Putting it as bluntly as I can: one device can resume a play that another device was in the middle of. Practically, this means that I can listen to a long opera on my headphones using my laptop in bed at night; hit the pause button when I think I'm too tired to continue; then in the morning, I can resume the opera from the point I'd reached but on the main listening room PC. The journey can be done in the other direction, too, of course: hit pause in the listening room, resume the playback once I'm safely in bed with the laptop at the ready.

The resumption is not perfect: Giocoso rounds things to whole seconds, so playback resumption might skip a fraction of unplayed music, or repeat a fraction of played music. The resumption on a second device also doesn't stop the original client device from thinking it's paused in the middle of playback: if you were to return to the original device, it will still think it's paused in the middle of whatever piece it had been playing. You can always simply hit the 'Terminate' option to deal with this, of course -though listening to a good opera second time round is no bad thing, either!

Pauses are device-specific. That is, the global_playstatus has three columns: the device that has paused, the recording it was in the middle of and the playback position it had reached. When a device wishes to resume a global play, therefore, it might be the case that multiple other devices have paused playback: we'll therefore need to know which paused device is to be 'taken over':

Note that if there's only one device is in pause mode, this 'prompt for a device' doesn't appear: the one and only device in pause mode is assumed to be the one you're trying to resume.

If the prompt for a device does appear, however, you simply use the up and down arrow keys to select the appropriate device name, then press [Space] to select a device and finally press [OK] to confirm the choice: playback then starts on the new device immediately. I trust it's obvious that a device can only play one piece of music at a time: therefore, only one piece of paused music can exist on (or 'for') a device at a time. Accordingly, by picking the device name in this dialog box, you've implicitly said what music you want to resume.

Resumed plays always start immediately: the usual 'countdown' of the number of 'seconds to wait before playback starts' (as configured in the Administration menu, Option 2) does not apply to resumed plays, because resumption is a deliberate one-time act that it's assumed you're in control of! That said, be warned that if you are resuming a 4 hour-long opera that you'd managed to get 3 hours into before pausing, the resuming machine will have to silent 'scan through' the entire opera (not in real time, I hasten to add!) in order to locate the resumption point correctly. That takes just a second or two when the resuming device has local access to music on a fast SSD; it can take over a minute if the resuming device has to pull music data over the network from a NAS, for example. So, when I say 'resumed plays always start immediately', I mean only that there's no deliberate 'countdown' but there may be a physically-imposed wait for the resuming device to work out where, precisely, play resumption should begin.

Attempting to perform a Global Resume when not operating in Pro mode results merely in the display of an error message explaining that resuming someone else's play requires Pro mode. Similarly, if you attempt to resume something when no other client device has paused playback, you'll simply see a message to this effect and nothing further will happen.

11.0 A Plan of Action

Switching over to running Giocoso in Pro mode can be a little awkward and one client device can trip things up for all the others if you're not careful. Here are a few guidelines for how to go about a successful Pro implementation:

Make every client device a proper non-Pro Giocoso device first. Create a local database and populate it with recordings from your collection. Make a few plays on that device, too, to ensure everything is working correctly in non-Pro mode first
Choose one device to be the primary client: the one that will be responsible for refreshing its own local database of recordings on a regular basis and then pushing that to the global database. Other clients then need to be set to be non-primary: their local database refreshes will still happen but won't be pushed to the global database
Make sure that the primary device's folder structure can be split into suitable prefix and suffix components that will work for all proposed client devices
Build a Giocoso Pro Server and ensure it's ready to accept client connections from across the network
Configure the MySQL IP address for all non-Pro clients that you wish to convert to Pro clients, along with appropriate Port, File Prefix and Primary flags in the Administration menu, Option 2.
Double-check the file prefix settings: are you sure that when applied to your music folder structure, they will correctly identify a physical location where that device can find the necessary FLAC files?
On the chosen primary device, use the Pro menu, Option 1: Initialise a remote Global Database to push the local recordings and plays tables across to the Pro server
On all the non-primary devices, use the Pro menu, Option 3: Push Plays to remote database to add their plays into the global_plays history: there's obviously no need to push their recordings to the Pro database, because they'll be the same as those already pushed by the primary device.

After that lot, you should be ready to run in Pro-mode in earnest: good luck!

12.0 MySQL or MariaDB?

Throughout this documentation, the database engine the Pro server uses will be called MySQL. However, in practice, nearly all Linux distros these days install a database engine called MariaDB, even if you explicitly ask to install MySQL: the two names are basically aliases of each other and are treated as such by nearly all mainstream Linux distros, with MariaDB being regarded as a 'drop in replacement' for MySQL. If you are not aware of the history, it might cause some confusion when I talk 'MySQL' and commands seem to talk 'mariadb'. The short version of that history, therefore, is that MySQL was an independently-developed and mostly open source database engine before being purchased by Solaris, who in turn got purchased by Oracle Corporation. Now, Oracle Corporation is not enamoured of open source projects and are renowned for being a corporate nightmare to have dealings with: I used to work for them and 'Orrible Oracle was a common enough epithet to hear thrown about by staff and customers alike!

Accordingly, the moment Oracle bought Solaris, the MySQL software was forked, which basically means 'copied and re-named and independently-developed thereafter'. The forked copy was called MariaDB. That's all perfectly legal to do in the world of open source software -and it meant that further development of MariaDB could be pursued without Oracle involvement. Thus, MySQL and MariaDB are no longer the identical copies of each other that they were immediately after the fork happened. Nevertheless, for the sort of functionality that Giocoso is making of MySQL/MariaDB, they can be considered equivalent, practically identical, database engines.

This then explains why most Linux distros (who prefer not to touch proprietary software with a bargepole, and who definitely don't want to be in Oracle Corporation's legal and licensing sights) have quietly aliased MySQL and MariaDB, such that if you ask for the one to be installed, you'll get the non-Oracle other instead.

This complex history needn't detain you for long: just know that the two names can, for the current purposes of Giocoso Pro, be used completely interchangeably. If I say 'start MySQL' the command to do that may well be to 'start MariaDB', but the results will be the same in either case.

Putting it simply, therefore, Giocoso Pro can be run on MySQL or MariaDB with equally successful results in either case: the code has been tested on both database platforms and functionality is identical on both.

However: you should not mix the products. If your Pro Server is running MySQL, your clients should also run MySQL; if it's running MariaDB, your clients should run MariaDB. Now, technically, it's true that I did test connecting one type of client to another type of server… and it all worked. But that's not a combination I'm ever going to test again, so it's emplhatically unsupported to mix products like that. On your own head be it, if you insist! Otherwise, for an easier life for everyone: one platform or the other, then, but not both, please!

Also note: Giocoso provides a number of scripts to get things done automatically. For example, to create a Pro Server, you can download a Pro Script which will do everything necessary for you. If you install Giocoso 3.30 using the gioinst script, things are also automated for you… and the point is that at all points of automation, Giocoso will automatically install and configure MariaDB, not MySQL. This can get quite serious: if you were to run the Pro automation script on a system that, say, is already running a webserver using MySQL, the Pro script will actually trigger the uninstallation of MySQL and its replacement by MariaDB! That is not a substitution that is likely to go well for you!

A separate article explains how you can manually set up a Giocoso Pro Server and Client using proper, Oracle MySQL -but the underlying point is that, though MySQL will work just fine, you must not do things automatically but should instead take manual charge of things.

| Back to Software Home | Back to Giocoso Documentation Home | Back to Pro Menu |

promdbchoice

Anonymous (anonymous@undisclosed.example.com) — 2025-12-10T11:05:23+00:00

Giocoso Pro On MySQL

1.0 Introduction

MySQL is a relational database. Around 2009, it was purchased by Oracle Corporation, which made it a licensing nightmare of a relational database, because Oracle Corporation is not a nice Corporation: Larry Ellison doesn't get to buy too many luxury yachts with niceness, I'm afraid. So, the code for MySQL was forked (i.e., copied) and thus was created MariaDB. MariaDB is practically identical to MySQL in functionality terms, though in the intervening 15+ years the two products have diverged in significant ways, too. Nevertheless, they are sufficiently identical that many database nerds use the name 'MySQL' when they, technically, ought to use 'MariaDB', and vice versa. This site and its Giocoso documentation is no exception: it will talk about 'MySQL' and expect you to mentally add the extra words 'or MariaDB'!

Giocoso Pro was, technically, written to work with MariaDB: running it using the 'proper' MySQL Oracle software was something of an afterthought …and I'd accordingly recommend that you stick to using MariaDB for both the Pro database server and the Giocoso client end of things. The main reason for that is: testing. I use MariaDB on real, varied hardware and therefore the Giocoso Pro code gets tested extensively in that environment. I have some virtual machines which run 'proper' Oracle MySQL: I test in those too, but nowhere near as frequently as I do for MariaDB installations, and on nowhere near as diverse a range of hardware.

So, my recommendation is: use MariaDB, client and server.

However, if you insist on using proper Oracle MySQL, you can definitely do so -though you need to use it on both Giocoso clients and the Pro server. You cannot use a MariaDB client with a MySQL server, nor a MariaDB server with a MySQL client. One family or the other is fine, but don't mix them!

The trouble these days with trying to use proper Oracle MySQL is that most distros will automatically install MariaDB software components if you mention MySQL: they alias the two product names and proceed to install the free, open source, license-complications-free MariaDB despite you explicitly asking to install the Oracle-laden one Worse, if you run the usual Giocoso installation or upgrade scripts after you've installed the proper MySQL software, you'll usually find that the MySQL stuff is auto-deleted and replaced by MariaDB equivalents, because that's what most distro's package managers are programmed to do. If you insist on using proper MySQL, therefore, you'll need to do things manually -which is what the following steps achieve.

I've written the following steps using Ubuntu and Debian-based distros, but they should be generally applicable to all other distros, provided only that you replace the 'sudo apt' commands with the equivalent package manager command for your distro (e.g., sudo dnf for Fedora, sudo zypper for OpenSuse and so on). Refer to your distro's specific documentation for variations in package names, too.

2.0 MySQL Server

The Giocoso Pro server is built on MariaDB by running a script downloadable from this site, and everything gets automated for you. Doing it with proper MySQL, however, is an entirely manual affair. To start with, you bring your distro up-to-date and then install the MySQL Server package, like so:

sudo apt update
sudo apt install mysql-server

Once that has been installed, you need to perform some configuration steps to make the database server accessible across the network, like so:

sudo nano /etc/mysql/mysql.conf.d/mysqld.cnf

In the nano text editor, scroll around until you find the entry for bind-address and set it to the IP address of the server itself (which can be determined with the command ip addr). Here's me doing it for an Ubuntu box:

The right-hand terminal shows you the IP address of this server is 192.168.137.147. You then see me editing the mysqld.cnf file in the left-hand window, setting the bind-address to that IP address. Save the file: to have the changes picked up, you then need to restart the MySQL server daemon:

sudo systemctl daemon-reload
sudo systemctl restart mysql.service

Next, we make the installation a little more secure than it is by default by issuing the command:

sudo mysql_secure_installation

You are prompted with various questions, to which you should supply the following answers:

n (implement password validation)
y (remove anonymous users)
y (disallow remote root logins)
y (remove test database)
y (reload privileges)

Next, we need a firewall that allows MySQL database traffic but blocks everything else. Issue the commands:

sudo ufw default deny incoming
sudo ufw default allow outgoing
sudo ufw allow 3306/tcp
sudo ufw enable
sudo systemctl enable mysql.service

And finally, you then need to create the tables and user that Giocoso clients will expect to exist before they can connect to the new server:

sudo /usr/bin/mysql -e "create database giocoso3 character set = 'utf8mb4' collate = 'utf8mb4_general_ci'"
sudo /usr/bin/mysql -e "create user 'giocoso3'@'localhost' identified by 'giocoso3'"
sudo /usr/bin/mysql -e "create user 'giocoso3'@'%' identified by 'giocoso3'"
sudo /usr/bin/mysql -e "grant all on *.* to 'giocoso3'@'localhost'"
sudo /usr/bin/mysql -e "grant all on *.* to 'giocoso3'@'%'"
sudo /usr/bin/mysql -e "flush privileges"

At this point, you've got a proper, Oracle MySQL database server ready to offer services to Giocoso clients.

3.0 MySQL on the Giocoso Client Device

The simplest way to get a Giocoso Pro client using MySQL is to install Giocoso as normal: that triggers the automatic installation of the MariaDB client, but removing that and replacing it with the Oracle MySQL software is relatively straightforward, as follows:

Install or upgrade to Giocoso 3.30 in the normal way. For installation, the commands would be:

wget https://bbritten.com/gioinst
bash gioinst

Once that's done, removal of the auto-installed MariaDB components and their replacement with Oracle MySQL ones is done as follows:

sudo apt remove mariadb-client mariadb-client-core
wget https://dev.mysql.com/get/mysql-apt-config_0.8.30-1_all.deb
sudo dpkg -i mysql-apt-config_0.8.30-1_all.deb

That last command triggers this sort of response:

Arrow up and down each item in the main list, pressing Enter to select it and change it. You want to end up with the selections: mysql-8.0, MySQL Tools enabled and MySQL Preview enabled (though the last one can be disabled without consequence).

Once those three values are visible in the main list, arrow down to the 'OK' item in the main list and press [Enter] to confirm. This will take you back to the command prompt, where you then type:

sudo apt update
sudo apt install mysql-client

At this point, your distro is running 'proper' MySQL and you can proceed to enable Pro functionality within Giocoso itself as normal (i.e., take the Administration menu, Option 2 and set the 'MySQL IP address' to the IP address of the MySQL Server you prepared in Section 2 above). Use of Giocoso Pro functionality is standard fare from that point on.

| Back to Software Home | Back to Giocoso Documentation Home | Back to Pro Menu |

promenu

Anonymous (anonymous@undisclosed.example.com) — 2025-12-10T14:58:47+00:00

The Pro Menu

“Giocoso Pro” is the name given to a set of features that allows a local Giocoso installation to communicate with a remote MySQL database -and thus share its own play history with that of other devices who were running Giocoso. In this way, statistics would accurately reflect what was being played on all Giocoso devices, not just one. Similarly, you could make notes about a recording on a laptop and then review them later on a PC: data again being shared between devices, thanks to storing it in a common, shared database that all clients could access equally well.

Switching 'Pro Mode' on involves editing your Persistent Configuration File (see the Administration menu, Option 2) and filling in the IP address of the remote Giocoso Pro server to which all client devices will send their play histories. Only when you've switched on Pro mode in this way will the Pro menu appear on the main program interface.

The Pro menu thus handles what you do after taking those two first steps of Giocoso Pro Server creation and client-Pro Mode-switch-on. Putting it simply, four of the Pro menu options are all to do with pushing a local client's data to the remote Pro server, so that it comes to know about previous plays and what recordings are available to play in the future. Other options generate reports or data extracts from the remote Pro database. Another option allows you to view notes about recordings that may have been created on multiple Giocoso clients. Finally, there's an option to switch the operation of the Reports menu from purely-local to purely-remote mode: when you run the aggregate statistics report, for example, do you want to see the statistics that only this PC has generated, or do you want to see the ones that all your Giocoso devices produce when aggregated? You can flip back and forth between either reporting mode, as the mood takes you.

The Pro menu therefore is important in initiating Giocoso running in shared-database, Pro mode. It also has a couple of potentially useful features that only make sense once that shared-database environment has been created. Links to a detailed description of each menu option are listed below:

Initialise a remote Global Database

Push Plays to a remote database

Clear the remote recordings table

Push Recordings to a remote database

Extract remote plays to CSV

Extract remote recordings to CSV

Analyse plays by device & OS

View a global note

Switch reports to local/remote mode

Clear all global pauses

| Back to Software Home | Back to Giocoso Documentation Home |

pulseaudio

Anonymous (anonymous@undisclosed.example.com) — 2026-03-14T18:40:22+00:00

PulseAudio

1.0 Introduction

PulseAudio is a fairly complex and potentially abstruse feature of most Linux distros (including when running under Windows Subsystem for Linux) and macOS. You can read about it at exhaustive length here, but the really high-level overview is this: PulseAudio is to audio what X is to video. Allow me to explain!

An application wants to draw its main program window on a screen, so you can interact with it. Using the X Server technology, the application is an “X Client”: it wants to draw itself. To do so, it must find an “X Server”: a PC which happens to have a monitor or screen attached, on which things can be drawn. Most commonly, the X client and server run on the same PC: so you click the Calc icon and LibreOffice Calc launches and draws its main screen on the same PC where you clicked the launch icon. From the outset, however, the X developers recognised that wouldn't always be true: if you're sat at a weedy Raspberry Pi 3, you really don't want LibreOffice laboriously launching itself on that feeble computer. You'll be there 'till Christmas! No: ssh to a really powerful PC running in your home server room under the stairs and have Calc run on that server… but pass its interface drawing instructions to your Pi desktop. The X client is the machine under the stairs, powerful and capable; the X server is your Raspberry Pi, able to draw things on a monitor but not much else. In this way, X made wanting to draw and being able to draw separate things that can be separated over a network connection: you can interact with a thin-client Pi, but the powerful PC under the stairs can be doing all the calculating and computational heavy lifting.

Well: PulseAudio is the same, but for audio. Your PulseAudio client is a program that wants to output audio; the PulseAudio Server is a computer that has a set of loudspeakers attached, able to 'sound' that audio. Generally, we expect client and server to be running on the same physical PC, but the protocol was invented to allow the client and the server to be entirely separate machines, communicating over a network.

Giocoso can use PulseAudio. It's a lightweight program, but it has to do quite a bit of computation and processing to generate an audio stream: that requires a reasonably capable PC. To 'sound' that audio stream, however, only requires a weak and feeble computer that happens to be attached to some sort of loudspeaker output (or headphone or bluetooth output, etc.) Thus, the machine on which Giocoso runs will be a PulseAudio client and the machine which makes the audio stream physically audible will be the PulseAudio server …and those could be two completely separate computing devices.

What's more, a single PulseAudio client could direct its output to multiple PulseAudio servers. Think of a decent PC running under the stairs that is able to output music to a feeble Raspberry Pi running in your conservatory one minute, your kitchen the next, your bedroom sometime later that evening and your main listening room during the afternoon. Without PulseAudio, your conservatory, kitchen, bedroom and listening room would all need their own hefty PCs, each running Giocoso. With PulseAudio, you set up one capable PC with Giocoso, once; you can then direct its audio output to small computing devices in each of those rooms as your needs arise. You'll still need speakers in each of those rooms, of course: audio doesn't manifest itself from nothing! But you could, for example, hook a Raspberry Pi up to a small Bluetooth speaker in each of the rooms, rather than a full-blown PC plus monitor plus keyboard plus amplifier plus speaker.

PulseAudio allows for computing devices to sound forth the audio stream: headless, keyboardless, small and discreet; the need for substantial computers with keyboard, mouse, monitor and speakers is eliminated (unless you want that sort of setup everywhere, of course).

In this article, I'll explain how I use a virtual Giocoso installation on a server hidden in the corners of my house to play music to any room I happen to be in: it all depends on PulseAudio!

[Under Construction]

replaygain

Anonymous (anonymous@undisclosed.example.com) — 2026-01-26T09:53:57+00:00

Giocoso and ReplayGain

1.0 Introduction

ReplayGain (the Camel Case spelling is obligatory, I'm afraid!) is a standard developed back around 2001/2002 as a way of normalizing 'perceived loudness' when playing back digital music files. In essence, the aim was to have all the tracks on an album play back at around the same sort of volume level so that you weren't constantly fiddling with the volume control on your amplifier. It was cooked up, originally, by Joachim Heintz and Florian Fricke, primarily for use with MP3 and Ogg Vorbis file formats, but it soon spread to other audio codecs and can be employed perfectly well by FLAC players, too.

The traditional way of normalising volume was to scan through your audio files and discover their peak loudness: if that was significantly below 0dB (the traditional way of describing maximum, non-distorting volume) you would boost the volume in your audio file until it did reach 0dB, or close to it. This is, indeed, the way Semplice did all its volume boosting for the best part of half a decade. It's still a valid way of doing it but, because it's driving off transitory bursts of volume, it might leave 'volume on the table' as it were. A quiet piece with fleeting seconds of loud cymbal crashes would remain extremely quiet, because those crashes would leave little room for much volume boosting.

ReplayGain uses ~~black magic~~ clever acoustic analysis to analyze the overall 'perceptual loudness' of a track, rather than concerning itself with transient peaks. It computes a volume boost sufficient to bring the overall loudness up to a reference loudness of 89dB. The effect is basically the same: your music volumes get adjusted so that you don't have to keep fiddling with the volume knob on your amplifier, but it's done in a subtler way than peak-driven boosting.

ReplayGain can be done on a per-track basis, or on a per-album basis. That is, given a four movement symphony, comprising four separate FLAC files, do you want to do a perceptual analysis of each movement separately, resulting in four different volume boosts? Or would you rather treat the four FLACs as part of a single entity and compute a single boost to get the symphony as a whole to a desired loudness level? I hope it's obvious that in the world of classical music, per-track ReplayGain would be a disaster! You do not want your quiet movements being boosted a lot and ending up as loud as your loud finales! Be assured, therefore, that when Giocoso uses ReplayGain it only ever does whole-album ReplayGain: each recording (i.e., composition and thus physical folder of FLACs) is always treated as a single, whole entity.

The danger with album-wide ReplayGain is that you boost quite a bit to get the symphony as a whole playing at a perceived 89dB… but those darn'd cymbal crashes still take place and spike wildly above the point where distortion kicks in! If you simply let the ReplayGain tide rise and float all boats, some transient 'masts' are going to rise to the point where they'll hit the bridge above them There is a way to fix this, though: in the trade it's called “doing ReplayGain but avoiding clipping”. Over-simplifying greatly, having determined that you can boost a recording's volume by (say) 4dB to achieve an overall, album-wide gain, you then scale it back a bit to prevent transients exceeding the no-distortion threshold. There's actually a formula for computing this properly (brace yourself!):

safe_gain_dB=ALBUM_GAIN−20⋅log10(ALBUM_PEAK)

Be assured that Giocoso computes all that for you in the background whenever a recording begins to play, if you configure it to do so (see below). It means that Giocoso has the same sort of 'Album-wide ReplayGain without clipping“ that players like Foobar2000 can use.

One final word: sometimes, recording engineers master their recordings at exceedingly low levels for a reason. Usually, that reason has something to do with background noise which is mostly drowned out by music in the foreground but which would become noticeable if everything got volume boosted by a lot. I have several recordings in my collection that were made in Kingsway Hall, which happened to be right next to a London tube line (subway): at quiet moments in the music, there's a distinct rumble of a train passing in the background! Boost the volume of that recording and the rumble becomes extremely noticeable; left at the level provided on the CD, you probably wouldn't notice it unless wearing headphones. Another recording I have is of organ music played in Norwich Cathedral, mastered at an extraordinary -21dB. Boost that to near 0dB and you soon realise that the Cathedral must have remained open for the duration of the recording, because footsteps and people shuffling and coughing their way around the place are extremely annoying. Down at the original -21dB, however, and it's just a boomy, Cathedral acoustic that you can hear which doesn't interfere with the thunderous organ in the foreground at all. All of which is by way of saying that sometimes you don't want an enormous ReplayGain, even if the analysis and statistics suggest one is required in theory. Accordingly, Giocoso imposes an absolute limit of a +7.5dB ReplayGain: even if the numbers say a bigger boost should be possible, Giocoso won't allow one to take place.

In Summary: ReplayGain is a useful technology for making quiet music louder in a way that preserves the relative volume differences within a composition, which is psychoacoustically rigorous and justified, which is limited on the up-side to prevent over-boosting of quiet recordings and which will not introduce clipping or distortion when applied. And Giocoso supports using it -though it's optional.

Configuring Giocoso to use ReplayGain

Giocoso does not use ReplayGain by default. For it to do so, you need to take the Administration menu, Option 2 to modify your persistent configuration file:

This is the fourth (and last) page of configuration options and the relevant parameter is the last one shown: Use ReplayGain if appropriate tags present. By default, that's set to a value of “no” but setting it to “yes” effectively 'switches on' ReplayGain playback. Sort of!

The issue is that Giocoso's ReplayGain 'engine' needs, as the parameter name indicates, some sort of 'tags [to be] present' before it can do anything. These are the tags in question:

There are five 'canonical' ReplayGain metadata tags that need to be physically written into your FLAC files:

Reference Loudness (always 89dB)
computed Track Peak transients
computed Track Gain volume adjustment
computed Album Peak transients
computed Album Gain volume adjustment

The computation of the numeric tag values has to be done as part of an analysis of your digital music files: it's something that my own Semplice program can be configured to do as part of its volume boosting capabilities, for example. Some CD rippers compute the data and write it into tags at the point of ripping the files off a CD, too. The point is that if you haven't done that sort of audio analysis and tag-writing, then switching the Giocoso parameter to use ReplayGain will have no effect:

The 'ReplayGain Applied = none' data shown in the lower left-hand corner of the program display is what happens when the canonical ReplayGain tags are not present as tags within the FLACs being played, even though the configuration option says that ReplayGain ought to be in use. It's also what you'll get if the tags are present but they're set to null values, by the way.

When the tags are present, with non-empty values and the Giocoso parameter is set to use ReplayGain, you'll instead see something like this:

This time, you'll see that a numeric ReplayGain has been applied, dynamically and in real-time, to the music being played back. You'll notice that in this specific case, a negative ReplayGain has been applied: the playback is being made at around 2.27dB quieter than the audio signal in the FLACs is actually stored at. That's perfectly valid and isn't a sign of anything wrong. If you're interested, it happens for me quite a bit because I used Semplice's other volume boosting technique of maximising to peak values: a lot of my recordings are thus physically rather loud in absolute terms (still without distortion, I hasten to add). ReplayGain being applied to such physically-boosted FLACs tends to find them too loud and adjusts downwards accordingly. Were I to rip a 1980s classical music CD today, without applying a Semplice physical (peak-driven) boost, it's almost certain that the displayed ReplayGain value would be a positive one.

Another little detail you'll see in that last screenshot, too: the volume change is shown as -2.27 dB~. That little squiggle after the numeric value tells you that clipping avoidance has been activated: that's Giocoso's way of saying that in achieving a 'reference' perceived loudness, it's taken care to ensure that transient loud spikes in volume won't trigger clipping: it has applied a 'safety margin' to the boost to prevent it.

If it ever happens that Giocoso can apply an album-level boost without needing to apply clipping protection, that last character will be a simple . and not a ~. That is, a period/fullstop indicates no clipping protection was needed, but a cedilla indicates that it was.

3.0 Retro-fitting ReplayGain

I've come pretty late to ReplayGain but have found that when it's being used by Giocoso, the results have been pleasing. Trouble is, I've been doing peak-level volume boosts for years and therefore none of my approximately 17,000 recordings have had ReplayGain computed for them: what I need, therefore, is a way of batch-updating my music files to add ReplayGain in a hurry.

Here's the script I used to do that:

clear
sqlite3 "$HOME/.local/share/giocoso3/db/test.db" "select dirname from recordings order by composer" > "directories.txt"
tput civis

# File containing the list of directories
DIRFILE="directories.txt"

# Initialize counters
GAINCOUNTER=0
SKIPCOUNTER=0

# Loop through each line of the file
while IFS= read -r dirname || [[ -n "$dirname" ]]; do

  # Change into the directory
  cd "$dirname" || { echo "Failed to cd into $dirname"; continue; }

  FLACFILE=$(find "$(pwd)" -name "*.flac" | sort | head -n 1)
  DISPLAYFLAC="${FLACFILE#/*/*/*/*/}"; DISPLAYFLACFILE="$(basename "$DISPLAYFLAC")"; DISPLAYFLACFILE=${DISPLAYFLACFILE:0:98}
  DISPLAYPATH="$(dirname "$DISPLAYFLAC")"; DISPLAYPATH=${DISPLAYPATH:0:98}
  GAIN=$(metaflac --show-tag=REPLAYGAIN_ALBUM_GAIN "$FLACFILE" 2>/dev/null | cut -d= -f2)
  tput cup 2 54; echo -n "ReplayGain Computed: $GAINCOUNTER - Skipped: $SKIPCOUNTER"
  if [[ -z "$GAIN" ]]; then
      tput cup 6 2; printf '%*s' 98 ''; tput cup 6 2; echo -n "$DISPLAYPATH"
      tput cup 7 2; printf '%*s' 98 ''; tput cup 7 2; echo -n "$DISPLAYFLACFILE"
      echo "$FLACFILE" >> "$HOME/Desktop/adjusted.txt"
      metaflac --add-replay-gain *.flac 2>/dev/null 
      ((GAINCOUNTER++))    
  else
      tput cup 6 2; printf '%*s' 98 ''; tput cup 6 2; echo -n "$DISPLAYPATH"
      tput cup 7 2; printf '%*s' 98 ''; tput cup 7 2; echo -n "$DISPLAYFLACFILE"
      ((SKIPCOUNTER++)) 
  fi
done < "$DIRFILE"
tput civvis

The code depends on Giocoso having been installed and a local, non-Pro database of all your music files being in existence. The line reading “sqlite3…” is the code needed to open that database for reading: obviously, you'd need to replace the “test.db” with whatever database name you're actually using.

Otherwise, the code simply queries the local database and extracts a list of folders containing FLACs from it, into a text file called “directories.txt”, stored in whatever folder you're in when you launch this script.

It then loops through each line of that text file. It cd's to each folder in turn. It checks to see if ReplayGain has been previously computed or not: if it has, it simply skips doing anything further and merely increments a 'skipped' counter. If it hasn't, though, it analyses all the FLACs in that folder and writes the newly-computed REPLAYGAIN_* tags back to the FLACs and increments a 'Gain Applied' counter. It also writes the name of the FLACs for which it has modified the metadata into an 'adjusted.txt' on your Desktop.

You save that code into a file called, say, “applyreplaygain.sh” on your Desktop. In a terminal, you then type:

cd
cd Desktop
chmod +x applyreplaygain.sh
./applyreplaygain.sh

…and then leave the thing to chug away for however long it takes to process your collection. It's output is not pretty and isn't meant to be: this is not something you'll be running routinely!

You can run the script multiple times though: if you let it complete the first time, then the second time you run it, there should be nothing to do and you'll get all skips and no gains applied. That isn't actually what happened to me, though: I had three files that kept coming up time and time again as needing gain applied. The fact that gain failed to be written back to the files the first time of asking indicated that something was internally amiss with those files (knowing which files had this problem is when the “adjusted.txt” file becomes handy). A re-rip of the three CDs in question then fixed the problem.

I don't generally approve of bulk updating of anything to do with my music collection: the risks of something going horribly wrong are too awful to contemplate. I made an exception for this only because the script is simply adding the five ReplayGain tags to the files and not messing with any other metadata or with the audio signal: it's thus (a) safe; and (b) reversible. I still made sure my backup was fully updated before I began, though: and I strongly recommend you do likewise!

4.0 Final Thoughts on ReplayGain

There are differing views on the utility and effectiveness of ReplayGain. Some people love it, as it allows you to achieve a sort-of 'average, overall loudness' in a listening session, without having to fiddle with volume controls all the time. Some people find it ineffective. And some people hate it, preferring the peak-driven loudness boost approach instead, because that just makes everything louder without fancy psychoacoustic modelling mucking things up!

That's why the use of ReplayGain in Giocoso is optional: even if the ReplayGain tags are there and assigned real values, Giocoso's default behaviour is to ignore them and to just play the audio signal as it comes straight out of the FLAC files. The configuration option is there to make it easy to switch on the use of ReplayGain if you want to give it a go, though (provided you've previously done the analysis and tag-writing in other software first, of course).

I should mention, however, that once switched on, ReplayGain stays on until you switch it off in the configuration options: you cannot flick it on and off as a piece of music plays, for example, to compare the 'before' and 'after' volumes. The way Giocoso is written, that sort of on/off mechanism is simply not physically possible.

To my mind, it's very clever and has the great advantage of not messing with the actual audio signal you ripped off a CD or SACD. The adjustment to playback volume is handled by the player, dynamically, not by altering the audio data directly or physically. It's therefore reversible (i.e., just switch it on or off in the configuration options as the mood takes you), where physically boosting the volume of a FLAC by measuring its peak loudness and getting the peak as close to 0dB as you can is an irreversible alteration of the audio signal itself. If you care about reversibility and pristine data preservation, ReplayGain has a lot to offer, I think.

rptmenu

Anonymous (anonymous@undisclosed.example.com) — 2026-02-21T11:26:43+00:00

The Reporting Menu

Giocoso stores data about what recordings are available and what recordings have been played in a database. If you are using Giocoso in 'Global mode' because you've enabled Giocoso's “Pro” features, those two tables are, respectively, GLOBAL_RECORDINGS and GLOBAL_PLAYS. If you are using Giocoso only in 'Local mode', they are called just RECORDINGS and PLAYS. You'll know which reporting mode you're running in by looking at the top of the screen for any Giocoso reporting option:

The 'Reporting in GLOBAL mode' you see in this screenshot will instead read 'Reporting in LOCAL mode' if that's the mode you're using. Whichever mode you're using, this pair of recording/plays tables can be queried to generate reports. Production of any report is entirely non-destructive: reports show you what data exists, but cannot themselves delete or alter that data. Therefore, they are perfectly safe to experiment with -and I accordingly don't propose to go through each reporting menu option in detail. Try them out, see if the data is of use to you and if not, move on!

Here, then, I'll mention some specific features of all reports, before describing Option 4 (the 'advanced reporting' option) in some detail.

General Report Behaviour

All Giocoso reports will be displayed as HTML documents in a web browser/viewer of some sort. Which browser or viewer gets used to display data is configurable via the Administration menu, Option 2:

Here, I've set the Firefox browser to be my report viewer. I could type in any browser name that is already installed on my system: Giocoso won't check it actually exists, install it for you or even check that you've typed the name correctly. It does, however, force the installation of the w3m terminal-based browser as some sort of fallback (and for fans of things staying in a terminal environment!) If you leave this setting blank (which is actually the default), Giocoso will use whatever your system's default browser has been set to. On many Linux distros, that will be Firefox; on macOS it might be Safari.

In short: leave the setting blank to get your system's default browser; or specify the name of a preferred 'reporting browser'; or type in w3m to use an in-terminal report viewer.

Having set (or left to defaults) as report-viewing browser, all of Giocoso's reports will then appear as follows:

Or, depending on your preferred browser settings, the same data might look like this:

That's the difference between setting 'firefox' and 'w3m' as the preferred browser! In all cases, an attempt has been made to make the data look 'reasonably presentable' in CSS, but the width of certain columns may necessitate a bit of manual window re-sizing before you are satisfied with the results.

Once you can see a report in a browser, you can export it to a PDF file (or print it to paper!) using your browser's standard menu options.

Advanced Reporting by SQL

The Reporting menu Option 5 presents a blank text box to you:

In this text box, you can type any valid SQL select statement. Keywords such as 'update', 'insert' and 'delete' are stripped from any input you provide, so this cannot be used to modify the contents of the Giocoso database, but if you know how to write a SQL select statement, this window lets you submit it and have its results returned to you.

This is not the place to teach you how to write correct SQL, of course, but the simplest construction possible is always in the form of: select something from somewhere. The 'something' is a comma-separated list of column names, and the 'somewhere' is the name of a table. So, for example: select composition from recordings which yields this result:

…at which point you suddenly decide that it might be useful to know who composed each recording:

…and so a modified version of the query, with the extra column inserted into the 'something' part of the query can be re-run, with the modified results displayed.

You maybe look at that and think 'the output appears to be in no particular order, but I prefered the original 'composition-name' order. So, you need to add an instruction to order by something, too:

…and now the rows of the report list compositions that start with punctuation, before those that start with a number, before those that start with standard letters.

Of course, queries can also include aggregation and grouping. So, for example, it's possible to look at all the RECORDINGS, group by composer and sum the total duration of each composer's recordings, like so:

Note how complex queries can be broken up so that consist of multiple lines: Giocoso is happy to handle multi-line queries in this way, fortunately!

Remember: this functionality can be run against a local database, or a remote 'Pro' one… but if you're querying a Pro database, you'll need to use GLOBAL_RECORDINGS and GLOBAL_PLAYS table names, not just RECORDINGS and PLAYS. Fortunately, however, Giocoso is not stupid: it knows what sort of table name you're supposed to query in the appropriate local or global context: it will therefore automatically re-write your query if you happen to query PLAYS when you meant to query GLOBAL_PLAYS or vice versa (and the same is true for when you query RECORDINGS rather than GLOBAL_RECORDINGS). For all practical purposes, therefore, you can simply 'select from plays' and 'select from recordings' without having to worry about whether those are the technically correct names to be querying at any given time!

Be aware that this 'Advanced Reporting' functionality is not a replacement for a dedicated database querying tool, such as sqlitebrowser or DBeaver. It provides a minimal level of functionality, enabling you to knock together complex reports relatively easily, but it doesn't do syntax checking and if your logic is wrong, you may well end up viewing reports like this:

That is, nicely formatted HTML pages with absolutely no data on them! If you look closely at the foot of this report you'll see why this report is blank: the query submitted said “slect” not “select”: Giocoso won't save you from such typographical howlers!

It will, however, strip out any mention of the words “delete” or “update” in your queries. This is a tool for viewing data, not for modifying it!

Report Mode Switching

It is entirely possible that you run Giocoso in Pro mode for day to day use, but suddenly get the urge to query the local database for its own, unique plays (for example).

Should you ever wish to do this, a toggle switch is provided under the Pro menu, Option 9. Obviously, being a Pro menu option, you'll only ever see this option if you've filled in the IP address of your remote Giocoso Pro server (using the Administration menu, Option 2). Doing that means, by definition, that you're now running Giocoso in Pro mode.

At that point, Option 9 on the Pro menu will read, “Switch reports to local mode”. Taking that option will then immediately throw you onto the Reporting menu: anything you now report on will be from the local database only:

At the top of the terminal window in this screenshot, you'll see Giocoso declaring that it's “Using database Main & Pro”… so we're definitely in Pro mode… and yet, at the top of the report being displayed in the browser window, we see we're reporting the “Aggregate Statistics for local database 'main'”.

You'll stay in local reporting mode until you either quit Giocoso completely and re-launch it; or until you re-visit the Pro menu and once again take Option 9… which will now be reading “Switch reports to global mode”.

Since the option to switch reporting modes only exists under the Pro menu, I hope it's obvious that you cannot take a local-only Giocoso instance and switch it into reporting globally (because the entire Pro menu is invisible to Giocoso instances running in non-Pro mode).

Browsing the Database with a GUI

A final data querying tool is made accessible by the Reporting menu: browsing the local database in a GUI tool, called SqliteBrowser. Note that this tool is nothing to do with Giocoso and Giocoso doesn't install it as part of its own installation routine. It's a third-party tool produced to make working with Sqlite databases easy which you can install yourself, if you would like to -but it's entirely optional to do so. If you don't install it, then you can tap the 'B' key (or the 'b' key: case doesn't matter) whilst sitting on the Reporting menu until the cows come home: nothing will happen. But if it is installed, then tapping 'B' will produce this sort of response:

A new window opens in which the Sqlite Browser program runs: notice from the window's title bar that it has opened the local database sitting on my hard drive, even though I'm allegedly in GLOBAL reporting mode, according to Giocoso. This is an inherent limitation: it doesn't matter whether you're running in Pro or Local mode, Sqlitebrowser can only query local, sqlite databases (not the MySQL database that a Pro database consists of).

I will not spend time here explaining how to use the Sqlite Browser tool itself: it's an advanced tool and you should only really use it if you know what you're doing… and if you know what you're doing, you don't need me to teach you! Just be warned: the 'browser' has full read and write access to the local Giocoso database, so if you want to use it to edit or delete data, you can do so. If you really wanted to, you can use it to completely screw around with your Giocoso local database and make it unusable… but I wouldn't advise it. It's a dangerous tools in incompetent hands, therefore… but also a very useful one in competent ones!

Incidentally, if you are in Global mode and wanted an equivalent (and equivalently dangerous!) GUI tool for working with the MySQL/MariaDB global database, I can recommend DBeaver, which has the same sort of querying and modifying tools for all sorts of databases, but especially for the type that Giocoso Pro uses. It's again not something Giocoso ever installs for you, but it's available in most distro's standard package repositories, so shouldn't be difficult to install (sudo apt install dbeaver will do it on Debian/Ubuntu for example). No shortcut to launch DBeaver from within Giocoso is provided, however: running it and getting it to open the Giocoso Pro database is a matter left entirely to your own database administration skills!

A Quick Word about Safari

I should mention that there is a known issue with using Safari as the report viewer on macOS:

You'll note that whilst there's nothing wrong with the report data, the header presentation is a bit 'off': next to the report title, there's supposed to be a thumbnail image of the Giocoso logo. There will always be such a logo on reports viewed in Firefox, Chromium and other common browsers. Safari, however, is very much part of the Apple security ecosystem and it doesn't like displaying images from just any random folder on your hard disk, even if it's inside your own home folder. There's nothing to be done about this until Apple allows us to configure security exceptions for Safari, so it's a feature, not a bug in the meantime!

Some Other Browser "Issues"!

Finally, be aware that on macOS, launching some browsers involve calling them by a name that has spaces in it. The Brave browser, for example, is launched by calling Brave Browser, capital letters and spaces included. If you need to launch a browser that uses spaces in its executable name, you need to quote the parameter in the configuration file, like so:

If you fail to provide the quotes, the reports will open in the system's default browser (which might be Brave Browser anyway, I suppose). Quotes are not necessary if you are using a browser whose 'launch name' does not include spaces.

| Back to Software Home | Back to Giocoso Documentation Home |

troubleshoot

Anonymous (anonymous@undisclosed.example.com) — 2025-12-10T18:24:23+00:00

Troubleshooting

Here I'll list issues I come across myself when using Giocoso or which others notify me about and that I can reproduce. If I've been able to identify any solutions or workarounds, I'll document them here too.

Q. I'm running Giocoso on Ubuntu and whenever music starts playing, I see an error message along the lines of 'invalid date @-nan'. What's wrong?

A. Confirmed. It's not a problem with Giocoso as such, but a known bug with certain versions of Bash on Ubuntu. See this Ubuntu support page for an overview. Giocoso rounds a recording's duration from fractional to whole seconds. For example, if a recording actually lasts 306.89 seconds, Giocoso will round that to be a duration of 307 seconds. To do the rounding, it uses the 'printf' built-in function, and until January 2025, there was a known bug whereby printf would return the text '-nan' instead of the actual numeric answer, on certain versions of Ubuntu 24.x. That bug was fixed at the end of January 2025, so if you update your system now (February 3rd 2025 at the time of writing), you should get the corrected version of printf installed: and this returns the correct numeric value. If you can't upgrade, music will still play as normal, but the 'Played x of y' and 'Ending at…' displays won't be correct, as there will be no valid computation of a duration for the recording and hence no possible computation of an end-time for the play can be made. You will also still see error messages, of course. Version 3.30 of Giocoso makes sure that if the rounding function ever errors again for similar reasons, you at least won't see the distracting error messages.

Q. Sometimes, when new music starts playing, the program display area shows a message along the lines of "convert-im6.q16: CorruptImageProfile `.../giocoso3/art/albumart.jpg' (XMP) @ warning /profile.c/ValidateXMPProfile/1675." What does that mean? And what can I do to stop that appearing?

A. Confirmed as an issue:

The issue is not, technically, Giocoso's but to do with ImageMagick, the tool Giocoso relies on to do image processing. It has all sorts of policies regarding who is allowed to convert images, how big they can be and how much memory they are allowed to take up, for example. It is possible that the artwork you've associated with particular recordings is too big or has internal issues that don't manifest themselves in visual artefacts. The image in the above screenshot was a 1500×1500 pixel one, though, which isn't massive.

The file which governs these ImageMagick policies is /etc/ImageMagick-6/policy.xml. If your ImageMagick version is 7+, the folder name will be ImageMagick-7, of course. (Run convert --version to find out if your distro uses ImageMagick 6 or 7). Whatever its precise location, the file contains lines such as these:

You could try increasing some of these resource limits (by editing the file as root), but my specific values look sufficient to me: 256MB of memory should be enough to handle very large images; an image width and height limit of '16KP' means 16000×16000, which is about 100 times larger than the image which triggered the above error! So, if there are some limits you could increase, fine. If, as in this case, they seem fairly generous to begin with -it could just be a bug that ImageMagick has. They are not unknown, after all!

A more specific suggested reason and possible solution was mentioned here:

Over the last year we have added checks in ImageMagick to help prevent security issues (e.g. aborts, uninitialized values, integer overflow). One new check is that the XMP profiles are compliant. The exception you received suggests that your image has a XMP profile that does not validate.

Using this idea that an image's embedded metadata might be tripping things up, I tried to fix the earlier error I was experiencing with one of my own recordings as follows:

Use Semplice in that recording's folder to extract the existing album art (to a file called folder.jpg)
Use the command exiftool -all= -overwrite_original folder.jpg to remove all existing EXIF data from the image
Use Semplice to re-tag the FLAC with the modified folder.jpg

…and when I then used Giocoso's Play Music menu Option 3 to play music from the specific folder, the album art displayed correctly, without weird warning messages:

So, in my case, it would appear that something was definitely amiss in the album art's metadata and it was this that was tripping up ImageMagick. Fixable outside of Giocoso, basically.

The good news is that however ugly the error message is when it appears, it shouldn't affect music playback at all -and the errors and generally screwed up display should resolve themselves when the next recording is played. You'll notice from the above screenshot, too, that the message is a warning, not an error: it didn't stop Giocoso correctly producing and displaying the appropriate album art+caption panel when needed.

Q. When I play music, the count-down timer thing in the top-right corner of the main display doesn't seem very accurate. Sometimes it stops several seconds short of the claimed duration before something new starts playing, though it sounds as if the whole recording was played. What's wrong?

A. Nothing, but it's a confirmed issue (see below for the eventual fix, however!). Here's proof: a recording that has ended 2 seconds before it was thought it would:

The 'pausing play for 3 seconds…' text tells us that this recording has ended and the 'pause between plays' timer has kicked in… yet the display in the top right-hand corner of the screen says that only 30 minutes and 10 seconds have been played of a 30 minutes 12 seconds-long recording. So you are spot on to observe that the countdown timer thing is not terribly accurate (I can confirm with my ears, which you'll just have to trust, that the entire recording was actually played: it didn't abruptly stop two seconds short of its final notes!)

So what's going on?

Firstly, there are truncation errors: if a track lasts 3 minutes 27.51 seconds, Giocoso will calculate it to be 3 minutes 28 seconds long. Up to 0.99 seconds of a track's duration can thus be lost by truncation: if you have multiple tracks making up a recording, that extra 0.99 seconds per track can start adding up to a claimed duration for the whole recording that's significantly longer than it truly is. Truncation can also produce timing errors the other way, of course.

More problematically, the bit of the display that says 'how long has this recording been playing for' is computed in a loop of code that is meant to iterate every second. But if your PC is a bit underpowered (think: Raspberry Pi 4, for example, where this issue personally bit me hard!) and it suddenly has to do background housekeeping work, that loop starts taking a tiny bit more than a second to complete and that error can start to accumulate: the display will say 'you've played 45 seconds of music' and actually it's been 46 seconds: it's just that the loop to update the counter is running slow versus clock time. It can even work the other way round: if your PC's internal clock is less than perfect and has little to process in the background, it can skip through the loop in less than a second, making the 'you've played X seconds of music' display go faster than it should (though this is rarer than the 'running slow' scenario).

I actually wrote some 'clock correction' code to deal with this. By comparing the number of played seconds with the known number of elapsed clock seconds since playback began, Giocoso can sometimes 'jump' a second, or display the same seconds for an extra second, depending on which way it needs to adjust the counter. This actually works quite well: you should generally never be more than 2 seconds out, 'played time' v. 'of time', as a result of its continual clock-watching and counter auto-adjustment. On a reasonably fast PC, I find that the counter adjustment code rarely kicks in, anyway: “play v. of” discrepancies then tend to be entirely a matter of per-track rounding.

But notice how the counter adjustment works: it compares 'I have advanced the counter 50 seconds' with 'the clock time on the system has advanced 51 seconds since play of this recording began'. It therefore concludes, 'I need to jump the counter forward 1 second', which it will then do. The problem then arises: what if you now pause the playback for ten minutes? For then, the clock time will advance 600 seconds, but the 'played' counter is stuck at 50 seconds -legitimately, because that's what pausing playback means! When you resume playback, how can you know if the counter is 'out' any more? You cannot compare it to the number of clock time seconds since playback began any more, because that's now hundreds of seconds ahead of 'played' time! So the short version is, the moment you pause playback of a recording, Giocoso can no longer invoke the counter-adjustment mechanism: the 'seconds since play of this recording began' is now no longer a usable reference point against which to compare. As a result, if a play is paused, the auto-clock adjustment mechanism cannot be used upon playback resumption and ever-once-paused plays are therefore inevitably going to be many seconds, potentially tens of them, 'out' in their calculations.

I should just add that Giocoso will always play through to the end of a recording. The thing which triggers the move onto a new recording is the genuine end of the present recording, not the numeric values displayed in the countdown timer. So, yes: recordings will reach their actual, natural end even when the timer still says several seconds (or more) of playback are due. It's the recording that's correct, not the timer.

All of which is a long way of saying that the 'played X of Y' display is indicative, not an atomic clock! Yes, it will drift a little (and badly, after a pause), but it's there more as a visual cue and general progress indicator than as a pin-point accurate timer. So, you're observations are correct, but it's the nature of the beast, I'm afraid. Sorry!

Updated for Version 3.20 and above: Everything written above is now no longer true in Giocoso Version 3.20 and above!! That version introduced the ability of Giocoso to directly read the music-playing engine's location within the music stream, in near-realtime. This means that in the 'Played X of Y' display, the 'X' is always accurately and precisely known. The 'Y' is easy to detect directly, too (it's just the duration of the recording being played, which is trivially obtainable). Hence, all parts of the 'X of Y' display are always accurate (sort of… see below). The 'Ending at' computation is thus pretty accurate now, too. If I know you've played 5 minutes out of 20 and the current clock-time on your system is 10AM, I know this recording will end at 10:15. If at 10:10 you pause playback, you are now 15 minutes into the recording, with five minutes to go: as you initiate a pause of playback, the 'X' component will stop incrementing (obviously, because you've stopped playing music!) and the 'Ending at' time will begin to increment, one second for every one second of pause. The 'Ending at' time gets pushed back, in other words, for as long as the pause continues. If you come back at 10:30 and re-initiate play, I know you've still got 5 minutes of the recording to play, so I can update the 'Ending at' time to be 10:35: that then stays fixed, and the 'X' component will resume incrementing once more.

The times displayed in this part of Giocoso's program output are now all accurate, from Version 3.20 up. Only two sources of imprecision remain: 1) your system clock does not keep perfect time, so if it drifts at all, then Giocoso's clock calculations will be 'off'; and 2) Giocoso still truncates times to whole seconds, whereas the underlying music playback engine reports its progress down to centiseconds. That is, if X really ought to be 'you've played 00:05:33.34 seconds of this recording', Giocoso will truncate the digits after the decimal point and report (and calculate) based on you having played 00:05:33 of it. The truncated tenths and hundredths of a second can add up for a long recording and introduce a second or so of inaccuracy. Giocoso will actually correct for this if accumulated drift from clock-time exceeds 2 seconds. Otherwise, a 2-second inaccuracy is something you still have to live with.

Q. When I play music, the album art displays with a white bar and some illegible yellow text underneath it. What's wrong?

A. Definitely reproducible:

The problem is most likely that you've run out of usable disk space in /tmp, because Giocoso has to be able to write its analysis of the colours found in the album art to that file system. If /tmp is full, then it cannot write out the analysis, and thus ends up reading in blank for the discovered colours -and that means it makes the 'text panel' under the album art completely white… and goes on to select entirely the wrong text colour as well, just for good measure! Here's proof that the space problem in /tmp is an issue for me:

You can see I'm down to “0 avail” for /tmp, and 100% used. So: I cleaned out my /tmp folder (using the fairly crude technique of rm * issued as a non-root user whilst sitting inside the /tmp folder):

That's got me back to just 1% used, 99% or 7.8GB available for use, and my album art is back to its usual self:

The short version is, therefore, that Giocoso needs 'working space' in /tmp (not much of it, mind; but some) and bad things will happen if it can't get any at all.

Q. When I start playing music, using my local PC to control a remote ssh session, the display gets a bit garbled with blank space displaying where it shouldn't. What's up?

Reproducible. You are probably describing this sort of output:

That break in the line-drawing characters to the right of the 'Ending at', which appears to obliterate the first part of the next line, again leaving a blank space which shouldn't be there, is probably what you're looking at. The trick is to highlight that area of the screen and copy-and-paste the text into, say, a text editor of your choice …and then you'd see the text which is actually causing that 'blank space':

Pulling that text out completely, you'd see it says: connect /tmp/.X11-unix/X1: No such file or directory. That's a fairly common ssh error and nothing technically to do with Giocoso: it's just that Giocoso doesn't know how to handle ssh-related errors gracefully.

There are numerous online resources for solving this issue: see, for example, this one. In a nutshell, it means that something is wrong with your ability to do X-forwarding and that the remote PC running Giocoso doesn't know how to write back to the screen display your local PC is running. Commonly, that's because the DISPLAY environment variable is set incorrectly. It can also be because your local PC has its own ssh server configuration which is messed up in some way. This recently happened to me, for example: I had actually just installed ssh server for the first time onto my local PC and this screwed up the remote PC's ability to draw to my X server (display): a simple reboot resolved that particular issue. If a system update and a reboot (of your local PC) doesn't resolve the issue, then you will need to brush up on your Google-fu and try and diagnose your ssh/X forwarding issues using whatever online resources you can find. It fundamentally isn't Giocoso going wrong, though.

| Back to Software Home | Back to Giocoso Documentation Home |

underplayedcomposers

Anonymous (anonymous@undisclosed.example.com) — 2025-10-25T16:35:37+00:00

A Note about Under-played Composers

1.0 General Thoughts

A central goal of Giocoso has always been: to help uncover music by composers who would otherwise tend to be forgotten. One of its central music-choosing strategies is randomisation, after all: pick something to play at random and it might just as well turn out to be by Kurpinskí or Kenins as by Mozart or Mahler. However, if you were to switch on Giocoso's 'Only play previously unplayed recordings' feature, you would slant the playing pitch the wrong way -because the likes of Mozart or Brahms or Bach wrote huge quantities of music and the likes of Kenins or Novák didn't. It's therefore easy to play the three pieces you have by Novák and have nothing else by him that hasn't been played previously, whilst the well of unplayed Bach or Beethoven is likely to be very deep.

So, is there a way to swing things back the other way and to give the Tormises, Peeterses and Salzedos of this world more of a chance of getting their limited wares before your ears? Sure: that's what Giocoso's new (to Version 3) 'under-played composer' feature is for.

The Underplayed Algorithm (as I'll call it henceforth) takes as its starting premise the idea that if there are 500 composers represented in your music collection, then in a completely fair and reasonable world, each composer would constitute 1/500th of the plays from that collection (or 0.2%). If you had collected music by fewer composers than that, the percentage would go up; with more composers, it would go down.

But 0.2% of what? It can't be simply the count of “plays”. A 45-second keyboard sonata by 4 year-old Mozart should not have the same mathematical significance as one of Wagner's lengthier Gesamtkunstwerks! Instead, it must be of cumulative play time: one play of Wagner counts for a lot more than one play by Tylman Susato (say), because it lasts an eternity whereas a Susato dance lasts mere minutes.

Thus, to make a 'fair deal for unknowns' algorithm work, we first have to know the length of time all music plays performed to date have taken. Giocoso computes this as simply the total sum of the DURATION column in the PLAYS table, measured in seconds. We also have to know how many distinct composers we have in our collection: Giocoso computes this as a select distinct of the COMPOSER column in the RECORDINGS table.

If the total duration is X seconds; and if there are Y unique composers in the collection, then a 'fair deal' would result in 1/Y * X as a 'fair play' time: we can use that formula to generate a 'threshold amount of time' below which a composer is being hard-done by; above which, a composer is being played more often than is strictly 'fair'. For ease of use, rather than derive the threshold as a number of seconds of playtime, we can also use straight percentages. If 1/500 is 0.2%, then a composer whose personal, total plays represent 0.3% of all play time is over-played; one whose personal play-time is 0.15% would be considered under-played.

To put some numbers on that: say my collection consists of 602 composers; and its total duration if played end-to-end would be 400,000 seconds (6,666 minutes, or 111 hours). Then we can say any composer whose cumulative plays to date have lasted less than (1/602)*400000=664 seconds (around 11 minutes) would be classed as 'under-played'. A single play of anything by Wagner would clearly make him 'over-played', but even a dozen plays of early stuff by Mozart would have difficulty crossing that threshold. In percentage terms, 1/602 composers is about 0.1667%, so any composer whose total, personal play-time was less than 0.1667% of the 400,000 global play-time would count as under-played.

One slight fly in the ointment remains: you cannot just add up 'cumulative plays to date' and declare the job complete: if your collection has recordings by composers who have never previously been played, they should be regarded as 'under-played' too… but if you were only to count up play durations from the PLAY table, they'd never be considered. Accordingly, the algorithm needs to do the previous mathematic calculation which does exclusively check the PLAYS table, but it must then also bolt on any composer who appears in RECORDINGS and not in PLAYS.

2.0 Code

So with all that in mind, here's the actual code which makes up Giocoso's 'under-played composer' algorithm:

select recordings where composer in (
with duration_in_secs as (select composer, substr(duration, 1,2)*3600 + substr(duration, 4,2)*60 + substr(duration, 7,2) as duration_secs from plays),
total_durations as (select sum(duration_secs) as totalcount from duration_in_secs),
composer_durations as (select composer, sum(duration_secs) as composertime from duration_in_secs group by composer),
percentages as (select c.composer, c.composertime, t.totalcount, cast(c.composertime as real) / t.totalcount * 100 as playpercentage from total_durations t, composer_durations c),
threshold as (select cast(1 as float)/(select count(distinct composer) from recordings)*100 as threshold_value)
select composer from percentages where playpercentage < (select threshold_value from threshold)
union all
select distinct composer from recordings where composer not in (select composer from plays)
)

With apologies for the colour-coding for any of my colourblind readers, we can pick that apart as follows:

The 'with' clause introduces five separate sub-queries:

Duration_in_Secs takes every record in the PLAYS table and, for each, isolates the COMPOSER and DURATION fields, whilst converting the DURATION (which is physically stored in hh:mm:ss format) into a simple count of seconds. So this sub-query tells us 'here, composer X was played for Y seconds; here composer A was played for Z seconds…' and so on)

Total_Durations takes all the records in the Duration_in_Secs subquery and simply generates a one-line total number of seconds of play for everyone, for all time. This is the sub-query that says every play you've ever made, regardless of who composed it, amounts to 400,000 seconds of play-time.

Composer_Durations takes all the records in the Duration_in_Secs subquery and generates a per-composer total number of seconds-of-play. It's this query that says 'Copland was played for 450 seconds, Britten for 3,200 seconds, Brahms for 145 seconds…' and so on.

Percentages takes the results from Total_Durations and Composer_Durations. It takes the per-composer total playtime and divides by the total-total-playtime, to generate a percentage of total play by composer. Here, then, we take Copland's 450 seconds of play-time, divides by the total 400,000 seconds of play-time and conclude that Copland was played 0.11% of the time; Britten's 3200 seconds represents 0.8% of all play-time, and so on.

Threshold simply counts up the total number of unique composers found in the RECORDINGS table and computes what 1 ÷ that total is: if I have 602 composers in RECORDINGS, the Threshold subquery is going to return a value of 1 ÷ 602 = 0.166%.

We finally get to the main query: return composer names whose personal play-time percentage is less than the gobal, threshold play-time percentage. These are the underplayed composers: both Copland and Brahms would make my list of the under-played, but Britten would not.

But this doesn't account for composers who have never been played yet. We therefore bolt on an extra query any composer whose name appears in RECORDINGS but which doesn't appear in PLAYS: these are the never-before-played composers, and by adding them via a union all clause to the list of underplayed composers generated by the main query, we now have a complete list of composers we think have been underplayed to date.

3.0 Observations

Note that the Threshold is computed dynamically. This means it will change as you add new recordings (and new composers) to your music collection. If I own music by 602 composers, the threshold is about 0.166%; but if I add music by 32 new composers, the threshold changes automatically to 1÷634 = 0.1577%. A composer that was barely 'under-played' before the addition (with a play percentage of, say, 0.162%) would now automatically be regarded as somewhat over-played now: there are 32 never-before-played composers to worry about before re-playing this fellow's work again!

At first glance, talking about thresholds of 0.16% sounds ridiculously low -but simple maths indicates it's correct. If you only had music by 10 composers, then each would 'fairly' have 10% of the total play-time; if there were 100 composers, then a fair-share would be just 1%. The moment you have music by more than 100 composers in your collection, the 'fair share' threshold becomes a percentage less than 1%. Once you have music by 1,000 composers, the fair-share threshold becomes less than 0.1%… and so on.

The necessity of using substrings to convert per-play durations from hh:mm:ss format into a simple number of seconds in the Duration_in_Secs sub-query is unfortunate, but arises from the way Giocoso version 1 (and it's predecessor music player) stored play durations, coupled with my reluctance to alter the database structure for backward-compatibility considerations. The conversion works by knowing that if a duration is stored in hh:mm:ss format, then characters 1 to 2 are the hours, which need to be multipled by 3600 to convert to seconds. Characters 4 to 5 are the minutes, which thus need to be multipled by 60 to derive seconds. Finally, characters 7 to 8 are the seconds component, which need no conversion, because they are already in seconds. It's a simple matter to add the three converted numbers together to thus derive a per-play duration in pure seconds.

Another consequence of storing play durations in hh:mm:ss format is that the PLAYS table is not quite accurate -because durations in the RECORDINGS table is actually measured in seconds with multiple decimals. A recording that is said to last 1487.146667 seconds, for example, will be played as lasting for 00:24:47, which is close but not perfect, as the 0.146667 seconds decimals have been discarded. For a composer right on the threshold of being under- or over-played, the rounding that takes place at this point of the calculation might make a significant difference, but it's something that has to be lived with due to prior database design consequences.

A very important point to note: the use of the 'under-played composer' filter is determinative. By this I mean that, as you can see from the SQL query it triggers, it literally restricts the list of composers whose music can be regarded as an acceptable random choice for the next play. It doesn't just mean that an under-played composer might get randomly picked for the next play: it means an under-played composer definitely will be the next pick. You just don't know which under-played composer it will be. This is quite different from, for example, the use of the exempts file to exempt a composer from the usual time bar: mentioning Britten in the exempts file doesn't mean a piece by Britten will be the next one played, but only that a piece by Britten could be the next one played. The exempts file is persuasive; the under-played filter is determinative.

One final point: if you left this filter on long enough, every composer ought to more-or-less reach the threshold and thus cease to be a candidate for play: at which point, Giocoso would have no viable candidates for play and your life would go silent! Think of the filter as a way of roughly levelling the playing field for a time, not as something you'd leave on permanently, therefore.

usetips

Anonymous (anonymous@undisclosed.example.com) — 2025-12-10T18:05:05+00:00

Usability Tips & Techniques

I thought it might be helpful to document how I use Giocoso on a regular basis. Some of this may be useful to you, too!

1.0 Remote Access

I do not run Giocoso on my main, desktop PC. Instead, I have a Raspberry Pi 4 running completely silently in the drawer of a console table, to which I can connect via Ethernet network and I run Giocoso on that instead. However, I am sat at my desktop PC for long hours of the day: that's obviously the computer with which I want to control Giocoso. So how do I issue commands on my desktop PC and yet control Giocoso running in the console drawer? I wrote a separate article about how I achieve this using SSH and turn it into a button-clickable capability with a little bit of desktop environment manipulation.

This all simply means that I can operate Giocoso from my desktop PC, but everything I do is actually running on the music PC. I have remote control of what Giocoso does… but the program display is entirely as if I were running it locally.

| Back to Software Home | Back to Giocoso Documentation Home |

win11

Anonymous (anonymous@undisclosed.example.com) — 2025-12-13T14:01:36+00:00

Installing Giocoso on Windows 11

1.0 Introduction

By way of introduction to the topic of installing Giocoso on Windows 11, I have to make several disclaimers:

I'm using real, physical hardware
The physical hardware is a Lenovo L460 laptop, with an i5-6200U CPU and 16GB of RAM, manufactured in about November 2016
That laptop does not meet Microsoft's official, supported hardware requirements for Windows 11
My Windows 11 installation is thus unofficial and unsupported by the operating system manufacturer

Accordingly, what I go on to describe in this article might not be representative of what will happen on properly-supported hardware. I should also mention that I'm writing using Windows 11 25H2, which is the latest version of that operating system at the time of writing, in December 2025.

The basic principle of getting Giocoso working on Windows 11 is to install the Windows Subsystem for Linux (WSL) onto your Windows system, then install a Linux distro of your choice, and finally install Giocoso into that distro. It is, in other words, a cheat! Giocoso is, essentially, a Bash script that orchestrates a number of Linux programs and utilities to play music: it doesn't really run on Windows at all… but thanks to WSL, Windows can run Linux, and if Linux is running, Giocoso can run within that.

In what follows, I'll show you how I installed the Windows Subsystem for Linux on my Windows laptop; how I then installed a distro; and how I then made that distro run Giocoso. I'll finish up by showing you how I went on to install more distros on the same laptop and was able to run Giocoso under all of them, mostly with total success.

2.0 Installing the Windows Subsystem for Linux (WSL)

Microsoft actually invented two versions of the Windows Subsystem for Linux, so technically the one we're about to install is properly known as WSL2: it's the second version and is needed because only it allows direct access to graphical and audio hardware from within the virtualised Linux workspaces it creates. I will generally refer to it as merely “WSL” however, as almost no-one is going to be using the first version of it these days.

In order to be able to install WSL2, your computer needs to using a 64-bit CPU (which is practically a given these days, I think). You also need to make sure that your computer's BIOS or UEFI settings are configured to enable the virtualisation features of your CPU: that's not a given and you may need to hunt around for the right setting to switch that on.

Assuming those minimal prerequisites are met, however, then installing WSL consists of opening a command prompt with Administrator rights and issuing the command:

wsl --install

Windows will respond by downloading some software, installing it and then prompting you to reboot:

When you see this message, do as it says and reboot your PC to make the new feature available and functional. Once your PC has rebooted, nothing will apparently have happened and nothing terribly Linux-y will be available to you to use! That's because you haven't installed a distro yet… so that's the next thing to do.

3.0 Installing a Linux Distro

Open another command prompt with Administrator rights and type the command:

wsl --install ubuntu

It doesn't have to be 'ubuntu' here: you can install 'debian' or 'fedora' or several other distros if you prefer. But I'm running with Ubuntu for now and we'll see how to install these other distros later on.

As you can see, Windows pulls down various software packages, installs them and then 'provisions' them for you. At the end of that process, you are prompted to supply a new username and password combo: this will be the Linux user, which is not the same as the Windows user at all. If you choose to type in, when prompted, the same username as you use to log onto Windows 11 in the first place, that's perfectly fine… but you don't have to do that. Similarly, your Linux password does not have to match your Windows one… but they can do so if it makes it easier for you.

As soon as you've supplied a new user/password combo, you are unceremoniously dumped at the command prompt of your new Ubuntu environment, as you can see in the above screenshot. A rather important point to note here is that you are dumped at a Linux command prompt (the slashes slant forward!) but in a Windows folder location. In my case, you'll note that I'm in /mnt/c/Users/hawen: that “/mnt/c” prefix part of the path is how the Linux environment 'sees' my Windows C: drive. If you have music files stored in C:\Users\hawen\Music, for example, then the Linux environment will be able to see them in /mnt/c/Users/hawen/Music, too.

As soon as you have a functioning Ubuntu system, you must update it, by issuing the commands:

sudo apt update && sudo apt upgrade

That will trigger a lot of in-terminal activity:

As you can see, in my case there were over 100 updates to apply, totalling around 150MB of software download. Let that happen, responding 'y' when prompted: Giocoso will not install on a Linux environment that hasn't been fully updated.

Once your distro has been fully updated, close the terminal window, which is kind of equivalent to rebooting the Linux environment and having the updates applied. You've just built yourself a working Linux environment inside a Windows PC (which to this day still impresses me as a significant technical achievement on the part of Microsoft).

4.0 Installing Giocoso

If you click your Windows 'Start' button now, you should see an icon in the 'Recommended' section of the start menu for launching an Ubuntu environment directly. Click that and Windows' new 'Terminal' application will be launched, dumping you straight into an Ubuntu terminal session, in your Linux user's new $HOME folder. You can check this by typing the commands:

pwd
uname -a
cat /etc/os-release

…just in case there's any doubt in your mind that you are actually sitting inside a Linux virtual environment at this point. Another way you can get into your Ubuntu environment is to open the Terminal application from the Windows start menu yourself, then click on the little down-chevron you see along the top bar of the display:

As you can see, that displays options as to which sort of terminal session you want opened, and Ubuntu is listed there, with its familiar roundel icon. Click that and a new terminal tab will open, in Ubuntu's trademarked purple hue, giving you a strong visual clue that you are indeed using Ubuntu at this point.

However you launch your Ubuntu session, type the following command into the terminal prompt:

wget software.bbritten.com/gioinst

You'll see a flurry of screen activity as the Giocoso installer script is downloaded:

The script is tiny, so it takes hardly any time to download. Once it has, type the command:

bash gioinst

…and this will happen:

The screen-full of text is there to warn you that installing Giocoso will trigger the installation of a bundle of software that Giocoso relies on. You can tap 'n' to back out of the installation without it having altered your system at all… but if you tap 'y' to proceed, this immediately happens:

That's just a little bit of preliminary checking and configuring taking place, after which the screen will change to display this:

Here, a progress bar will indicate the installer's gradual installation of all the software packages Giocoso needs to work properly. There aren't that many of them and so it shouldn't take more than a couple of minutes for the installer to display this message:

Clicking OK at this point (or just pressing [Enter]) will move the installer onto its second phase, where it begins to pull down the Giocoso software components themselves:

Once that's been done, you'll see this confirmation message:

Click OK (or press [Enter]) at this point and the installer will verify that all the Giocoso components came down successfully by computing and comparing the hash values for the files:

That bunch of gobbledygook is just Giocoso's way of checking that the local file installed on your PC actually matches the one stored on this website's servers, precisely and completely. If they don't, it will be because there was some sort of glitch in the download process -and, accordingly, the installer will attempt to fetch the relevant files one more time. If everything matches, however, then we know the local installation is a good one and you'll thus see this message by way of conclusion:

That's the message that tells you that Giocoso has indeed been successfully installed. You can do what the message suggests and close your terminal… or you can run Giocoso immediately, by typing the command:

giocoso

…which will trigger this display:

It's a bit bare-bones and you may have to manually fiddle with the size of the terminal window to get everything to display nicely, but Giocoso is, at least, running. Your next steps are to create a new music database; discover a bunch of music files to play; and start playing some music! Taking those steps one at a time therefore…

If you tap 'D' to get to the Database Management menu and then '1' to Create a music database, you'll first be prompted for a name for the new database:

You can supply any name at this point, but I suggest you keep it to a single, short word, as in the screenshot example. Once you submit a name, you'll immediately be prompted to specify where music files can be found on disk:

Your job is to navigate your way to wherever your music files are located. Mine happen to be stored in the Windows user's Music folder:

…inside a sub-folder called 'classical' and within additional sub-folders named after the initial letter of each composer's first name. You'll recall from Section 3 above, however, that the Linux environment sees the C: drive at '/mnt/c', so my Windows path needs to be converted to /mnt/c/Users/hawen/Music/classical. I could just type that into the horizontal panel of the Giocoso folder selection screen or I could use the upper panel to navigate to that location: either method works equally well, so long as Giocoso ends up 'inside' the folder, looking at the initial-letter sub-folders, as you see in the above screenshot.

Click [OK] or press [Enter] when the correct path has been supplied and you'll see Giocoso do this:

That's Giocoso discovering FLAC files within the path supplied and, for each one, reading the internal metadata contents and populating its database with those details. Once that process completes (which can take many hours if your music collection consists of tens of thousands of FLACs), you can at last play music: just press 'P' to get to the 'Play Music' menu and then tap '1' to select the 'Play music with defaults' option: Giocoso will randomly select something to play from the database of music you just created and the result should look like this:

You'll note that Ubuntu-in-Windows has zero difficulty displaying the album art for a FLAC …and you'll have to take my word for it that my laptop's speakers were full of music, sounding great, as intended! Giocoso on Windows (via Ubuntu) thus works perfectly.

5.0 Other Supported Distros

If you'd prefer not to use Ubuntu, you have various other distros that can run under Windows without difficulty and which are officially supported by Microsoft. You just open a command prompt with administrator privileges and issue commands such as:

wsl --install fedora
wsl --install debian

wsl --install archlinux

As described earlier, each of these commands will trigger the download and installation of the necessary Linux environment files. You'll be prompted to create a new Linux user/password combo, as described above for the Ubuntu environment. You should then perform a full system update, using your distro's standard package management features. For Fedora, that would be:

sudo dnf update

…whereas for Debian, it's the slightly more convoluted:

sudo apt update && sudo apt upgrade

You then just obtain the Giocoso installer script… but this is where things can get a bit interesting!

On Fedora, for example, you'll issue the command:

wget software.bbritten.com/gioinst

…without any drama at all, but when you try and run that script with the command bash gioinst this will happen:

That's the Giocoso installer noticing that ncurses is not a standard part of the Fedora-on-Windows installation. Without it, the installer cannot proceed. You'll therefore need to install it manually:

sudo dnf install ncurses

…and then try the bash gioinst command once more: this time, the installer will function entirely as documented above. You can then launch Giocoso, create a music database, point it to your FLAC files, and start playing music as previously described: music playback and display of album artwork both work perfectly.

Using Debian poses a different set of issues, however:

Here you'll see me in my shiny new and updated Debian environment trying to download the Giocoso installer script with a wget command: unfortunately, wget is not a standard part of the Debian installation, so the attempt to download fails. It's therefore necessary to manually download the utility with the command:

sudo apt install wget

Once that's installed, the bash gioinst command will work perfectly: music sounds correctly and album art will be displayed correctly.

The Arch distro is rather different than anything discussed hitherto! It's extremely minimal, to the point that there isn't even a prompt to create a non-root user. You probably should create such a user, but that's outside of scope for this article. For my purposes, the point is that you install and run Giocoso as root… but even that is not straightforward. For a start, you need to manually update, then install wget and sudo before you can successfully run the Giocoso installer: pacman -Syu updates; pacman -S wget sudo installs the necessary prerequisites. After that, wget software.bbritten.com/gioinst and bash gioinst will work correctly. Unfortunately, after you've created a database and discovered FLAC music files, though they will play correctly, album art will not display correctly, unless you configure Giocoso to use a pop-out window to do so. I'll discuss a possible workaround for this below, when I discuss using non-Microsoft-supported distros.

Apart from the need to install either ncurses or wget manually before the Giocoso installer can be launched successfully, therefore, there's little difference between running Giocoso running on Windows via Ubuntu, Debian or Fedora. The choice of distro to host the Giocoso installation is therefore largely immaterial. Arch is suit generis however… and I can't honestly recommend trying to run Giocoso on that distro within Windows.

6.0 Non-Suported Distros

I'll conclude this description of getting Giocoso running under Windows by mentioning that although there aren't many distros that are officially supported by Microsoft for running in a WSL2 environment, WSL2 can actually run pretty much any Linux distro, with varying degrees of awkwardness. Sometimes, distros provide specially-packaged versions of their distro to make life fairly easy (think: Devuan or Manjaro). For other distros, you'd have to construct your own converted distro 'bundle' and import it to the WSL environment: I won't document that approach here, but you essentially have to extract the root file system from the standard ISO and turn it into a tarball, which can then be imported into WSL. There are guides on how to do this elsewhere on the Internet.

For now, I'll document how I got Manjaro to run under Windows, and sort-of got Giocoso running on that!

First, obtain your Manjaro-on-WSL software: I've already pointed you to the website I used for that: at the time of writing, the latest release was called “ManjaroWSL2-20251201” and within that section of the site I downloaded the ManjaroWSL2.zip file for that release. Once downloaded, I right-clicked the file and selected the 'Extract All…' menu option. That creates a “ManjaroWSL2” folder, within which you'll find an item called, simply, “Manjaro”. It should be labelled as an 'Application' in one of the columns visible in Windows File Manager. Double-click that item and this happens:

Windows begins to import the new distro and install it 'within' the WSL environment. The process is relatively quick and ends like so:

Press [Enter] at this point and the terminal window will close. If you were to look at your Windows Start menu at this point, you'd probably see something like this:

The existence of a Manjaro icon in the 'Recommended' section of the menu here tells you that Manjaro has indeed been installed. It's not quite ready for use, though: click that icon to launch it and you'll see this:

That's the new Manjaro getting itself provisioned properly. Part of that process is this prompt:

You don't have to create a non-root user, but it's strongly recommended to do so. Follow the prompts and supply a new password for the new user when asked; eventually this will happen:

The distro will reboot itself and when it comes back, you'll be able to log in as the new user. You can now do a standard Giocoso install: start by bringing your Manjaro distro fully up to date with the command:

sudo pacman -Syu

Once that's done, obtain the Giocoso installer:

wget software.bbritten.com/gioinst

…and then launch it by typing:

bash gioinst

The standard Giocoso install process will then run its course without incident. Giocoso itself can then be launched with the simple command. giocoso. You then use Giocoso in an entirely standard fashion: create a music database, discover music files, go to the Play Music menu and start playing:

It is at this point that you'll discover that 'non-standard' distros have non-standard quirks! In this case, you can tell that music is playing fine: the counter in the top right of the Giocoso screen is saying we're six seconds into playing a 51 minute recording, for example. But you'll notice that there's no album art: that's because Manjaro-on-WSL's default terminal is not configured to display 'sixel graphics', Giocoso's default mechanism for displaying graphics within a terminal.

Various workarounds for this problem are available. First, you could use the Administration menu, Option 2 to tell Giocoso (on the last page of options) to 'Display album art in its own window':

You can also adjust the 'Size of album art when displayed' parameter to make that standalone album art window bigger or smaller, as needed. If you insist on seeing album art within the Giocoso terminal window, however, you're going to have to jump through some hoops. First, install the Konsole terminal emulator:

sudo pacman -S konsole

You can then launch konsole from within the main Manjaro terminal:

You'll note that the window is tiny and really not much use for anything. To fix that, click the 'hamburger menu' (three horizontal lines) at the top right of the konsole window. Select settings → Configure Konsole…. On the General options, uncheck the option to 'Remember window size'. Switch to the 'Profiles' option. Click New, then create a new profile that sets the initial terminal size to 103 columns and 28 rows. Click Appearance, and select 'Green on Black'. Click on the [Choose] button to alter the font: select Luxi Mono at 14pt. Click OK. On the list of profiles, select the profile you just created and click the 'Set as Default' button. Click [OK] once more. Now you can close the existing konsole session and start a new one. The new konsole window should open looking much more usable:

Launch Giocoso from within that konsole window and you should see Giocoso looking perfectly normal… but it still won't be able to display album art properly just yet. For that, visit the Administration menu, Option 2 and switch on the option to 'Use Kitty Graphics for in-terminal display'. Kitty is an alternative in-terminal graphics protocol …and konsole understands how to use it. When you start playing recordings, the result should be acceptable:

As you can see, everything is finally behaving normally… though having to use a terminal to launch a terminal to launch a program is not exactly ideal. To fix that inconvenience, you might consider editing your $HOME/.bashrc to contain the line:

alias giocoso="konsole -e giocoso3.sh"

Save that file and then get its modified contents applied by typing:

. ./.bashrc

(That's dot-space-dot-slash-dot-bashrc). You can now just type the command “giocoso” and konsole will be launched for you, with Giocoso already running within it. It's a slight improvement on doing it all manually, I think!

The short version of this section is, therefore, that of course you can run unsupported distros under WSL, which means you can run Giocoso on them, too. However, you are likely to run into visual presentation issues when Giocoso runs that don't arise in the more 'standard' distros. With a little bit of effort, they can be worked around, so that Giocoso still runs well on Windows… but expect to encounter problems that require workarounds! My personal recommendation is that, given you simply want Giocoso to work well on Windows, stick to a mainstream distro as discussed above in Sections 3, 4 and 5.

7.0 Conclusion

Summing this all up, therefore: Giocoso doesn't really run on Windows at all: it always runs on Linux. However, the Windows Subsystem for Linux allows you to run Linux on Windows in a practically invisible manner… and that means Giocoso can run, effectively, on Windows after all. WSL installation is straightforward, installing one of the supported distros is easy, and Giocoso installation is mostly straightforward in all cases. Non-mainstream distros are also a possibility but I wouldn't personally recommend them.

| Back to Software Home | Back to Giocoso Documentation Home |