Liner Notes
Red Guitar Pick
The FATpick Blog

There are a bunch of configuration options to be found in FATpick's settings menu. You can customize the user experience and application look-and-feel; configure the audio devices that FATpick listens to (or plays from); enable or disable features; even adjust the pitch and note-onset detection to better fit your equipment and environment; and more - using the various toggles, sliders and selectors found in the settings menu.

But there are a number of other configuration options that are too advanced, experimental, or otherwise inappropriate to expose as one of the in-app preferences. In support of these "hidden" settings, an alternative configuration mechanism - the .ini file - is provided. This is a plain-text file - saved in your home directory - that can be used to control some of the more foundational aspects of the application, its behavior, and the context in which it executes.

PLEASE NOTE: Most users can simply ignore this feature. It's just not needed, virtually all of the time. But we thought it would be useful to document the basics of the INI file configuration, in case you're feeling adventurous and so that our customer support team has something to point users to in the rare cases in which this sort of advanced configuration is recommended or required.

I will describe the basic INI file set-up (and testing) in this post, but it's not meant as an exhaustive reference for the configuration options themselves. We're making changes (adding new settings, sometimes removing old ones), well, not "all the time", but often enough, so it would be hard to provide that sort of reference even if we wanted to. We'll add subsequent posts to cover specific options as needed; and the customer support team might provide instructions on the use of certain settings in response to some issue or question that you raise. The objective for this post is just to be a general introduction to the capability, how to set it up, and how to make sure it's working.

What is an INI File?

An INI file is a loosely standardized or at least conventional format for storing an application's configuration settings. A lot of applications use this sort of thing to allow for persistent, user-specific application configuration in a format that is relatively convenient to edit by hand, outside of the application itself. INI is short for "initialization".

INI files are plain-text documents, typically stored in a user's home directory, that specify the configuration of various application settings. This configuration is expressed as a list of key-value pairs, e.g., something like key = value. See below for a more detailed description of the syntax used for INI files.

INI files are often used to control some of the fundamental or foundational aspects of an applications's behavior: options that may be difficult or impossible to change after the app is fully up and running. This rubric describes some but not all of the options that FATpick supports within its INI file configuration. In some cases the value specified in the INI parameters must be known before the application can start - they influence the context in which the process itself is running. But in other cases the INI file is simply a convenient way to specify a default or initial value for settings that can also be changed (often via the in-app settings menu) while the app is running.

Most INI-file supporting applications, FATick included, will read the contents of the INI file and apply any relevant settings or customizations are applied when the application is launched.

Creating an INI File for FATpick

The ini file is a simple, plain-text file of the sort you might create with Notepad or TextEdit.

TIP: Be sure to actually save the file in a plain text format. Windows Notepad should do this automatically, but the TextEdit app on macOS defaults to a "rich text" mode. Go to the Format menu and select "Make Plain Text" to switch to the plain text mode in TextEdit. More generally, in whatever editor you're using you may want to check for a plain-text option within the "Save As..." menu, or save the file with a ".txt" extension which may cause the editor to use a plain-text format by default. If nothing else, there are a few free online tools that let you type into a web-based form and save (download) the content as a plain text file. Based on nothing more than a quick Google search, here are a few that seem to be decent for this purpose: TextdDoc.co, OnlineTextEditor.com, EditPad.org

Using the editor of your choice, create a document that contains the following:

# my first fatpick.ini file
[env]
FATPICK_EVAR_TEST=Hello World!

You can use this link to download that example configuration as a plain-text file.

Save this document as a plain-text file named fatpick.ini, or if you prefer, fatpick.ini.txt.

Move this file into your "user home" directory. On macOS that's usually something like /Users/account-name. On Windows it's usually something like C:\Users\account-name.

Congratulations! You've created your first FATpick ini file. Now let's make sure it's working properly.

INI config info messages
Details of the active INI file configuration as reported at the bottom of the General Settings menu.

Once the fatpick.ini file has been placed in your home directory, launch the FATpick app like you normally would. Once FATpick is open, got to the General Settings menu (Settings > General Settings). If everything is working properly you should now see a message at the bottom of the menu (you may need to scroll down to see it) that states something like:

Custom application settings were applied at launch from the ini file at: YOUR-INI-FILE-LOCATION

This means that FATpick was successfully able to find your configuration file.

Moreover, FATPICK_EVAR_TEST is special setting that can be used to test or debug the configuration setup itself. When that parameter is set you should find a message at the bottom of the general settings menu that displays the value of that property. So when the INI configuration above is provided, if everything is working properly you should see something like:

You have successfully set FATPICK_EVAR_TEST to the value "Hello World!".

at the bottom of the general settings screen.

If you see that message, you know that (1) your INI file is saved in the right location for FATpick to find it and that (2) FATpick was able to parse your INI file successfully.

TIP: If any errors are encountered while parsing the INI configuration you should find a warning message and some additional diagnostic information at the bottom of the General Settings menu.

Where to Save the INI File

At launch, FATpick looks in a few well-defined locations in an attempt to find a custom configuration file. When a configuration file is found in one of these locations, FATpick will parse the file and apply the recognized settings.

At most one configuration file is ever active at one time. The first such file that is found is the one and only file that will be used for that session. All other config file locations will be ignored, even if they also contain an otherwise valid configuration.

TIP: Look at the message at the bottom of the general settings screen to verify which configuration file - if any - FATpick is currently using.

The INI file must exist when the application is launched, and is only read at start-up. Any changes made to these files after FATpick is already running will be ignored until you close and re-open the program.

Base File Name

By default, FATpick expects the ini file to be saved undre one of the following names:

  1. fatpick.ini.txt
  2. fatpick.ini
  3. .fatpick.ini.txt
  4. .fatpick.ini

It doesn't really matter which one you choose, they all work the same. But that list of names is in priority order. FATpick will look in that order for your INI configuration. The first such file that is found will be the configuration that is applied. Any other files, should they happen to exist, will be ignored.

To avoid confusion, we recommend that you only use one of these filename variations at a time. The variants are meant to provide flexibility in selecting a name that works for your environment, not as some sort of queue for configuration fallbacks.

Parent Directory

The ini file should be saved into the home directory for your account. This is typically located at C:\Users\your-account-name (on Windows) or /Users/your-account-name on macOS. So the fully-specified location of your FATpick ini file will look something like C:\Users\your-account-name\fatpick.ini (Windows) or /Users/your-account-name/fatpick.ini (Mac).

Custom INI File Location

If you know what an environment variable is and how to set one for your operating system, you can use one to override the default INI file discovery logic, and specify a new, custom location for the file instead.

When the environment variable FTPK_INI_FILE is set - and a file is found at the location specified by the value of that environment variable - FATpick will use that configuration file, ignoring all others.

Again note that you can look at the message at the bottom of General Settings to confirm which configuration FATpick is picking up.

The INI File Format

An INI file is typically divided into one or more sections, indicated a single word (no spaces) enclosed in square brackets, [LIKE_THIS].

Beneath each heading you can provide a set of name/value pairs to describe the individual settings or properties, and the value that they are set to. These take the form key=value.

For example, in FATpick, [env] is one of the recognized section names, and FATPICK_EVAR_TEST is one of the recognized keys (properties) that can appear in the [env] section. So one example of a valid fatpick.ini file is the following:

# Lines that start with a hash character are comments.
[env]
FATPICK_EVAR_TEST=ini syntax example

As seen in the example, lines that start with # are treated as comments (as are lines that start with ;, which is a older but popular INI syntax convention). Everything after the comment delimiter (through the end of the line) is ignored by the parser. You can put anything you want in there.

Blank lines - and leading whitespace characters like spaces or tabs - are also ignored, so you can use spacing and indentation to lay-out the file to your liking. In most cases you are also allowed to add spaces around the = symbol in key/value pairs, so foo=bar, foo = bar and foo= bar are equivalent and equally value ways of setting the parameter "foo" to the value "bar".

There are some more advanced syntax options available, but most of the settings used by FATpick are covered by the simple key = value formulation.

NOTE: As you might be able to deduce from the label and some of the in-app messaging, the [env] section of FATpick's INI file is used to specify configuration options that can also be represented as environment variables. That is, the [env] section of the INI file is just an alternative - and for many users, more convenient - way to control the application's execution context via environment variables. For most of the application settings that can be configured through environment variables, adding a name-value pair to this section is equivalent to setting the environment variable with the same name, and vice versa. I.e., rather than using the INI file listed above you could specify a FATPICK_EVAR_TEST value by setting the corresponding environment variable (roughly like export FATPICK_EVAR_TEST=HelloWorld but the details vary from platform to platform). For this particular setting the General Settings menu message will be displayed whether the value is provided via the INI file or through an environment variable, so the same approach can be used to validate both your INI and your ENV configuration.

Please note that this equivalency only applies to the FATpick-specific environment variables - those that are managed by the application itself. These typically have a FTPK_ or FATPICK_ prefix. There are other environment variables that may impact the way in which FATpick executes, but many are handled by the operating system, outside the scope or control of the application itself. Only those variables that are fully "self-contained" - i.e., only known to or used by the FATpick application itself - can be specified in the INI file. Moreover, there are even some FATpick-specific parameters that for various logistical reasons cannot be defined within the INI file and must be provided as actual environment variables. The FTPK_INI_FILE variable described above is one example. Since that variable is used to indicate where to find the INI file we should apply, by the time the INI file is loaded and parsed it's no longer relevant. But this sort of exception is rare.

There's little need to include data that fall outside of the basic ASCII or extended Latin character set in a FATpick INI file (roughly the numbers, letters and symbols you find on a typical North American or European keyboard), but if you should need to include other glyphs - even emojis - you can do that too. FATpick assumes that the text in the INI file is represented in the UTF-8 encoding. UTF8 can represent pretty much any character, glyph or symbol used in modern (and many historical) languages an writing systems, but it is also compatible with ASCII and most ASCII-superset encodings across the range of single-byte characters you're likely to use in practice. If you're not sure what all those words mean, the gist of it is that you probably don't need to worry about the text encoding (the way in which letters, numbers and symbols in the text are represented in raw binary data) used when you write the INI data to a file, it should "just work". But if you're asked to choose an encoding while saving the file, use UTF-8. That's what the parser is expecting.

FATpick's INI file parser is pretty forgiving, but if any errors are encountered while processing the file you will find a warning message at the bottom of the general settings menu, below the ini-file-location indicator.

Removing a Custom INI Configuration

To disable your custom settings and restore the default context, simply move, delete or rename the configuration file and re-launch the app.

Look for the messages at the bottom of the General Settings menu to confirm that your custom configuration was removed. If any INI configuration is active, the location of the source file will be listed there. If no such message appears, no INI configuration was found or applied.

Caveat Emptor

We like to move fast. But we don't like to break things.

FATpick maintains an aggressive pace of development: an updated version of the app is released roughly every couple of weeks. To square that with our desire not to break things we're pretty diligent about backwards compatibility. We put a lot of effort into ensuring that your application settings and other local customizations are preserved (and continue to be supported) from release to release. It's a little aspirational - sometimes we deliberately decide to replace or override legacy options in the interest of progress, and we're not perfect so we've screwed it up accidentally a few times too, of course - but our track record on this is pretty strong. But most users are unaware of the degree to which their configuration for legacy or retired are "translated" into the nearest equivalent when the app is updated, and we see that as an absolute success.

We intend to apply a similar philosophy to the INI file configuration. That is, we want to make sure that any customizations you've set up within your INI file configurations are respected - i.e., continue to work as you expect - even when the application is upgraded to a new version.

However, with the INI file customizations you are venturing into more uncharted territory. Many of these options are too experimental or complicated to fully "commit" to just yet. Often that's part of the reason they haven't been added to the regular application settings interface.

Because of this, it's a little more difficult to hold the INI file configuration options to the same backwards-compatibility standards that we use for the regular application settings. We still make an effort to maintain compatibility whenever possible. And to be honest backward compatibility for these hidden settings hasn't yet been much of an issue. But if you're using the INI file (or ENV) configuration to manage certain obscure or undocumented application settings, please be aware that it's possible that an upgrade may change the way in which the application responds to a given setting (or whether it responds at all).

FATpick
Also see more posts by or tagged , or .
Or, visit the tag index or view the latest posts from the Liner Notes blog.