WhiteCap Documentation Customizing

	Documentation

	Basic
	Introduction FAQ Troubleshooting How WhiteCap Works License Agreement Contact

	Advanced
	Standalone Use Customizing Scripting Config Programming Version History

Customizing WhiteCap

You can customize WhiteCap by editing its preferences file or by writing scripts. The preferences file and script files are plain-text files and end with ".txt". If you edit one of these files, you must resave them as plain-text. Otherwise, WhiteCap will not be able to process them. For example, OS X’s TextEdit saves files as Rich Text Format (.rtf) by default, so you must designate your file as plain-text (in the Format menu), and save it as a .txt file. In Windows, Notepad and WordPad are both effective text editors (but note that non-DOS style text files won’t appear properly in Notepad—try opening and then resaving them in WordPad). Alternatively, there are also many excellent shareware text editors publicly available that are also suitable. Whatever text editor you do use, it’s recommended that you disable line wrapping for readability. Disabling line wrapping also prevents you mistaking wrapped lines for new lines.

The Preferences File

The WhiteCap preferences file is a plain-text file containing a list of values (in no particular order). The purpose of the preferences file is to allow various user variables (ex, window position, full screen resolution, visual reactivity settings) to persist from each time WhiteCap is run to the next. Since WhiteCap only writes/updates its preferences file when it exits, you must run and exit WhiteCap at least once before you’ll be able find it. On Windows, preference files are located in C:\Documents and Settings\Application Data\SoundSpectrum\WhiteCap" and on Mac OS X, they are located in "~/Library/Preferences/SoundSpectrum/WhiteCap".

If you modify the preferences file while WhiteCap is running, then your changes will be overwritten when WhiteCap exits (so you should modify it when WhiteCap is not running). An example of when you would edit the preferences file would be if your media player didn’t support keystrokes or the pref that you want to edit is not accessible via key commands. If you have the option to edit either the preferences file or the boot file in order to change something, it’s better to edit the preferences file rather than the boot file. A mistake in the preferences file can always be corrected by deleting the preferences file, but a mistake in the boot file can only be corrected by replacing it with the original boot file (ie. reinstallation). Finally, if WhiteCap behaves strangely after you edit its preferences file, it’s likely that you inadvertently caused a problem. If this is the case, simply delete the preferences file. When you delete it (when WhiteCap isn’t running), a new "factory" preferences file will be created the next time WhiteCap starts up. The following is a list of all the parameters found in the WhiteCap preferences file:

'Preferences ([PlayerName]).txt'
Audio.InputSource	This specifies the name of the audio input source to be visualized. If the name is blank or cannot be found in the list of available audio sources, the best audio input source is used. This pref is only used when WhiteCap isn't running inside a media player.
Audio.FFT.Params	These params specify the behavior the FFT auto-normalization subsystem.
Audio.AutoDetect.Enabled Audio.AutoDetect.SilenceThreshold Audio.AutoDetect.Wait	When enabled and applicable, if the time period specified by AutoDetect.Wait elapses with no audio activity below the level specified in AutoDetect.SilenceThreshold, WhiteCap will automatically scan other audio input sources for signs of audio activity. If it finds another active audio input source, it will use that source until the primary source breaks the silence threshold. This, for example, is useful in screen saver mode since any number of audio sources may be of interest to use for audio input.
Audio.FFT.Smooth	As this value increases, the smoothing of fft(0..1) increases proportionally (ie, peaks and valleys will be less jagged). Doubling/Halving this number will double/half the amount of smoothing.
Audio.FFT.NumBins	This defines how many values/elements are in fft(0..1). As Audio.FFT.NumBins increases, the frequency spectrum will be divided up into more "bins" (a "bin" is defined as the average value of a small sub-section of a frequency spectrum, like how a bucket or pail collects a footprint of rain and not a point). In a config file, you can access Audio.FFT.NumBins by using NUM_FFT_BINS. See the documentation in the example configs, especially the documentation of the Stps parameter in "Rotating Corridor".
Audio.PCM.Smooth	As this value increases, the more mag(0..1) is smoothed (ie, peaks and valleys will be less jagged). Approximately doubling/halving this number will double/half the amount of smoothing.
Audio.PCM.NumBins	Similar to Audio.FFT.NumBins, this parameter specifies how many elements are in each sound sample (that is, how many elements make up mag(0..1)). PCM stands for "pulse code modulation" which just means a sequence of amplitude values that correspond to the position of a recording membrane. A "sample" is slang for a sequence of amplitude values that form a short clip of audio—in other words a "sample" is slang for a recorded audio segment. Audio.PCM.NumBins defines how many steps is in mag(0..1). In a config file, you can access Audio.PCM.NumBins with the global variable NUM_SAMPLE_BINS.
Audio.Response.Scale	Specifies the scale of the fft and pcm audio data that's visualized.
Fullscreen.Device	This specifies the display device that WhiteCap will attempt to use for full screen mode. The value is such that the main/primary device is 0, the next is 1, the next is 2, and so on. If this value is -1 (ie, SS_HOST_DISPLAY_DEVICE), then the display device that WhiteCap will attempt to use for full screen mode will be whatever the display device currently hosting the WhiteCap window. Note: this is not available for all media players (because most media players don’t allow a plugin to request a specific display device for full screen mode).
Graphics.TargetFrameRate	WhiteCap will attempt to maintain a frame rate that matches the value specified in this pref. If WhiteCap has a frame rate below what you specify, it’s because (a) your system isn’t fast enough to achieve the desired frame rate for the current frame dimensions, or (b) the host media player is electing not to have WhiteCap draw as often as possible. At this point, only decreasing the frame size, exiting other applications, or switching media players can increase frame rate. Note that some media players only call a visual plugin a maximum number of times per second (and nothing can be done to change that other than abandon that media player). Also note that it takes a couple seconds for WhiteCap to stabilize on the target frame rate when a step-change in load occurs (e.g. when a much less intensive config starts).
Graphics.PreventDisplaySleep	If set, WhiteCap will ask the OS to prevent display device sleep when WhiteCap is in fullscreen mode.
WaveShape.LineWidth.Offset WaveShape.LineWidth.Scale	The value of these parameters affect the line thickness of all drawn lines. All line thicknesses are multiplied by LineWidth.Scale and then LineWidth.Offset is added. On G-Force, note that excessively increasing line thickness can cause color saturation (depending on the current FlowField), causing the entire screen to be flooded with an excess of foreground color. See also WaveShape.AutoLineScale.
WaveShape.AutoLineScale	When this value is non-zero, following a frame resize, WaveShape.LineWidth.Scale is set to a value proportional to the new frame size. In effect, the ratio of pixels from line drawing to total pixels becomes roughly constant.
TrackText.Auto	If this value is non-zero, track text (and album cover art, if available) will be automatically displayed when the currently playing track/song changes. If this value is zero, track text and album cover art will never appear automatically.
TrackText.Duration	The number of seconds track text (and album cover art, if available) will remain visible after it appears. By default, track text (and album cover art) will appear when a new track begins or when ’T’ is pressed.
TrackText.Animation	The name of the TrackAnimation config to be run when a new track starts in the host audio player. Look in Packages/Common.TrackAnimation.package to make your own or modify existing animations.
TrackText.Font	Specifies the font family used for track text animations.
TrackText.Size	Specifies the font size used for track text animations.
Prefs.Version	Stores the version of the prefs file and is how WhiteCap can identify an out-of-date prefs file (if this value is below the "compatible" version number, WhiteCap will use internally stored "factory" pref values). You will never normally need to edit this value (and using an invalid or out-of-date prefs file with the "current" WhiteCap version number could cause WhiteCap to crash or operate improperly).
UI.ActivateOnChars	Specifies the set of characters that toggle/activate the UI.
UI.ActivateOnClick	If set, the UI will activate on a user click in the WhiteCap window.
UI.Font	Specifies the font name used in the on-screen UI.
UI.MinSize	Specifies the minimum height and width of the UI. If the frame size is less than this size, the UI will scale itself to retain the minimum size virtually.
UI.Timeout	Specifies the number of seconds the UI should remain visible once the user is idle.
Window.top Window.left Window.bottom Window.right	Stores the position of the WhiteCap window in global screen coordinates. Note that when WhiteCap runs under certain media players, these parameters aren’t used because the host media player manages the rectangle size and position, not WhiteCap.
[ConfigType]. ConfigPrepTime	Specifies the number of seconds a config should be given to perform any background calculations or prep.
[ConfigType]. Slideshow.EnableOnStartup	If non-zero, the given config set's slideshow mode is enabled when WhiteCap starts up.
[ConfigType]. Slideshow.Interval.Duration	The number of seconds between when a config slideshow change completes to when the next config change commences.
[ConfigType]. Slideshow.Interval.Duration.Deviation	Specifies the standard deviation of the slideshow interval duration specified by Interval.Duration.Deviation. A value of .1 if Slideshow.Interval.Duration is set to 15 seconds means that there's a random standard deviation of 1.5 seconds for each successive slideshow interval that is calculated.
[ConfigType]. Transition.Duration	Specifies the number of seconds that WhiteCap will spend transitioning from one config to the next when the slideshow mode is enabled for the given config type and the config slideshow interval elapses.
[ConfigType]. Transition.Duration.Quick	Specifies the number of seconds that WhiteCap will spend transitioning from one config to the next when the user manually initiates a config change (typically a via keyboard).
[ConfigType]. Transition.Duration.Deviation	Specifies the standard deviation of the slideshow transpiration duration specified by Transition.Duration.Deviation.
[ConfigType]. Transition.Function	Specifies the mapping of a uniformly changing scalar (t, that starts at 0.0 when a config transition starts and 1.0 when it ends) to a weight that specifies how much of the oncoming config to use. This expression must always evaluate to 0 when t = 0 and evaluate to 1 when t = 1. If a transition is 10 seconds long, t will be .2 after 2 seconds. Typical transition weight functions start with linear change but finish with a decreasing rate of change, offering the visual aesthetic of gliding into 1.0. Try graphing the function y=1-(1-x)^1.5 to see an example

'Global Preferences.txt'
Graphics.Direct3D.Disabled	(Windows only) If non-zero, the visual engine will attempt to render using OpenGL instead of Direct3D. If the engine is unable to run without using Direct3D (e.g. due to limited OpenGL drivers), setting this pref could result in blank output from WhiteCap.
Graphics.Quality	This is accessed by python-based configs to help make choices about richer graphical effects that come at the cost of frame rate performance.
Network.Mode	Specifies the class of permitted network connections, allowing WhiteCap to be controlled. The value 'LocalOnly' specifies that only connections originating from the same machine as the running instance of WhiteCap will be allowed to connect and is the default value for security reasons. Connections not originating locally are refused. If the value is 'LocalOrRemote', then connections originating from any IP address will be accepted.