1. Edit the Excludes File
This menu option launches your system's default editor (often nano these days, but configurable by setting the EDITOR environment variable) and opens the $HOME/.local/share/giocoso3/txt/excludes.txt file (or creates an empty version of the file if one doesn't already exist). This file controls which composers are explicitly banned from being randomly selected for playback by any of Giocoso's 'default' play mode (see Play Music menu Option). The file takes one name per line; the name needs to be that of a composer; and it needs to be spelled exactly as it would appear in your metadata tags. If you are sick of listening to Johann Sebastian Bach one day and want to ensure he doesn't get played until you've got over the brain-fit, you'd have an excludes file like so:
There is no limit to the number of names you can add to the file.
The file needs to be saved after initial creation or subsequent editing (in nano, you'd press Ctrl+X, then tap 'y' to confirm), but once saved, its contents take immediate effect for the next Play Music menu Option 1 play. Note that the excludes file has zero effect on what might get selected for play if using other Play Music menu options. If, for example, I were to take Option 2 and fill in the selection filters with an explicit request to 'play something by Johann Sebastian Bach', that takes precedence over the excludes file. Similarly, if you choose to play a playlist (Play Music menu Option 5) that mentions something by Johann Sebastian Bach, that would be played regardless of the fact that the excludes file lists him.
In short, the excludes only bars a composer from being selected for random play. User-directed plays are unaffected.
2. Edit the Exempts File
This is new in Giocoso Version 3. The Exempts file lists composers who are exempt from the usual 'time bar' that Giocoso applies when doing randomised music plays (Play Music menu Option 1). The time bar is specified in the persistent configuration file, using the parameter TIMEBAR=x, where x is a number of hours, and defaults to 6. It means 'if I've played something by Mahler at 9AM one day, I may not randomly select to play another piece by Mahler until at least 3PM'. A mention of Gustav Mahler in the exempts file, however, means that something new by Mahler could be selected for play immediately after the 9AM play concludes.
Like the excludes file, the exempts file is a text file ($HOME/.local/share/giocoso3/txt/exempts.txt) that takes one composer name per line, where each composer name is spelled exactly as it would appear in your FLAC files' metadata tags.
The Administration menu Option 2 opens the exempts file (or creates it, if one doesn't already exist) in your system's default text editor (which is set by the EDITOR environment variable, but is usually nano by default in most Linux distros these days). Edits made to the file take immediate effect once the modified file has been saved.
Please note that being listed in the exempts file doesn't mean that composer X will be played again shortly after having been played. It simply means that Giocoso isn't prevented from doing so by the ordinary TIMEBAR setting. Its randomised selections will remain randomised and thus Composer X might or might not get selected for the next randomised play, depending on how the Cosmos is feeling at the time!
3. Create or Edit the Configuration File
The persistent configuration file ($HOME/.local/share/giocoso3/txt/giocoso.conf) controls major aspects of the way Giocoso works, looks and behaves. The Administration menu Option 3 lets you edit the file in a simple, prompted fashion -but, if you prefer, you could simply open the file in the text editor of your choice.
The program option prompts you in four separate screens or 'pages' to fill in parameter values for four separate groups of parameters, as follows:
- A source database parameter
- Parameters requiring text entries
- Parameters requiring numeric values
- Parameters requiring yes/no answers
You move between the four pages by pressing [Enter] to submit each one as it is completed. If you press ESC or select the 'Cancel' operation at any point, your final configuration file will have default values applied to any parameters on pages you didn't reach before your left the program, which is probably not what you want to happen.
If you have a pre-existing configuration file (which should usually be the case, as a default one is created as part of Giocoso's installation procedures), then values from it are loaded into most of the screens. They can then be edited and saved back to create a modified parameter file. If no configuration file exists already, the screens will be displayed with blank fields and filling them in and submitting the completed forms will result in a new file being created from scratch.
3.1 Source Database
The first screen you see when taking this menu option sets the SOURCEDB configuration parameter, which represents the database you want to use by default whenever you first launch Giocoso:
It lists all the database files (i.e., with .db extensions) that have been detected in the $HOME/.local/share/giocoso3/db folder. If the parameter file already has a value for the SOURCEDB parameter, that database name will be displayed with an asterisk next to it: in the above screenshot, for example, though database 'hjr' is highlighted (because it is all-red), database 'main' has the asterisk next to its name, so is the one that's selected. That's because my configuration file already had a setting for SOURCEDB=main.
Whether anything is pre-selected or not, you can simply up- and down-arrow to highlight a different database and press the Space Bar to select it. Press [Enter] when the right database is selected to move on.
3.2 Parameters requiring text entries
A handful of configuration file parameters require textual entries, as follows:
3.2.1 Audio Device
The audio device can be tricky to work out! It's the hardware device Giocoso sends its audio signal to, so if it's not set correctly (or is set to the wrong device), you won't hear music playback at all, or you'll hear it on your PC's internal speaker (for example) rather than the external DAC you've got wired into an amplifier. The command to determine what to type for this parameter is aplay -l (that's a lower-case l at the end):
Most PCs will have multiple audio output devices: here, you see that mine has five of them! That can happen because on-board audio is detected, even though you're using a dedicated sound card; or perhaps an HDMI port is detected as having audio output capabilities. It can be awkward trying to work out which of the possible output devices is the right one to use. In my case, I want audio coming through my Philips monitor, via an HDMI connection: if you look very closely, you'll see that one of the devices mentions "HDMI...PHL 252B9", which is a clue that it's that device that is both HDMI and something to do with Philips. I will agree ahead of time that it's not always easy to interpret things this way, though! Here's another example from my main Giocoso player:
On this machine, I want my Topping E30 external DAC to be the output device -and that's quite clearly listed as 'Card 3: E30', so that one's a bit easier to identify.
In either case, if you've managed to identify the hardware device you're interested in, you then need to see what 'card' and 'device' it's been assigned: on my desktop PC with the Philips monitor, that's Card 0, device 3. On my main Giocoso PC, the Topping E30 is 'Card 3, Device 0'. Knowing those two numbers, you then convert that to a value of plughw, colon, then the two numbers with a comma separating them. In my case, I'd have a value for the Philips PC as plughw:0,3 and for the one with the Topping E30, it would be plughw:3,0. It's these constructed 'strings' which become the value to submit on the second form of the Configuration File editing menu option.
3.2.2. Report Durations
When you run some Giocoso reports, the durations associated with recordings can be displayed in either hours or minutes (that is, do you want to see that you own 600 hours of J.S. Bach's music, or 36,000 minutes of it?!) By default, those durations are shown in minutes, but the parameter on this form can take a value of 'hours' or 'minutes'. If you type in anything else, you'll get the 'minutes' default. This parameter governs the way Reporting menu Options 2 and 3 display their outputs.
3.3.3 Backup Folder Location
The final textual parameter tells Giocoso where to store backups of its music database (which are generated by taking Database Management menu Option 6). By default, backups are written to $HOME, but setting a value for this parameter overrides that. Giocoso tests whether the folder specified for this parameter actually exists: if it doesn't, then the default $HOME is used instead.
3.3 Parameters requiring numeric values
A bunch of configuration parameters require numeric values, as follows:
3.3.1 Number of Plays per Cycle
A 'cycle' is the number of recordings Giocoso plays, one after the other, before stopping and returning to the main menu. The default value for this parameter is 1: Giocoso plays one piece of music, then stops and waits for further input before playing anything else. In the example screenshot, I've upped this to a non-default value of '5': Giocoso will play five recordings, one after another, before stopping and awaiting further input. You can set this value to anything greater than 0. If you try setting it to a non-numeric value, or to a value less than or equal to 0, the default of '1' will apply anyway.
3.3.2 Pause between plays
If you're playing more than one piece of music in a cycle (see 3.3.1 above), you will probably want there to be a pause between one recording ending and another starting. The default value for that 'pause between plays' is 5 seconds, but you can enter any number greater than 0 here. As ever, a non-numeric entry, or trying to enter a value less than or equal to 0, will result in the default of 5 applying anyway.
3.3.3 Hours before composer is eligible for second play
This parameter sets the 'time bar': the number of hours after a composer has had something played before something else by that same composer is allowed to be selected at random by Giocsoso's default play mode. (The time bar is not applied at all for user-directed plays, such as when you select by filter, advanced SQL or by playlist). By default, 6 hours must elapse between plays by the same composer, but you can change that here to any number from 0 upwards. In the above screenshot, you'll see I've set mine to 48 hours: if I play some Beethoven on Monday, I won't randomly hear anything else by him until Wednesday. You are allowed to set this parameter to 0: it means you are switching the time bar feature off in its entirety. If you don't mind hearing the same composer's music played three times in quick succession, zero here is a perfectly valid entry.
3.3.4 Minimum length
This parameter acts as a filter for what music can be randomly selected for playback via Giocoso's default play mode. It's measured in minutes and a recording is only playable if it's longer than the value type here. By default, the parameter is set to 0 -meaning that's there's no effective minimum duration filter applied at all. If you set this parameter to a non-numeric value, or try to set it to a value less than 0, the default of zero will apply regardless. You are allowed to set the parameter explicitly to 0, though.
3.3.5 Maximum length
This parameter is another filter controlling what music Giocoso can randomly select to play in its default play mode. It's again measured in minutes and a recording is only eligible for selection if it lasts for less than the specified number of minutes. The default value for this parameter is a rather silly 525960 minutes, which is the number of minutes in a year. If you have any music recordings which last for more than a year, I'd be surprised! In other words, this parameter's default value is something so ridiculously large that it's unlikely to filter anything at all out of being playable. As usual, trying to set this parameter to a non-numeric value or to something less than or equal to zero will result in the default being applied anyway.
Note that it's possible to submit minimum and maximum length values the 'wrong way round': if you were to say minimum length is 100 and maximum length is 30, those would both be valid values for the parameters. Unfortunately, they'd also be logically nonsense, because a recording cannot both be at least 100 minutes long, and also last no more than 30 minutes. Happily, Giocoso will sort this out for you: if it detects the parameters are the wrong way round, it will automatically swap them round.
3.3.6 Maximum number of searches
When selecting music to play at random, Giocoso first selects a composer, then it selects a recording featuring that composer's work, and only then does it say 'does this recording meet the minimum and maximum durations, the time bar, or any of the other filters that might apply'. At that point, it may find that the recording it was proposing to play isn't a suitable candidate for playback after all, as it falls foul of one filter or another. If that happens, Giocoso makes another random selection of composer and recording... and repeats the same process for as many times as it takes to find something it can play.
Constantly searching and re-searching for candidate recordings can take time, though -so this parameter exists to let you specify a limit to the number of times it will search before simply giving up.
The default value for this parameter is 500 searches (which should only take a few tens of seconds to reach, though it will depend on the speed of your PC). You can, however, enter any number of searches here, provided that the value is greater than zero. A non-numeric, zero or less-than-zero submission will be ignored and the default of 500 will be applied anyway.
3.3.7 Screen Width and Height
When Giocoso plays a recording, it likes to display the album art associated with that recording. By default, it will display it 'within' the same terminal window that Giocoso itself is running in, like this:
If Giocoso is used like this, the value you assign to the Screen Width and Screen Height parameters is irrelevant and makes no difference to how anything works or is displayed.
However, you can also ask Giocoso to display album art in an 'external' window (see Section 3.4.4 below), like this:
The location where that external display window appears is then governed by what you specify as the Screen Width and Height parameters here. By default, the parameters are set to 1920 pixels wide and 1080 pixels high, given those are probably the commonest screen dimensions in use these days. Left at those settings, assuming those are indeed the correct values for your monitor, you'll find that the external album art display window appears in the middle of the screen in the horizontal direction, and down at the bottom of the screen in the vertical direction.
By manipulating the values of the parameter, you can however change that initial display location (and, of course, you can always just click-and-drag it with a mouse to some more convenient location). On my system, for example, if I set the parameters to be 5000 x 2000, I get this:
...meaning that the album art has displayed itself right on top of my main terminal window. If I set both parameters to 500, I get this:
Suddenly, the album art is being displayed to the left side and upper left corner of the screen, compared to where it was before.
The short version is that these two parameters can be set to anything you like, provided they are numeric entries greater than 0. There's no need for them to describe the actual pixel dimensions of your screen: by fiddling them up and down, you can arrange for an external display of album art to appear by default in different parts of the screen, which is their entire purpose. If you set them to non-numeric values or to zero, they will acquire the actual physical pixel dimensions of your primary monitor.
3.3.8 Size of Album Art
As previously mentioned, Giocoso likes to display album art when a new recording starts playing: the question is, at what size should it display it? This parameter controls the answer to that. By default, Giocoso will display all album art at 340 pixels high by 340 pixels wide, plus another 50 pixels high for the 'caption panel' that appears underneath the actual album art and which spells out the composer and composition being played.
You can supply a number for one of the dimensions on the parameter form: it must be non-zero and numeric (otherwise the default of 340 applies). Giocoso takes your submission for one of the dimensions and makes the other exactly the same (it has a fondness for square album art!). If you enter, as I have in my original example screenshot, a value of '310', then your album art will be displayed as a 310x310 pixel square. If you wanted a 900x900 square display, you'd supply a single value of '900' here, therefore. You cannot specify multiple dimensions, and thus you cannot specify a non-square album art display.
Be warned that altering this parameter's value can result in screwy program display. A setting of 810, for example, with pop-out artwork (i.e., displayed in its own window) might be just about acceptable:
But the same pixel dimensions when pop-out artwork is disabled (and thus, artwork is embedded within the main program terminal itself) probably won't be:
You may therefore need to experiment with album art size, depending on whether you're using pop-out artwork, or embedded. My non-default setting of 310x310 with embedded artwork seems to work nicely for my particular setup, but it will depend on your terminal font, size and monitor capabilities as to what will work best for you.
3.4 Parameters requiring yes/no answers
The last set of parameters that you can set all take yes/no answers and appear as follows:
The default value for all these parameters is: no. If you don't type 'yes' for any parameter, the default of 'no' will apply.
3.4.1 Accented Characters
Some Linux distros have an issue where by words such as champêtre or Götterdämmerung are rendered by Giocoso as 'champetre' or 'Gotterdammerung' -that is, without their accents and other diacritic marks. This usually only happens on distros that have, for whatever reason, been installed with the wrong locales, so it's an operating system error that Giocoso is being affected by. This parameter forces the use of accents and diacritic marks regardless of what locale is installed on the system, however. If you discover Giocoso playing un-accented versions of things you know you tagged with the correct accented characters, you should set this parameter to 'yes'. My distro of choice is Manjaro and it is actually affected by this problem, which is why you see me setting this parameter to 'yes' in the above screenshot.
3.4.2 Unplayed Composers
This is a filter which can affect what Giocoso selects to play when using its default, randomisation mode of play. It has no effect for modes of play that require user input (such as play by filter, advanced SQL or playlist).
To determine if a composer has ever had something by them played before, Giocoso looks in the plays table. If a composer's name is found there, even once, and this parameter is set to 'yes', then that composer is ineligible to be randomly selected for play. Only if there are recordings attributed to a composer in the recordings table, and whose name never appears in the plays table, is the recording eligible for random selection.
It's a bit of a peculiar filter, and I don't think anyone will use it much -but if you've just acquired a bunch of recordings by a brand new composer you've never heard of before, this is a way of ensuring you can sample at least one of the new recordings quickly. (Of course, the first play of one of the new recordings will render all the other recordings by that composer ineligible for random selection!)
3.4.3 Unplayed Works
This is a genuinely useful filter that again restricts what recordings qualify for random selection or not. If set to 'yes', you're saying to Giocoso, 'only play recordings which have never been played before'. This is very handy for ensuring that you don't listen to the old Karajan war-horse recordings over and over again! It means Giocoso is always looking for recordings that do not have entries in the plays table, and ensures that your listening experience is of recordings you've never heard before (at least, not whilst Giocoso is playing them!)
If you look at my own play history on this website, you'll notice that (around September 2023 at least), (almost!) every single play recorded has a play count of one:
That was achieved by setting 'only play previously unplayed works' to 'yes'. It has meant that I'm approaching the point where I can say with confidence that every recording I own has been listened to at least once. I therefore have no 'dark corners' of my music collection that have remained unplayed and unloved for years on end. Once I reach the point that everything I own has been played at least once, I can set this parameter back to 'no' and let Giocoso pick what it likes to play next, but it's certainly been a useful tool up to this point.
3.4.4. Display Album Art in its own Window
As described in Section 3.3.7 above, Giocoso displays album art associated with each recording it plays. By default, it displays it embedded within the same terminal window in which it is itself running -but not all terminals support doing this. Even if your terminal does support doing this, it might not be something you prefer to happen. If, instead, you'd like to see album art displayed in its own, separate window (as it was in all previous Giocoso versions) then you can set the value of this parameter to 'yes'.
3.4.5 Force the use of PulseAudio
By default, Giocoso will output its audio signal to the ALSA sound system, which is why (back at Section 3.2.1) you have to supply an audio device parameter to Giocoso. The reason for this is that ALSA (the Advanced Linux Sound Architecture) is pretty 'fundamental' and close to the hardware. Sound servers such as PulseAudio and PipeWire run on top of ALSA, so there's an extra layer of indirection involved (and that can mean mucking about with the audio signal, which is a bit of a no-no for classical music listeners).
However, this reliance on ALSA brings some restrictive consequences. For example, you cannot play more than one audio signal on the same ALSA device at a time, so if a Web Browser tab has played (say) a YouTube video and then been paused, it's now 'grabbed' the audio device and nothing else can play to it. Playback from Giocoso will therefore just never start.
You also can't 'pipe' audio via ALSA over the network. That might be something you've never even thought of wanting to do in the first place, I realise: but it's actually quite a nice thing to have a little PC in the loft acting as your Giocoso server and being able to tell it to play music on your desktop PC one minute, and on the tablet in the kitchen the next. ALSA cannot do that -but sound servers like PulseAudio can.
It might, therefore, happen that you need Giocoso to use PulseAudio, despite its default insistence on the 'purity' of directly using ALSA! That's what this parameter is for: set it to 'yes' and Giocoso's audio output will go via a running PulseAudio server, from where it could (if suitably configured) be piped to another PC on the network entirely.
Obviously, this sort of audio signal indirection and general mucking-about is not what Giocoso expects or recommends, so it's not recommended to set this parameter to 'yes', but it's there if you need it to be.