These tools are intended to assist with manipulating the foobar2000 configuration file, foobar2000.cfg. This file is in a proprietary binary format, and is therefore difficult to edit or even view normally. Furthermore, it has a checksum embedded within it to make editing it impossible.
The FooCfgToXml tool will take a binary config file and produce an XML file from it. This XML file is a complete description of its contents, and can be edited by any XML or plain text editor. The same tool can then take that XML file and re-create a binary config file from it. Because this binary config will not contain a valid checksum, the tool's third function is to patch the foobar executable so that it ignores the checksum when loading config files.
Additional tools are provided as a convenience to help with common manipulations of the XML file, but as the format is now open and readable it is hoped that others will develop further scripts, transforms or tools to work with it.
No installation is required for these tools, each .exe file is self contained. They do, however, require the .NET Framework 2.0 to be installed.
All the compiled tools can be found in the "bin" folder of the distribution.
This tool has three uses. Primarily, it can convert a foobar binary config file to an xml file, convert that xml file back into a binary config file. If the filename passed to it has an extension of .cfg, it tries to convert it to xml. If the extension is .xml, it tries to convert it to binary.
The xml format should be fairly clear. Where the binary data can be guessed to be a UTF8 string, the string is presented in a <String> element so it can be edited easily. For data that is not a string, the data is presented as hexadecimal values, in <Hex> elements. These can also be edited, but more care must be taken with them than the strings.
The third use of this tool is to patch the foobar2000.exe file so that it ignores the checksum of config files.
Although backups will be automatically created, it never hurts to make your own backups before running this tool on anything you would hate to lose.
Usage: FooCfgToXml.exe (foobar2000.cfg|foobar2000.cfg.xml|foobar2000.exe)
Examples:
FooCfgToXml.exe "C:\Program Files\foobar2000\foobar2000.cfg"
Reads the foobar2000.cfg file and creates (overwriting if already present) the file foobar2000.cfg.xml
FooCfgToXml.exe "C:\Program Files\foobar2000\foobar2000.cfg.xml"
Reads the foobar2000.cfg.xml file and creates (overwriting if already present) the file foobar2000.cfg. Any existing foobar2000.cfg file will be backed up to foobar2000.cfg.bak
FooCfgToXml.exe "C:\Program Files\foobar2000\foobar2000.exe"
Patches the foobar2000 executable (version 0.9.4.0 to 0.9.4.2 only) to ignore the checksum of .cfg files, allowing it to load .cfg file generated from XML by this tool. This operation permanently alters the .exe file, and only needs to be performed once. The original .exe is backed up as foobar2000.exe.bak
This tool is provided to help manipulate the xml file generated by FooCfgToXml. It does nothing that can't be done with an xml or plain text editor, but might be easier.
As well as the config xml file to be filtered, the tool should be passed a space-delimeted list of the component names that are required. The component names are just the filename of the component dll, or "Core" for the general settings. The xml file will then be filtered so that it only contains settings for the named components; all other settings will be removed from it.
Note that if a binary config is generated from such a filtered xml file, foobar will fill in the missing component settings with their defaults when it is next loaded.
Usage: FilterCfgXml.exe foobar2000.cfg.xml ["component" "component"...]
Examples:
FilterCfgXml.exe "C:\Program Files\foobar2000\foobar2000.cfg.xml" foo_ui_columns.dll foo_uie_tabs.dll foo_uie_playlists_dropdown.dll
Removes all component settings (including Core settings; add Core to the argument list to keep it) from the file foobar2000.cfg.xml, except for the settings for the components foo_ui_columns, foo_uie_tabs, and foo_uie_playlists_dropdown
This tool is provided to help manipulate the xml file generated by FooCfgToXml. It does nothing that can't be done with an xml or plain text editor, but might be easier.
Two config xml files should be passed to this tool. The first is the target config file, which is usually your current configuration. The second is the source config file, which is usually a partial configuration containing settings only for a few components. The tool will then merge the settings specified in the source file into the target file, replacing the existing settings. Any settings not specified in the source file are left as they are, so if the source file only contains settings for foo_run, for example, then only foo_run settings will be replaced in the target config file, and all other settings will remain the same.
Usage: MergeCfgXml.exe foobar2000.cfg.xml partial.cfg.xml
Examples:
FilterCfgXml.exe "C:\Program Files\foobar2000\foobar2000.cfg.xml" "C:\Downloads\Playlist.cfg.xml"
Takes the contents of the xml config file Playlist.cfg.xml and merges them in to the file foobar2000.cfg.xml. The settings specified in Playlist.cfg.xml will overwrite those in foobar2000.cfg.xml, but any other existing settings will remain unchanged.
This batch file is provided to help perform the common operation of taking a partial configuration xml file and merging it into the current foobar config file. If your foobar2000.cfg file is not found in "C:\Program Files\Foobar2000" then the variable set at the start of the file should be changed.
Usage: MergeToCurrentConfig.bat partial.cfg.xml
Open the file and edit the line:
set foobar_cfg="C:\Program Files\Foobar2000"
to point to wherever foobar2000.cfg can be found
Examples:
MergeToCurrentConfig.bat "C:\Downloads\Playlist.cfg.xml"
Converts the current foobar2000.cfg to foobar2000.cfg.xml, merges the contents of Playlist.cfg.xml into it, then converts it back to foobar2000.cfg.
These examples assume that foobar is installed without per-user settings, in C:\Program Files\foobar2000. It should not be hard to extrapolate them to other cases, though.
This is the simplest usage of the tool. Simply run FooCfgToXml.exe "C:\Program Files\foobar2000\foobar2000.cfg" and it will generate the file "C:\Program Files\foobar2000\foobar2000.cfg.xml", which you can then look at in a web browser or text editor to see what strings and values are in your config file.
If you want to distribute a config to other foobar users, but only want to include settings for certain components, then this can be done as follows:
First, run FooCfgToXml.exe "C:\Program Files\foobar2000\foobar2000.cfg" to generate the foobar2000.cfg.xml file as before.
Next, clean this xml config file by running FilterCfgXml and passing it a list of all the components that you want to distribute settings for. For example, FilterCfgXml.exe "C:\Program Files\foobar2000\foobar2000.cfg.xml" foo_ui_columns.dll foo_uie_tabs.dll would contain settings for only the foo_ui_columns and the foo_uie_tabs components.
Optionally, the next step could be performed on a separate foobar installation or as a different user to avoid having to worry about restoring the original configuration later. To do this, copy the file foobar2000.cfg.xml to the other installation folder or user's folder.
After cleaning, the xml file can now be converted back into a binary config by running FooCfgToXml.exe "C:\Program Files\foobar2000\foobar2000.cfg.xml". This will create (or replace) foobar2000.cfg, but it is best not to distribute this just yet as it won't have a checksum in it, so will only work with patched foobars.
If you haven't patched your foobar to ignore checksums yet, do so now: FooCfgToXml.exe "C:\Program Files\foobar2000\foobar2000.exe"
Finally, run foobar so that it will open the cleaned config file, populate any missing settings with their default values, and create a checksum for it. After closing foobar, the config file can now be distributed to other users without them worrying about how it was produced.
If you think there is some chance that the recipient might have a copy of this toolkit then it might also be worth sending the cleaned xml file from step 2 aswell. See the next example for more details.
If you know that the person you are distributing your settings to has a copy of this toolkit, then it is possible to send them the xml file containing only the settings you want to share with them. They can then merge these in with their existing settings and avoid having irrelevant settings reset to defaults, or to your values.
To do this, start in the same way as for cleaning a config for distribution, but after running FilterCfgXml to produced the cleaned xml file, simply send that xml file to the person you want to distribute the settings to.
The recipient can then use the MergeToCurrentConfig batch file to integrate the settings you sent them with their own.
Some settings have values which have their own deeper structure. In order to deal with these, there is an extensibility model for FooCfgToXml. Any dll files placed in the same folder as FooCfgToXml.exe will be attempted to be loaded as addins. This toolkit ships with one such addin dll already, ColumnsLayoutsInterpreter.dll, which can interpret the value of the foo_ui_columns Layouts setting.
To create a new addin, create a new .dll assembly which references FooCfgToXml.exe. Include at least one public type which implements FooCfgToXml.IValueInterpreter. Implementing this interface will allow your class to specify the guid of the type it can interpret, and to handle the conversion from byte array to XML, and in the other direction. More details about how to implement this interface can be found in the intellisense for it, or in the source file FooCfgToXml/IValueInterpreter.cs.
There are useful helper functions available to addins in the classes FooCfgToXml.CfgToXmlUtilities, FooCfgToXml.XmlToCfgUtilities and FooCfgToXml.Utilities.
This addin will interpret the layouts setting value, producing an XML tree reflecting the items of each layout preset. Each item in the tree has its own settings which are included in the tree. Some items' settings have their own deeper structure just like top level settings, so require further decoding. The addin has native support for the following item types:
It also has its own extensibility model to allow addins to support further item types, which works in the same way as the main model, except that the dll's must have a reference to UiColumnsInterpreter.dll, and implement the interface UiColumnsInterpreter.IItemInterpreter.
The source code to all tools should have been included in the distribution. If it wasn't, then please ask the person you got it from for it. All code is in C#, and should be compileable under the freely available Visual C# Express.
The goal of this toolkit was freedom to tinker, and freedom to share creativity. In the same spirit, please feel free to give copies of this work to whoever you think might find it useful. I'd recommend including the source code, as you never know when that might come in useful. Of couse, if you improve on anything that you think might be useful to others, please share your changes too!
If you have a previous version of this toolkit installed, upgrading should simply be a matter of deleting the folder of the existing files, and replacing it with with the new ones. If you have any xml config files created prior to version 0.0.3 then they will not be successfully converted by versions from 0.0.3 onwards, so should first be converted to cfg format under 0.0.2, then converted back again to xml under 0.0.3.
Version 0.0.3 adds additional support for opening files written under previous versions, so hopefully subsequent versions will be able to read xml files written under 0.0.3 and above directly.
Any third party extension dll's will probably need recompilation to link to the new file versions.