Configuration File sections

A configuration file contains the instructions to sync your foobar2000 stuff to ONE target. Therefore it is a good idea to store a configuration file in the root folder of the target it belongs to.

Comments in configuration files
Lines that begin with an Apostrophe are ignored. So you can put comments in your files. Also any line that does not start with a sectionname followed by equal-sign is ignored.

' This line is just a comment
Because this line does not begin with a sectionname it is ignored to.

Below sections each contain a table with following information:

Header	meaning
Name	is the section name in a configuration file. It is always followed by '=' (equal-sign) and it ends with the end of the line.
optional	means that you may omit the section. Best to do this is to place an Apostrophe right before it.
array	tells you if this section name can be used multible times. Best example is the section SyncRules, which defines the rules (plural!) for your synchronization.
items	tells the number of arguments, seperated by the seperator (below).
sperator	is used to seperate the arguements. Most times it is an asterisk ('*') but space and comma are also used.
status	should always be 'ok'. Maybe future functionallity or issues are signed here.

General sections

MediaName

Simply gives your target a name that is shown at some places.

Name	optional	array	items	sperator	status
MediaName	yes	no	1	none	ok
MediaName=Mom's 60 GB Ipod with Rockbox-Player

MaxSizeOnTarget

You may want to limit the total size of items on the target. You can do so by useing MaxSizeOnTarget. When the anaylisis is finished and more space would be required, you will be prompted to continue.

Name	optional	array	items	sperator	status
MaxSizeOnTarget	yes	no	1	none	ok
'simply specify the maximum size of all items in MB, that should be allowed on target. MaxSizeOnTarget=4000

MaxItemsOnTarget

If your target is limited to a maximum number of items it can manage, you can use this to give a warning if the maximum is exceeded. If the anaylisis is finished and there would be more than MaxItemsOnTarget on the target, you will be promptet to continue. If there is no maximum just enter 0 or comment that line.

Name	optional	array	items	sperator	status
MaxItemsOnTarget	yes	no	1	none	ok
MaxItemsOnTarget=1000

ReserveFreeSpace

You may want to reserve a given amount of free space on the target for other stuff then audio. You can do so by useing ReserveFreeSpace. When the anaylisis is finished and the estimation would cause less free space after sync, you will be prompted to continue.

Name	optional	array	items	sperator	status
ReserveFreeSpace	yes	no	1	none	new, ok
'simply specify the amount of space in MB that should be preserved. ReserveFreeSpace=1000

WhiteListChrs

Contains all allowed characters for the paths on your target as RegExp expression. So any file/folder will get filtred and all characters which are not whitelisted here will be omited.

Name	optional	array	items	sperator	status
WhiteListChrs	no	no	1	none	ok
WhiteListChrs=[A-Z 0-9-+#@.=!_ÖÄÜßöaöäü(){}&§$\[\]]+

ReplaceChrs

Does a case insensitive search&replace for one or more sets of characters in the destination paths of your audio-files on the target. Useful if e.g. your car audio does not support special charcaters like german umlauts.
Replacement is done before WhiteListChrs-filtering happens. As you can see it is possible to replace single characters with words ('$' -> 'Dollar'). But because the seperator is the space character you can not replace space or use space in the replacement.
Below example replaces umlauts ä, Ä, ö, Ö, ü and Ü with '#' and '$ ' with 'Dollar'.

Name	optional	array	items	sperator	status
ReplaceChrs	yes	yes	2	<space>	ok
ReplaceChrs=äöü # ReplaceChrs=$ Dollar

SyncRules

Any source item (Medialibrary or playlist item) is matched against the rules to decide if it should be copied or converted (and which format). Rules cover items format, codec details and bitrate but also any TitleFormat-Expression can be used.
See detailed documentation here: SyncRules

Name	optional	array	items	sperator	status
SyncRules	no	yes	3	none	ok
'Tracker Formats SyncRules=IT0ignore SyncRules=MOD0copy SyncRules=6690copy SyncRules=XM0copy SyncRules=S3M0copy ' anything else SyncRules=<115copy SyncRules=>115VORBIS_96

ConvertFormats

contain the instructions for the formats you wish to use on your target.
See extra documentation here: ConvertFormats

Name	optional	array	items	sperator	status
ConvertFormats	no	yes	4-5	*	ok
' DEFAULT ConvertFormats=Vorbis_Q2OGG-vn -c:a libvorbis -ac 2 -ab 96k96_q2 ' MP3 ConvertFormats=MP3_256MP3-vn -ac 2 -ab 256k*256

MaxFFMPEGThreads

Defines how many parallel encoding tasks are allowed.

Name	optional	array	items	sperator	status
MaxFFMPEGThreads	yes	no	1	none	ok
MaxFFMPEGThreads=3

preCMD

Invokes a command line before analysis is started.

Name	optional	array	items	sperator	status
preCMD	yes	yes	1	none	not jet implemented!
preCMD=attrib "%1\%2\." -h%*%&
Parameter	meaning
%1	will be replaced by the driveletter of your target, for example 'G:'
%2	will be replaced by MLSyncBaseDir of your target, for example 'G:'
%3	will be replaced by PLSyncBaseDir of your target, for example 'G:'
%4	will be replaced by PlayListDir of your target, for example 'G:'
%*	will make FoobarSync tell to hide the cmd-window
%&	will tell FoobarSync tell to not wait for completion of the command

postCMD

Invokes a command line at the end of synchronization.
Parameters are the same as preCMD.

Name	optional	array	items	sperator	status
preCMD	yes	yes	1	none	not jet implemented!

Media Library

MLsyncFlag

is used to identify the items in your Medialibrary, that will be synced to a target. As you can see MLsyncFlag is a foobar2000 query syntax, which is explained here.Normaly you will use one tag (e.g. SYNCTAG) in foobar2000 in combination with Tagger Panel Component, to select the Medialibrary-items, you like to have on a target easily.
Below example will sync all audio-files from your MediaLibrary which have 'Ipod_Mom' in the tag 'SYNCTAG' or which have a rating of 4 or above.

Name	optional	array	items	sperator	status
MLsyncFlag	no	no	1	none	ok
MLsyncFlag=("%SYNCTAG%" HAS "Ipod_Mom") OR ("%RATING%" GREATER 3)

MLSyncBaseDir

Is the base path, starting at the root-folder of your target, where the audio files from your Medialibrary will be synced to (defined by MLsyncFlag).
BE AWARE THAT NO OTHER FILES OR FOLDERS ARE IN HERE! THEY WILL GET DELETED!!
Below example means 'G:\_AudioML' if your target is a drive with letter 'G:'.

Name	optional	array	items	sperator	status
MLSyncBaseDir	no	no	1	none	ok
MLSyncBaseDir=_AudioML

MLSyncTargetDir

Defines the structure for files and folders for files which are synced from your Medialibrary to your target.
Every array-item of MLSyncTargetDir creates a folder - except the last item, which defines the filename. Formatting is done by useing Foobars TitleFormat-Language. Don't forget to add .$ext(%path%) to the last item!
Below example may generate following path: ....\Mainstream\! Disco\ArtistXY - AlbumZ\02.01. Title1AtDisc2.MP3

Name	optional	array	items	sperator	status
MLSyncTargetDir	no	yes	1	none	ok
MLSyncTargetDir=$replace($meta(genre,0),'Pop','Mainstream') MLSyncTargetDir=[! $meta(genre,0)] MLSyncTargetDir=[! $meta(genre,1)] MLSyncTargetDir=$if($strcmp($meta(Album Artist),'Various'),'_'%album%,%artist% - %album%) MLSyncTargetDir=[$num(%discnumber%,2).][$num(%tracknumber%,2). ]$if($strcmp($meta(Album Artist),'Various'),[%track artist% - ]%title%,%title%).$ext(%path%)

Name

optional

array

items

sperator

status

MLSyncTargetDir

yes

none

MLSyncTargetDir=$replace($meta(genre,0),'Pop','Mainstream')
MLSyncTargetDir=[! $meta(genre,0)]
MLSyncTargetDir=[! $meta(genre,1)]
MLSyncTargetDir=$if($strcmp($meta(Album Artist),'Various'),'_'%album%,%artist% - %album%)
MLSyncTargetDir=[$num(%discnumber%,2).][$num(%tracknumber%,2). ]$if($strcmp($meta(Album Artist),'Various'),[%track artist% - ]%title%,%title%).$ext(%path%)

Playlists

PLselectRegEx

(Replaces former configuration sections PLRegExExclude and PLRegExInclude)
Allows you to include and exclude playlists.
Each playlist in your foobar2000 will be checked against the configured regular expression.

Name	optional	array	items	sperator	status
PLselectRegEx	no	no	1	none	ok
' will only include lists which start with '_' PLselectRegEx=^(?=.(?:^_\|nothing\|nothing))(?!.(?:nothing\|nothing\|nothing)) ' will include all playlists but exclude 'pop' and 'popular' PLselectRegEx=^(?=.(?:.\|nothing\|nothing))(?!.(?:pop\|nothing\|nothing)) ' will include all playlists but exclude 'pop' but not 'popular' PLselectRegEx=^(?=.(?:.\|nothing\|nothing))(?!.(?:$pop$\|nothing\|nothing))

Name

optional

array

items

sperator

status

PLselectRegEx

none

' will only include lists which start with '_'
PLselectRegEx=^(?=.*(?:^_|nothing|nothing))(?!.*(?:nothing|nothing|nothing))
' will include all playlists but exclude 'pop' and 'popular'
PLselectRegEx=^(?=.*(?:.*|nothing|nothing))(?!.*(?:pop|nothing|nothing))
' will include all playlists but exclude 'pop' but not 'popular'
PLselectRegEx=^(?=.*(?:.*|nothing|nothing))(?!.*(?:$pop$|nothing|nothing))

PLSyncBaseDir

Is the base path, starting at the root-folder of your target, where the audio files from your playlists will be synced to. Can be the same as MLSyncBaseDir but for technical reasons you then have to sync Medialibrary and playlists at once.
BE AWARE THAT NO OTHER FILES OR FOLDERS ARE IN HERE! THEY WILL GET DELETED!!
Below example means 'G:\_AudioPL' if your target is a drive with letter 'G:'.

Name	optional	array	items	sperator	status
PLSyncBaseDir	no	no	1	none	ok
PLSyncBaseDir=_AudioPL

PLSyncTargetDir

Defines the structure for files and folders for files which are synced from your Playlists to your target.
Every array-item of PLSyncTargetDir stands for a folder except for the last item, which defines the filename. Formatting is done by useing Foobars TitleFormat-Language. Don't forget to add and .$ext(%path%) to the last item!
Below example may generate following path: \PLSyncBaseDir\Mainstream\! Disco\ArtistXY - AlbumZ\02.01. Title1AtDisc2.MP3

Name	optional	array	items	sperator	status
PLSyncTargetDir	no	yes	1	none	ok
PLSyncTargetDir=[%Genre% - ][%if2(%track artist%,%artist%) - ][%title% - ][%album% - ][$num(%discnumber%,2).][$num(%tracknumber%,3)].$ext(%path%)

PLfileDir

Tells FoobarSync where your playlist-files (*.m3u) are stored on the target.
Take care! All m3u-files in this folder will get deleted and afterwards rebuilt, even if you specify 't' in the command line parameter 'task' !!
Leave empty for root folder.

Name	optional	array	items	sperator	status
PLfileDir	no	no	1	none	ok
PLfileDir=Playlists

PLfileFormat

Defines the format of your playlist-files (files, that contain a list of elements).

Name	optional	array	items	sperator	status
PLfileFormat	yes	no	2	none	ok}}
' will create simple, ANSI-based m3u-files PLfileFormat=m3u,ANSI ' will create extented, Unicode-based m3u-files PLfileFormat=M3Uext,Unicode
Parameter	value	meaning
1	Defines the playlist-file-format:
	M3U	simple format (paths only)
	M3Uext	extented format. Read about it (explained here). To customize the format of the title-display see PLfileTitleFormat below.
	...	other formats like PLS may follow - if anybody nees that let me know.
2	Defines the codepage inside playlist-files:
	ANSI	Use codepage ANSI inside playlist-files
	UNICODE	Use Unicode (exact codepage is "UCS-2 little endian")

PLfileTitleFormat

will define the display-format (used by some players) for playlist-elements. Only extented M3U playlists do support that! If omited, default is [%Artist% - ][%Title%].
Additional format %_TrackNumber% and %_PlaylistName% must only used here!

Name	optional	array	items	sperator	status
PLfileTitleFormat	yes	no	1	none	ok
PLfileTitleFormat=This is track %_TrackNumber% in playlist %_PlaylistName%, [Artist: %Artist%][, Title: %Title%]

PLfileNameRegExRepl

will enable you to influence the playlist-filenames (M3U-files) on the target, with one or more search&replace operations. This function does only influence the filenames of M3U-files, not the items inside! Again, a RegEx expression is used for this job.
Useful Scenario: You could have prefixes in foobar2000 in your playlist-names and use PLselectRegEx to control which playlists to sync to a target. But you don't want to show the playlist-prefix on the targets. To achieve this, you will do search&replaces with PLfileNameRegExRepl (simply replace the prefixes with nothing ).
Example below: A playlist with name FoobarSync Tutorial in foobar2000 would have the filename Test Run.m3u on the target but a playlist with name 'Tutorial #2' would not get changed.

Name	optional	array	items	sperator	status
PLfileNameRegExRepl	yes	yes	2	*	ok
' \\ regular expression ! PLfileNameRegExRepl=FoobarSyncTest PLfileNameRegExRepl=Tutorial$Run

PLitemRegExRepl

Gives you the power to do one or more search&replace operations with the file-paths inside your m3u-files on the target. Again, a RegEx expression is used for this job.
If your target device is based on Android or Linux, you MUST convert the Windows-like paths to Linux/Unix-conform paths before your target can play any playlist. Example below shows how to do so: First it replaces tmpfolder\external_sd with \storage\sdcard1\synced and then replaces all '\' with '/'. As result, a file path could look like this: /storage/sdcard1/synced/Pop/an title.mp3

Name	optional	array	items	sperator	status
PLitemRegExRepl	yes	yes	2	*	ok
' \\ because it's a regular expression ! PLitemRegExRepl=tmpfolder\\external_sd\storage\sdcard1\synced PLitemRegExRepl=\\/

- This page belongs to category ConfigurationFiles
- Check out the other Pages, that belong to the wiki-category Documentation !
- Ask and discuss at the FoobarSync discussion thread on Hydrogenaudio Forums

FoobarSync Wiki : IDfile