Niente's Persistent Configuration File

1.0 Introduction

Nientes 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/niente folder and called niente.conf. A default parameter file is downloaded from this website whenever you first install Niente. It can be edited at any time using your own preferred text editor (or by taking Option 9 from Niente's Main Menu screen, which opens the file in whatever text editor the EDITOR environment variable has been set to). Changed parameters will usually be applied immediately, but sometimes exiting and re-launching the program will be required before they take effect.

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). Niente 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 Niente runs, it will download a fresh copy of the default configuration file, and you can start clean from there.

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, but I'll try to spell out some details about each parameter in what follows


Niente is a database-driven application. It scans your hard disks for FLACs, but the data it captures about those FLACs (describing their names, their tag values and so on) are stored within a database that you have to create. A database must have a name, however, and the DBNAME runtime parameter determines what name the database will have when it's first created (by taking Main Menu Option 1). The same parameter then controls what database Niente will automatically open every time it's launched after database creation. The defauilt database name is niente, but you can change that to something else if you'd prefer.


The MUSICDIR parameter tells Niente what folder on a hard disk is to be considered the 'root' of the folder hierarchy in which your music files are stored. Niente will scan all sub-folders of this 'root' folder, trying to find FLACs, whenever an integrity check is launched. There is no default value for this parameter (hopefully, for obvious reasons). You are required to set it the first time you run Niente, therefore. The folder structure it points to must already exist on disk.


UTFCHARS is a bit of a strange parameter and is needed by Niente only when running on particular operating systems/distros that, for one reason or another, are misconfigured in their region/locale settings. Niente relies on the metaflac program to read tag data from 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 Niente) 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.


PARALLELISM allows Niente to use your CPU's multi-threading capabilities, so that it can perform more operations simultaneously (meaning things complete more quickly). By default, Niente 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 Niente would naturally discover to be available. For example, on a 16-core CPU running with hyperthreading enabled, you'd expect Niente to decide it can run with a degree of parallelism of 32. Set PARALLELISM=4, however, and Niente 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 Niente'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 Niente uses whatever number of threads your CPU actually provides.


When you produce reports in Niente, the font used to display the reports is the one specified by the TERMINAL_FONT parameter. By default, it will use Courier, but you can set it to anything you like -though it really needs to be a fixed-width (or 'monospaced') font, otherwise the reports will display in an extremely garbled fashion. Whatever font name you supply for this parameter, it needs to have been already installed on your operating system.


When running Niente's Reports Menu Option 9 (the 'Recordings with ALBUMART sizing issues'), Niente will list any FLAC files which it has found to have embedded album art which is too small, too big or not square. The SMALLART parameter is how Niente works out that a piece of album art is too small: it is set to the minimum number of pixels which is to be considered acceptable, in either or both the horizontal or vertical dimensions. By default, it's set to 300, meaning that a piece of album art that was 280x760 pixels wide/tall would be considered too small, because its width falls below the minimum acceptable value.


Very similar to SMALLART, the LARGEART runtime parameter defines the maximum number of pixels which is to be considered acceptable, in either or both the horizontal or vertical dimensions, before a piece of embedded album art is declared to be too large. If you were running with a standard 1080p monitor, for example, it would be pointless to embed artwork that's (say) 3800x3800 pixels big, since you could never meaninfully display artwork of that size on your screen in the first place. By default, the parameter is set to 1600, meaning artwork that was 900x1800 would be considered too large for reporting purposes, because one of its dimensions exceeeds the permitted size.


The SQUAREART runtime parameter is a Boolean (meaning it takes a value of 1 if on and 0 if off). By default, it is set to 1 (i.e., 'on'). The parameter determines whether Niente should consider non-square album art to be a problem for reporting purposes. If a piece of album art is discovered to be (say) 600x602 pixels wide/high, then that is well within the default SMALLART and LARGEART parameters, so it's not going to be considered too small or too big. But 600x602, whilst very nearly square, isn't actually spot-on, 100% square... and with SQUAREART=1, that will be considered worth reporting on the 'Recordings with ALBUMART sizing issues' report.


The VOLUMETHRESHOLD runtime parameter takes a numeric value which represents an absolute volume level (in decibels) below which Niente is not to consider a FLAC file to be a suitable candidate for volume boosting, as per the Reports Menu Option 10 report ("Recordings with potential volume boosts"). That is, zero decibels is considered to be the maximum possible volume for a file to have before its audio starts distorting or clipping, so we want to avoid boosting files to a volume greater than 0. Niente's analysis of FLACs (undertaken with Main Menu Option 7) might indicate that a particular FLAC was recorded with a peak volume level of -1.3dB, meaning that it's 1.3dB below zero... and could thus conceivably be volume-boosted by 1.3dB to get its maximum volume to be zero, the loudest non-distrorting volume it could have.

The question, however, is: is a 1.3dB volume boost worth it? Do you care if a FLAC is 1-and-a-bit decibels quieter than it theoretically could be? By setting the VOLUMETHRESHOLD runtime parameter, you control the point at which you separate 'worth having' volume boosts from 'not worth it' ones. The parameter has a default value of 2, meaning that the FLAC with a volume of -1.3dB would be considered 'loud enough' and would therefore not be included on the 'potential volume boosts' report. A FLAC that was discovered to have a peak loudness level of -2.4dB would, however, be considered a suitable candidate for a volume boost and would thus be listed on the report.

Niente, of course, does not do any volume boosting (you'll need a program like Semplice for that), but it merely reports on what could be volume-boosted, with this parameter defining a 'filter threshold' so that files which are already almost as loud as they could possibly be are not included on the report.

11.0 Conclusion

In summary, therefore, there are two parameters which need to be set from the moment you first run Niente: DBNAME and MUSICDIR. Whilst DBNAME has a default value (of 'niente') which you could live with, MUSICDIR has no such default and you need to set it to the root of your music collection folders before anything useful can be accomplished with Niente.

All the other parameters make adjustments to the way Niente works: the font it uses to display reports, the threshold cutoffs to apply when deciding if some artwork is too large or a FLAC is too loud, and so on.

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

|[Back to Front Page]|