Semplice’s Persistent Configuration File

1.0 Introduction

Semplice's behaviour is controlled by the value assigned to a number of configuration parameters. Those parameters are contained within the persistent configuration parameter file, which is a plain text file stored within the $HOME/.local/share/semplice folder and called semplice.conf. A default parameter file is downloaded from this website whenever you first install Semplice. It can be edited at any time using your own preferred text editor (or by typing 'e' from the main Semplice program menu, which opens the file in whatever text editor the EDITOR environment variable has been set to). Changed parameters will be applied the next time the program is run.

Whenever you edit the persistent configuration parameter file, it's important that you make no changes whatsoever to the first 10 lines (the ones bounded by a double-lined box). Semplice validates the configuration file by assessing these ten lines. If you add so much as a full-stop or comma to any of the lines contained within that box, the configuration file will be declared invalid. If you accidentally invalidate your configuration file, you can simply delete the file completely: next time Semplice runs, it will download a fresh copy of the default configuration file, and you can start clean from there.

Some persistent configuration parameters control appearance; some control behaviours; some enable particular capabilities. For the most part, it is hoped that the commented-out text contained within the configuration file for each parameter is self-explanatory and self-documenting. Nevertheless, in the sections which follow, I'll try to describe each 'group' of parameters in turn in more detail.

2.0 Appearance Parameters

The Semplice main menu is drawn with 'IBM Linedraw Characters', by default. Your operating system or your choice of terminal font may not permit these characters to be drawn correctly, resulting in a garbled appearance. You can, however, change the values for LINEDRAW1, LINEDRAW2 and LINEVERT characters to help matters. For example, if you set LINEDRAW1="*", LINEDRAW2="=" and LINEVERT="|" (asterisk, equals sign and vertical pipe characters respectively, directly typed from your keyboard), you'd get this result:

It's 'dottier' than the IBM linedraw characters would make things appear, but at least only 'normal' characters are in use, so standard monospaced fonts should display them correctly, without special effort.

Please note that the values for these parameters must be enclosed by double quotation marks and should only be one character long: they are in any case truncated to be the first character supplied if you try to set any of them to be more than a single character.

The colour of the lines and text within the main menu are governed by the DISPLAYCOLOR persistent configuration parameter. By default, the parameter is assigned a value of 'newclassic', but other values of light, dark, neutral and classic are valid. If the parameter is set to an invalid value, the 'newclassic' is silently applied. The way these parameters interact with the apperance settings of your terminal can be complicated, so you'll need to experiment with them. For example, here's a setting of "light" whilst the terminal is set to use a 'Solarised' appearance profile:

But change the terminal's profile to be 'Red on Black', and the same setting of DISPLAYCOLOR=light causes the program to appear like this:

The results are very different, and yet the Semplice parameter remained set to the same 'light' value in both cases. As I say: experiment to get the best results!

3.0 Behaviour Parameters

NAMEBITS is set to either 1 or 0: 1 is the default, 0 switches the behaviour off. If enabled, the parameter kicks in whenever you properly 'Q'uit from Semplice, to perform 'post-processing' on any FLAC files contained within the current folder. At that point, Semplice will analyse the FLACs to determine if they are 44100Hz 16-bit standard CD Audio, or whether they are 24-bit files at higher resolution sampling rates -and, having determined this, those bit depths and sampling rates will be incorporated into the physical file name.

For example, say you have a file called 01-Allegro.flac. If NAMEBITS=1 (the default) and you have, for example, used Semplice's Option 1 to set that file's composer, and then you type q to quit, the file will be renamed to be 01-Allegro-16-44100.flac

AUTOREPLACE tells Semplice what to do if, when trying to tag up a new set of FLACs with track titles, it detects that the files already have TITLE tags. The parameter takes value of 1 (enabled) and 0 (disabled): enabled is the default behaviour. Remember: the parameter only kicks in when track titles are being set (using Semplice's Option 9). Here's what happens if the feature is disabled:

Semplice has detected the presence of an existing TITLE tag and therefore displays it and asks if you want to alter or replace it. You have to answer yes or no to that, then type in the new TITLE tag. Now imaging doing that for 60 tracks belonging to, say, a Handel oratorio!

So here is what happens when the Autoreplace feature is enabled (the default):

This time, Semplice has spotted the existing tag and is displaying it (in white, here)... but has already assumed you will want to update/alter it, so isn't bothering to ask you the question. If you start typing, you are automatically supplying a brand new TITLE tag for this file. You can still, of course, just press [Enter], which will mean the existing tag will be re-applied to the file without alteration.

AUTOREPLACE thus just stops you being asked 'are you sure' questions interminably, which can be helpful when there are lots of track titles to be replaced!

AUTODELETE sounds similar to AUTOREPLACE, but it only kicks in when you take Semplice's Option 11 to combine multiple FLACs into a single SuperFLAC file. It has values of 1 (enabled) or 0 (disabled), and disabled is the default. The issue is that, if I combine 4 movements of a Beethoven symphony into a single SuperFLAC representing the entire symphony, do I want the original per-movement tracks left on disk, or would I like them to be deleted automatically? When you get comfortable with SuperFLACs, you will probably be happy with an auto-delete, but before you reach that point, you may naturally have misgivings about losing your source FLACs before having listened to the SuperFLAC and made sure it sounds OK.

Set this parameter to 0, therefore, and Semplice will ask you if you want to delete the source, per-track, FLACs -and you can decline to do so or accept the proposal as you prefer. Set the parameter to 1, however, and Semplice will assume that, once the SuperFLAC has been created, the per-track source FLACs should automatically be deleted -and will therefore delete them without asking you first. Handle this option with care until you are comfortable with it, basically!

ARTDELETE defines what happens when you tag your FLACs with album art files, using Semplice's Option 6. The parameter takes values of 1 (enabled) or 0 (disabled) and 0 is the default. Once Semplice's has been pointed at a JPG or PNG on disk as the album art that should be applied to a set of FLACs, it embeds the image file within the FLACs themselves. There is thus no real need for the standalone JPG or PNG to remain on the file system any longer. If ARTDELETE is enabled, therefore, Semplice will automatically delete the source image file once embedding has completed. If it is deleted, the album art image will remain on disk as a separate image file, somewhat redundantly because, as I say, it will also have been embedded into the FLAC files themselves.

Although the default for this option is disabled, I would recommend setting it to enabled as soon as you are comfortable with album art embedding: having spurious JPGs clogging up your file system unnecessarily is not a good thing to have happen!

AUDIOIN_DELETION is another of these 'shall I automatically delete things' parameters. It applies only when you are converting files from one audio codec to another, using Semplice's Option 15. If you have converted an MP3 to an OGG, for example, do you want the MP3 retained on disk? Or if you are converting an ISO to a bunch of high-resolution FLACs, do you want to keep the ISO once the FLACs are safely created? If the parameter is set to 1, Semplice will automatically delete the source audio file once the converted files are known to have been created. If the parameter is set to 0 (the default), the source files will be left alone and it will be up to you to delete them when you are certain you have no further need for them.

Personally, I would only ever perform audio conversion on backups of my audio files, so I would have no problem setting AUDIOIN_DELETION=1... but your mileage may well vary and you might not want to get that bold until you've done a few conversions and found the results to be satisfactory!

UTFCHARS is a bit of a strange parameter and is needed by Semplice only when running on particular operating systems/distros that, for one reason or another, are misconfigured in their region/locale settings. Semplice relies on the metaflac program to actually write tags into FLAC files and metaflac itself has a capability whereby, if it cannot detect your operating system's locale correctly, it will automatically convert 'foreign' or accented characters to plain 'English' equivalents. The trouble is that the system locale detection sometimes goes wrong and, at that point, metaflac starts replacing accented characters when it's not supposed to do so.

For example, if you type the composition name as Concert champêtre, you may find it being stored as Concert champetre (without the circumflex accent on the first e of 'champêtre'). Similarly, if you ever carefully type in Götterdämmerung as the track tile and then discover it's been stored as plain Gotterdammerung, you know you're affected by this locale problem.

Setting UTFCHARS="--no-utf8-convert", however, stops metaflac (and thus Semplice) from doing this 'down-conversion' of accented characters to plain-English equivalents. If your locale settings are fine, such that no erroneous down-conversions happen anyway, then leaving the parameter to this value makes no difference: which is why the parameter defaults to this value. It does no harm when not needed and prevents accent downgrades if it is.

If you set the parameter to have a value of anything other than "" or "--no-utf-convert", you get --no-utf8-convert anyway. Commenting the parameter out entirely, or setting it to "", is fine: it means metaflac will do as it sees fit and if that means downgrading your accented characters, so be it.

4.0 Capability/Feature Parameters

DESTDB is only relevant if Semplice is run on a system that has already had my Giocoso music player installed on it. Let's say you have used Semplice's Option 14 to boost the volume of a folder full of FLACs; maybe you've converted them into a single SuperFLAC file. The sensible thing to do at that point is, perhaps, to play the resulting files to make sure they sound OK. Semplice's Option 16 lets you invoke Giocoso in 'play this folder' mode, if Giocoso is already installed (if it's not, the menu option is not displayed at all).

Once Giocoso has played a folder-full of FLACs, it can record the fact of its play completion in a database -and the name of that database can be passed to Giocoso by setting the DBNAME parameter in Semplice's persistent configuration file.

The default value for this parameter is nothing at all -meaning that Giocoso can play FLACs just fine, but it won't record the fact of the play anywhere. If you set the parameter to a non-null value, the value must relate to a Giocoso database name that actually exists: if you set it to a name that doesn't represent a Giocoso database, then Giocoso will error when it tries to record the fact of a play in a non-existent database.

PARALLELISM allows Semplice to use your CPU's multi-threading capabilities, so that it can perform more operations simultaneously (meaning things complete more quickly). By default, Semplice works out for itself how many simultaneous 'threads' your CPU is capable of running: this parameter should only be used to force a lower degree of parallelism than Semplice would naturally discover to be available. For example, on a 16-core CPU running with hyperthreading enabled, you'd expect Semplice to decide it can run with a degree of parallelism of 32. Set PARALLELISM=4, however, and Semplice will only use 4 simultaneous threads, leaving 28 'on the table', as it were.

If you comment out the parameter entirely, or set it 0, then Semplice's default behaviour (use as many threads as are available) kicks in. This also happens if you try to set the parameter to a number higher than the number of threads actually available: the parameter's assigned value is silently ignored and Semplice uses whatever number of threads your CPU actually provides.

AUDIO_QUALITY is used by Semplice when creating lossy audio files, using its Option 15. It is set to 4 by default, which provides 'reasonable' audio quality for WMAs, MP3s and OGGs alike. The parameter can take other numeric values, however, which will produce files with higher or lower audio quality, depending on which direction you move the number. Unfortunately, MP3s work their quality in an inverse way to that used by OGGs or WMAs. In other words, set AUDIO_QUALITY=9 and WMAs and OGGs will be produced at their highest possible quality -but MP3s will be produced at their worst. Set AUDIO_QUALITY=1, however, and MP3s will sound great, but WMAs and OGGs will likely sound pretty awful. Practically, therefore, unless you are prepared to keep altering the AUDIO_QUALITY parameter value, you need to pick a lossy audio format to use... and stick with it; you then set an AUDIO_QUALITY that works best for that audio codec and no other.

ALLOW_CUSTOMTAG takes a value of 1 (enabled) or 0 (disabled), with 0 being the default. Custom tags let you mark up your FLAC files with tags for things like recording engineer, record label, price at purchase, year of acquisition... and anything else you can imagine. You configure these custom tags separately (see below), but unless you also set ALLOW_CUSTOMTAG=1, they won't be usable. Practically, this parameter governs whether Semplice Option 7 is visible or not: if it's set to 0, then Option 7 just won't be seen on Semplice's main menu.

CUSTOMTAGx (where 'x' is a number from 1 to 8) allows you to define up to 8 pieces of metadata which you might wish to add to your FLAC files which are not otherwise allowed for in Semplice's main tagging options. They are free-form, in the sense that you define (a) the 'prompt' you want to see when adding the tag; and (b) the name of the tag that will be used when the metadata is added to the FLAC. The two component parts of the tag must be separated by a colon, and both must be enclosed within double quotation marks.

For example: CUSTOMTAG1="Recording Engineer Name:RECORDING_ENGINEER" means that you will see a sub-menu option labelled "Recording Engineer Name" and when you take that option and type in "John Culshaw" as its value, the metadata "RECORDING_ENGINEER=John Culshaw" will be added to your FLACs.

The prompt is related to the actual tag name only by the assignment of both to the same CUSTOMTAGx parameter. That is, if you set CUSTOMTAG1="Tea Lady:RECORDING_ENGINEER", you'd be prompted to supply the name of the Tea Lady at the recording session -and if you said "Miss Hudson", you'd end up with "RECORDING_ENGINEER=Miss Hudson" as your FLAC tag.

You can only define eight custom tags. If you define more than that (say, by adding CUSTOMTAG9 into the parameter file), the extra ones are silently ignored.

DISPLAYONEXTRACT is a new parameter introduced in version 1.01. That version introduced the ability to extract album art from the first FLAC found in the current working folder, by selecting the 'a' menu option. Taking that option always causes the embedded album art found in the first FLAC to be written to a standalone file, called albumart.jpg, within the current working folder. From there, you could move, copy or even edit the album art using any of your preferred graphics applications. In addition, however, if DISPLAYONEXTRACT is set to a value of 1 in the persistent configuration file, then the albumart.jpg file will be automatically displayed (in a non-editable graphics window) after it has been extracted. Set the parameter to any value other than 1, or don't set it at all, and though the extraction of the album art will still take place, the auto-display of it afterwards won't happen.

5.0 Conclusion

In summary, therefore, there are quite a few parameters settable within the persistent configuration file which can make significant changes to Semplice's default behaviours, capabilities and appearance. For the most part, however, it is hoped that the default values for all the parameters will provide adequate functionality for Semplice, out-of-the-box. Only start tweaking parameter values if you determine that there are areas of lacking functionality that you really need.

Should you ever muck up your configuration file, such that you prevent Semplice running properly, it is OK to simply delete it: when you first run Semplice after that, it will fetch a new, default file down from this web server for you -and you can start editing it again, from scratch.