Create/Edit the Configuration File

Giocoso's Persistent Configuration file is a simple text file that contains a number of parameters that tell the program how to behave. As it's merely a text file, you could open it using any text editor of your choice (the relevant file to edit is found at $HOME/.local/share/giocoso3/txt/giocoso.conf). The Administration menu Option 2 is there simply as a convenience to allow you to edit the file within Giocoso itself -and to present the file as a simple set of prompts and responses which it will turn into a syntactically-valid configuration file, rather than you having to worry about whether you've typed things correctly if you were editing the file directly.

If you manually edit the file, you'll need to quit and re-launch Giocoso to have the new values applied. If you use the Administration menu Option 2 to edit it, the new values are applied immediately and automatically, without need for a program restart to have new parameter values picked up. It is accordingly recommended that you only use the Administration menu Option 2 to make changes to your configuration file.

This option basically presents you with a 4-page wizard that steps you through various types of configuration option: some require numeric values, some yes/no answers and some bespoke text entries. You can quit the wizard at any time by pressing the [Cancel] button. If you do so, you'll lose everything you may have modified up to that point: the entire configuration file reverts to having the settings and parameter values that were there before you started editing anything. To save altered values, therefore, you need to complete the entire configuration wizard, not quit half-way through!

I'll now take you through each of the configuration option screens (there are four of them in total) in the order you'll meet them.

Giocoso only plays music that has been discovered on your file system -and details of what, precisely, has been discovered have to be stored inside a database. You create that database using the Database Management menu, but here you need to tell Giocoso which one of potentially many different databases should be opened by default whenever the program is run:

All possible databases are listed (these will be files with .db extensions that are housed in the $HOME/.local/share/giocoso3/db folder). You get to pick just one of them: arrow up and down the list until the right database name is highlighted, then press the Space Bar to select it. An asterisk will appear in the brackets shown before the selected database's name. If you select incorrectly, just arrow to a new database and press the Space Bar once more: the asterisk will jump to the newly-selected database. When you're sure you've selected the correct database, press [Enter] to move on.

Note that you're only setting the default database here. You can always switch dynamically to use a non-default database at any time (just use Option 4 on the Database Management menu), so whatever you set here doesn't preclude the future use of any other database.

The next set of configuration parameters that are displayed are ones that require text (or numbers that are treated like text) to complete properly:

The audio device is an important parameter that tells Giocoso where to direct its audio output. By default, the parameter is set to 'default', which on most Linux distros these days will mean Giocoso outputs to a PulseAudio server, though PipeWire is becomeing more common, too (see this blog piece for a bit of an explanation as to how the different Linux audio software layers interact). This may be perfectly acceptable for your purposes. For my own media player, however, I prefer to bypass PulseAudio and instead pass the audio signal direct to the ALSA sound server. To do that, I need to know the hardware device identifier for the Douk ST01 Pro DAC that my music playing PC is connected -and the easiest way of identifying that is to issue the command aplay -l (that's a 'minus ell' at the end there):

This output requires some interpretation! I can start by dismissing anything mentioning HDMI: I don't connect my PC to the Douk DAC by HDMI, so those must just be audio capabilities of the monitor that's attached to the PC. That therefore leaves me outputting to a device “CS4208” in either analogue or digital mode. I happen to know that I connect my PC to the DAC via an optical TosLink cable, I know I must be dealing with the digital device, not the analogue one. From this output, therefore, I know my audio device should be identified to Giocoso as 0,1 (because the output lists the device as being 'Card 0, device 1'. I stick the string plughw: in front of that and thus replace the default value of my audio device with this:

If I'd typed plughw:1,3 instead, Giocoso's music plays would be pumped out through an HDMI connection (which might be handy if your audio player was a well-provisioned TV set, for example).

If in doubt about what hardware device ID to use, by all means stick with 'default': I personally don't like routing audio via PulseAudio, because PulseAudio introduces latency and other processing artefacts into the audio signal and, for classical music reproduction, I prefer things to be as 'clean' as possible. When you can't work out your audio hardware, however, then at least PulseAudio produces sound you can enjoy, most of the time!

Report durations is a minor parameter that controls how numbers are displayed in the various reports you can produce using the Reporting menu options. By default, the parameter is set to minutes, but if your music collection is large enough, you may well want to report in hours instead. The difference would show up in a report such as this one, for example, which is the 'Top Composers' (by play durations) report, Option 2:

You can see I've played Benjamin Britten 562 times, amounting to a cumulative play time of 12,186.63 minutes. That's the sort of display you get, then, with the Report durations parameter set to 'minutes'. Change it to 'hours' instead, and re-run the report and you'll see this instead:

It's the same basic play data, but this time the cumulative play totals are expressed in hours (and yes, 12,186.63 minutes is actually 203.1105 hours -but Giocoso rounds things down!)

This parameter is therefore really more cosmetic than anything else.

The Backup folder parameter determines where music database backups (produced by taking the Database Management menu Option 6) are written. The default value for this parameter is /tmp, but you can set it to any folder to which you have write permissions. An invalid folder name, or a valid folder name you can't write to, will be silently reverted to a $HOME default.

The Remote MySQL Server IP Address and Remote MySQL Server Port parameters basically enable Giocoso's “Pro” features: those are documented at length here, but the short version is that if Giocoso is told where to find a MySQL or MariaDB database on the network, it will begin using that database instead of its own local one, both to store details about what music has been played and also as the 'source' of data about what recordings are available to be played in the first place. Identifying where that MySQL/MariaDB database can be found is done by specifying its IP address and port number. If the IP Address field is left blank (as is the default), then no Pro features are switched on, even if the port number is filled in with something.

The Local music folder prefix parameter is also related to Giocoso Pro functionality. The idea of having a remote database is that it can be shared amongst different PCs: my garden shed computer can play music sourced via the one, central database just as effectively as the PC in my main listening room. However: my garden shed computer may access its music at (say) /home/hjr/Music/classical whereas my listening room PC finds its music at “/music/classical”. What we need to specify for this parameter, therefore, is the bit of the path to music files that is unique to each PC. In my case, that would be “/home/hjr/Music” for the garden shed and “/music” for the listening room. The Pro database can therefore tell either PC to play music from “A/Aaron Copland/Ballet/Rodeo” and each PC will prepend the 'local prefix' to that, to arrive at '/home/hjr/Music/classical/A/Aaron Copland/Ballet/Rodeo' and '/music/classical/A/Aaron Copland/Ballet/Rodeo' paths respectively. One shared database can thus tell multiple differently-configured PCs how to find the same music files with this parameter.

Finally, the Is this a Primary Device parameter takes yes/no values (so really ought to be on the last page of configuration variables!). It's another parameter which relates to Giocoso Pro functionality. If set to 'yes', you're saying that if this PC were ever to do a scan for new recordings, it ought to then upload its discoveries to the global, shared database. There's no point in each PC running Giocoso Pro uploading the same set of 'discovered recordings' to the same shared database: the second PC's results will just over-write the first PC's identical results, for example. So, you set the parameter to 'yes' for one of your PCs, and to 'no' for the others. If you happen to set it to 'yes' for all of them, no harm is done: you'll just be wasting CPU and network resources, uploading and over-writing the same dataset multiple times as each PC searches for new recordings to play.

The third set of parameters you are prompted for all take numeric values:

Since there are quite a few of these sorts of parameters, I'll go through them in table form:

The final page of the in-program Configuration file editing menu option now appears:

All these parameters take binary, yes or no entries. The code is written so that if your entry contains a 'y' in it, that's counted as a 'yes' response. So, y, Y, or yes would all count as 'yes'. Type anything else at all, however, and it's taken as being a 'no' entry. So, x, Q or nooooo would all get assessed as meaning 'no'.

I'll again discuss each parameter in tabular format: