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 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.
That is why you will periodically want to run the Database Management menu, option 2 'Fast Scan for new recordings'. This program 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.
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 that whilst you can create and maintain multiple databases, you can only refresh one of them at a time, therefore.
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 deleted from disk will remain in the database
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, but nothing already existing in the database is ever altered or deleted.
By way of example, here's a simple test database I created:
The database consists of a single recording -and you can see it there, physically, in a 'testmusic' folder on my Desktop, consisting of a single FLAC, representing a String Quartet. Let's suppose I suddenly notice one day that this particular string quartet ought to have been catalogued as 'Op. 20', not 'Op. 2'. So I alter the physical file name to that effect, and I use my FLAC tagging software to adjust the 'ALBUM' tag to match:
With those changes made, I perform a Fast Scan in Giocoso and this is the result:
You will note that Giocoso still knows of a 'String Quartet Op. 2': the change to '20' in the file name and the metadata is irrelevant: though the file name changed, the folder name didn't. The lack of a folder name change means Giocoso saw nothing new to add to its database -and it never updates existing records via a Fast Scan, anyway. So everything in the database remains untouched. Let's pursue the example a bit further, then:
Here, I've created an entirely new sub-folder, called 'Grachaninov Quartets' and moved the FLAC file into that new folder. Since this does cause a change in the physical folder, this should look like a new recording to Giocoso and a new Fast Scan should pick it up:
...and sure enough, Giocoso is now reporting that it knows about a 'String Quartet Op 20'. Trouble is, as you can see, it still also "knows" about the original String Quartet No. 2! The Fast Scan only ever adds to the database. It never triggers removals from the database, even if a FLAC is physically no longer on the disk where Giocoso originally saw it. This, of course, will cause Giocoso some issues if it ever tries to play something it thinks exists on disk but which physically no longer does! Giocoso will silently work around such issues -but it's certainly an issue it has to work around 🙂
To conclude this little worked example: I could edit the metadata associated with this file in a bazillion ways -and none of them will be picked up by Giocoso:
Here, I've changed the ALBUM and TITLE tracks to mention the Amadeus Quartet, not the Utrecht. I've even changed the ARTIST tag to say this work is by Benjamin Britten. Finally, I've even altered the physical name of the file (displayed over on the left-hand side of the screen), so that it too mentions 'Amadeus' and not 'Utrecht'. Do another new Fast Refresh:
As you can see, Giocoso still firmly believes the recording to be by music written by Grechaninov, not Britten... and played by the Utrecht Quartet, not the Amadeus.
You get the idea, I hope: Fast Scans are relatively quick ways of add new data into a Giocoso music database, but are useless when it comes to updating anything about existing recordings, for nothing already extant in a Giocoso database is ever modified or deleted by a Fast Scan.
Functionally, the way a Fast Scan 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.