1.0 What is Giocoso Pro?
Giocoso Pro is the name I've given to Giocoso's new capability (starting with Version 3.30) to communicate with, and post data to, and remote MySQL or MariaDB database. It doesn't cost money and doesn't require new software: it's baked into ordinary Giocoso and merely has to be switched on to use (see below for how to do that). It means a particular installation of Giocoso running on, say, a desktop PC, can have its local plays and recordings tables copied to a network-accessible database where the data becomes rows in the global_plays and global_recordings tables.
The point of doing that is to enable a separate, isolated instance of Giocoso 'see' what every other separate, isolated instance of Giocoso has been up to -and that's important, for example, if you want to 'play unplayed music by Haydn' on your laptop. Before the advent of Giocoso Pro, the laptop would have told you what it thought was unplayed Haydn, totally unaware of the fact that you've been playing Haydn like mad on the main listening room PC. Giocoso Pro makes the laptop aware of every play performed by every device in your home, so it's new assessment of what Haydn remains unplayed will now take account of the Haydn you've been playing on the main PC.
As another example: Giocoso has long had a 'time-bar': a period of hours during which playing music by a previously-played composer is impossible. By default, it's 6 hours, so if I play something by Bruckner at 9AM, I can't hear any more Bruckner chosen at random until at least 3PM. However, if I play the 9AM Bruckner on my laptop and then move into my listening room at 11AM, the listening room PC won't know that Bruckner's just been played and so thinks it's a valid random choice at 11AM. Giocoso Pro fixes that: since the laptop and listening room PC both 'see' the same history of plays, both know that Bruckner is blocked from random selection until 3AM.
From a mere 'data accuracy' point of view, too, Giocoso Pro fixes a long-standing problem. If my play statistics tell you I've played 18,879 recordings, that number had better be accurate... but it won't be if it's merely coming out of my main desktop PC's local Giocoso database! It won't be taking account of the several thousand plays I may have performed on my laptop PC, for example, or the several hundred played in the garden shed on it's ancient PC. Giocoso Pro pumps all three devices' plays into the one global_plays table, though: so if the play statistics come from that instead, the figure really will be accurate.
In short, the concept of Giocoso Pro is that each separate computing device accesses the one music collection (so file paths are, more or less, identical for each); each has its own local installation of Giocoso in which plays are recorded; but each now posts its plays data to a database that is shared amongst all music-playing devices. All devices thus become aware of what the others are doing and all statistics produced from the global database will be an accurate summary of what all devices have been playing.
2.0 Requirements
2.1 A Giocoso Pro Server
To make Giocoso Pro work, there has to be a MySQL or MariaDB database running somewhere on the home network, accessible to all music-playing computing devices. By way of immediate clarification, MariaDB is the free and open source fork of the original MySQL database: they are almost the same thing (any differences are irrelevant at the level at which Giocoso works) and their names can therefore be used interchangeably. Where this documentation uses one name, you may infer the other. The 'MySQL' name will tend to be used more commonly, because it's shorter to type, but almost all Linux distros these days supply MariaDB even when you explicitly ask to install 'mysql', because it is free of the commercial peril attendant on using the Oracle Corportation-owned MySQL.
Anyway: there needs to be a MySQL server. It needn't be an expensive, dedicated server: it needs about 2GB of RAM and 10GB of disk space or so. You can run it in a virtual machine, or even on the same computer that's running an instance of the Giocoso client software. A new script is supplied (downloadable from doco.absolutelybaching.com/pro) that you can run on a freshly-built Linux operating system that will download all the right software and configure it in such a way as to turn a blank, new server into a suitable Giocoso Pro server. I've also produced a guide to setting up a suitable server on Arch and further guides for different Linux distros are also available.
2.2 Switch on Pro features in each Giocoso client
Apart from that, your clients (the individual music-playing computing devices running Giocoso) need to be running Giocoso Version 3.30 or higher. Once upgraded to that version, the Administration menu, Option 2: Create or Edit the Configuration File will acquire three new options on its first page of 'parameters requiring text entries':
You turn on Giocoso Pro capabilities by entering the IP address of your Giocoso Pro Server in the Remote MySQL Server IP Address field. If you have previously enabled Pro capabilities by filling this entry in, you can turn them off again at any time simply by blanking this entry out.
MySQL usually listens, by default, for connections from elsewhere on the network on port 3306: you probably won't need to change that value in the Remote MySQL Server Port entry, therefore, but if you decide to craft a non-standard MySQL implementation that listens on a non-default port, you can specify that here now.
2.3 Specify a Local Folder Prefix
Finally, the Local folder prefix entry needs some explanation! Recall that Giocoso Pro is about multiple music-playing devices seeing the one collection of music files (perhaps stored on a NAS or some other network-shared folder), so it is assumed from the outset that if you've got a folder called (say) /Beethoven/Symphony No. 5 on one device, there'll also be a /Beethoven/Symphony No. 5 on all the other devices. However, the precise location where that folder can be found might well change. How so? Well, my main PC is the 'source of truth' for all my music collection: it's found in /home/hjr/Music/classical, so that particular folder would live at /home/hjr/Music/classical/Beethoven/Symphony No. 5 on that particular machine. But I copy my Music folder and all its contents to a NAS device, where it is stored in /mnt/bulkdata/music, so the exact location of that folder on that device would be /mnt/bulkdata/music/Beethoven/Symphony No. 5. And on a different PC, I mount the NAS share at /netmusic, so for that device the path would be /netmusic/Beethoven/Symphony No. 5.
You get the idea, I hope: the exact same folder and its music contents can appear to have different paths, depending on what device is using it and how that particular device has been configured to access a shared music collection. Yet a shared database of global recordings needs to be able to describe where to find this recording of Beethoven's fifth regardless of which device is trying to find it.
Here's a specific example, using my main desktop PC (called 'zelenka') and my listening room PC (called 'schumann'):
On PC 'zelenka', you see the same data as you do on PC 'schumann', but the specific path to get to that data is different in each case. We therefore need to 'generalise' a file's location, separate from its particular location on a specific device. In the above screenshots, I hope you can see that /classical/A/Aaron Copland/Ballet would apply to both machines, but that /home/hjr/Music and /sourcedata/music would be specific to each machine. We call the 'apply to both' bit of the path the 'file suffix', and the device-specific bit the 'file prefix', and it's this prefix which you type into the configuration file for each device running the Giocoso client. Precisely where you cut the full path into prefix and suffix can be subject to some nuance, provided only that you end up with invariant and variant parts which apply to all machines. In practice, therefore, I actually declare /home/hjr/Music/classical and /sourcedata/music/classical as my prefixes, though things would work if I moved the '/classical' bit into the suffix instead.
Whatever you supply as a file prefix is removed from the actual file path when a client device's local recordings are pushed to the global database, so that the global_recordings table only stores the file suffix. Here's what my global_recordings table looks like, for example:
The point is that when a client device says 'select me a recording I can play', the global recording table will only tell it to play '/A/Aaron Copland/Balklet/Appalachian Spring (Bernstein - 1961)', because that's the 'device-agnostic' location. Each client then bolts on its own 'file prefix' to that to turn it into a physical location that makes sense to that device. In the case of my schumann PC, therefore, it will end up hunting for a folder called '/sourcedata/music/classical/A/Aaron Copland/Balklet/Appalachian Spring (Bernstein - 1961)', because it will bolt on its '/sourcedata/music/classical' local prefix to whatever it receives from the global database as the file suffix. My laptop will bolt on '/netmusic/music/classical', since that is it's particular file prefix (because I'm not consistent about where I mount my NAS on different devices!), and thus it will look for the same file as before at '/netmusic/music/classical/A/Aaron Copland/Balklet/Appalachian Spring (Bernstein - 1961)'.
3.0 Client Changes once Pro Mode enabled
3.1 Changes to the Giocoso program display
Once an IP address to a remote server has been specified in the persistent configuration settings (see Section 2.2 above), Giocoso's main program display will change in a couple of ways:
You'll notice firstly that the 'Using database' display will not only show you the name of the local database it's using (in my case, one called 'Main'), but will also show you the IP address of your Giocoso Pro server. It's important to remember that even though you're operating Giocoso in 'pro mode', which means it uses a remote database to work out what to play and to store details of what it has played, that remote database is used in addition to the local database, not instead of it. When you use the 'Database Management' menu, for example, to perform fast or full refreshes, you're still updating the local database first. Being in pro mode simply means that once the local database has been updated, the data is also then copied to the remote database. It's therefore quite proper that Giocoso's main program display reminds you that there are two databases in use now, not one.
The second change you'll notice is the appearance of a new top-level menu option, called Pro:
This new menu contains eight options, a lot of which you are unlikely to use very often! For our current purposes, the critical option is Option 1: Initialise a remote Global Database.
3.1 Initialising the Remote Database
When you built your remote Giocoso Pro server (see Section 2.1 above) you will have run a script that turns a blank MySQL database into one that contains tables and views and indexes that Giocoso will need to use: but all those tables are currently empty. So this new Option 1 is what you take from any one of your client Giocoso devices to populate them. Hopefully, it's obvious that you only initialise from one of your client devices! If you do it a second time from a second client, it will erase the data pumped there from the first and replace it with its own play history. The first device's play history isn't lost, of course: it's still safely there in its local database and can be re-pushed to the global server at any time... but then it will over-write the second device's play history, and so ad infinitum!
So, you pick one client device to initialise the remote database. It doesn't really matter which client device you pick to do this task, but I'd pick the one with the most number of plays. You select Option 1 to initialise the remote database:
3.2 Transferring Subsequent Client Devices' Play Histories
On all other client devices, you want their particular and unique play histories pushed to the remote database, but without erasing the play histories that got transferred earlier: that's what Option 3: Re-Push Plays to remote database is for. That does not wipe the remote plays table: it adds to it. You take Option 3 on every client device that isn't the first one. You can take it as many times as you like on the same device, too: the process is guaranteed not to double up the play history records so though it may look a device's plays are being pushed a second or third time, actually in the remote database no extra rows are being inserted into the global_plays table.
3.3 Clients and Recordings
You'll notice that the new Pro menu has two options explicitly involved with doing things with recordings: Option 2: Clear the remote recordings table and Option 4: Re-Push Recordings to remote database. These should rarely need to be used. The basic premise of Giocoso Pro is that all client devices are accessing the one music collection, though it's accepted that the specific paths to particular files within that collection might vary between devices, depending on how the remote storage is mounted on each device (see Section 2.3 above). So, by the first client device initialising the remote server, it has already pushed it's prefix-stripped version of the location of the music collection's recordings to the remote database... and thus no other device should ever need to do so again, because it's the same collection!
Moreover, the remote database is kept up-to-date by local database refreshes. If you physically add a new recording to your collection, therefore, a database refresh on one client device picks up that new recording, adds it to its local database ...and then pushes that new piece of data to the remote database, thereby informing all the other devices of its existence, too.
So, again: there really ought never to be a need for any client device to fiddle with the remote recordings table, except by one of them initialising it using Option 1. Nevertheless, Option 2 allows a client to completely wipe the remote recordings table (literally erasing all data from it). Option 4 then allows a client device to push its entire local recordings table to the remote database, re-populating it ab initio. If you take Option 4 repeatedly, without first taking Option 2, the process will once again appear to be re-pushing data to the remote database, but actually no data is being inserted at the remote end, because it's impossible for the same recording to exist twice in the remote database.