Manual

Documentation for the latest beta version of Rainmeter. Use links in the sidebar to navigate.

Installation

Download the latest release or beta version from rainmeter.net.

Standard installation

The standard installation is recommended for most users. Simply run the installer and follow the instructions.

Portable installation

To run Rainmeter from a single folder, so it can be easily taken with you or even run directly from a removable drive, select 'Portable install' during the install process. Note that the required C++ and .NET runtime libraries will have to be manually installed.

Silent installation (advanced)

To install Rainmeter without user interaction, use the installer command line switches.

Default file locations

Program folder:
C:\Program Files\Rainmeter

Skins folder:
C:\Documents and Settings\YourName\My Documents\Rainmeter\Skins (Windows XP)
C:\Users\YourName\Documents\Rainmeter\Skins (Windows Vista and later)

Rainmeter.ini and themes:
C:\Documents and Settings\YourName\Application Data\Rainmeter (Windows XP)
C:\Users\YourName\Appdata\Roaming\Rainmeter (Windows Vista and later)

Settings

The general configuration settings are in a file named Rainmeter.ini. To modify settings, use the Manage dialog by clicking on the Rainmeter tray icon. Alternatively, right-click on the tray icon and select "Edit Settings" to modify the options with a text editor.

The Rainmeter.ini file has several sections: [Rainmeter], [TrayMeasure], and individual sections for each config which has been loaded. The Rainmeter section contains general settings that can be used to change how Rainmeter behaves. The settings are used as default values for all new configs that are opened. Once a config is opened it will write the settings under its own section in the Rainmeter.ini file.

Important: Some of the settings in the Rainmeter.ini file cannot be changed while Rainmeter is running becase a refresh will write the old values back to the ini file. If you cannot change something, try changing the value after completely closing Rainmeter.

Settings-Rainmeter

The [Rainmeter] section of Rainmeter.ini defines general Rainmeter settings. The following must be put under the [Rainmeter] section:

Options

Settings-TrayMeasure

One special section is [TrayMeasure], which can be used to define a measure for the tray icon. You can use any measure for this as long as it returns some meaningful values (i.e. numbers between some limits). The following must be put under the [TrayMeasure] section:

Options

Settings-ConfigName

The following should be put under the the sections for their respective configs, e.g. [illustro\Clock]. Most of these settings can also be set via the skin right-click context menu or through the Manage dialog.

Options

Settings-BuiltInVariables

The following are pre-existing variables that are set and controlled by Rainmeter. Their values cannot be manually changed.

Variables which return fully qualified paths.

Variables which return current skin information

Variables which return information about your screen

Miscellaneous variables

You may also use Windows environment variables, which can be obtained by the set command in cmd.exe (command prompt). To use them, use the name of the environment variable within two percent sign (e.g. %APPDATA%). Note that environment variables may vary from system to system.

Settings-Groups

Configs can be categorized into "groups" to allow quick control of multiple configs at once. To add a Config to a group, simply add the Group statement to the section under Rainmeter.ini. Alternatively, you may add Group under the [Rainmeter] section of the skin file.

Any number of groups may be added to a section, all of which must be separated by a vertical bar (i.e. "|"). Groups may also be specified under the [Rainmeter] section of Rainmeter.ini. In this case, that group will be considered the default for all configs that have no groups defined.

Example (Rainmeter.ini):

[Enigma\Sidebar\Systems]
Active=0
WindowX=0
WindowY=0
AlphaValue=255
FadeDuration=250
ClickThrough=0
SavePosition=1
SnapEdges=1
KeepOnScreen=1
Group=Enigma | Systems
The Enigma\Sidebar\Systems config be added to the "Enigma" and "Systems" groups, which can then be controlled through several bangs.

Example (skin):

[Rainmeter]
Update=1000
Author=Me
Group=Enigma | Systems
The skin is added to the "Enigma" and "Systems" groups, which can then be controlled through several bangs.

Settings-Monitors

There is a "Display Monitor" submenu in [Skins Menu]-[Position] of the Rainmeter tray icon.

These menus set the position of the skin to the desired monitor in a multiple monitor configuration.

AutoSelectScreen
If set to 1, the WindowX and WindowY "@n" settings are made automatically based on the position of the meter's window. If a monitor is selected directly using "Display Monitor" in the Rainmeter / skin context menu, this setting is reset to 0.

Built-in variables for multiple monitors

Variables for the virtual screen: Variables for the PRESENT monitor:
Note that these variables automatically change by the WindowX and WindowY "@n" settings. If "@n" is not set, these variables return the value of the primary monitor. Variables for the PRIMARY monitor: Variables for the SPECIFIED monitor (@1, @2, ...):

Skins

All skins are placed in the skin folder. Each skin must be in its own subfolder. The actual skin file is a normal .ini file with several sections that define the skin layout and values. A subfolder may contain several .ini files, but only one .ini file per folder can be active at a given time.

The skin .ini file is divided into several parts. All the general settings are put under the [Rainmeter] section, details about the are placed in the [Metadata] section, and the variables in the [Variables] section. Then follow the measures (which collect data) and meters (which display data). While it is not necessary to place the sections in this order, it is the convention that is observed by the vast majority of skin authors.

Note: Rainmeter reads and executes measures and meters in the order they are in the skin .ini file. This is important in particular for positioning of meters relative to each other.

Skins-Rainmeter

The [Rainmeter] section of a skin defines skin-wide options.

Background Options

Other Options

Skins-Metadata

This section contains details about the skin. The information is displayed in the Manage dialog.

Options

Skins-Variables

Variables represent other values. There are several built-in variables, but custom variables may also be defined to centralize common values used later on in the skin.

Variables are defined as follows under the [Variables] section:
VariableName=Value

The variable can then be referred in measures and meters as:
#VariableName#

For example, to set a variable for the size of the font you want to use on all your meters you might use:

[Variables]
Size=11

[SomeMeter]
FontSize=#Size#

[SomeMeter2]
FontSize=#Size#

If you want to use the variable name (and not its value), use asterisks to escape the variable:
#*VariableName*#. This is useful especially when using the !SetOption bang.

Skins-AeroBlur

Allows users on Windows Vista and later to enable Aero blur effects on transparent parts of the skin.

The following options must be in the [Rainmeter] section of the skin. The options have no effect on Windows XP or when Aero is disabled.

Options

Bangs

Example Skin


Skins-DynamicVariables

By setting DynamicVariables=1 in a measure or meter, the measure or meter will respond to variable changes by the !SetVariable bang. Additionally, if dynamic variables is enabled, a measure's name can be used as a variable by enclosing it in square brackets (e.g. [MyMeasure]). Dynamic variables can be used in any meter or measure, but not in the [Rainmeter] section.

Dynamic variables can only be used with a limited number of plugins. Currently, the following plugins support dynamic variables:


Example:

[Rainmeter]
Update=1000

[Variables]
Width=100

[MeasureCalc]
Measure=Calc
Formula=Counter%100

[Square1]
Meter=Image
SolidColor=255,0,0
W=#Width#
H=50
MouseOverAction=!SetVariable Width 200
DynamicVariables=1

[Square2]
Meter=Image
SolidColor=0,0,255
W=[MeasureCalc]
H=50
Y=R
DynamicVariables=1

In this example, Square1 would show a red 100x50 pixel box. When the mouse is place over the box, it grows to 200x50 as the variable is changed. Square2 shows a blue box that is 50 pixels tall and continuously grows from 0 to 100 pixels wide as it gets its width from the value of MeasureCalc.

Skins-Include

The @Include option is used to load an external .ini file into the skin. The loaded file is treated as if the contents were included in the actual skin .ini file. The option is often it is used in the [Variables] section of a skin to include common variables shared between skins. If there are multiple included files within the same section, each @include statement should be numbered as follows: 

@include1=...
@include2=...
@include3=...

Include files must use the INI format, meaning that they must have appropriate section names followed by key and value pairs. Commonly, Include files use the .inc file extension (rather than .ini) to avoid listing the include files in the Rainmeter skin list.

The included file is read at the position where the @include is defined so the values from the included file with the same name as those from the .ini file will overwrite the values from previous sections and vice versa. While the file is read at the given position, the contents of the file are treated as if they are at the bottom of the file in which the @include is called.

Note: You may use a variable as the name of an @include file, but not a dynamic variable.

Example:
IncludeFile.inc: 

[Variables]
Color=255,255,255,255

Skin.ini: 
[Variables]
Font=Arial
@Include=IncludeFile.inc

[SomeMeter]
FontFace=#Font#
FontColor=#Color#

Further explanation as well as examples of use are available at The power of @include.

Skins-MeterMeasureGroups

Measures and meters can be categorized into groups to allow easier control over a set of meters and measures with the Group bangs (e.g. !HideMeterGroup). To add a measure or meter to a group, simply add the Group= option. Any number of groups may be added to a section, all of which must be separated by a vertical bar (i.e. |)..


Example:
In this example, both of the meters belong to the "CPU" group. In addition, MeterCPUText belongs to the "Strings" group and MeterCPUBar in turn belongs to the "Bars" group.
[MeterCPUText]
Meter=String
MeasureName=MeasureCPU
Group=CPU | Strings

[MeterCPUBar]
Meter=Bar
MeasureName=MeasureCPU
Group=CPU | Bars
Meters in the CPU group, for example, can be hidden as follows: !HideMeterGroup CPU

Measures

Measures are sections that determine what information Rainmeter should retrieve. Within a .ini file, names for measures must be unique and they must not have spaces. The meters use these section names to bind to the measures and display the results.

Note: Some meters require a range of values (BAR, HISTOGRAM, etc) so that they can display the measured value as relative to the minimum and maximum values. Not all measures are able to calculate the minimum and maximum value automatically so you need to do that manually with MinValue and MaxValue.

Measures-GeneralSettings

These general settings apply to all measure types.

Options

Measures-IfActions

Measure IfActions are commands you add to a measure to have Rainmeter take some action when a defined "above/equal/below" threshold value is returned by the measure. You can have Rainmeter run a built-in !Bang, several !Bangs at once, or even execute some external command.

IfActions are done by using pairs of Above, Equal, and Below Value and Action statements. You may have one of each kind of IfAction in a single measure.

How an action is formatted varies somewhat depending on which !Bang is being used, or what an external application expects. The rules can be found at the Bangs page.

Options

Example Skin

Measures-Substitute

Substitute is an option used on measures to replace some or all of a string value returned by the measure with another string. When combined with the RegExpSubstitute option, regular expressions can be used in the option.

[MeasureYear]
Measure=Time
Format=%Y
Substitute="2012":"Twenty Twelve","2013":"Twenty Thirteen","2014":"Twenty Fourteen"

Substitute

RegExpSubstitute

Measures-Calc

The Calc measure is used to calculate formulas.

Options

Operators

Logical Operators

Note: Conditional statements evaluate to 1 (true) or 0 (false).

Functions

Constants

Conditional Operator

<condition> ? <expr. if true.> : <expr. if false.>
This will evaluate condition as being either true or false. If it is true, the expression to the left of the colon (:) is evaluated. If it is false, the expression to the right is evaluated. This is equivalent to the following if-then-else statement:

   if (condition)
     then
       expr. if true
     else
       expr. if false
   end if

Example:
[Example]
Measure=Calc
Formula=1<2 ? 3 : 4
This measure would return the number 3 since the condition 1<2 evaluates to true.

Rainmeter can also handle nested conditional operators. It should be noted that there is a maximum of 30 nested operators.

Example:
[Example]
Measure=Calc
Formula=1>2 ? 3 : (4<5 ? 6 : 7)
This measure would return 6. Since the first statement of 1>2 is false the nested conditional operator in the else statement is executed.

Random Function

The word RANDOM returns a random number between the values of "LowBound" and "HighBound" defined in the measure.

Other Bases

The Calc measure allows numbers to be represented numbering systems other than decimal. To use another base, prefix the number with a zero then the letter representing the system you wish to use. The following are accepted prefixes, which are case (lower) sensitive:
Example skin

Measures-CPU

Returns the percentage used of the entire CPU or individual cores.

Options

Example Skin

Measures-FreeDiskSpace

FreeDiskSpace returns usage statistics for the selected drive.

Options

Example Skin

Measures-Memory

Measures the amount of virtual memory free in bytes. Virtual memory is equal to Pagefile + RAM + RAM.

Options

Example Skin

Measures-NetInOut

Measures various types of network traffic.

NetIn

Measures incoming network traffic.

NetOut

Measures outgoing network traffic.

NetTotal

Measures total network traffic.

Example Skin

Measures-PhysicalMemory

Measures the amount of physical RAM memory free in bytes.

Options

Example Skin

Measures-Plugin

A plugin in Rainmeter is a dynamic link library (.dll) program specifically written to provide additional functionality not built into Rainmeter. A plugin is used in Rainmeter with the specific measure type Measure=Plugin. Each plugin in turn has its own settings that must be placed in this section. See Plugins to learn more on the plugins included with Rainmeter and what settings are required for each.

You may also use a 3rd-party plugin developed for Rainmeter but not included with the installation. Simply place the new plugin .dll file into the Plugins folder under the location of your Rainmeter.exe and the new plugin can be used like any of the default ones. Note: Be sure that the 3rd-party plugin you add was compiled for the same architecture version of Rainmeter (32bit or 64bit) as the version you are using. You may not use a 32bit plugin with 64bit Rainmeter or a 64bit plugin with 32bit Rainmeter.

Options

Example Skin

Measures-Registry

Provides a way to read data from the Windows Registry.

Options

Registry data types

If you open Regedit.exe to the location you are trying to read, you will notice the second column in the right pane is called "Type". There are several different types, but the two most common - and the two supported by Rainmeter - are REG_SZ and REG_DWORD. If the value is of type REG_SZ it means it is a string. If it is REG_DWORD it is a number. Many of Rainmeter's meter types require a number as input rather than a string. This means that if the value you are trying to read is of type REG_SZ, meters like Line, Histogram, Bar, etc. will not recognize the value. Even if the value is entirely numeric, it will still be read as a string.

Numeric string values from the registry can be used as a number if you convert them with a Measure=Calc.

[MeasureRegistry]
Measure=Registry
...

[MeasureStringToNum]
Measure=Calc
Formula=[MeasureRegistry]
MinValue=0
MaxValue=100
DynamicVariables=1

Example Skin

Measures-Script

The Script measure allows the execution of Lua (a scripting lanague) code. The Lua script can be used to retrieve the values of measures, send bangs, and more. A Lua script can do programming that would be difficult or impossible in native Rainmeter code, and can return values or change settings in the Rainmeter skin.

Options

Custom options can be added to the measure, which can then be retrieved and used with SELF:GetOption() or SELF:GetNumberOption() in the script. Example:

[MeasureScript]
Measure=Script
ScriptFile=MyLua.lua
ItemsToCount=5

Bangs

The Script measure can be controlled with the !CommandMeasure bang. The argument must be valid Lua code and will be executed in the context of ScriptFile.

A full explanation of how to use this measure type with the Lua scripting language can be found at Lua Scripting. This guide should be carefully read before creating a skin using the Script measure.

Measures-SwapMemory

Measures the amount of virtual (swap) memory free in bytes.

Options

Example Skin

Measures-Time

Measures the current date/time.

Options

Format codes

Full details on Time/Date formatting codes can be found at msdn.microsoft.com.

%a - Abbreviated weekday name
%A - Full weekday name
%b - Abbreviated month name
%B - Full month name
%c - Date and time representation appropriate for locale
%d - Day of month as decimal number (01 - 31)
%H - Hour in 24-hour format (00 - 23)
%I - Hour in 12-hour format (01 - 12)
%j - Day of year as decimal number (001 - 366)
%m - Month as decimal number (01 - 12)
%M - Minute as decimal number (00 - 59)
%p - Current locale's A.M./P.M. indicator for 12-hour clock
%S - Second as decimal number (00 - 59)
%U - Week of year as decimal number, with Sunday as first day of week (00 - 53)
%w - Weekday as decimal number (0 - 6; Sunday is 0)
%W - Week of year as decimal number, with Monday as first day of week (00 - 53)
%x - Date representation for current locale
%X - Time representation for current locale
%y - Year without century, as decimal number (00 - 99)
%Y - Year with century, as decimal number
%z, %Z - Either the time-zone name or time zone abbreviation, depending on registry settings
%% - Percent sign
# - A "#" character used before a code (%#d) will removing leading zeros from the result.

Example Skin

Measures-UpTime

Returns the amount of time since the last restart of the computer.

Options

Example Skin

Meters

Meters are the sections that tell Rainmeter how to display information. Each meter needs to have a unique name, which should be put inside [Square Brackets]. It does not matter what the name is as long as there are no spaces and it is not used elsewhere within the same.ini file.

Meters by default are evaluated and displayed in the order they are in the skin .ini file. Settings like W= and H= and X= and Y= can be used to size and position meters in the context of the skin containng them. So a meter with a setting of X=0 will be positioned 0 pixels from the left edge of the skin it is in. If you drag the entire skin to another location, the meter will remain positioned 0 pixels from the left edge of the skin, irregardless of where the skin is on the screen.

There are many different types of supported meter types in Rainmeter. The manual pages for each describe them in detail, with settings specific to each type.


Example Skin

Meters-GeneralSettings

The following are setting which apply to all meter types.

Options

Meters-ColorCodes

Rainmeter uses colors in the settings of many different meters.

Color codes in Rainmeter are based on RGBA, which stands for red, green, blue, and alpha. The values can be entered either using a set of four numbers ranging from 0 to 255 in either decimal or hexadecimal form. You may leave off the alpha value, and Rainmeter will default to 255 / FF, or fully opaque.

Note: If you use an alpha of 0, then the element using the color will not only be invisible, but will not be seen by Rainmeter at all for the purpose of mouse actions. If you want a meter to be invisible but still seen by Rainmeter, use an alpha of 1.

A online color picking tool which will provide the RGB and HEX codes for a color can be found at Rainmeter Color Picker.

Examples

Solid opaque red is 255,0,0,255 or FF0000FF
Solid opaque blue is 0,0,255,255 or 0000FFFF
Solid opaque grey is 128,128,128,255 or 808080FF
Half-transparent green is 0,255,0,128 or 00FF0080

Meters-MeterStyle

MeterStyles allow CSS-like common "styles" for meters. This allows you to centralize common parameters for meter into a single section. Using the MeterStyle option will essentially cause the specific meter to inherit all applicable properties from the given style. A style is just another section (it can even be a meter). Multiple styles can be used by separating them with a pipe (i.e. Style1 | Style2 | ...).

Note: You may not "daisy chain" MeterStyles. In other words although a meter may be used as a MeterStyle for another meter, that second one may not be used as a MeterStyle for a third.


Example Skin

Meters-ANoteOnFonts

Fonts are used in String meters through the FontFace option. Fonts can either be installed directly into Windows (allowing the font to be available to all installed programs) or you can use the LocalFont option (under the [Rainmeter] section) to restrict the font to Rainmeter only (and not require a separate install).

Using fonts

Installing fonts

Install the font by right clicking it and selecting "Install Font". This will install the font in Windows\Fonts and it will be available in Rainmter and all other Windows applications.

Note: Rainmeter must be restarted after installing fonts in order for Rainmeter to detect the change.

Use the font with the Family Name in a Meter=STRING meter.

[MeterName]
Meter=String
FontFace=MyInstalledFont

Using LocalFont

Place the actual .ttf font file in a folder. Use the LocalFont="Path\FileName.ttf" option in the [Rainmeter] section of your skin. Then use the Family Name in FontFace=xxx as normal.

Note: You may use more than one LocalFont in [Rainmeter] by simply adding a number: LocalFont2, LocalFont3, ...

[Rainmeter]
LocalFont="#CURRENTPATH#SomeFont.ttf

[MeterName]
Meter=String
FontFace=MyLocalFont

Example Skin

Meters-ToolTips

This creates a ToolTip which appears when you hover the mouse over the meter. You must be careful not to overlap two meters with ToolTips as both will be displayed if the mouse is over both at the same time.

Options

Meters-TransformationMaxtrix

This defines a 3x2 matrix which can be used to transform the meter. There must be exactly 6 values separated by semicolons (e.g. TransformationMatrix=1;0;0;1;0;0). The values a;b;c;d;e;f correspond to the following matrix: 
|a c e|
|b d f|
In short, the values have the following effects: Combining these can have drastic effects on the meter it is applied to. For more comprehensivev information on TransformationMatrix, read this forum thread. The following are some examples showing the actual matrix and the corresponding TransformationMatrix values:

Flip X along line x=20:
|-1 0 2x|   |-1 0 40|
| 0 1 0 | = | 0 1 0 |
TransformationMatrix=-1;0;0;1;40;0

Flip Y along line y=50:
|1  0 0  |   |1  0 0  |
|0 -1 2*y| = |0 -1 100|
TransformationMatrix=1;0;0;-1;0;100

Scale X by 0.5 (at x=50):
|0.5 0 0.5*x|   |0.5 0 25|
|0   1 0    | = |0   1 0 |
TransformationMatrix=0.5;0;0;1;25;0

Note: All transformations are relative to the top left corner of the window and not to the meter itself. So if you want to rotate the meter by its center the translation component in the matrix must be relative to the top left corner of the window.

Also note that the even if the meter's visual location and orientation is changed by the transformation the place where it would be located without the transformation will still be used to define the window size and register the mouse clicks. This might change in the future though.

Meter-Bar

Bar meters display the value of a measure in a single vertical or horizontal bar. The amount the bar is filled corresponds to the relative value of the measure. Bar graphs require that the measure being used is from 0.0 to 1.0 or has both MaxValue and MinValue set.

Changes to the bitmap are applied in the following order: ImageCrop -> GreyScale -> ImageTint -> ImageFlip -> ImageRotate.

Options

Example Skin

Meter-Bitmap

The Bitmap meter takes an image and divides it into equally-sized frames. Each frame is shown as the relative value of the measure attached to it reaches the relative position of the pieces. For example, if the image a strip of 5 images, when the measure is between 0% and 19% the first frame is shown, from 20 to 39% the second frame is show, and so on. Bitmaps are often used with counters to display animations, or are used to show stylized numbers.

Changes to the bitmap are applied in the following order: GreyScale -> ImageTint -> ImageFlip.

Options

Example Skin

Meter-Button

The button meter cannot be bound to any measure. Its entire purpose is to make the creation of buttons easier. A button can display a normal, clicked and hover state of an image and perform an action automatically.

Changes to the button image are applied in the following order: GreyScale -> ImageTint -> ImageFlip.

Options

Example Skin

Meter-Histogram

Histograms display values using vertical bars - once per update - on a graph. They require that the measure being used ranges from 0.0 to 1.0 or has both MaxValue and MinValue set.

Changes to the images are applied in the following order: ImageCrop -> GreyScale -> ImageTint -> ImageFlip -> ImageRotate.

Options

Example Skin

Meter-Image

The Image meter is used to show images. It does not necessarily need to be tied to a measure and is often used just to display a specific image for aesthetic purposes. However, when used with a measure, it will try to display the image whose filename corresponds to the value of the measure.

Changes to the image are done by applied in the following order: ImageCrop -> GreyScale -> ImageTint -> ImageFlip -> ImageRotate.

Options

Example Skin

Meter-Line

The line meter shows the values of a measure as a graph with a line connecting each data point. Any number of lines can be shown depicting as many measures with a single meter, all overlapping. Line meters require that the measure being used is from 0.0 to 1.0 or has both MaxValue and MinValue set.

Options

Example Skin

Meter-Rotator

The Rotator meter displays an image that rotates around a point where the angle of rotation is determined by the measure it is attached to. Rotator meters require that the measure being used is from 0.0 to 1.0 or has both MaxValue and MinValue set.

The center of rotation will be located at the center of the height and width specified for the meter. If height and width are not specified, the center of rotation will be located at the X and Y coordinates provided for the meter. It is also important to remember that if the height and width are not specified, any portion of the meter that lies outside of the skin window will be cut off.

An example of how the center of rotation works is at Rotate an Image Around its Center.

Changes to the image are applied in the following order: ImageCrop -> GreyScale -> ImageTint -> ImageFlip -> ImageRotate.

Options

Example Skin

Meter-Roundline

The Roundline meter displays a single line that rotates around a point. The angle of the line is determined by the measure. By default, the minimum position is pointing to the right, the line then moves clockwise until it is pointing to the right again. Roundline meters require that the measure being used is from 0.0 to 1.0 or has both MaxValue and MinValue set.

If the width and height are not defined, the center point is the at the X and Y position of the meter and any part of the meter that intersects with the edges of the skin window will be cut off. If width and height are specified, the center point will be in the middle of the bounding box and the skin windows will include the meter.

Options

Example Skin

Meter-String

String meters display the value of measures as text. A string meter does not necessarily need to have a measure attached to it and can just be a static string of text by using Text=. You can mix the results of measures and static text by using Text= combined with %1, %2 etc. to indicate the value of the measures used by the meter. If you are only displaying the result of a single measure, no Text= statement is needed.

Options

Example Skin

Plugins

A plugin in Rainmeter is a dynamic link library (.dll) program specifically written to provide additional functionality not built into Rainmeter. A plugin is used in Rainmeter with the specific measure type Measure=Plugin. Each plugin in turn has its own settings that must be placed in this section. Click on any of the plugins listed on the right to learn more about the plugins included with Rainmeter and what settings are required for each.

You may also use a 3rd-party plugin developed for Rainmeter but not included with the installation. Simply place the new plugin .dll file into the Plugins folder under the location of your Rainmeter.exe and the new plugin can be used like any of the default ones. Note: Be sure that the 3rd-party plugin you add was compiled for the same architecture version of Rainmeter (32bit or 64bit) as the version you are using. You may not use a 32bit plugin with 64bit Rainmeter or a 64bit plugin with 32bit Rainmeter.

If you are interested in creating a 3rd party plugin for Rainmeter, there are source code templates available for both C++ and C# coders. Further information can be found at Developers.

Plugin-AdvancedCPU

Plugin=AdvancedCPU

This is similar to using PerfMon to measure the CPU usage except that you can filter out processes or only include some of them.

Options

Example Skin

Plugin-CoreTemp

Plugin=CoreTemp

This plugin can retrieve the values measured by CoreTemp. CoreTemp must be running in the background in order for the plugin to work. A list of supported CPU's is available here.

Options

Example Skin

Plugin-FolderInfo

Plugin=FolderInfo

FolderInfo.dll can be used to count files in a folder, their size, and more.

Options

Example Skin

Plugin-InputText

Plugin=InputText

InputText inserts user-supplied text into one or more bangs. The plugin works by defining a series of commands, which can be triggered by any "action" string (this includes mouse actions, conditional actions in a Calc measure, and other commands in an InputText measure, including the same measure). When triggered, a free-floating text input box is created to gather user input at the specified points in the command series. When all input has been submitted, the commands are carried out.

Options

Bangs

LeftMouseUpAction=!CommandMeasure "MeasureInputTextPlugin" "ExecuteBatch ALL X=100"
IfAboveAction=!CommandMeasure "MeasureInputTextPlugin" "ExecuteBatch 3"
Command4=!CommandMeasure "MeasureInputTextPlugin" "ExecuteBatch 2-4 Password=1"

Notes: Example Skin

Plugin-iTunes

Plugin=iTunesPlugin

This plugin can be used to remote control iTunes and get information from it.

Note: New skins should use the NowPlaying plugin as it supports multiple media players (including iTunes).

Options

Bangs

iTunes can be controlled through !CommandMeasure statements. You can either one of the following methods.

The example skin below demonstrates both methods.

Example Skin

Plugin-NowPlaying

Plugin=NowPlaying

The NowPlaying plugin is used to control various media players and retrieve track metadata (including album art) from them.

IMPORTANT: This plugin uses the the concept of 'main' and 'secondary' measures. To understand the difference, refer to the example skin at the end of this page.

Options

Bangs

The media player can be controlled with !CommandMeasure statements. See the sample example skin below for usage.

Supported Players

This list contains all supported media players in the latest beta version of Rainmeter. Note that using an unsupported type or bang is perfectly safe (it will simply result in in a empty value or no action, respectively).

Other Players

In addition to the players listed above, the NowPlaying plugin may support other players through supported interfaces. You may want to give the following interfaces a try.

If none of these work, leave a suggestion in this thread. If you're nice enough, support for your player will be added shortly after your message :-)

Donate

This plugin was was developed as a personal project by our user poiru at some cost of time, but is being freely distributed. If you find the plugin valuable, please express your gratitude by donating any amount by clicking on the following PayPal link.


Example Skin

Plugin-PerfMon

Plugin=PerfMon

Use Window's Performance Monitor to find out the valid values for these settings. There are a great many counters which Windows tracks in Performance Monitor. From the Start Menu, type "Perfmon.msc" to run the tool and find the counters you wish to measure.

Note: The names of the objects, counters and instances need to be in English even in localized versions of Windows.

Options

Example Skin

Plugin-PingPlugin

Plugin=PingPlugin

This plugin can be used to send ping packets to a server and measure the network latency.

Options

Example Skin

Plugin-PluginMediaKey

Plugin=MediaKey

The MediaKey plugin allows you to send various keystrokes found on multimedia keyboards. It has been tested to work with Spotify, Zune, foobar, and Windows Media Player.

Usage:

[MeasureMediaKey]
Measure=Plugin
Plugin=MediaKey

The plugin is controlled via !CommandMeasure statements sent to its measure. E.g.:

!CommandMeasure "MeasureMediaKey" "NextTrack"

Valid arguments are:

Plugin-PowerPlugin

Plugin=PowerPlugin

This plugin can be used to measure battery status and the current MHz on laptops. Note that not all laptops support this (or all the values).

Plugin-Process

Plugin=Process

Detects if a defined Windows process or application is currently running.

Options

Returns values of -1 (not running) or 1 (running).

Notes: This can not be used to detect if a Windows "service" executable is running, as those processes are run inside of the "svchost.exe" process. Also, the plugin may not be able to identify a process that is started with "Run as administrator" if Rainmeter is run with normal user privileges and UAC is enabled in Windows.


Example Skin

Plugin-Quote

Plugin=QuotePlugin

This plugin has two different uses: it can display a random string from a text file or it can select a random file from a folder which can be displayed with the IMAGE meter (if it's an image that is).

Options

Example Skin

Plugin-RecycleManager

Plugin=RecycleManager

This plugin can be used to check the size and count of the files in the recycle bin.

Options

Bangs

The following bangs can also be sent to any RecyleManager measure:

Example Skin

Plugin-ResMon

Plugin=ResMon

Requires Windows XP with Service Pack 1 or newer. The plugin was originally made by Daedalus.

Options

Plugin-Speedfan

Plugin=SpeedFanPlugin

This plugin can read the values measured by SpeedFan. You need to have SpeedFan running for this plugin to work since it doesn't do any measuring itself.

Options

Plugin-SysInfo

Plugin=SysInfo

This plugin returns various information about your system.

Options

Plugin-VirtualDesktops

Plugin=VirtualDesktops

A virtual desktop manager (VDM) allows you to distribute programs across multiple desktops. The VirtualDesktops plugin gives access to information from different VDMs for Windows and can be used to trigger desktop switches.

General Options

Options for VDManager=Dexpot

Note that bangs do not default to the current skin (use !Refresh "#CURRENTCONFIG#" instead of just !Refresh, for example).

Additional types for VDMeasureType:

Other options specific to VDMeasureType=Screenshot:

Plugin-WebParser

Plugin=WebParser

WebParser reads information from webpages. The plugin uses Regular Expressions to parse the web page which allows it to extract information pretty much from any page. The plugin can be used e.g. to get the current TV shows, weather conditions, stock exchange values, news and basically anything that is on the net. The negative side is that the regular expressions might look rather complex especially if you're not familiar with programming languages (and even if you are :-).

More information and examples for WebParser can be found at WebParser Primer and RSS Skin Tutorial.

Options

Examples:

Retrieve the title and first item from Slashdot's RSS feed.

[MeasureRSSTitle]
Measure=Plugin
Plugin=WebParser
UpdateRate=3600
Url=http://slashdot.org/slashdot.rdf
RegExp="(?siU)<title>(.+)</title>(.+)<item(.+)<title>(.+)</title>"
StringIndex=1
FinishAction=!Redraw

[MeasureRSS]
Measure=Plugin
Plugin=WebParser
Url=[MeasureRSSTitle]
StringIndex=4
Substitute="&amp;":"&"

Download the current weather map from Finnish Meteorological Institute.

[MeasureDL]
Measure=Plugin
Plugin=WebParser
UpdateRate=1800
Url=http://www.fmi.fi/saa/sadejapi_5.html?selected=7
RegExp="(?siU)ennuste" SRC=\"(.*)\"></TD>"
FinishAction=!Redraw
StringIndex=1
Download=1

[MeterImage]
Meter=IMAGE
MeasureName=MeasureDL
X=0
Y=0
W=400
H=300

Plugin-WiFiStatus

Plugin=WiFiStatus

The WiFiStatus plugin can be used to display various attributes of visible wireless networks in your area. Windows XP SP2 users need to install the KB918977 hotfix.

Options

Examples: 

[MeasureSSID]
Measure=Plugin
Plugin=WiFiStatus
WiFiInfoType=SSID
WiFiIntfID=0

[MeasureNetworks]
Measure=Plugin
Plugin=WiFiStatus
WiFiInfoType=LIST
WiFiIntfID=0
WiFiListStyle=3

A more detailed sample and support is available at the WiFiStatus support thread.

Plugin-Win7AudioPlugin

Plugin=Win7AudioPlugin

Controls sound device and volume for Windows Vista and newer. Previous versions of Windows are not supported. This plugin has been written by Reiswaffel.

Usage

[MeasureWin7Audio]
Measure=Plugin
Plugin=Win7AudioPlugin

Returns the name of the current sound device (when used in a STRING meter) and the percentage (0-100) of current volume level (when used in a measure which requires a number).

Bangs

The current device and volume is controlled with !CommandMeasure statements sent to the plugin. See the sample .ini below for examples.


Example Skin

Plugin-WindowMessage

Plugin=WindowMessagePlugin

This plugin can be used to send and receive information from other applications. It can send window messages to other applications and show the result. The plugin can be used for example to control WinAmp or some similar media players.

Options

Bangs

Messages can also be sent on demand with the !CommandMeasure bang. The arguments are similar that of the WindowMessage option.
!CommandMeasure "MeasureName" "SendMessage Msg wParam lParam"


Examples:

This returns the name of the song that is playing in WinAmp.

[MeasureWinamp]
Measure=Plugin
Plugin=WindowMessagePlugin
WindowClass=Winamp v1.x
Substitute="[Paused]":""," - Winamp":""

Check if Winamp is playing, or not. This returns 0 if it's not playing, 1 if it is playing and 3 if it's paused.

[MeasureWinampPlaying]
Measure=Plugin
Plugin=WindowMessagePlugin
WindowClass=Winamp v1.x
WindowMessage=1024 0 104

Show song progress. The  [MeasureWinampDuration] will return the current song position as a value between 0 and 1. You can use for example the BAR-meter to display the value.

[MeasureWinampFull]
Measure=Plugin
Plugin=WindowMessagePlugin
WindowClass=Winamp v1.x
WindowMessage=1024 1 105

[MeasureWinampCurr]
Measure=Plugin
Plugin=WindowMessagePlugin
WindowClass=Winamp v1.x
WindowMessage=1024 0 105
[MeasureWinampDuration]
Measure=Calc
Formula=(MeasureWinampCurr<=0)?0:(MeasureWinampCurr/(MeasureWinampFull*1000+1))

MouseActions

Mouse actions allow the execution of bangs on specific mouse events.

Note: When using a mouse action on a string meter or image meter with transparency, the action will not be executed when clicking on fully transparent areas. This can be solved by adding SolidColor=0,0,0,1 to the meter, which will create an near-invisible but solid background behind the meter.

Note: Actions defined for the meter will override actions defined in the [Rainmeter] section.

Bangs

Bangs are commands that are used to control various aspects of the skin and Rainmeter. Bangs are specified in options such as LeftMouseUpAction.

General Rules

Bangs

In the list of bangs below, parameters enclosed by [square brackets] indicate required parameters. Parameters enclosed in (normal brackets) indicate optional parameters.

Several bangs take Config as an optional parameter. When left out, the bang will affect the current skin only. If the Config is specified, the bang will affect the specified config. Use * as the config to apply the bang to all open configs.

Operating system

Application

Options and variables

Skins

Meters

Measures

Deprecated bang functionality

LuaScripting

Rainmeter provides scripting support through Lua. The scripting interface provides access to the Lua 5.1 standard library, which can be used to read and write files, format strings, perform arithmetic, and a lot more. In addition, the interface provides Rainmeter specific features such as retrieving values of measures and variables, executing bangs, and writing to the log.

Note: This page merely describes Rainmeter specific features. To learn about the Lua language itself, consider the Lua manual, Lua tutorial, or the Programming in Lua book.

Note: The Lua debug library is not available. In addition, access to external libraries such as LuaCURL and the use of functions such as require or dofile is not currently supported.

Script measure

Lua scripts (.lua files) are used through the Script measure:

[MeasureLuaScript]
Measure=Script
ScriptFile=MyScript.lua

Script files

A Lua script can define the following functions.

Example

Skin:
[MeasureScript]
Measure=Script
ScriptFile=LuaSample.lua
ExampleNumber=20
; [MeasureScript] will have a numerical value of 70 and a string value of "70"

Script:
function Initialize()
	exampleNumber = SELF:GetNumberOption('ExampleNumber')
end

function Update()
	local newNumber = exampleNumber + 50
	return newNumber
end

Log

Errors in Lua scripts are reported through the Log tab of the About dialog. The Lua print function can also be used to output to the log.

print('The value of variable myVar is: '..myVar)

SKIN object

The predefined SKIN object exposes functions related to the current skin. For example:

meter = SKIN:GetMeter('ExampleMeter')
SKIN:Bang('!Refresh')

SELF object

The predefined SELF object exposes functions related to the current Script measure. In addition to the functions listed below, other functions listed under "Measure objects" can also be used with SELF without needing to obtain a handle to the measure with SKIN:GetMeasure(). For example:

SELF:GetOption('SomeOption')
SELF:GetNumberOption('SomeOption')

Meter objects

The meter object exposes functions related to an existing meter. To create a meter object, use the SKIN:GetMeter() function. For example:

exampleMeter = SKIN:GetMeter('ExampleMeter')
exampleMeter:SetX(25)

Measure objects

The measure object exposes functions related to an existing measure. To create a measure object, use the SKIN:GetMeasure() function. For example:

exampleMeasure = SKIN:GetMeasure('ExampleMeasure')
exampleMeasure:Disable()

Handling actions

The !CommandMeasure bang can be used to execute Lua code in the context of a Script measure. This is especially useful when reacting to mouse or other action events. For example:

LeftMouseUpAction=!CommandMeasure "ScriptMeasure" "someVar = 5"

LeftMouseUpAction=!CommandMeasure "ScriptMeasure" "func(); var = 2;"

Formulas can be passed to the script with !CommandMeasure in the skin and evaluated using SKIN:ParseFormula(). For example:

LeftMouseUpAction=!CommandMeasure "ScriptMeasure" "func('(5 + 5)')"

function func(arg)
   local result = SKIN:ParseFormula(arg) -- result will be 10
end

Formulas should be enclosed in single quotes and parentheses.

Deprecated features

These are features that should not be used. They are still supported, but may be removed in the future.

RMSkinCreate

The Rainmeter skin package (.rmskin) is an increasingly popular method of distributing various Rainmeter components. It allows one-click installation of skins, themes, fonts, and more.

To create a .rmskin package, get the .rmskin template from here, then extract and open the newly created Template folder. It should contain five folders along with a file called Rainstaller.cfg.

Adding your skins / themes / addons / plugins and fonts.

To add components to the package, simply copy it into the correct folder.

For example, to include the "MySkins" suite of skins, simply copy the entire Documents\Rainmeter\Skins\MySkins folder from your Rainmeter installation into Template\Skins in the template folders.

More on including plugins

You are able to include both 64bit and 32bit in one single .rmskin. If you decide to take advantage of this, you must specify at least MinRainmeterVer=2.0.0.740 into Rainstaller.cfg. Then, create the Template\Plugins\32bit and Template\Plugins\64bit folders and copy the plugin(s) into the appropriate folder.

Template\
- Plugins\
-- 32bit\
--- MyPlugin\
---- myplugin.dll
-- 64bit\
--- MyPlugin\
---- myplugin.dll

More on including Fonts

There are three ways to include font(s) in your distribution:

Changing settings

After you have copied all the necessary files into the correct folders, open any text editor (e.g. notepad) and drag & drop the Template\Rainstaller.cfg file into the text editor. Fill in the obvious (Name, Author, and Version) and save the file. A detailed explanation of the other values is available at the end of this page, be sure to glance through that list.

Creating the .rmskin file

The .rmskin file is simply a renamed .zip file. So, in order to create a .rmskin file, you'll need to create a .zip file first. To do this, right-click on the Template folder and select Send to -> Compressed (zipped) folder. You will be asked to name the newly created .zip file. Give it the name of your choice and press Enter.

To convert the created .zip file into a .rmskin file, simply change the file extension from .zip to .rmskin. If you don't know how to do this manually, grab and run ExttensionChanger from from here. It will allow you change extensions from .zip to .rmskin and vice versa.

Testing and sharing

Before sharing the newly created .rmskin with others, you will need to make sure it works properly. Remember to delete the components from your own computer before installing to make sure the files were installed properly. For example, if you know that the .rmskin is going to install a skin called "BestSkinEver", delete "BestSkinEver" from Rainmeter\Skins.

After you have ensured that everything works as intended, you are free to upload and share your .rmskin with others.