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".