Giocoso on macOS

1.0 Introduction

Giocoso has been tested to work on a physical Sierra Mac Mini, a physical Catalina iMac, the same iMac with Monterey installed and a Big Sur installation on a VirtualBox. I am therefore pretty confident that Giocoso will run on any version of macOS (i.e., from 10.12 [Sierra] upwards), though I haven't tested every single one of them and I have no idea what will happen with anything Apple releases later in 2022. However, anything which claims to be macOS and isn't one of the versions I've just listed has not actually been tested and I do not have the physical resources required to provide support on those macOS versions (unless you'd like to donate hardware that's capable of running those other versions: please get in touch if you do!) For similar reasons, I cannot say whether Giocoso will run on M1 Macs: I've only ever used Intel chips.

Giocoso has several package dependencies -that is, programs which must also exist on your Apple computer for it to be able to work. The simplest way of ensuring all those dependencies are installed correctly is to install them with a package manager called 'MacPorts'. Once MacPorts exists, installing almost any other piece of software is just a matter of issuing an appropriate 'port install... ' command.

I should also point out that the other popular way of installing software onto a Mac via the command line is called 'Homebrew'... and using MacPorts and Homebrew at the same time (at least on Intel CPUs) is a really bad idea. At this time, therefore, if you've already used Homebrew to install software, you should not attempt to install Giocoso using these instructions, because they will expect to work the 'MacPorts' way! If you are skilled enough, fine: you can finagle things to co-exist and with a judicious bit of symlinking, maybe it will all hang together... but you're very definitely on your own at that point!

For the avoidance of doubt, then: these instructions assume a relatively clean Mac install and no prior use of Homebrew to install anything.

Thus, in this article, we're going to 1) Install the command line utilities that MacPorts itself will depend on; 2) install MacPorts itself; and 3) install the necessary Giocoso package dependencies. Once all that is done, you'll be able to download and run Giocoso on macOS (Sierra and up) without drama.

In all that follows, bear in mind that a functioning Internet connection is a necessity.

2.0 Installing Command Line Tools

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:

When you see this prompt, just click [Install], then agree to the huge license agreement that appears (having first read it carefully, of course!)

The installer will find and download the relevant software. Click [Done] when it's complete.

Once the install completes, you're ready to move on to the business of installing MacPorts.

3.0 Installing MacPorts

There are different versions of MacPorts to install, depending on what version of macOS you're using: you can click the Apple icon in the top panel and select the 'About this Mac' menu item to find out your OS version, if you've forgotten it.

At the time of writing, the following downloads were available:

(Installing Giocoso on anything earlier than Sierra is not supported, so I've not bothered to list any MacPorts version for earlier versions of macOS than that, either).

Click whichever one of those links applies to your version of the macOS operating system and download the relevant package. Once it has downloaded, issue the following terminal commands, in sequence:

cd
cd Downloads
sudo installer -pkg MacPorts-2.7.2-10.13-Sierra.pkg -target /

The specific filename mentioned there may vary, depending on the version numbers and OS release you're actually using: the above is true for me and my Sierra macOS installation in May 2022. Remember that you can type 'MacPorts <tab>' to have the correct file name filled in for you automatically, before finishing off the command with the '-target /' bit. Since the command mentions 'sudo', you'll be asked to supply your password before the command can complete successfully: do so when prompted.

A successful installation will be indicated as you see here: 'The install was successful' is the last message returned by the installation command.

Unfortunately, the package will have been installed into a folder which is not ordinarily searched by the operating system, so we need to correct it with the following command:

sudo nano /etc/paths

That opens a text file in which the names of all the folders that macOS searches by default are listed. We need to add the one into which MacPorts was just installed to the end of that list, like so:

That is, you type the text /opt/local/bin onto a new line at the beginning of the existing list of folders, without altering any of the existing content of the file. Once that's done, you save the edited file by pressing Ctrl+X followed by y+Enter. It's vital that the /opt/local/bin folder appears first in the list, because that way we ensure that macOS searches that folder for executables before it looks elsewhere. If you tack it onto the end of the list (for example), then the old and out-of-date version of Bash will always take precedence over the more up-to-date version we're about to install.

Anyway: the short version is, make the list in your /etc/paths look like the one shown above, please!

You make the edit take effect by closing your existing terminal session and opening a brand new one. Once you've done that, we're ready to use MacPorts properly!

4.0 Installing Software Prerequisites

Now MacPorts is installed, you can move on to install the additional software that Giocoso will need to work properly. You can do that in the terminal by typing this command:

sudo port install xorg-server ffmpeg flac xdotool bash imagemagick xterm wget coreutils fd xrandr gsed grep dejavu-fonts findutils

(NB: Note that the requirement to install findutils is a new requirement in version 2.01 and above. If you are upgrading from 2.00 to 2.01 or later, you will need to add that package to your existing system).

At times, you may be prompted to install associated packages that the explicitly-mentioned packages depend on. You must answer 'y' to any request to install such dependencies.

Otherwise, be prepared to wait quite a long time for that lot to finish: on my admittedly virtual version of Sierra, installing xorg-server all by itself took over 20 minutes! On the other hand, the entire installation of everything took about 30 minutes on a physical Catalina iMac. Either way, just be patientand let the process complete in its own sweet time.

Be warned too: on the latest Monterey macOS, running the 'sudo port' command caused this to happen:

The 'would you like to install the tools' prompt looks suspiciously like a duplicate of the original prompt to install the Xcode tools we did back in Section 2, so I'm not quite sure why that's happening! Meanwhile, in the background, the terminal window is displaying all sorts of dire warning messages about 'all compilers are blacklisted'! These responses only happened in Monterey -and I'm running that on officially unsupported 2012-era hardware, so that's possibly why this issue arose for me. It didn't occur in either Sierra or Catalina, for example.

Anyway: for Monterey, I chose to click [Install] in the foreground and let the port install command continue doing what it wanted to do in the background:

I left the terminal 'Continue y/n' prompt sit tight until the software installation in the foreground was complete, and then switched back to the terminal to tell it to continue. That seemed to work and the rest of the software installation proceeded without incident:

I will also note that at the end of my Monterey-installation of the software dependencies, I was told that the xorg-server had failed to install because of 'unmet dependencies', which were listed as being some X server-related fonts. I'm not entirely sure why that should have been the case, but MacPorts is known to occasionally have bugs and glitches -and maybe this was one of them. In any event, I simply re-ran the exact same 'sudo port install' command again... and, second time around, everything worked just fine:

So, depending on your version of macOS and whether you're running on Apple-supported hardware, installing MacPorts software may not be the straightforward exercise it usually is. Nevertheless, I got there in the end, and you should be able to as well!

5.0 A Little System Preconfiguration...

Once the software prerequisites are installed, we need to do a couple of bits of system re-configuration to make the next steps work properly.

5.1 System Integrity Protection Modification

First, on Catalina and up, we need to make sure that the built-in System Integrity Protection (SIP) O/S feature doesn't stop the terminal application from being able to do what it will need to do in order to be able to run Giocoso. Earlier versions of macOS seem to have been more permissive about this, so this step wasn't necessary in Sierra, for example, but I found it was definitely required in Catalina and Monterey.

Click the Apple icon in the top panel, then System Preferences -> Security & Privacy. On the Privacy tab, scroll down on the left-hand pane until the Full Disk Access item is visible. Click on it to select it, then click on the padlock symbol at the bottom of the screen with the 'Click the lock to make changes' text next to it: that will prompt for your password, which you should supply as usual. With the Full Disk Access item still highlighted over on the left of the screen, click the '+' button underneath the blank area on the right:

The specifics may be a little different on different macOS versions, but the general point is that you're trying to give the Terminal application full disk access. So, in the dialog that popped up when I clicked the '+' button, I've navigated to 'Applications' on the far left; I've scrolled down to 'Utilities' in the second column; I've then found 'Terminal' in the third column. With that selected, click the [Open] button:

Obviously, I was doing all of this whilst a terminal session was already open -so I get to enjoy the message you see here. If you had closed down all your terminals before attempting this bit of security re-configuration, you won't have to deal with it! The issue is that running terminals can't inherit new security permissions, so the system wants to close existing terminals and re-open them. That's usually fine, so clicking [Quit & Reopen] is fine for me. If not, you can always click [Later] and close your own running terminals when it suits. Note that if you do opt for the quit-and-reopen option, the terminal tends to re-open on top of the Security and Privacy dialog: so if that disappears suddenly, it'll be hiding underneath the new terminal window!

You end up with this result:

...which means Terminal now has new permissions to access your hard disk. This is needed by Giocoso, but it's also fair to point out that it's a weakening of the tight security restrictions Apple brought in with macOS Catalina. If you are at all uncomfortable about the security implications of this, you can obviously revoke the permissions grant by selecting the 'Terminal' item and clicking the '-' button.

Close the Security & Privacy dialog once the Full Disk Access permissions have been granted to Terminal.

5.2 Creating a Local Bin Folder

Next, we need to create a non-root-read-writeable /usr/local/bin folder, because at the moment it probably doesn't exist (but by all means check if it does, and if it does, you can skip these next few commands). In a new terminal session, type:

sudo mkdir /usr/local/bin
sudo chown -R $(whoami) /usr/local/bin
sudo chmod -R u=rwX,go=rX /usr/local/bin

You can confirm the result of those commands with a simple ls -la /usr/local command:

The mere existence of a bin folder within /usr/local is a good start; the fact that it's owned by me and thus writeable by me, too, is an important bonus, however!

With all that done, we're finally ready to install and run Giocoso.

6.0 Installing Giocoso

Once all the prerequisite software has been installed, you can obtain the Giocoso installer like so:

cd
wget https://absolutelybaching.com/abc_installer

Then run the installer:

cd
bash abc_installer --giocoso

You'll be asked to provide your password at one point, since Giocoso needs to copy scripts to appropriate folders to which access is ordinarily restricted.

Once Giocoso has been installed, you run it most simply with the bare command giocoso (though you'll see that this soon can become more complicated, with lots of run-time options being passed to the program via runtime parameters). When you launch the program for the very first time, you'll see this happen:

That message only appears the first time Giocoso is run with all software prerequisites satisfied: a persistent configuration file is expected to be found in the $HOME/.local/share/giocoso folder, and when one can't be (as will always be the case on the very first run of the program), Giocoso will download a 'default' configuration file from the absolutelybaching servers and store it in that folder. You just press any key at this point in order to proceed. As soon as the default configuration file is downloaded, the screen will end up displaying something similar to this:

That wall of red error message text doesn't look too promising, does it?! In fact, however, it means Giocoso is running fine. The only thing happening at this point is that you are trying to run Giocoso in its default mode without there being a database to use to find music to play (because you haven't created it yet!), or without telling it explicitly not to use a database. This is described in more detail in the sections of this manual about Direct Play Mode and Database Play Mode. For now, the problem is easily corrected by appending a runtime parameter to the basic 'giocoso' command to formally instruct the program not to use a database for now:

giocoso --dbname=none

But if you type that command into the terminal now, you'll encounter another error:

Again, the red error text can look intimidating, but all Giocoso is saying here is: when you run me without a database, I must either be physically in a folder of music files I can play, or you must direct me to where such files can be found. In my case, I know I can find some music within my /sourcedata/music folder, so let me visit a folder there and try again:

This time, I'm sitting in a folder which clearly contains a FLAC file (and it must be a FLAC file: Giocoso won't play MP3s, OGGs, WAVs, ALACs or any other type of audio file). If I once again launch Giocoso with the giocoso --dbname=none command from before, I now get this result:

...and that's Giocoso happily playing the music, displaying the album art that's been embedded within it whilst it's at it!

I found I needed to reboot Catalina and Monterey to get the X server displaying album art, though I don't know if this is always a requirement (I don't recall needing to do it with my Sierra-running Mac Mini, for example). Once you've seen it once, it will work thereafter, anyway.

7.0 Creating a Database and Music Scanning

With a network drive mounted locally, you can now get Giocoso to scan the network share and create a local database of all that it finds, by typing into a terminal the command:

giocoso --createdb --dbname=mymusic --musicdir=/usr/local/sourcedata/music/classical

...or whatever path actually applies in your specific circumstances. The 'dbname' can be anything you want, though I'd avoid putting spaces in it. It would be ideal if the path to your music folder also didn't have spaces in it. However, if you need to mention spaces, you do so by wrapping the relevant parameter in double-quotes. You might, for example, do this:

giocoso --createdb --dbname="My music" --musicdir="/usr/local/sourcedata/classical music"

If you miss out the --dbname parameter entirely, then the default of 'music' will be used instead.

As soon as you submit the create database command, you'll see something like this:

You're told that the relevant database files have already been created, but now they need to be populated with the results of a scan of the music folder you mentioned. Press any key you like to make that scan start: be aware that scanning a large music folder will potentially take hours: my 2TB of FLACs, for example, takes about 4 hours to scan over a gigabit ethernet network connection. A locally-stored-on-SSD collection can be expected to be scanned a lot faster, of course.

The scan actually comes in two parts: first, Giocoso works out what music folders exist; then it interrogates each music file found within those folders to determine their tagging (who is the composer, what is the composition name and so on) and their physical characteristics (how long the music lasts for, and so on). It is this detailed tagging and duration data which ends up being inserted into the database. The screen changes as each phase of the scan takes place. Here's the first bit, where what folders exist is being worked out:

Once the detailed tag and physical attributes of each music file is being determined, the screen changes to this sort of display:

You note that the specific folder and file names are mentioned in the top part of the program display as the data is collected. Since the list of folders to visit has been sorted alphabetically, this gives you some idea of how long the scanning process will take: clearly, if I'm sitting in 'Adrian Willaert', I've got a long way to go before I finish, as there remain all the other 25 letters of the alphabet to move through in sequence!

Once the scan completes, you'll see this sort of summary screen:

As you see, you'll be told the aggregate total of the 'recordings' discovered, and the number of unique composers to whom they can be attributed. A 'recording' is simply what Giocoso finds in the ALBUM tag of each FLAC read and scanned; the 'composer' is similarly the contents of the ARTIST tag. Once you have these statistics displayed, you can get Giocoso to play music using the database as the source of information about where on the hard disk to find it by running it with a command such as:

giocoso --dbname=main

(though 'main' is just the name of my database and yours will probably be called something completely different!). Anyway, here's what happens when I issue that command on my Mac Mini:

You'll note from the top of the Giocoso window that we're in 'Database Play Mode' and using database 'Main' (Giocoso init-cases names for display purposes, but the name you supply in the --dbname parameter has to be case-aware). For some reason, Giocoso has decided to play a piece of music by William Croft: I didn't ask it to do that, but Giocoso simply picked something at random, and this is what it happens to have picked.

This, in fact, is the essence of Database Play Mode: randomisation. Without other filters and 'guidance' you may provide to it, Giocoso simply picks a composer at random (each composer having an equal chance of being selected as any other, no matter how much or how little music they may have contributed to your music collection) and then picks a recording attributed (in the ARTIST tag) to that composer. You end up hearing a completely randomly-selected piece of music.

If you want to 'guide' Giocoso, so that its selections aren't completely random, you can do so by adding one or more selective runtime parameters (which are discussed at length here). Suppose you want to play a piece of randomly-selected music that's by Beethoven? This command will do it:

giocoso --dbname=main --composer=beetho

...resulting in this slightly-modified program display:

Notice how Giocoso displays your filters to you in blue, in the main part of the screen. Again, the parameter value 'beetho' has been upper-cased for display purposes -though, in fact, on this occasion, it makes no difference how you typed in the parameter value. All textual comparisons within the database are done having first forced everything (temporarily!) into upper case. You'll also spot that though I supplied the parameter value 'beetho', Giocoso has correctly found music which it knows was written by 'Ludwig van Beethoven': parameter values such as composer name are always 'wild-carded', meaning that 'bri' could match Frank Bridge as well as Benjamin Britten.

If particular performers, rather than composers, are your thing, then other runtime parameters can be fed to Giocoso. For example:

giocoso --dbname=main --comment=robles

...produces this result:

Why is something by Handel now being played in response to that request? Well, in this case, the album art gives the game away: Marisa Robles is the harpist on the recording. You'll notice back in the main part of the Giocoso display, too, that whilst Iona Brown and the Academy of St. Martin-in-the-Fields are listed as performers, so too is Marisa Robles singled out as 'harp'.

Again, you can wild-card your searches, so 'rob' would have matched Marisa Robles too... though it would also have matched 'Robin Ireland' or 'David Robertson': wild cards can be very helpful, but also result in surprises (which, in the world of making sure you don't listen to the same music over and over again is no bad thing, actually!)

I should perhaps finally mention that these sorts of runtime parameters only achieve their proper effect when you tag your FLAC files in the manner I've documented elsewhere in my 'Axioms of Classical Tagging' articles. Specifically, I used the --comment runtime parameter to find Marisa Robles because she is a performer on a recording and all the performers of a particular recording under my tagging axioms are always typed into the COMMENT tag. There is also a --performer runtime parameter, but that only searches the PERFORMER tag -and, in my system of tagging, that only contains one name, the name of the 'distinguishing artist' that makes a recording unique from any other. That means the PERFORMER tag usually contains the name of the conductor of the piece, not the singer nor the orchestra nor the harpist! If I wanted to listen to something conducted by Karajan, for example, I could certainly invoke Giocoso with the parameter --comment=karajan, but I could also use --performer=karajan, and achieve much the same results. Why duplicate in this way? Well, sometimes you get conductors who perform. Think Benjamin Britten, for example: if I wanted to hear him as a conductor, I'd say --performer=britten. If I wanted to hear him as a pianist, I'd say --comment=britten.

Anyway: this is not the place to discuss the subtleties of tagging strategies! The point to take away from here is that once Giocoso has scanned your music collection, it can play any part of it at random -or you can provide runtime parameters to guide and shape its random choices. In all cases, the program display will tell you what's been selected to play and what filters guided that choice.

8.0 Conclusion

This article was intended to get you started with Giocoso on macOS. There is quite a bit of preparatory work to do to make macOS a suitable environment for Giocoso, because of Giocoso's dependency on X11 and Bash. Once those particulars are sorted, however, using Giocoso becomes merely a matter of learning how to use the abc_installer script to install Giocoso; how to run Giocoso in Direct Play Mode; and finally to run it in Database Play Mode, with and without filters to 'guide' the randomisation process. Hopefully, you've seen how easy it is to install and run Giocoso... after that, everything is simply a matter of becoming familiar with the array of things you can do with it.

For which the rest of this manual should be your guide!

[Back to Front Page]|[Giocoso on Linux]|[Giocoso on Windows]|[Giocoso on Raspberry Pi]