BBritten.com - softwares:giocoso:dbmenu

backupdb

Anonymous (anonymous@undisclosed.example.com) — 2025-11-22T12:41:33+00:00

Backup A Database

Keep in mind that most of a Giocoso music database, by design, can always be reconstructed from scratch by doing a Full Scan (Option 3): so long as your music files are safe on disk somewhere, you can always get Giocoso to have a fresh look at them and thereby re-create the RECORDINGS table.

But there's the rub: a Giocoso music database is more than just the RECORDINGS table: it's also the PLAYS table, storing the history of everything you've ever played with Giocoso… and that definitely can't be reconstructed, should it ever be lost or corrupted for some reason. Protecting your history of plays is thus a rather important thing to do on a fairly regular basis. The Database Management menu Option 6 has accordingly been provided to make taking a backup of your local music database, including its previous play history cargo, as painless as possible.

I should mention that this option really does only work on the local database: backups of any remote, shared Pro database you might be using are handled in a completely different way. It is also true to say that a Pro database is a sort-of backup of your local system's PLAYS table. In a Pro context, every music play is recorded twice: once in the local database and then on the remote database. You could lose your local database completely… and yet the Pro database will still know what you have listened to. Nevertheless, even in a Pro context, it's a good idea not to lose your local PLAYS table… so, backing it up remains an important thing to do.

Performing such backups requires that you first say where you want your backups saved to: take the Administration menu Option 3 to edit the configuration file. Once you've selected the database you want to work with, you'll see this:

The 'Folder where to write database backups' value is a full path to the location where you want backups stored: in the case above, I'm proposing to store things in my home folder, /home/hjr. The default folder is /tmp, but you can set the path to be anything you like, provided only that it exists and you've got permissions to write there. If you were to specify a folder that doesn't exist, for example, then the value is automatically replaced with /tmp anyway.

Once the backup folder has been configured in the Persistent Configuration file in this way, you can simply take the Database Management menu Option 6 to create a fresh backup:

You have first to specify which database you want backed up: you can only backup a single database at a time, no matter how many others might exist. Just up- and down-arrow through the list until the right database is highlighted, then press the Space Bar to select that entry. An asterisk will appear in the brackets next to the database name. Press [Enter] to submit the selection when ready: nn practically no time at all, you'll see this message appear:

Press [OK] to dismiss that message and you'll be returned to the main menu. But what exactly has been produced by this process and where is it?! Well, it's time to break out your PC's file manager:

Here, you see my /home/hjr folder: and the latest entry in it is a file called 'main_Classical_database…something or other'. If you compare that with the name of the database I selected to backup about three screenshots back, you'll be able to work out that the backup file created by Option 6 starts with the name of the database being backed up. The word -backup- is there, too, so that you know, er, that it's a backup of the database! Finally, a time-and-datestamp is appended to the end of the file name (so, you can tell my backup was taken at 10:03 in the morning on 6th November 2023), along with a .tar file extension.

The tar extension tells you that this backup is created as a 'tape archive' -that is, as an uncompressed bundle of folders and files, wrapped up into a single output file. On most Linux distros, you can right-click a tar file and say 'open in Ark' or some equivalent 'archive extractor' tool. If I do that now and click to open all the nested folders included in the tar, you'd see this:

You can see the entire file structure, right down to the .local/share/giocoso3/db from which the data for this backup was sourced. However the db folder inside the tar file only contains the .db file for the selected database (and any related files, such as the .db-wal and .db-shm files needed to make the Giocoso database work properly).

Recovery from this backup would therefore consist of grabbing those three files out of the tar file and copying them manually into the 'real' $HOME/.local/share/giocoso3/db folder, over-writing anything sharing the same file names.

Since backups are so important to do, Giocoso provides one of its few remaining runtime switches to create them on a scheduled basis, without manual interaction. The relevant command is simply:

giocoso3.sh --backup

…which will backup the default database (as specified in the Persistent Configuration file) only. Backing up non-default databases is only possible using the Database Management menu Option 6 interactively. As an example, here's how I backup my primary music database on a nightly basis, using the crontab on my music PC:

# Backup the Giocoso Database every night at 2am
# ---------------------------------------------------------------- 
0 2 * * *      /usr/bin/giocoso3.sh --backup

Bear in mind, however, that the Giocoso database is only a file on a file system: you can perfectly well use standard file system tools to take backup copies of it at any time, without needing to use any of Giocoso's built-in backup capabilities. Here, for example, is another crontab entry I use to create remote backups of all my Giocoso databases in one hit:

# Backup the Giocoso Database every Tuesday at 6pm
# ----------------------------------------------------------------
0 18 * * TUE     /usr/bin/rsync -avh --delete $HOME/.local/share/giocoso3/db/ hjr@remote_server:/home/hjr/Documents/GiocosoBackups

…which simply copies everything sitting in my Giocoso /db subfolder into a single folder on a remote server. The backup gets over-written every week by the newest backup, but that's OK for my purposes. Simple use of 'cp' and 'mv' could achieve similar results. The main point to make here is not that it necessarily matters how you backup your music database… but that you should back it up! Your music play history is at risk if you don't.

| Back to Software Home | Back to Giocoso Documentation Home | Back to Database Management Menu |

createdb

Anonymous (anonymous@undisclosed.example.com) — 2025-11-22T12:03:41+00:00

Create A Music Database

All music databases have to be created in the first place: the Database Management menu Option 1 will first prompt you to supply a name for the database you're about to create. The name can be anything you like, though it's case-sensitive and spaces will be converted to underscores:

If you were to supply what you see above as the database name, for example, you will eventually end up with this physical outcome:

You'll note that all created databases end up in the $HOME/.local/share/giocoso3/db folder, with a .db extension tacked onto the end of their name (and, as I say, with underscores used to replace spaces, but with any upper/lower-case letters preserved).

Since a database name maps to a physical file on disk, if you try to create a database with a name that already exists, you'll be told about the problem:

The only thing you can do at this point is press [Enter] and try typing a new name that doesn't conflict with that of an existing database.

As soon as you've supplied a unique database name that doesn't already exist, Giocoso will prompt you to point at the folder which sits at the root of the folder structure which contains your music files, so that a scan of them and their metadata can take place -and the scanned data will then be loaded into the new database:

This screen can be tricky to use properly! The general idea is that you use the upper 'pane' to move around your hard disk's folder structure, whilst the second low-height panel records the full path currently achieved. The tricky bit is that the two panels are inter-linked, so if you simply type a path in the second panel, the upper panel's contents will change to reflect that, just as if you press [Space Bar] on a folder name in the upper panel, that counts as 'entering into' the highlighted folder, whose name thus gets added to the path appearing in the second panel. It takes a bit of getting used to, is the short version!

As mentioned, your job is to point to the 'root' or top-most folder in your music file storage structure. For example:

From this screenshot of my file manager, you can see I keep all my music inside the /sourcedata folder -but that, within that, there is quite the forest of folders and sub-folders! Thus you see a particular FLAC file stored inside a folder whose full path is /sourcedata/music/classical/C/Camille Saint-Saëns/Ballet/Ballet from Henry VIII…. So the question is, what folder would, when pointed at, imply 'catching' all my FLACs in one go. It's no good me pointing at /sourcedata/music/classical/C, because though that would mean scanning Saint-Säens, Dittersdorf, Abel, Weber, Nielsen and others, I would not end up scanning and Aaron Copland or Benjamin Britten! Meanwhile, if I pointed at /sourcedata, that would catch too many FLACs -because I don't want anything in 'backups' or 'audio' to be catalogued as part of my music collection.

I should point out here that there's an implicit truth being touched on here: a good music catalogue is also a good physical folder structure! Ideally, your physical folder structure will mirror your logical data structures as contained within your FLAC metadata. Having physical and logical structures mirror each other like this means you can easily navigate your music collection using both standard tools (like a file manager) and logical tools - such as a selection filter in a music player! If the two are fighting each other, life gets much more complicated than it needs to be :)

Anyway: I digress. For my purposes, the correct folder to point to would be /sourcedata/music/classical. That captures all the A, B, C… and so on sub-folders (and everything they, in their turn, contain). Having used the folder-choosing dialogs to point to that location, Giocoso goes off to scan it for any possible FLACs, which can take a long time for a large music collection -and nothing much happens as it searches, so it can look like Giocoso has frozen: be patient with it! Eventually (after a couple of minutes, perhaps), you'll see this sort of thing:

You can see that it has worked out how many folders within the file storage hierarchy you pointed to contain FLACs… and it visits every single one of them in turn to inspect the FLAC files themselves. The percentage bar in the middle of the screen will gradually increment as the file inspections take place. Again, for a large music collection, this inspection process can take a long time: my 15,388 folders get scanned by an asthmatic 2012 i5 CPU in about an hour, for example.

This process is actually a 'full scan' refresh of the database contents -something that you can trigger yourself, without the initial database creation bit, by selection Database Management menu Option 3.

A full scan wipes every table in the database (apart from the PLAYS one, which obviously at the point of database creation has nothing in it anyway!) and populates it from scratch by extracting the metadata tags from every FLAC inspected, then aggregates the individual tracks into per-recording entries in the RECORDINGS table. When considering what data Giocoso takes from the FLAC files and stores in its database, it helps to think about what use it will eventually put that data… and the best example of that I can think of is the Play Music menu Option 2 search filter:

When you search for a 'Composer Name', you're actually searching what Giocoso calls 'Composer' -and that is extracted from the FLAC's ARTIST tag. Similarly, the 'Composition Name' search field is internally called 'composition', and that's extracted from a FLAC's ALBUM tag. The complete set of search field, Giocoso internal name and source FLAC tag is as follows:

Composer Name = composer → ARTIST tag
Composition Name = composition → ALBUM tag
Genre = genre → GENRE tag
Performer = comment → COMMENT tag
Distinguishing Artist = performer → PERFORMER tag if present, otherwise the COMMENT tag, truncated at first comma, colon or open parenthesis
Duration = duration → computed by adding the per-track durations of all FLACs housed in the same folder

It's important to note that Giocoso's composer is derived from the ARTIST tag; the composition name is derived from the ALBUM tag; and the complete list of performers on a recording is derived from the COMMENT tag (all exactly as explained in my Axioms of Classical Tagging article, in fact).

Confusion may arise between 'Performer' and 'Distinguishing Artist'! In Giocoso's world, 'performers' are the complete set of people performing on a recording: Herbert von Karajan, the Berlin Philharmonic Orchestra and Christa Ludwig would all be 'performers' on a recording of Mahler's Rückertlieder, for example …and would all be listed in the COMMENT tag of those FLACs. Only one of those artists counts as the 'distinguishing artist', though: the one artist whose presence distinguishes this recording of those songs from any other. Many people might think Christa Ludwig is that person; many others might regard Karajan as the more readily-identified person of significance: there's no rule of the Universe that says it should be one or the other… but it can only be one!

Well, in an ideal world, you'd pick one and write it into a PERFORMER tag: and if a dedicated PERFORMER tag is present, Giocoso will extract the data from that and stick it in a column it internally also calls 'performer' and which the search filter references as 'Distinguishing Artist'.

If you don't have a dedicated PERFORMER tag, though, then Giocoso improvises: it again looks to the COMMENT tag and grabs the first name it finds before the first comma and assumes that first name is the most important or 'distinguishing' artist.

So, if you've tagged your Mahler songs with COMMENT=Herbert von Karajan, Berlin Philharmonic Orchestra, Christa Ludwig (mezzo-soprano), and there's no dedicated PERFORMER tag present, then Giocoso will grab Herbert von Karajan (the first name before the first comma) and use that as what it calls the 'performer' and what the search filter refers to as 'Distinguishing Artist'.

Obviously, that makes a difference as to what fields you'd search if, one day, you fancied listening to something being sung by Christa Ludwig.

The automatic determination of a PERFORMER tag uses three bits of punctuation to determine where names stop and lists start: commas, colons and open brackets. For example, if your COMMENT tag was Utrecht String Quartet (Eeva Koskinen (violin), Katherine Routley (violin), Sven Arne Tepl (viola), Sebastian Koloski (cello)), the performer value in Giocoso's database would end up being Utrecht String Quartet, because the 'chop' at the first open bracket would break the whole string at that point. Another example: a COMMENT of Rinaldo Alessandrini, Concerto Italiano, Akademia: Ensemble Vocal Regional Champagne & Ardenne, Deborah York, Patrizia Biccire, Sara Mingardo would result in the distinguishing artist being Rinaldo Alessandrini, because the first comma kicks in as the delimiter at that point. Finally, Robert King: The King's Consort in COMMENT would become Robert King as distinguishing artist, because the first colon acts as the only available delimiter.

Generally, it's not a great idea to have to guess what a program has interpreted as the distinguishing artist if you're intending to use that data later on! It's therefore best if you make sure your tagging software creates proper, dedicated PERFORMER tags (as my own Semplice program does, for example), long before Giocoso gets to look at the metadata. Then all you have to remember is COMMENT is all the performers, and PERFORMER is the one, special performer that makes this recording particularly memorable.

Anyway: once the analysis of the discovered FLACs has completed, the progress bar will disappear and be replaced with this message:

Press [Enter] to submit an 'ok' response, and you'll be returned to the main menu:

You might notice that the blue text at the top of the display now says you are using (in my case) 'Main_Classical_database': that indicates the newly-named database has been created and populated correctly and is ready to use: you could press P, then tap 1… and music chosen at random from your database will then begin to play. Be aware, however, that unless the Persistent Configuration File (see Administration menu, Option 2) lists (again, in my worked example) 'Main_Classical_database' as the default database, then the next time you launch Giocoso, this is not the database that will be used for other plays automatically.

In Summary, therefore: Creating a database means (a) providing a unique name that doesn't already exist; and (b) pointing Giocoso to a folder within which the music you want Giocoso to catalogue can be found, after which © Giocoso performs the equivalent of a 'full refresh' of the new database. Metadata tags embedded with each discovered FLAC are used to populate the Giocoso database with values that can subsequently be searched and filtered by, thereby allowing Giocoso later on to play music you want to be played. A freshly-created database can be used immediately to play music, but won't subsequently be used automatically unless the Persistent Configuration file mentions it, by name, as the 'default' database.

| Back to Software Home | Back to Giocoso Documentation Home | Back to Database Management Menu |

fastscan

Anonymous (anonymous@undisclosed.example.com) — 2026-02-06T22:36:41+00:00

Fast Scan For New Recordings

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

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.

Where a full local refresh triggers a complete replacement of the GLOBAL_RECORDINGS table content, a fast local refresh triggers a process of working out what records the local database has the remote one hasn't (those 'missing' records need to be added to the global table). There's also a process of working out whether the global database knows about recordings that the local database no longer thinks exist: those need to be removed from the remote database. In either case, a full or fast refresh keeps the remote database completely 'in sync' with the local one, but the fast refresh is, as its name implies, considerably faster to perform than a full one, especially if it's just a question of keeping the databases informed after you've catalogued 3 or 4 new CDs that day!

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 itself locally, it too will want to 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, the sensible thing to do is to pick just 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. For this reason, the Administration menu, Option 2 allows you to designate a Giocoso installation as being a Primary Device:

If you declare PC 'A' to be yes, a Primary Device; and you further declare PC 'B' to be, no, not a Primary Device; then when PC A performs a fast refresh, its RECORDINGS will become the new GLOBAL_RECORDINGS table. PC B running in Pro mode will then immediately become aware of any new recordings that PC A has discovered: it doesn't need to do a local fast refresh at all. If it were nevertheless to perform a local fast refresh, its results would not be pushed to the Pro database: non-primary devices don't push their RECORDINGS table to the GLOBAL_RECORDINGS one.

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 how precisely full refreshes work is a matter for another bit of documentation!

Summing up, therefore: to schedule a database refresh you pass database, music folder and a 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 the Crontab Guru website 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 to metadata values will not.

| Back to Software Home | Back to Giocoso Documentation Home | Back to Database Management Menu |

fullscan

Anonymous (anonymous@undisclosed.example.com) — 2025-11-22T12:06:05+00:00

Full Scan All Recordings

1.0 Performing a Full Scan

Fast scans are great for picking up the existence of new recordings. From Version 3.30 onwards, they also clear out old recordings that no longer exist on disk. A Fast Scan, however, never picks up modifications to the metadata inside existing FLAC files. For that, you'd need to completely re-scan your music collection, starting with a totally blank slate -and that's called a Full Scan and is what the Database Management menu Option 3 will do for you.

When you first take this menu option, you are required to specify which database you want to refresh:

The form will simply list every file with a .db extension that's found in the $HOME/.local/share/giocoso3/db folder. Whilst there may be many such files, you can only select one of them at a time with this form: you simply arrow up-and-down the list of file names until the correct one is highlighted, then press the Space Bar to select it. Doing so causes an asterisk to appear in the brackets next to the selected database's name. You can then press [Enter] to complete the selection.

Giocoso then prompts you for the 'root' folder of your music collection: the one folder that is at the 'base' of your folder structures in which all FLACs can be found, no matter how many sub-folders they may be buried in:

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.

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 Full Scan completely wipes Giocoso's existing RECORDINGS table (though it never touches the PLAYS table: Giocoso's play history contained in PLAYS is far too precious to ever be deleted, truncated or modified in any way, shape or form). It re-populates it from scatch, which means the process is exhaustive and will accordingly take quite a lot of time, depending on the size of your music collection. With 15,000+ unique recordings, for example, my i5 from 2012 takes about an hour to complete a Full Scan. Functionally, the Full Scan is exactly what happens when you create a database in the first place: every FLAC is analysed and its metadata tags read; that metadata is then loaded into an empty RECORDINGS table.

Practically, this means that a Full Scan will not only add new recordings into a Giocoso music database, but will pick up any metadata changes to existing recordings and will also notice (and record the fact) that this or that recording no longer exists on disk, because you chose to delete it. In other words, if you are actively curating your music collection -adding new stuff to it, deleting obsolete recordings from it, whilst also modifying the metadata associated with particular recordings- you will want to periodically perform a full scan of the collection, so as to ensure that Giocoso's 'picture' of it is as accurate and up-to-date as it can be.

2.0 Scheduling Full Scans

In fact, you will probably want to run fast scans on a daily basis (so that new additions to your collection are picked up in a timely fashion), whilst reserving full scans to be performed maybe once a week (so that metadata edits and recording disposals are taken notice of in a reasonable amount of time).

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

Notice that when you want to automate the unattended running of Giocoso in database maintenance mode, you have to launch Giocoso with one of its few remaining runtime switches: –fullrefresh or –fastrefresh, depending on what type of database maintenance you're wanting to perform. You will also note that it's necessary to pass two additional parameters to the program when launched in this manner: the database name you want to refresh and the 'root' music folder in which Giocoso will find all its FLAC files. The three variables you add to the basic call to run Giocoso are, therefore, and in order: database name (without the .db extension of the file name associated with that database), the root of the music folder containing the FLACs you want to scan and, finally, the full or fast refresh runtime switch.

From the above crontab entries, you can see that whilst I do a nightly fastrefresh, I only do a fullrefresh once a fortnight. That's a mix of maintenance functions which is about right for me: I do add new recordings to my collection quite often, so I want Giocoso to take notice of those very qickly. However, I try to get my tagging correct at the point of adding the new recordings to my collection, so I don't do a lot of metadata correction or modification after they've been added. Accordingly, I personally don't need to do very frequent full refreshes. So this particular mix of nightly fast scans and only infrequent full scans makes sense for me and the way I interact with my music collection. You will obviously want to strike your own balance, depending on what you do with yours!

3.0 Full Scans and Giocoso Pro

All fast (and full) refreshes of Giocoso are updates to the Giocoso local database only, by default. Each installation of Giocoso on different music-playing computing devices will have its own, unique database, periodically refreshed and kept accurate by separate 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, both a fast and a full 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 full refresh can (and can no longer) see.

If you declare PC 'A' to be yes, a Primary Device; and you further declare PC 'B' to be, no, not a Primary Device; then when PC A performs a full refresh, its RECORDINGS will become the new GLOBAL_RECORDINGS table. PC B running in Pro mode will then immediately become aware of any new recordings that PC A has discovered: it doesn't need to do a local full refresh at all. If it were nevertheless to perform a local full refresh, its results would not be pushed to the Pro database: non-primary devices don't push their RECORDINGS table to the GLOBAL_RECORDINGS one.

| Back to Software Home | Back to Giocoso Documentation Home | Back to Database Management Menu |

importdb

Anonymous (anonymous@undisclosed.example.com) — 2025-11-22T12:20:09+00:00

Import Plays To A Local Database

Suppose you created a database called 'renaissance' and a separate database called 'post-renaissance', thinking that keeping the two separate would be useful. Each database thus has its own set of recordings and its own play history. One day, you decide it's pointless keeping the two databases separate in this way, so you create a brand new database called 'classical music'. You get the new database to scan a folder that contains within it both your renaissance and post-renaissance music files. No problem: you now have a new database that contains a single RECORDINGS table containing both sets of music, created from scratch.

Of course: the new database will not have any play history associated with it -and you surely don't want to lose the play history you built up when the two databases were separate entities! So, how do you port those separate play histories to the new database?

This is where the Database Management menu Option 5 comes in handy. You use it to 'point' to a 'source' database and Giocoso will extract the plays out of the source and write them into a second database you 'point' to, the 'destination' database's play history table. You can do that as many times as you like, using different source databases: the plays fetched into the destination database are added to the plays already stored there. So, by running Option 5, pointing to 'renaissance', the plays are pulled into 'classical music'. Run Option 5 again and this time point to 'post-renaissance': the 'classical music' database now contains plays from both source databases: the two original databases have effectively now been merged into one (though they remain as separate databases on disk: you can delete them yourself at some time of your choosing).

Here's a worked example. I start with two databases, one called 'main' and one called 'main Classical database'. Here is the aggregate statistics report for main:

That's a database with data concerning recordings by 603 composers, 13 of which have been played. Now here is the aggregate statistics report for 'main Classical database':

So that's a database with only a single composer's work represented in its database, and with just 5 of those recordings having been played.

My goal now is to create a single database that records 13+5=18 plays!

So, first I create a blank database: for speed, I'll point Giocoso at a folder containing just a single recording for now. Immediately after creation, therefore, this new database's aggregate statistics are:

So, a new database containing just 1 recording by 1 composer …and zero plays. We are starting with a very blank slate, in other words!

So now I take Database Management menu Option 5:

You are first directed to pick a source database. In my case, that's going to be 'main':

The program now displays all .db files it has found in $HOME/.local/share/giocoso3/db: your job is to use the up- and down-arrows to highlight the required source database and to press the Space Bar when it's highlighted in order to select it. You can only select one source at a time. An asterisk appears in the brackets next to the selected database name. Press [Enter] to proceed:

You are now instructed to select the destination database: the one into which the source's plays will be piped. Note that you can select any database to be the destination: it doesn't have to be the one currently in-use by the main Giocoso program. As before:

…you are presented with a list of all possible databases. You just up- and down-arrow to highlight one and press the Space Bar to select it. In this case, I'm wanting main's plays to be ported across to the 'newclassical' database. Press [Enter] to confirm your selection:

A confirmation is given that the source has X number of plays and that those will be ported across to the newclassical database. You can back out at this point if you prefer: note that 'No' is the default option selected. Were you to just reflexively press [Enter] here, therefore, the import process would end with no harm being done to either database. But I do want to proceed, so I left-arrow to get the 'Yes' option highlighted and only then press [Enter]:

A confirmation message appears: just press [Enter] again to dismiss it. Now, all I have to do is repeat the entire process, just remembering to pick 'main Classical database' as my source database, whilst also remembering to pick 'newclassical' as the destination (as before). This time, I see this:

At this point, I can select the Reporting menu, Option 1 once more:

The newclassical database is now said to contain 1 composer's music as before and only 1 recording… but 18 plays. The plays from the two source databases have been migrated to the new database, just as intended.

I should point out that if you merely want to move an entire database from one PC to another (for example), the simpler procedure is literally to copy the .db file, physically, from one hard disk to another. Physically copying a database in this way moves both the RECORDINGS and the PLAYS tables from one device to another: there is no need in this case to extract the plays and handle them in this special way. Remember, too, that the RECORDINGS table can always be re-constructed from scratch, just by performing a new Full Scan (Option 3) and pointing Giocoso at your music collection's hard disk folders afresh. It is therefore only when you need to preserve just the PLAYS table in a database that this 'Import plays to a database' functionality makes any sense -and that's usually going to be because you wish to merge the plays from multiple prior databases, as I've described here.

Note that an import doesn't delete anything in the destination PLAYS table before running. Imports are therefore cumulative -and there's nothing to stop you importing and re-importing from the same source database multiple times, if you are of a mind so to do.

Finally, note that this option only works on the local music database. If you've switched on the Giocoso Pro features to enable working with a remote, shared music database, this import option will have zero effect on that remote database. You will need to use the Pro menu, Option 2 to push a local PLAYS table to a remote pro database: you could push the plays from two or more local databases to the remote, shared database to achieve the same sort of 'merging' of databases in the pro 'context'.

| Back to Software Home | Back to Giocoso Documentation Home | Back to Database Management Menu |

optimsdb

Anonymous (anonymous@undisclosed.example.com) — 2025-11-22T12:42:23+00:00

Optimise A Database

You won't need to use this menu option very often, if ever; and I'm not going to spend a lot of time explaining it. Putting it as simply as I can, databases that are constantly being written to, and deleted from, and on the end of lots of updates, can get 'flabby' over time. Internal space that was used to store a piece of data that gets deleted may never get re-used, meaning it's taking up space and doing nothing to earn its keep. Over time, that wasted space means the database has to process 'blanks' rather than real data. That can slow things down.

Database developers are aware of this, however, and therefore provide 'vaccuming' options which tidy up all the dead space, compacting things back to maximum efficiency, and rebuilding indexes to make them as small (and hence as fast) as possible, too.

This inherent database functionality is what Giocoso's Database Management menu Option 7 triggers.

Taking this option triggers the appearance of the standard 'select a database' form. Once a database has been selected and the [Enter] key pressed, the relevant internal database maintenance commands are given and a confirmation message that the database has been 'compacted and optimised' will be displayed. And that's really all there is to this option!

There are a couple of caveats to mention, however. The first and most significant is: don't take this menu option if music is actually being played by another Giocoso session elsewhere. The optimisation process is 'blocking': that is, it will prevent the music-playing session from reading or writing from the database. The second point is: don't use this option very often. Compacting a database is a 'good' thing, like chocolate. But, also like chocolate, too much of a good thing is a bad thing: constantly compacting a database risks corrupting it, and you definitely don't want that happening!

The only reason for ever using this menu option is if you have an enormous music database and are constantly deleting from it, adding to it, and updating what's inside it. Even then, those sorts of operations should not cause noticeable 'bloat' in the database -so, you'd only even consider taking this optimisation option if you noticed real and significant degredation in, say, the length of time it takes Giocoso to find a piece of music to play at random, or if a report that used to be created in sub-second time starts to take multiple tens of seconds to complete. Short of that sort of obvious deterioration in performance, you are best to leave this menu option entirely alone.

| Back to Software Home | Back to Giocoso Documentation Home | Back to Database Management Menu |

switchdb

Anonymous (anonymous@undisclosed.example.com) — 2025-11-22T12:06:32+00:00

Select & Use A Different Database

When Giocoso is first launched, it opens and uses as its music database whatever database is mentioned in the Persistent Configuration file (which can be viewed by taking Administration menu Option 3):

…or which can be viewed simply by opening the configuration file ($HOME/.local/share/giocoso3/txt/giocoso.conf) in the text editor of your choice:

Taking the Administration menu Option 3 to set a default database will trigger the display of all databases found in the $HOME/.local/share/giocoso3/db folder, but only the one of them that you select to put an asterisk next to it will be the program's 'default database', the one is opens by default each time it is run.

Most people are likely to only create a single music database with Giocoso anyway, as they would presumably want the program to be able to play any part of their collection: in that case, the 'default database' in the Persistent Configuration file is probably the 'only' database, and there would never need to be a way to make Giocoso use any other database.

Some people, however, may wish to create different Giocoso databases for (say) classical v. jazz, or renaissance, classical, romantic and modern music. In these sorts of cases, whilst it's fine for Giocoso to open with one specific database, you would want to be able to easily switch to another database. This is what the Database Management menu Option 4 is all about:

The menu option displays the above screenshot: once again, it's listing all the files with .db extensions that it has found in the $HOME/.local/share/giocoso3/db folder. You arrow up-and-down the list until the database you want is highlighted, then you press the Space Bar to select it. That causes an asterisk to appear in the brackets next to the database name. Once the right database has been selected, you just press [Enter] and Giocoso will open and use that database from then on as its 'current working database'

The top of the main program window will always change to display the currently-operative database name:

The third line of text will display the in-use database name, though for 'artistic' reasons, it will capitalise the first letter of the name! If you were now to switch to the Play Music menu and take Option 1, the next random selection of music to play will be from the currently in-use database, regardless of what the default database might be set to in the Persistent Configuration file.

The currently in-use database remains in-use until either (a) you take this same Database Management menu Option 4 once more and pick a different database; or (b) you quit out of Giocoso altogether and then re-launch it (at which point, the database specified as default in the Persistent Configuration file will be the new in-use database).

| Back to Software Home | Back to Giocoso Documentation Home | Back to Database Management Menu |