1.0 Introduction
At the last count, there were more than 45 runtime parameters that could be added on to the bare 'giocoso' command needed to launch and run Giocoso. Now, not all of them make sense to use at the same time; and some of them are likely to be very rarely used indeed... but that's still a hell of a lot of command-line typing needed to play some music!
New in Giocoso Version 2, therefore, is the idea of a persistent configuration file: a text file which contains many (but not all) of those runtime parameters with settings which persist for as long as the text file exists and whose existence therefore means that the equivalent runtime parameters don't need to be specified for their meaning to take effect.
To take a simple example: if you want to run Giocoso in Database Play Mode, you need to point it at a previously-created database which it can use as a source of information about what music exists. You could do that every time you launch Giocoso with the command giocoso --dbname=music. Or you could set SOURCEDB=music in the persistent configuration file and launch Giocoso everytime thereafter with the simpler command: giocoso. Most persistent configuration file items duplicate runtime parameters, therefore. Their existence in the configuration file, set to some value or other, means you don't have to set that value with a runtime parameter every time you run Giocoso.
On the other hand, runtime parameters always take precedence over configuration file equivalents. If I have SOURCEDB=music in my configuration file and launch Giocoso with the command giocoso --dbname=main, then Giocoso will run using the "main" database, not the "music" one: the explicit presence of a runtime parameter makes the persistent parameter in the configuration file redundant.
Finally, there are a handful of parameters that affect the way Giocoso works (usually newly-introduced ones in Giocoso Version 2) that only exist as persistent configuration file items. An example of such a parameter would be SCREENWIDTH or CAPTIONFONT. There is no runtime parameter to set either of those two attributes, so you either put up with the Giocoso defaults or you make sure you set them in the configuration file. There are also one or two parameters in the configuration file which cannot be over-ridden by a runtime parameter. For example, if SCROBBLE=Yes in the configuration file, there's no way to turn that off with a runtime parameter, because there is no --noscrobble or --scrobble=no runtime parameter to override it.
2.0 Location and Format
The persistent configuration file will be pulled down as a template file from the Absolutelybaching servers the first time Giocoso Version 2 is run:
Just press a key when you see that message and the download will happen almost instantaneously, creating a file called $HOME/.local/share/giocoso/giocoso.conf. Note the fullstop (period) in front of the '.local' part of that path/filename: it means .local is a hidden folder and you may need to switch on your file manager's 'show hidden files' functionality before you can browse there. You can edit the file once downloaded with any standard text editor of your choosing. Here's me opening in KDE's Kate editor:
You will see immediately that the vast majority of the file is just lots of lines beginning with '#': these are commented-out lines, so they are of no practical effect. They are there, for the most part, to provide readily-accessible documentation about what each parameter does, what it's possible values are and so on.
It is very important that you do not alter or amend to any extent the content of lines 1 to 14. Though they are commented-out lines, they have significant practical effect, as they are what Giocoso uses to determine whether a file called 'giocoso.conf' is actually a valid configuration file at all. By altering any of those first 14 lines of the file in the slightest, you render the entire file unusable. After performing such an edit, the next time you run Giocoso, you'll see this error message:
Use the command shown in blue to retrieve a fresh copy of a default configuration file from the Absolutelybaching website servers and replace the defective copy. Once that's happened, you'll be able to use Giocoso normally thereafter (though all your persistent parameter settings will, of course, need to be reset to their prior values, because they will start by being reset back to their defaults).
Everything from line 15 onwards may be edited at will. Hopefully the text explanations contained within the configuration file itself will give you a clue as to what each parameter does and what its plausible values can be. Whenever you edit the file, make sure you leave no space between the parameter name and the value you wish to assign to the parameter. It is, for example, SOURCEDB=music, not SOURCEDB = music. Most parameter values are case insensitive: if you set SCROBBLE=Yes, that works just as well as setting SCROBBLE=yes or SCROBBLE=yEs. Some parameters are definitely not case insensitive, however: SOURCEDB must be set to a name that actually exists as a file on disk... and in the world of Linux file systems, "music" is not the same thing as 'Music'. The general rule is that if you had to be case-sensitive with a runtime parameter, its persistent configuration file equivalent will be case sensitive, too. Fortunately, this sort of thing is rare.
To 'turn off' a parameter, whether or not it has a value assigned to it, prefix it with a '#' (hash) character (which comments out the line). To turn a parameter on, simply remove any hash characters that begin the line.
I won't go over most of the parameters here, partly because the file is self-documenting in that regard and partly because most of the parameters are adequately documented in the context of their runtime parameter equivalents. I will, however, now document the handful of parameters that have no runtime equivalents.
3.0 Persistent Configuration Parameters
| LINEDRAW1="x" | Giocoso Version 1 drew horizontal lines with a series of simple hyphens (or minus signs). Giocoso Version 2 uses the IBM linedrawing character to achieve a slightly more polished look. If your terminal font cannot render those IBM characters properly, however, then the program display will look a bit of a disaster! By setting this parameter back to a simple minus sign, you can return the program appearance to its Version 1 characteristics (and every font on Earth should be able to render a simple hyphen correctly). Technically, any character could be mentioned as the parameter value -but clearly, program appearance will suffer if you decide to get 'experimental' about it! 🙂 If you do decide to change this value, make sure the replacement character you decide to use is enclosed within double quotation marks. |
| LINEDRAW2="x" | Same sort of story as for LINEDRAW1: in Giocoso Version 1, double horizontal lines were drawn with a simple equals sign. Giocoso Version 2 uses the IBM linedrawing equivalent, which your terminal font should be able to render correctly... but may not be able to. In the event that you need or want to revert to Giocoso Version 1 line drawing characters, you can set this parameter back to a plain equals sign. Any value you provide for this parameter must be enclosed in double quotation marks. |
| LINEVERT="x" | A sort of vertical line equivalent to LINEDRAW1 and 2. In Giocoso Version 1, vertical lines (if any) were drawn with a simple 'pipe' character (i.e., |). Giocoso Version 2 uses the IBM linedrawing equivalent and if you need to revert to the old pipe character because the IBM one doesn't display properly, here's how you can change things back to the old way of drawing vertical lines. As ever, the character you provide here must be enclosed within double quotation marks. |
| CAPTIONFONT="xxxx" | Every time Giocoso displays the album art associated with the piece of music it's just started playing, it will construct a 'caption panel' underneath the artwork, displaying the composer's name and the specific name of the composition being played. The font used for the text in that caption panel is generally 'Dejavu Serif', which is freely available and pre-installed on most Linux distros. If that font is not present, however, then Giocoso will (by default) pick some other system font by way of fallback -and the results usually end up looking less than ideal. This parameter lets you specify the specific font to use for the caption panel text. If you specify one that doesn't actually exist on your system, Giocoso will again fallback to using something that does exist. If you don't use this parameter at all, then Dejavu Serif is still the default. To know what fonts are installed on your Linux system, the command fc-list can be issued, but the results may be messier than you'd like. For example: /usr/share/fonts/TTF/Inconsolata-ExpandedSemiBold.ttf: Inconsolata,Inconsolata Expanded SemiBold:style=Expanded SemiBold,Regular From that list, you have to experiment: though there's a font file called 'DriodSans.ttf', the font would most likely be called 'Droid Sans'. Similarly, though you might try 'Inconsolata Expanded Medium', I think you'll generally find 'Inconsolata' works and secondary characteristics in the apparent font name likely won't work. It may take some degree of experimentation to find a font setting that works for you (always assuming that the default font doesn't meet your typographic needs, of course!) Enclose whatever font name you do decide to specify inside double quotes, or nothing will work. |
| SCREENWIDTH="n" | Described fully in Section 3 of the Changing Appearance article. The short version is: by fiddling with the numbers used for this parameter, you make Giocoso move the album art display window around your monitor in the horizontal direction. You can thus devise a fixed position for the artwork display, without having to use desktop environment-specific features (which many desktop managers don't even provide in the first place). |
| SCREENHEIGHT="n" | Described fully in Section 3 of the Changing Appearance article. The short version is: by fiddling with the numbers used for this parameter, you make Giocoso move the album art display window around your monitor in the vertical direction. You can thus devise a fixed position for the artwork display, without having to use desktop environment-specific features (which many desktop managers don't even provide in the first place). |
| TIMER_PRECISION="xxxx" | Giocoso always 'counts down' a play, so that the footer area of the program display shows you how long you've got until the play completes. In Giocoso Version 1, this counter was 'clocked' by a timer that slept relatively infrequently, so that the countdown time was super-accurate, but at the expense of quite high CPU resource usage. This parameter is new to Giocoso Version 2 and allows you to specify values of either High or Low (the parameter values are case insensitive, so HIGH=high=HiGh and so on). The HIGH setting is exactly what you had in Giocoso Version 1. The LOW setting means the countdown timer sleeps more, thus freeing up the CPU more, and reducing CPU consumption by tens of percent. The drawback of the LOW setting is that the timer may, very occasionally, appear to stumble or skip a digit now and then. Nevertheless, the CPU savings from using the LOW setting mean that LOW is indeed the default -and recommended- value in Giocoso Version 2. |
| MAXSEARCH="n" | When Giocoso searches for music to play in Database Play Mode, by default it will scan through every single recording in your collection trying to find something that will meet all the selection and filtering requirements you've put in place. For a small music collection, this has the benefit of comprehensiveness: if it can't find a match after testing everything, then it's pretty obvious that nothing at all can meet the search criteria. On a large music collection, however, this approach can take multiple minutes to complete and is really not a sustainable way of managing things. The MAXSEARCH parameter takes a numeric value (not enclosed in quotes) which puts a hard limit on the number of randomly-selected pieces of music Giocoso will inspect to see if it meets the selection criteria specified by you when you launched Giocoso. A value of 500, for example, means the search time is limited to taking a few seconds, no matter the size of the music collection. Of course, this means that the search for music will no longer be comprehensive: Giocoso could randomly miss a piece of music that would meet the search criteria, if only Giocoso was allowed to stumble across it. The question is really whether or not that degree of comprehensiveness is worth striving for if it takes 10 minutes to unearth the one piece of music that meets the criteria! |
Where a parameter is shown taking an "=n" parameter value, that indicates a numeric value is expected; a single "=x" indicates a single textual character is required; a value shown as "=xxxx" indicates a multi-character textual value is expected (such as a font name, for example).
4.0 Editing the Configuration File
As previously mentioned (see Section 2), the persistent configuration file is simply a text file and can therefore be edited in any text editor with which you are comfortable. However, opening it in Kate or Notepadqq involves navigating your file system -and dealing with the fact that the Giocoso configuration files are all stored in a folder which is partly hidden (i.e., its name starts with a fullstop/period). It's not difficult to do, but it's something you always have to keep in mind.
To make editing the persistent configuration file a little easier, Giocoso itself provides an ability to do edits, by invoking Giocoso with the --editconf runtime parameter. This command will do the job, for example:
giocoso --editconf
...and will result in a display such as this:
In this case, the configuration file has been opened in the nano text editor. Why? Because that's the default text editor on this particular operating system. The default is always determined by whatever the EDITOR environment variable is set to, usually by an entry in the .bashrc or equivalent environment-setting file, or by explicitly setting it to something. For example, if I issue these commands:
export EDITOR=/usr/bin/mousepad
giocoso --editconf
...then this is the result:
That is, Giocoso launches the Mousepad graphical text editor in the foreground, whilst it continues running in the background. With a graphical text editor, you may see background messages about 'Failed to load module...', but these can be ignored: they are an artifact of launching GUI applications from a terminal, not a problem with the functionality of the text editor (or Giocoso) itself.
Once the file is open, in whatever text editor, just edit it as you would any other text file and use your chosen editor's save-and-quit options to save the results of your changes. Quitting the editor will return control back to the Giocoso session, which will terminate gracefully and put you back at a clean, functional command prompt.
4.0 Conclusion
Summing up:
- Giocoso needs user input to make it do 'things'. That input has always previously come from dozens of double-hyphen parameters, supplied on the command line, as part of the command that launches Giocoso in the first place... but there are now so many such 'runtime parameters' that running Giocoso correctly can involve a complex typing operation! You could work around this in Giocoso Version 1 by creating 'aliases' in your .bashrc or similar environment-setting file, whereby the bare command 'giocoso' was interpreted to mean 'giocoso --dbname=x --selections=9 --device='plughw0,2' --maxduration=90 --unplayedworks' and so on. But aliases are not very transparent to people who don't know their operating systems like the back of their hands! They are also not terribly cross-platform: Windows doesn't know about them the same way Linux does, for example.
- Giocoso Version 2 therefore introduces the persistent configuration file that allows many of the runtime parameters to be stored as having values that persist from one run of Giocoso to the next. As a text file, it's easily edited, either by manually editing it with any suitable text editor, or by invoking Giocoso with the --editconf runtime parameter. Should the file ever be corrupted or you simply want to get a 'clean' version to start over with, you can force the download of a fresh copy by issuing the command:
wget https://doco.absolutelybaching.com/gs1 -O $HOME/.local/share/giocoso/giocoso.conf
- A handful of parameters now only exist in the persistent configuration file, with no runtime equivalents.
- Where a persistent parameter does have a runtime equivalent, should they ever disagree on the value assigned to the parameter, then the runtime parameter always wins. Thus --dbname=X and SOURCEDB=Y will result in the X database being used.
The presence of two 'sources of instruction' can, I think, make things a little awkward to diagnose at times. You think you're running Giocoso with no limits on the duration of playback, for example, because you didn't specify --maxduration=n when launching the program. Unfortunately, you've forgotten that MAXDURATION=10 has been set in the persistent configuration, so all you ever get played are short pieces! The interplay between runtime and persistent parameters can pose challenges of its own, therefore. It is perhaps, then, a good idea to get into the habit of setting the persistent configuration file to a set of generally acceptable and generous settings and only using runtime parameters to 'tighten things up' on specific Giocoso runs; and when Giocoso appears to be doing weird stuff that you can't explain... check your persistent configuration file settings before doing anything else!