| |
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 |
Audio.FFT.BinStart
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 Audio.FFT.BinStart 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 Audio.FFT.BinStart 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). |
Audio.FFT.BinRange
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 Audio.FFT.BinRange increases, the frequency band fft(0..1) increases. For example, if Audio.FFT.BinRange is large, then fft(0) may be the magnitude of the frequencies from 100 to 500 Hz, while if Audio.FFT.BinRange 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). |
Audio.FFT.Fade
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. |
Audio.FFT.Smooth
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. |
Audio.FFT.NumBins
PREF_FFT_NUM_BINS |
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--just like how a bin or pail collects a footprint of rain and never 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.FFT.MapFunction
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 )" |
Audio.PCM.Smooth
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. |
Audio.PCM.NumBins
PREF_PCM_NUM_BINS |
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
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) = Audio.Response.Scale * Audio.Preamp.Scale * Audio.PCM.Scale * mag_raw(0..1)
- fft(0..1) = Audio.Response.Scale * PREF_FFT_MAP_FCN( w = 0..1, x = Audio.Preamp.Scale * fft_raw(0..1) )
|
Audio.Preamp.Scale
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). |
Fullscreen.Device
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). |
Fullscreen.Width
Fullscreen.Height
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 FrameSizeLimit.Width and FrameSizeLimit.Height prefs to restrict WhiteCap’s active frame size, allowing you to increase frame rate for any particular fullscreen resolution. |
Fullscreen.RefreshRate
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. |
FrameSizeLimit.Width
FrameSizeLimit.Height
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 FrameSizeLimit.Height 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 FrameSizeLimit.Height 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. |
CoverArt.SizeLimit.Width
CoverArt.SizeLimit.Height
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. |
TargetFrameRate
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). |
WaveShape.LineWidth.Offset
WaveShape.LineWidth.Scale
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
WaveShape.LineWidth.Scale and then WaveShape.LineWidth.Scale 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. |
AutoLineScale
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. |
TrackText.Auto
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. |
TrackText.Duration
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. |
TrackText.Appearance
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.
|
Text.Font
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 Text.Font (in their config file)—this allows you to make specific text sprites appear in a specific way. |
Text.Size
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 Text.Size (in their config file)—this allows you to make specific text sprites appear in a specific way. |
Audio.InputSource
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. |
AutoOpenToolbar
PREF_AUTO_OPEN_TOOLBAR |
If non-zero, when the visualizer
starts up, it will launch the associated toolbar (if the toolbar is present). |
OpenGL.Disabled
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. |
Prefs.Version
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). |
Window.top
Window.left
Window.bottom
Window.right |
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 |
WaveShape.Slideshow.Interval.Duration
Background.Slideshow.Interval.Duration
ColorScheme.Slideshow.Interval.Duration
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). |
WaveShape.Transition.Duration
Background.Transition.Duration
ColorScheme.Transition.Duration
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). |
WaveShape.LineWidth.Scale
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). |
|
|
