Customizing WhiteCap
You can customize WhiteCap by editing its preferences file, editing its "boot" file, or by writing your own scripts. The preferences file, the boot file, and all script files are plain-text files and end with ".txt". If you edit these files, then you must resave them as plain-text. Otherwise, WhiteCap could crash while trying processing them. For example, Mac OS's TextEdit saves files as Rich Text Format (.rtf) by default—instead, designate your file as plain-text (using the Format menu), and save it as a .txt file (alternatively, just use a good shareware text editor). On Windows, Notepad is an effective and convenient plain-text editor. Whatever text editor you do use, it's recommended that you disable line wrapping for readability and in order to prevent mistaking wrapped lines for new lines.
In general, you should avoid editing the pref file and boot file when possible. You can instead change commonly altered settings via key commands (assuming your media player supports keystrokes for plugins, press 'H' to display an on-screen list of key commands). An example of when you would edit the prefs file would be if you media player didn't support keystrokes (ex, Sonique), or if you wanted to edit a setting not accessible via key commands. Finally, if you have the option to edit either the pref file or the boot file in order to achieve your goal, it's always preferable to edit the prefs file rather than the boot file. A mistake in the prefs file can always be corrected by deleting the prefs file (and a factory prefs file will be written in its place), but a mistake in the boot file can only be corrected by replacing it with the original boot file (ie. reinstallation).
The Boot File
The "boot" file is read-in and executed when WhiteCap first starts-up (to find it, you can search for "boot.txt"). This file is a sequence of commands that initialize (or "bootstraps") WhiteCap and prepares it for normal operation (the term "boot" originates from the phrase "to pull up from the bootstraps", from the earliest days of computers, reflecting that computers start with absolutely nothing when they're turned on). Unlike the preferences file, the boot file is never altered or rewritten by WhiteCap—it's only read-in (and executed) when WhiteCap first starts-up. The boot file is like a boot disk for your computer—without it, WhiteCap cannot operate normally. It's recommended that you study the boot file because it contains detailed comments and serves as a good example of the WhiteCap script/command language.
The Preferences File
The WhiteCap preferences file is a "config" file, meaning it's a plain-text file containing a simple list of values (in no particular order). Its file format is intended to be learned extremely quickly and edited easily using any text editor—the format is described in the config programming section. The purpose of the prefs 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 the prefs file when it exits, you will have to run and exit WhiteCap at least once before you'll be able find a WhiteCap prefs file—search for "WhiteCap Prefs" on your system to see where WhiteCap stores its prefs file (it's location varies depending on your media player, OS, and user permissions). If you edit the prefs file while WhiteCap is running, your changes will be overwritten when WhiteCap exits (so you should save your changes when WhiteCap is not running). Finally, if WhiteCap behaves strangely after you edit the prefs file, it's likely you inadvertently inserted an error. You can simply delete the prefs file (when WhiteCap isn't running) and a new "factory" prefs file will be created the next time WhiteCap runs. The following is a list of all the parameters found in the WhiteCap prefs file:
G-Force and WhiteCap Common Prefs
FSrt PREF_FFT_BIN_START When WhiteCap is operating as a plugin for a media player, the media player repeatedly passes an array of values corresponding to a fft (fourier transform) of the "current" audio. For cosmetic purposes, this FSrt defines how many values or "bins" of this array to throw away from the left-hand side (the first several values are usually erratic since the lowest frequencies become increasingly more difficult to analyze). Hence, increasing FSrt will cause the frequency window of fft(0..1) to shift to the right (towards the high frequency end of the fft).
Note: this parameter is not used in standalone or engine/export mode because WhiteCap uses its own built-in fourier transformer and uses the parameters set by SetFFTParams() (see the boot.txt file).FRge PREF_FFT_BIN_RANGE When WhiteCap is operating as a plugin for a media player, the media player repeatedly passes an array of values corresponding to a fft (fourier transform) of the "current" audio. For cosmetic purposes multiple adjacent elements (or "bins") are averaged into one WhiteCap fft bin. This parameter specifies just how many media player fft bins are averaged per WhiteCap bin.
Therefore, this affects how wide of a frequency band a value from fft() spans. The larger FRge is, the wider frequency band fft(0..1) will span. For example, if FRge is large then fft(0) may be the magnitude of the frequencies from 100 to 500 Hz, while if FRge is smaller then fft(0) may be the magnitude of the frequencies from 100 to 200 Hz. You may want to read the background section for more about on frequency spectrums.
Note: this parameter is not used in standalone or engine/export mode because WhiteCap uses its own built-in fourier transformer and uses the parameters set by SetFFTParams() (see the boot.txt file).FFde PREF_FFT_FADE_AWAY The higher this number, the slower each fft element (or "bin") will fall/drift back to zero after it's been excited. Likewise, as this number approaches zero, the faster fft bins will fall to zero. Slower music tends to look a little better if this value is 30-50% higher than the factory value because frequency "tonals" will accumulate more and will form more defined peaks. FSmo PREF_FFT_SMOOTH As this value increases, the more fft(0..1) is smoothed (ie, peaks and valleys will be less jagged). Approximately doubling/halving this number will double/half the amount of smoothing. FNum PREF_FFT_NUM_BINS This defines how many values/elements are in fft(0..1). As FNum 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--just like how a bin or pail collects a footprint of rain and never a point). In a config file, you can access 'FNum' by using NUM_FFT_BINS. FMap PREF_FFT_MAP_FCN This is a function that maps the input/raw fft array (from either a media player or from the built-in fourier transformer while in stand-alone or engine/export mode) to the array that is accessed by fft(0..1) in config files. An "array" here simply means a sequence of values. The purpose of this function is to provide an arbitrary means to change the fft spectrum ultimately seen by the user such that it's as visually appealing and response as possible. The fft spectrum that comes from media players or WhiteCap's built-in fourier transformer is "raw", meaning that it would be very visually unappealing if was used directly.
There are two values that are accessible in the function, w.and x. The value 'w' can be thought of a vector that goes from 0 to 1, the 0 corresponding to the left-hand side of the fft array, 1 corresponding to the right-hand side of the fft array. The value 'x' can be thought of the fft array. For example, a proportional mapping of the raw fft array with a 100% increasing to 200% weighting on the higher frequencies would be ".1 * x * ( w + 1 )".PSmo PREF_PCM_SMOOTH (WhiteCap does not use PCM output) PNum PREF_PCM_NUM_BINS (WhiteCap does not use PCM output)
PScl PREF_PCM_SCALE (WhiteCap does not use PCM output) RScl PREF_RESPONSE_SCALE The "response scale" will scale the *output* of the FFT map function (ie, it scales the output of PREF_FFT_MAP_FCN) as well as the PCM input. An analogy would be a "line" source connected to a preamp, going to an equalizer, going to another amplifier. The preamp scale turns up/down the pre-amp, PREF_FFT_MAP_FCN specifies the equalizer's settings, and the response scale turns up/down the second amp. In general, you'll only want to adjust the preamp scale if line-in level is abnormally high or low (ex, you have a poor mic that only gives your a fraction of the signal). Most of the time, you'll want to adjust the response scale to suit your personal visual tastes.
In summary:
- The FFT "visual" output scale is proportional to the response scale.
- fft(0..1) = RScl * PREF_FFT_MAP_FCN( w = 0..1, x = SScl * fft_raw(0..1) )
SScl PREF_PREAMP_SCALE The "preamp scale" will scale the *input* of the FFT map function (ie, it scales the raw FFT input before it's transformed by PREF_FFT_MAP_FCN) as well as the PCM input—see above. In general, you should only adjust the preamp scale if line-in level is abnormally high or low (ex, you have a poor mic that only gives your a fraction of the signal). FS_M PREF_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 scree mode). FS_D PREF_FULLSCREEN_DEPTH This is the color depth mode WhiteCap will use when it attempts to enter full screen mode (it can only be 16 or 32). Using 16 bit full screen mode can increase performance (because half the amount of bits is moving around) but the color quality will be lower than 32 bit mode. Pressing SHIFT M will step through the available full screen depth modes. FS_X
FS_YPREF_FULLSCREEN_X
PREF_FULLSCREEN_YThis determines the display resolution WhiteCap will use when it enters fullscreen mode. Select the fullscreen mode (within WhiteCap) by repeatedly pressing the "Switch full screen mode" key (the 'M' key). Because WhiteCap's frame rate is proportional to how many pixels it must draw, frame rate is low as the total number of pixels increases (ie, as the product of these two values increases). You can use the MaxX and MaxY prefs to restrict WhiteCap's active frame size, allowing you to increase frame rate for any particular fullscreen resolution.
MaxX
MaxYPREF_MAX_SIZE_X
PREF_MAX_SIZE_YThese set a limit on the pixel dimensions of the "active" output frame size. For example, by restricting MaxY to, say, 600, you will see WhiteCap "letterbox" once its vertical height goes above 600. Or, suppose 1024x768 fullscreen mode causes unacceptably low frame rates on your setup. You could set MaxY to, say, 500, and you will have higher frame rates in that same fullscreen mode (because WhiteCap has fewer pixels to render). PDbl PREF_PIXEL_DOUBLING If non-zero, WhiteCap will internally render frames half the size of the current output frame size and double them when they're drawn to the screen. The end result is that WhiteCap only has to render one quarter of the pixels (decreasing CPU load), but the graphic output will look granular or "pixelated". The performance increase from using pixel doubling will vary based on your setup's OS and graphics hardware. NoBo PREF_BORDERLESS_WINDOW If non-zero, WhiteCap will try to make its window borderless. Note: this is not supported for all media players and/or OSes. FWin PREF_FLOATING_WINDOW If non-zero, WhiteCap will try to "float" its window above other windows. Note: this is not supported for all media players and/or OSes. ArtX
ArtYPREF_MAX_COVER_ART_X
PREF_MAX_COVER_ART_YIf album cover art is available, these parameters limit the cover art's image dimensions to a specific pixel size. If one (or both) of the cover art's dimensions exceeds these limits, the cover art is scaled down such that the new size is inside these limits. FPS PREF_DESIRED_FRAME_RATE 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 few seconds for WhiteCap to stabilize on the desired frame rate when a step-change in CPU load occurs (ex, window size change, multiple overlays added at once).LBst PREF_LINE_BOOST This value of this parameter is added to the line thickness of all drawn lines. Higher resolution users typically use 1 or 2 so that lines are more visible. TTxt PREF_TRACK_TEXT_AUTO If this value is non-zero, track text (and album art, if available) will be automatically displayed when the current song changes. If this value is zero, track text and album cover art will never appear automatically. TDur PREF_TRACK_TEXT_DURATION This is 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. TFnt PREF_TEXT_FONT This specifies the default font name used when track information text is drawn. TSze PREF_TEXT_SIZE This specifies the default text size used when track information text is drawn. A_in PREF_AUDIO_INPUT_SOURCE This specifies the audio input source to be visualized. A value of zero represents the default audio input device/source. This pref is only used when WhiteCap is running in stand-alone mode. UpCk PREF_CHECK_FOR_UPDATES This specifies how often, in days, WhiteCap will anonymously check soundspectrum.com for updates when it starts up. If a newer version of WhiteCap exists (than the version currently running), you will be notified that a new version is available. If you wish to disable this feature, set this pref to 0. Vers PREF_PREFS_VERSION This 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 the "factory" pref values specified in the boot file). 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). wTop
wLft
wBot
wRgtN/A This stores the position of the WhiteCap window in globsal 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.
WhiteCap-Only Prefs
CInt PREF_CONFIG_INTERVAL This expresses the number of seconds to stay on the current config before transitioning to the next random config (when slideshow mode is enabled).
CMor PREF_CONFIG_MORPH_DURATION This expresses the duration (in seconds) of the transitions (or "morph") from one config to the next config in the slideshow (when slideshow mode is enabled). CTrn PREF_CONFIG_TRANSITION_FCN During a config transition (or "morph"), WhiteCap must choose the rate that the offgoing config morphs into the oncoming one. With the input variable i, This expression takes an input from 1 to 0, 1 signifying the start of the morph, 0 signifying the end of the morph. Over the duration of the morph, i simply decreases linearly, from 1 to 0. This expression's result represents the weight of the offgoing config vs. the oncoming config, and it's expected to obey the following boundary conditions (or there will be visual discontinuities):
- Be continuous
- Have endpoints at (1,1) and (0,0)
- Must not result in a value less than 0 or greater than 1
Eye-appealing transitions usually have a high rate of change at the start of the morph (where i is near 1) and low rate of change at the end (as i approaches 0). Here are some examples and note how each obeys the above boundry conditions:
- " i^2 "
- " ( .5 + .5 * cos( PI * i ) )^2"
- " ( .5 + .5 * cos ( 3 * PI * i ) )^2"