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

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!

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

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

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

7.0 Installing Giocoso

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


Then run the installer:

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.

<more stuff to write here after delivery of iMac>

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.

8.0 Cosmetic Issues

Get size and title bar correct:

For further terminal refinement, consider installing something like iTerm2, which allows you to assign a hotkey sequence that will reveal/hide a terminal window, in the style of the Linux Yakuake or Guake drop-down terminals. This makes things disappear very neatly when not needed.

9.0 Networking Issues

My music library actually exists on a Linux server in the loft, not on a local hard disk. It's shared via NFS -so I need my iMac to be able to mount the network share as though it were its own local folder. Munting NFS shares in macOS, however, is a bit trickier than I'm used to, so I thought I should document it here!

First, create a blank /etc/fstab file by issuing the command:

sudo nano /etc/fstab

Once the new text file is open, type in something similar to what you see here:

The 'jsb:/bulkdata/music' bit is the 'address' of my network server. It's called 'jsb' and its NFS share is located at mountpoint /bulkdata/music. I'm then saying 'mount that locally in a folder called /usr/local/sourcedata' (which doesn't exist yet, but I'll sort that out before long). The remaining parts of the line are standard macOS NFS settings:

nfs     rw,nolock,noatime        0  0

The 'nfs' bit says 'this is an NFS share'; the other three options then say 'make this share read-writeable, without locks and without constantly trying to timestamp files with the last time they were accessed' (both of which would slow down access to the share massively). The closing '0 0' needn't detain us, but are fairly standard.

Save the edited file, then issue these commands to create the /sourcedata folder we promised in the fstab file would eventually exist:

sudo mkdir /usr/local/sourcedata
sudo chown -R $(whoami) /usr/local/sourcedata

I should point out that I'm having to use a mountpoint here that is hanging off the /usr/local folder (which, you'll remember, we created earlier and specifically granted ourselves rights over). In earlier versions of macOS, it would have been possible to create a mountpoint of (for example) /sourcedata -directly hanging off the root folder, in other words. That is not possible in anything from Catalina upwards. Attempting to use a folder hanging off root in these examples in Catalina and above merely produces a 'read-only file system' error, and there's no neat and easy way to work around it. On macOS, therefore, no matter what version you're using, I'd strongly advise getting used to using non-root-based mountpoints.

Now, we're not done yet! If you simply left things like this, you might well be able to mount the network folder, but you'd probably find that the permissions on that mounted network drive would be incorrect. This is because (at least in my case!), the server is using Linux and the client is using macOS... and, unfortunately, Linux assumes user IDs which don't apply in the Mac world. For example, on the Mac, I can issue the id command and get this sort of output:

You needn't worry about most of that -but pay attention to the 'uid' bit right at the start: it's saying that the account 'hjr' is assigned the User ID number 501. Now repeat the exercise over on your (Linux) file server:

You'll notice that the reply from the Linux server is a lot less verbose than the Mac manages to be! But the crucial bit is that on this Linux server, user account 'hjr' has been assigned User ID number 1000: assigning user ID's from 1000 upwards is, in fact, fairly standard Linux practice.

Now, the problem is that my music folder on the server will declare themselves to be owned and read-writeable by user 'hjr'... but what that really means is that they are owned and read-writeable by an account with User ID of 1000. You now connect to this from a Mac that says you are user ID 501 and the result is going to be: no access to these files for you! Fortunately, there;s a fix:

This is the /etc/exports file on the server: the file which declares what filesystems are exported via NFS to clients. You can see I have several of them to share around -but the crucial point is all the 'export options' shown in brackets after each folder is mentioned. The crucial ones from the Mac's point of view are:


Those three options are simply bolted on to whatever other share options I may have had there before, comma-separated and with no spaces anywhere. They say 'if someone accesses this share from a remote client, please convert (or 'squash') their actual User IDs into being number 1000'. It also squashes their group id into 1000, too, but that's not quite as important. The net effect, anyway, is that if I now access this network share as Mac user 'hjr', ID=501, the Linux server will treat me as being Linux user 'hjr', ID=1000... and that means I'll have the full access to the network share that I need.

If you ever alter the /etc/exports on a Linux server, you need to re-export the network shares with the command:

exportfs -ra

Again, you issue that command on the file server, not on your Mac. Once you've done that, you're finally ready to 'attach' your Mac to the network share with the command:

sudo mount /usr/local/sourcedata

You should then be able to 'cd' to the local mountpoint folder and 'see' network data:

And if you can see your networked music files, so can Giocoso... which means it's time to get Giocoso to scan your music folders!

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

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=mymusic

Notice there's no need for a --musicdir parameter any more: now that the database 'knows' where the music is located, you don't need to explicitly tell it. The database name does need to be supplied (because you might have multiple databases -one for classical opera, one for classical orchestral, one for jazz and so on). However, Giocoso Version 2 now uses a persistent configuration file to store 'defaults' for such things. It's located at $HOME/.local/share/giocoso and is called giocoso.conf. Accordingly, a command such as:

nano $HOME/.local/share/giocoso/giocoso.conf

...should yield this sort of result:

The configuration file is just a text file and one of the parameters it mentions is DBNAME=music, meaning that 'music' is the default name of the database Giocoso assumes it should use. If you've created a differently named database, just replace the 'music' bit here with the name you chose:

Save the edited file (in nano, that's Ctrl+X, y, [Enter]) and now you can run Giocoso with the simpler command:

giocoso that not even the --dbname parameter is required any longer: Giocoso will work out the database to use by reading the name from within the configuration file.

11. Conclusion

I'll stop at this point, since you will by now hopefully have Giocoso installed and running on your Sierra-and-up piece of Apple hardware and will have managed to get it reading music over a network (if that's your thing) and running with a stored database of what music exists where. Those are, in fact, the hardest things you ever need to do with Giocoso, so I'd say the back of this particular issue has been well and truly broken.

[Back to Front Page]