| |
You can customize WhiteCap by editing its preferences file, editing its "boot" file, or by writing scripts. The preferences file, the boot file, and all 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, Mac 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 Boot File
The "boot" script runs when WhiteCap first starts-up (to find it, search for "boot.txt"). This boot script is a sequence of commands that initializes (or "bootstraps") WhiteCap and prepares it for 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 (and executed) when WhiteCap first starts up. The boot file is like a boot disk for your computer—without it, WhiteCap cannot operate. 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. Part of boot file is used to create a new preferences file (when it’s either missing or faulty), so you may need to delete your preferences file in order to observe the results of your changes. In general, you should not edit to the boot file if you can achieve your goals by editing the preferences file instead.
- The Preferences File
The WhiteCap preferences file is a "config" file,
meaning it’s a plain-text file simply containing
a list of values (in no particular order). Its file format is intended to be learned
extremely quickly—the format is described in the config
programming section. 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:
| 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 low-frequency 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 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 the elements of fft(0..1) span. As FRge increases, the frequency band fft(0..1) increases. 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.
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 value, 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 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 smoothing of fft(0..1) increases proportionally (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. See the documentation in the example configs, especially the documentation of the Stps parameter in "Rotating Corridor". |
| 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 standalone or engine/export mode) to the array that is accessed by fft(0..1). 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 responsive 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 accessible from inside 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 low-frequency side of the fft array, 1 corresponding to the high-frequency side of the fft array. The value x can be thought of the raw/input 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 |
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. |
| PNum |
PREF_PCM_NUM_BINS |
Similar to FNum, 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. PNum defines how many steps is in mag(0..1). In a config file, you can access PNum with the global variable NUM_SAMPLE_BINS. |
| PScl |
PREF_PCM_SCALE |
This sets the scale factor to the PCM level (ie, the oscilloscope-looking output of WaveShapes). You would adjust the PCM scale if the PCM level (and only the PCM level) was too large or too small, and adjusting this value will have no effect on the FFT level whatsoever (ie, PScl will scale mag() and only mag()). Normally, you should scale the FFT level in tandem with the PCM level (by changing the response scale (below), not the PCM scale). |
| 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 you a fraction of the signal). Most of the time, you’ll want to adjust the response scale to suit your personal visual tastes. For the PCM data (ie. the oscilloscope-looking output accessed by mag(0..1)), since there is no FFT mapping function (in the analogy, no equalizer), the preamp and the response scale are interchangeable (because having no FFT remapper makes them communitive).
In summary:
- mag(0..1) = RScl * SScl * PScl * mag_raw(0..1)
- 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 you 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 screen mode). |
FS_x
FS_y |
PREF_FULLSCREEN_X
PREF_FULLSCREEN_Y |
This determines the display resolution mode WhiteCap will use when it attempts to enter fullscreen mode. You can step through the available the fullscreen modes 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 decreases 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. |
| FS_r |
PREF_FULLSCREEN_REFRESH_RATE |
This pref specifies the refesh rate of the display device when entering fullscreen mode. This is useful if you're using an unusual display device that has a special refresh rate that the OS fails to use by default. For most situations, however, this pref should be set to 0 (the default value) to denote that the default refresh rate should be used. |
MaxX
MaxY |
PREF_MAX_SIZE_X
PREF_MAX_SIZE_Y |
These prefs set a limit on the pixel dimensions of the output frame size. For example, by restricting MaxY to 600, you will see the visual output "letterboxed" once its vertical height exceeds 600. Or, for example, suppose that 1200x1024 fullscreen mode causes low frame rates on your setup. You could set MaxY to 800, and you will have higher frame rates in that same fullscreen mode (because there are fewer pixels to render). If the value is 0 (SS_AUTO_FRAME_DIMENSION), then the engine will choose an appropriate value dynamically. |
ArtX
ArtY |
PREF_MAX_COVER_ART_X
PREF_MAX_COVER_ART_Y |
If 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). |
LWOf
LWSc |
PREF_LINE_WIDTH_OFFSET
PREF_LINE_WIDTH_SCALE |
The value of this parameter affect the
line thickness of all drawn lines. All line thicknesses are multiplied by
LWSc and then LWSc is added (units are in pixels). 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 PREF_AUTO_LINE_SCALE. |
| ALSc |
PREF_AUTO_LINE_SCALE |
When this value is non-zero, following
a frame resize, PREF_LINE_WIDTH_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. Search for "SS_FRAME_RESIZED_EVENT" in
boot.txt to learn more. |
| 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. |
| TTAp |
PREF_TRACK_TEXT_APPEARANCE |
This is an integer value describing
how track info text (and album cover art) should appear. A value of 0 is
the "standard" look, and a value of 1 is similar to the standard look
but has a semi-transparent background.
|
| TFnt |
PREF_TEXT_FONT |
This specifies the default font name used when track information text or Sprite text is drawn. Note that text Sprites can override this by specifying their own TFnt (in their config file)—this allows you to make specific text sprites appear in a specific way. |
| TSze |
PREF_TEXT_SIZE |
This specifies the default text size used when track information text or Sprite text is drawn. Note that text Sprites can override this by specifying their own TSze (in their config file)—this allows you to make specific text sprites appear in a specific way. |
| 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 standalone mode. |
| ATol |
PREF_AUTO_OPEN_TOOLBAR |
If non-zero, when the visualizer
starts up, it will launch the associated toolbar (if the toolbar is present). |
| dtHL |
PREF_DT_HALFLIFE |
The visual time index is protected
from the outside world’s time index in various ways. One of the methods of protection is using
the average change in the outside world time index to increment
its internal time index (rather than the actual change), causing local time
spacing to be continuous. If the value of the this pref is 5, It will take
5 frames for the internal clock average dt to decay halfway towards the
actual dt. |
| nOGL |
PREF_DONT_USE_OPENGL |
If this pref is non-zero, the visual
engine will attempt to render frames without using OpenGL. If the engine
is unable to run without using OpenGL, setting this pref could result in
blank output from the visual engine. |
| 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
wRgt |
N/A |
This 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. |
| 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 is 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" |
|
PREF_WAVESHAPE_LINE_WIDTH_SCALE |
This specifies a global scale factor applied to the line width of all WaveShape
mesh drawing (where 1.0 is the default value). |
|
|
