Giocoso's Persistent Configuration file is a simple text file that contains a number of parameters that tell the program how to behave. It is read once at program startup. 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 3 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.
The Administration menu Option 3 displays the configuration file's contents in four distinct stages. Here's the first one:
You are first prompted to specify which existing database should be opened by default whenever Giocoso is launched. 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.
Parameters requiring Text Values
The next set of configuration parameters that are displayed are ones that require text values 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. 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 my Topping E30 USB DAC -and the easiest way of identifying that is to issue the command aplay -l (that's a minus ell at the end there):
Remember I know my audio device is a Topping E30: you can see some of that name appear as 'card 2: E30 [E30}, device 0: USB Audio...' towards the end of the list. From that output, therefore, I know my audio device is identified as 2,0. 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:0,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 420 times, amounting to a cumulative play time of 7,314 minutes. That's with the Report durations parameter set to 'minutes', however. Change it to 'hours' instead, and re-run the report and you'll see this instead:
Same basic play data, but this time the cumulative play totals are expressed in hours (and yes, 7,314 minutes is actually 121.9 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 new $HOME default.
Parameters requiring Numeric Values
The third set of 9 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:
|Number of plays per cycle||How many random selections of music does Giocoso make in one 'session', before terminating all playback?||Default value is 1: each play effectively stops Giocoso in its tracks. I like a decent number of plays in succession, so I've set mine in the screenshot to 15, meaning I listen to 15 different recordings, one after the other, before having to interact with Giocoso again.|
|Pause between plays in a cycle||How many seconds of silence does Giocoso wait between the end of one playback and the start of the next?||Default value is: 5 seconds. A countdown timer is displayed as one recording ends and before the next begins, starting at whatever this parameter is set to.|
|Hours before composer eligible||How many hours must elapse between plays of music by the same composer?||This is the 'time bar'. By default, it's 6 hours, meaning that if Wagner is played at 9AM, he can't be played again until at least 3PM. Setting this parameter to 0 means switching the time bar off completely: a piece of Mozart could be followed immediately by another piece by Mozart. At non-zero values, the parameter is designed to stop Giocoso randomly selecting work by the same composer over and over again.|
|Minimum length of play||How many minutes must a recording (in total) last for, before it can be selected for playback?||The default value is 0, meaning 'any recording of whatever length is a candidate for random selection'. Note that it's the folder that's evaluated for duration when working out if it meets the minimum duration threshold. That is, if you have 4 tracks of a symphony each lasting 3 minutes, and you set this parameter to (say) 10, then the symphony is allowed to be played: its total duration of 12 minutes exceeds the threshold.|
|Maximum length of play||How many minutes must a recording (in total) last less than, for it to be a valid candidate for playback?||The default value is 525960, which is the number of minutes in a year if 365.25 days! That's longer than any recording in existence of course, so effectively the default means 'all recordings, whatever their length, are valid candidates to be randomly selected'. Set it to (say) 120, however, and you're saying that anything that lasts, in total, for more than 120 minutes (2 hours) cannot be selected for playback. This is a way to stop Wagner operas being randomly selected for playback, for example. As with the minimum length of play parameter, a folder's total duration is assessed when determining if it's an acceptable candidate for selection. Lots of short tracks are added together to work out that the recording as a whole exceeds the threshold, for example.|
|Maximum number of searches||How many random selections to work through to see if it's a candidate for playback before giving up?||The default value is 500. Giocoso selects a composer, selects a recording of that composer's music, and then assesses it to see if it meets the minimum/maximum duration thresholds, the timebar ban, the excludes ban, or the exempts waiver. Only then might it realise the recording isn't a valid candidate. It then discards that selection and picks another. This select/discard/re-select process continues in a loop for as many times as this parameter permits. The default of 500 searches can take maybe 10 or 20 seconds to iterate through on a really slow, 2012 PC. Depending on your hardware capabilities, you may want to increase or decrease this parameter value accordingly.|
|Screen width||How many pixels does your screen or monitor use to display in the horizontal direction?||Defaults to 1920. The parameter helps controls where on the screen an independent album art window will display, should you configure to use one. By making the parameter value bigger than your actual screen width, you cause the album art window to be pushed over to the right. By making it smaller, the window gets pushed over to the left. When both the screen width and height parameters are set to their correct, actual physical values, the album art window is meant to appear in the lower-centre of the screen.|
|Screen height||How many pixels does your screen or monitor use to display in the vertical direction?||Defaults to 1080. The parameter helps controls where on the screen an independent album art window will display, should you configure to use one. By making the parameter value bigger than your actual screen height, you cause the album art window to be pushed downwards. By making it smaller, the window gets pushed upwards. When both the screen width and height parameters are set to their correct, actual physical values, the album art window is meant to appear in the lower-centre of the screen.|
|Size of Album Art||How many pixels wide and high should album art imagery be displayed at?||Defaults to 340. The parameter only takes one value, and then duplicates it for the other dimension. In other words, a value of 340 is converted into an image size of 340x340 pixels: Giocoso always expects to work with square album art imagery! You may need to play around with this parameter as you start working with Giocoso: the album art is usually displayed on the right-side of the main program window when something is playing and it may or may not fit that display area, depending on your terminal, its choice of font and font size and so on. The default of 340 has been set so that if you use the Xterm terminal and the fonts installed by Giocoso for the purpose, in-terminal album art should appear correctly. A 50-pixel high 'caption bar' is automatically added to the bottom of the actual album art: it displays text indicating the composer name and the composition/recording name being played. By default, therefore, you'd end up with a 340x390 piece of album art (that is, 340 pixels wide and 390 high).|
Parameters requiring Yes/No answers
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:
|Prevent accented character conversion||Should the use of accented characters (in terms such as Concert champêtre) be forced or not?||Some operating systems may take accented characters and auto-convert them to non-accented equivalents (so you end up with Concert champetre, for example, missing its caret accent in the second word). A setting of yes is not normally required for properly-configured operating systems, though it is the default, but if Giocoso on your operating system seems to be forgetting accents you know ought to be present, then set this to 'yes' to prevent their mysterious disappearance.|
|Under-played Composers||Should composers who have been played proportionately less than others be the only candidates for the next random selection for playback?||The default is 'no', but switching this to 'yes' enables the 'under played composer' feature that is discussed at length here. The short version is that if your collection contains music by 100 composers, a 'fair distribution' of plays would result in each composer's cumulative play time being 1% of total cumulative play time. Composers whose play time falls below that threshold would be the only ones allowed to be candidates for the next randomised selection.|
|Unplayed Recordings||Should Giocoso only select previously un-played recordings as candidates for the next random selection for playback?||The default is 'no', but turning this on means that only recordings mentioned in the RECORDINGS table that do not have matching entries in the PLAYS table are candidates for the next randomised selection. The determinant is the full folder name: if that appears in PLAYS, then it's a previously-played recording and would be excluded from candidate status. Setting this to 'yes' is a good way to ensure Giocoso plays through your entire music collection without just overlooking some of the more obscure parts of it!|
|Display Album Art in own window||Should album art be displayed in its own, separate and movable window?||Defaults to 'no'. Album art is then displayed 'in-terminal' -that is, within the main Giocoso program area. Setting it to 'yes' means album art gets displayed in its own program window, independent of and external to the Giocoso program window. Some operating systems do not know how to display graphics in-terminal very well (or at all!), in which case displaying it in an external window is a good workaround.|
|Force the use of PulseAudio||Should audio output be forcibly directed to a PulseAudio server?||Defaults to no. Usually, the audio device setting (see above, under parameters requiring text values) will control where Giocoso's audio output is directed. When in doubt, a setting of 'default' there is usually sufficient to get sound output working. However, in specialised situations, you may wish to forcibly direct Giocoso to output to a PulseAudio server by setting this parameter to 'yes'. One such scenario is: sending audio over a home network. If your living room PC is running Windows, for example, and you are running Giocoso on a Raspberry Pi in the loft, you can get the Pi to send its audio signal to a PulseAudio server running on your Windows PC over the network. PulseAudio is very handy for this cross-network audio capability (rather as x11 is great for cross-network graphics capabilities).|
|Attempt to fix album art display||Should Giocoso attempt to display a dithered version of album art in-terminal or not?||Defaults to no. By default, Giocoso will want to display album art in-terminal in high-resolution using full colour. Some operating systems do not like this, however, and completely garble the album art display as a consequence (see, for example, Fedora). One possible workaround is to set this parameter to 'yes': the result is a dithered, 8-bit representation of the album art which usually displays adequately. A better 'fix' if it's needed at all is to run Giocoso in a terminal emulator that knows how to display in-terminal graphics properly (such as Konsole), but this parameter at least provides a workaround that needs no additional software added to your system.|
Please note: the Persistent Configuration file is read once, at program startup. Any changes you make to it, therefore, will not be picked up and acted upon until you have completely quit Giocoso and re-launched it.