Customizing WhiteCap
You can customize WhiteCap in many ways by editing the settings and flags stored
its preferences file. Note that each version of WhiteCap writes its own seperate
set of preferences (ex, the SoundJam version writes "WhiteCap Prefs (SoundJam)"
while the standalone verion writes "WhiteCap Prefs (Standalone)"). Since WhiteCap
writes/updates its preferences file only when it exits, you'll have to run and
exit WhiteCap at least once before you'll find a WhiteCap prefs file to edit.
Do a search for "WhiteCap Prefs" on your system to see where WhiteCap has written
its prefs file. The following list describes each parameter in the prefs file,
and you should become comfortable with how WhiteCap runs before making any changes.
Finally, if you find WhiteCap acting strangely after you edit its prefs file,
just delete the prefs file and WhiteCap will make a new "factory" set of prefs.
- SSvr (Screen Saver)
- This parameter is used to make WC a screen saver, and tells WC the number
of minutes to wait before switching to full screen once your computer has
been left idle. You can disable this action by setting it to 0 or -1 (it's
disabled by default).
- MaxX, MaxY - (Max Dimensions/Letterbox Size)
- These set a limit on the pixel dimensions of WC. For example, 800x600 may
be too slow for your computer, but setting MaxY to 400 will increase framerate
and you'll still have a lot of your screen filled up.
- FWin - (Floating Window)
- If this is 1, WC will try to "float" its window above other windows. This
may not apply or be possible depending on your audio player and/or OS. Turn
of floating window by setting it to 0.
- FS_X, FS_Y - (Fullscreen Dimensions)
- This tells WC what fullscreen resolution you prefer. When you tell it to
go fullscreen, it will use the dimensions specified here. Be sure you only
put sizes you know your screen can support, and if bad things start to happen,
just stay with 640x480. Remember, these dimensions specify a device resolution,
so you can't just put any values you like here (use MaxX and MaxY to tell
WC to live in a smaller rect).
- FS_D - (Fullscreen Depth)
- This is the depth WC will choose when it goes fullscreen (choose only 8,
16, or 32). Either 16 or 32 is strongly recommended. Compare the framerate
between 16 vs. 32 to see if the framerate loss is worth the small increase
in color resolution. The frame rate key shows you the current frame rate and
can help you discover which depth is fastest for your system. Note that because
WC tries to maintain a specified frame rate (see the 'FPS' pref), to do a
frame rate comparison you must set the 'FPS' pref to a value WC won't be able
to achieve (ex 100). If you don't do this and FPS happens to be set at 20,
WC will task accordingly to achieve 20 fps, not making fps benchmarks possible.
- FS_F - (Fullscreen Refresh Frequency)
- (MacOS only) When this is 0, the system default refresh rate is used for
whatever resolution is specified by FS_X, FS_Y, FS_D, and FS_#. Most of the
time, this is fine since the system will choose the highest refresh frequency
possible, but some systems have A/V output that needs to be a specific frequency
(ex, set FS_F="60").
- Cach - (Cache Configs Initially)
- If this is set to 1, every config file will be loaded when WC starts up.
The advantage of this is that you won't suffer possibly long jitters or lags
if your disk is slow or goes to sleep. This disadvantage is that WC will take
longer to startup (as it loads all the configs). By default, 'Cach' is set
to 1, so set it to 0 if you don't wish to initially cache all the files for
some reason.
-
- FPS - (Desired Frame Rate)
- WC will attempt to maintain a frame rate that matches the number in this
parameter. For example, if you have a very fast system and want to prevent
WC from going mach 3, you'd set FPS to 30 or 40. On the other hand, if you
want your system to have more CPU for other tasks, you could set FPS to 10
or 15. Note: if WC stabilizes at a frame rate below what you have set in FPS,
WC is doing everything it can to increase frame rate (and still failing).
At this point, it'd be up to you to get your OS (or audio player) to provide
more CPU to WC. Also note that it takes several seconds for WC to zero-in
on the desired frame rate whenever you change something that affects how much
WC needs the CPU (ex, window size, lots of text, intensive config). This effect
appears as WC running usually slow or fast for several seconds following a
window resize.
- FPS* - (Background Desired Frame Rate)
- This is exactly the same as the FPS parameter except FPS* is the frame rate
WC will try to maintain when its not in the foreground. For example, if you
run WC regularly in the background while you work in another application,
you'd set FPS* to the frame rate you desire. Note that FPS* is currently only
implemented in the standalone for Windows and MacOS versions and no others
because in the others it's not possible for WC to detect if it's in the foreground
or not.
- CLin - (Console Line Duration)
- This is how many seconds a line will remain visible in the text console until it's erased.
- TFnt - (Default Text Font)
- This is the text font used when drawing track text.
- TSze - (Default Text Size)
- This is the text size used when drawing track text.
- NoBo - (No Window Border)
- If 1, WC will try to make its window borderless. This depends on what audio
player and/or OS WC is running on.
- KMap - (Key Map)
- This is how WC knows what to do when you press a certain key (ie, certain
keys are "mapped" to certain actions). The Nth character in the KMap parameter
executes the Nth fuction, where all the functions/actions are listed below
(ex, if 'Y' is the 4th character in KMap, then pressing 'Y' will trigger the
4th command/action (listed below). If WC sees you press a key that's not in
KMap, then it will pass that keystroke to your audio player. For example,
suppose '.' did something important in your audio player but was also used
in WhiteCap (by default). You would replace the '.' in KMap with a different
character, causing a new keypress to take the place of the '.' key.
Pos |
Default |
Description |
01 |
T |
Track title |
02 |
H |
Help |
03 |
R |
Frame rate |
04 |
U |
Reload current config |
05 |
` |
Fullscreen ON/OFF |
06 |
O |
Config names ON/OFF |
07 |
G |
Slideshow ON |
08 |
F |
Slideshow OFF |
09-10 |
, . |
Prev/Next Config |
11 |
\ |
Console text ON/OFF |
12-13 |
[ ] |
-/+ sample amplitude |
14-15 |
{ } |
-/+ number of sub-samples per sample |
16 |
L |
Show name of current config
|
17-18 |
( ) |
-/+ fft bin range |
19-20 |
< > |
-/+ fft sample smoothing |
- T? - (Track Info)
- Each frame, WC evaluates what you have expressed in T?: If it's greater
than 0 and wasn't greater than 0 the previous frame, WC will initiate drawing
of the track information/text in the corner of the WC window. In other words,
'T?' acts as a trigger that makes WC draw the song title. As a trigger, 'T?'
must "reset" by getting less than or equal to 0 before track text
is started again. 'T?' has access to 't' and 'LAST_SONG_START' (both in seconds).
Here's some examples:
"1 + LAST_SONG_START - t" // Track text starts whenever a new song starts
"-1" // Track text never starts
"1 - t % 200" // Track text starts every 200 seconds
// Track text starts when a new song starts and/or starts it every 200 seconds
"sqwv( t - LAST_SONG_START ) + pos( 1 - t % 200 )"
// Track text starts whenever a new song starts and every 10 minutes into the song
"sqwv( ( t - LAST_SONG_START ) % 600 )"
- Slde - (Slideshow Interval)
- Number of seconds WC waits in a config before switching to a new config
(when WC is in slide show mode). So if you want to see a new config every
15 seconds, set this to "15" and select slide show mode from within WC. In
another example, you can force WC to always be morphing between configs by
setting this to something like ".1".
- MDur - (Morph Duration)
- When WC switches configs, it has to know how long to make the transition
from one config to the next config. It decides this length of time (in seconds)
by evaluating the expression assigned to MDur. For example, setting MDur to
"5 + rnd(6)" means each morph/transition will be 5 to 11 seconds
long.
-
- SScl - (Sample Scale)
- Scales the amplitude of the input (ie, every sub-sample is multiplied by
this number). If the music you play is soft, try increasing this to 1.5 or
higher (1000 means 1.0 and 1500 means 1.5, etc). Press the 'H' key to see
what keys will change SScl in real time (ie, commands 19 and 20).
- FNum - (Frequency Sample Size)
- How many sub-samples are in each frequency sample and like SNum, FNum is
a resolution: there are FNum number of values in fft(0..1). The higher 'FNum'
is, the more "bins" the frequency spectrum will be divided up into
(note: "bin" is interchangeable with "sub-sample from a frequency
sample" and "freq sample" is interchangeable with "freq
spectrum"). See the background section for extra info. In a config, you
can access 'FNum' by using NUM_FFT_BINS. If you're totally confused at this
point, don't get upset--there's a lot to digest here--just see the documentation
in the example configs, especially the documentation of the Stps parameter
in "ArcticFox Memories".
- FSmo - (Frequency Sample Smooth Factor)
- The higher number this is, the more the a sample will be smoothed out (ie,
peaks and valleys will be less jagged). To give you an idea, approximately
doubling/halving this number will double/half the amount of smoothing. In
other words, FSmo affects the amount of smoothing of fft(0..1).
- FRge - (Frequency Range Per Bin)
- This is how "wide" of a frequency band a value from fft() is. 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 information on frequency spectrums.
- FSrt - (Frequency Sample Start)
- This controls or "anchors" what frequency fft(0) is. 'FSrt' controls the starting frequency of the freq spectrum and is independent of FRge and FNum. The proportionality constant depends only on what build of WhiteCap or G-Force you're using (ex, Standalone, Winamp, SoundJam, etc). In other words, the frequency bin returned by fft(x) is: const * ( FSrt + FRge * FNum * x ) Hz.
- FFTT - (Frequency Sample Transform Fcn)
- This parameter transforms input or "raw" freq values into the actual values accessed via fft(). For example, to increase the scale of fft(), just put a bigger scaling factor in front of the function (that's why there's no 'FScl' parameter). Each build of WhiteCap/G-Force has a different default FFFT function because each audio player's fft data is massaged differently to make it look nice. The variable W is the frequency, X is the raw fft value for that W, and the whole expression will be the new value of X. As a whole, I've chosen functions that suppress large fft values and amplify medium-level fft values.
- SCmd - (Startup Command List)
- A list of keystrokes or config names separated by semicolons that's executed
when WhiteCap starts up. For example, if you desire to have WC go fullscreen
whenever it starts up, insert the corresponding keystroke to SCmd. The format
SCmd should take is identical to the format of a command line in any script.
For example, also suppose after going fullscreen you wanted to run a script
(perhaps containing various sprites/images you wanted displayed). SCmd would
read, "`;Andy's Script".