1.0 Introduction
When you create a database, you tell Giocoso where your music files can be found and it reads all of them and populates its database with details gathered from them. As such, the Giocoso database is first created as a snapshot of your music files: that is, a statement about what files exist, and the metadata they contain, at a specific point of time. If you add new music to your collection, or alter the details associated with existing music files, or even delete unwanted music files -well, the previous snapshot is going to be out-of-date. Giocoso will, in other words, not know about these new additions, deletions and changes. To make it aware of these sorts of changes, you need periodically to run the Database Management menu, Option 2: Fast Scan for new recordings. This option makes Giocoso take a fresh look at your hard disk, whereupon it will notice if new things have appeared it ought to add to its own database. From Version 3.30 on, it will also spot when folders which used to be accessible on a hard disk have disappeared for some reason (perhaps actually deleted, perhaps merely re-named) and remove the corresponding entries for them from its database.
Note that the fast refresh only works on the basis of folder detection. If a new folder is spotted, then fine: its file contents are analysed and added to the database. However, if you change the metadata tags associated with a FLAC file, or physically change the name of the FLAC file itself, but leave the folder name the file is inside unaltered, then that will not be detected as a change that should trigger updates to the Giocoso database. The fast refresh is oblivious to file-level alterations: but if you rename a folder or create a new folder, then the fast refresh will spot those easily and make appropriate changes to the database for you. If you need the database to be aware of file-level metadata (tag) changes, that's what Option 3: Full Scan all recordings is for.
2.0 The Fast Scan Process
The Fast Scan starts by asking you what database you want to refresh:
The dialog box is simply listing all files with a .db extension that can be found in the $HOME/.local/share/giocoso3/db folder. You arrow up and down the list until the database you want to work with is highlighted, then press the Space Bar to select it: an asterisk appears in the brackets next to the selected database name. Note, therefore, that whilst you can create and maintain multiple databases, you can only refresh one of them at a time.
Next, Giocoso will prompt you for details as to where it should look to discover new music files:
This is the same folder-selection dialog you had to deal with when first creating your database. You can navigate your on-disk folder structures by arrowing around the entries in the top pane and pressing the Space Bar when a correct folder name is highlighted. As you 'descend' into a folder, its name is appended to the full path that appears underneath the folder list, in the second panel of the form. Alternatively, you can simply type the path in that second panel, and the top panel will automatically adjust itself to display the last folder on the path you've supplied.
The folder you point to should be at the 'root' of your music collection (or, somewhat confusingly, be the top-level folder in a folder hierarchy, depending on how you think of things!): Giocoso will search every sub-folder beneath the one you point to, looking for FLACs.
Once you've got the right 'root' folder mentioned in the second panel, press [Enter] and Giocoso will run off to that folder and start searching for FLACs:
The 'Scanning file system...' message will let you know that Giocoso is at least thinking about things, but there won't be any other evidence of it actually doing any work (potentially for many minutes, if your music collection is large). Eventually, however, that one, slightly cryptic message will give way to a proper progress dialog:
You can see the specific folder being investigated at each moment, and an overall progress bar clicks slowly up to the 100% mark. Eventually, you'll see a message to say the refresh has completed: click [Enter] on that and you'll be returned to the main menu.
It's important to understand what this fast scan process will and will not do for you. Putting it simply:
- New recordings will be added to the database
- Existing recordings that have changed physical folder name will be added to the database
- Existing recordings that have had metadata changed will remain unchanged in the database
- Recordings that have been physically moved or deleted from disk will be cleared from the database (only in Version 3.30 and above: in earlier versions, the data associated with missing or moved folders would be left unaltered)
Putting it even more simply: new recordings, or old recordings that look new because their folder names have changed, are added to the Giocoso database by a fast scan. Folders now found to be 'missing' are also cleared from the database (for Version 3.30 and above). But under no circumstances are the details of non-modified folders and their contents altered by doing a fast refresh.
3.0 Fast Scans and Giocoso Pro
All fast (and full) refreshes of Giocoso are updates to the Giocoso local database only. Each installation of Giocoso on different music-playing computing devices will have its own, unique database, periodically refreshed and kept accurate by fast or full refreshes.
However, the release of Version 3.30 introduced the concept of 'Giocoso Pro', whereby a device's local database contents can be 'pushed' to a remote MySQL/MariaDB database that is shared amongst all music-playing devices. Accordingly, from that version onwards, and if Pro functionality has been enabled by setting a remote database server's IP address in the Giocoso configuration file, a fast refresh will complete its local work by going on to copy the refreshed local RECORDINGS table to the remote shared database. Essentially, the local RECORDINGS table's data is inserted into the remote database's GLOBAL_RECORDINGS table.
This data copying process is always a complete replacement of the GLOBAL_RECORDINGS table contents. It starts by deleting all rows from that table and then re-loading it from scratch. In this way, the GLOBAL_RECORDINGS table always contains up-to-date data about the recordings that the device doing the fast refresh can and can't see. This thorough approach does mean, however, that a fast refresh might no longer be particularly fast!
If you are using Version 3.30 or higher of Giocoso and have not enabled Pro functionality, then fast refreshes do as they have always done and keep only the device-specific local database up-to-date.
Note the implication here: if Device A refreshes itself, it wipes and replaces the global_recordings table that all devices see and use. If Device B then comes along and refreshes, it will wipe and replace the global_recordings table... and so on for every other device. The assumption underlying Giocoso Pro, however, is that all devices see the same digital music collection, so Device B really didn't need to do a refresh at all if Device A had already done it: they'd both be scanning for the same files and both would discover the exact-same number of music files. In other words, in a Giocoso Pro environment, pick one device to be the one that does routine refreshes: all other devices just need to be pointed to the global database to get their source of plays. They themselves do not need to perform routine refreshes to pick up the latest arrivals to the collections, provided only that one designated device has done so.
4.0 Scheduling Fast Scans
If you are actively adding new recordings to a growing music collection, you will probably want to perform frequent full scans so that new folders of music are recognised and added to Giocoso's database of 'playable' music. Obviously, you can take the Database Management menu, Option 2 and do the job manually... but you can also use one of Giocoso's few remaining runtime switches to schedule the running of the appropriate database refresh operation without you needing to be present to watch it plod its tedious way to completion!
To this end, it's possible to schedule fast and full scans (using a tool such as cron). Here are my own crontab entries:
# Refresh the Giocoso Database every night at 11pm
# ----------------------------------------------------------------
0 23 * * * /usr/bin/giocoso3.sh main /sourcedata/music/classical --fastrefresh
# Full Refresh Giocoso every 1st and 15th of month at 4am
# ----------------------------------------------------------------
0 4 1,15 * * /usr/bin/giocoso3.sh main /sourcedata/music/classical --fullrefresh
When launching Giocoso in this manner, as well as having to pass the database name, you have to pass the root of your music folder and, finally, the type of database refresh you want to perform as a double-hyphened 'switch' or parameter. In this case, I'm scheduling a fast refresh every night at 11PM (23:00 for military types!) and saying to refresh a database called main, finding music in /sourcedata/music/classical and that I want a --fastrefresh, not a full one. I also schedule 4AM full refreshes on the 1st and 15th of every month... but full refreshes are a matter for another bit of documentation!
Summing up, therefore: to schedule a database refresh (from Version 3.30 up), you pass database, music folder and fast or full runtime switch, in that order, to the basic command needed to launch Giocoso. The rest is down to standard cron shenanigans (for which Crontab Guru is an excellent guide!)
5.0 Conclusion
Fast Scans are relatively quick ways of adding new recordings into a Giocoso music database, and for pruning out old ones that no longer exist. They are, however, completely useless when it comes to updating the metadata associated with existing recordings, since fast refreshes see folders, not files ...and thus the metadata within a file can be changed as often as you like and the fast refresh process will never spot the alterations!
Functionally, the way a Fast Refresh works is as follows:
- Produce a list of unique folder names already in the database
- Go off to the file system and produce a list of unique folder names from there
- Compare the two lists
- If anything on the second list is not already in the database, those are 'new folders'
- Visit every new folder discovered and add the metadata for the FLACs found there to the RECORDINGS table
This is why folder name changes to existing recordings will trigger the addition of the newly-named recording to the database, whereas mere changes to file names or any metadata changes will not.