AudioLevel plugin

Plugin=AudioLevel monitors and analyzes streams of audio sound to or from an audio endpoint.

AudioLevel will monitor, filter and analyze the amplitude (volume level) of sound input or output on the default or defined device and channels. The value returned will be a number from 0.0 to 1.0, which will be treated as a percentage for use in meters.

This can be used to create a volume level VU Meter for defined channels, or optionally can filter the audio stream into distinct frequency bands to create a Spectrum Analyzer.

The plugin monitors the amplitude of the post-mixer signal at a Windows audio endpoint. (i.e. sound card speaker output, USB audio interface, headphone port, microphone input) It does this by creating a WASAPI capture client in loopback mode. The capture client streams audio data to the plugin where it can be filtered and measured. The resulting volume level is returned by the plugin for use in Rainmeter measures and meters.

Note: Creating meters that display sound levels in real-time will require that the skin be set with a fairly low Update rate in the [Rainmeter] section of the skin. While the plugin is quite resource friendly and efficient, some care should be taken when deciding how much analysis should be done on the signal, and it is recommended that this plugin be used in a skin dedicated to it, and not as a part of a larger skin where the low update rate may cause higher CPU usage.

Usage

AudioLevel operates with a "parent / child" approach. A single "parent" AudioLevel measure is used to obtain and analyze the audio stream, and then as many "child" measures as desired request data from the parent to get individual values to display in meters. Example:

; This parent measure processes the default audio output.
[MeasureAudioRaw]
Measure=Plugin
Plugin=AudioLevel

; This child measure gets the current RMS value of the left channel (0.0 to 1.0).
[MeasureAudioRMS_L]
Measure=Plugin
Plugin=AudioLevel
Parent=MeasureAudioRaw
Channel=L
Type=RMS

; This child measure gets the current RMS value of the right channel (0.0 to 1.0).
[MeasureAudioRMS_R]
Measure=Plugin
Plugin=AudioLevel
Parent=MeasureAudioRaw
Channel=R
Type=RMS

Note: Only the Type, Channel, FFTIdx and BandIdx child measure options can be changed dynamically with !SetVariable or !SetOption. Parent measure options may not be changed dynamically.

Options

General measure options

All general measure options are valid.

Parent measure options

Port Default: Output

Specifies whether you want to measure the input or output levels for the given device.

  • Output (default)
  • Input
ID Default: None

Specifies the audio device to measure.

If not set, it will use the default device for the specified Port. If you specify Port=Output and no ID, the plugin will connect to the default audio output device defined in Windows.

To specify a device other than the default, you will need to find the Windows device ID. See the DeviceList child measure option for more info.

Device IDs will be in the form: {0.0.0.00000000}.{5c106e65-26b4-4d05-a9bf-b207a71e9eaa}

Note: The default audio device in Windows can be changed by using "Manage Audio Devices" from the Windows Start menu.

RMS options

RMS is a way of calculating the average of values over a period of time, using the mathematical algorithm Root Mean Square. The signal value (amplitude) is squared, averaged over a period of time, then the square root of the result is calculated. The result is a value, that when squared, is related (proportional) to the effective power of the signal.

This is the most meaningful way of measuring audio volume levels in a skin.

Note: To disable all RMS filtering, set both RMSAttack and RMSDecay to 0, and RMSGain as the default 1.0.

The following parent options are used in combination with child measures having the Type=RMS option set.

RMSAttack Default: 300

Specifies the time in milliseconds over which to interpolate as the signal level increases. For example, how quickly a needle jumps up as the sound level increases.

RMSDecay Default: 300

Specifies the time in milliseconds over which to interpolate as the signal level decreases. For example, how quickly a needle subsides as the sound level decreases.

RMSGain Default: 1.0

A multiplication factor that will be applied to the RMS analysis.

Peak options

Peak options are similar to RMS options, but measure the peak (high) values rather than squaring to obtain an average over a period of time.

Note: To disable all Peak filtering, set both PeakAttack and PeakDecay to 0, and PeakGain as the default 1.0.

The following parent options are used in combination with child measures having the Type=Peak option set.

PeakAttack Default: 50

Specifies the time in milliseconds over which to interpolate as the signal level increases. For example, how quickly a needle jumps up for a higher peak.

PeakDecay Default: 2500

Specifies the time in milliseconds over which to interpolate as the signal level decreases. For example, how quickly a needle subsides to a lower peak.

PeakGain Default: 1.0

A multiplication factor that will be applied to the Peak analysis.

FFT options

FFT options transform the signal from the time domain to the frequency domain, with FTTSize determining how many points you get back in the frequency domain. This is done by analyzing the audio stream into a linear-based number of points using the mathematical algorithm Fast Fourier Transform.

This frequency information can then optionally be extrapolated into logarithm-based Bands to distinctly measure by frequency in the ranges that are the most useful for spectrum display, based on the way humans detect changes in sound.

In order to use Bands, both FFTSize and Bands must be set on the parent measure.

The following parent options are used in combination with child measures having the Type=FFTand FFTIdx or Type=Band and BandIdx options set.

FFTSize Default: 0

A number value for the frequency resolution of the output data.

This will be an even integer greater than or equal to 0, usually a power of 2. Typical values are 256, 512, or 1024, with the higher the number the greater the frequency resolution.

Note: It should be kept in mind that as this number increases, more CPU resources and time will be needed to analyze the audio stream. A very high number here can both impact CPU usage and potentially cause some "lag" between the sound generation and the measurement by the plugin.

FFTOverlap Default: 0

Optionally, the FFT can be windowed to overlap successive sections. A Hann function is used to shape the data before the FFT is applied. Typical values are half the FFTSize. Increasing this value will lower the latency between the audio and the measure's response, at the cost of extra CPU.

FFTAttack Default: 300

Specifies the time in milliseconds over which to interpolate as the signal level increases. For example, how quickly a needle jumps up for a higher level.

FFTDecay Default: 300

Specifies the time in milliseconds over which to interpolate as the signal level decreases. For example, how quickly a needle subsides to a lower level.

Bands Default: 0

An integer, specifying the number of frequency bands to generate.

The FFT data can be extrapolated into a number of log-spaced frequency bands, similar to a typical spectrum analyzer. This option specifies the number of bands to create.

FreqMin Default: 20

A number in Hz, specifying the minimum frequency band calculation.

FreqMax Default: 20000

A number in Hz, specifying the maximum frequency band calculation.

Sensitivity Default: 35.0

A number specifying in what dB range the measure will return FFT and Band data. Increasing this value will cause the measure to respond to quieter sounds, decreasing it will only trigger the measure on louder sounds.

Child measure options

Parent Required

Defines the parent AudioLevel plugin measure to read values from.

Example: Parent=SomeMeasureName

Channel Default: Sum

This specifies which audio channel level to read from the parent. Channels can be identified by name or number, e.g. Channel=0 is the same as Channel=L or Channel=FL.

  • L or FL or 0
  • R or FR or 1
  • C or 2
  • LFE or Sub or 3
  • BL or 4
  • BR or 5
  • SL or 6
  • SR or 7
  • Sum or Avg
Type Required

Specifies the type of data to retrieve from the parent measure.

  • RMS : The current RMS level (0.0 to 1.0) corresponding to the specified Channel.
  • Peak : The current Peak level (0.0 to 1.0) corresponding to the specified Channel.
  • FFT : The current FFT level (0.0 to 1.0) corresponding to the specified FFTIdx option.
  • FFTFreq : The frequency in Hz corresponding to the specified FFTIdx option.
  • Band : The current FFT level (0.0 to 1.0) value corresponding to the specified BandIdx option.
  • BandFreq : The frequency in Hz corresponding to the specified BandIdx option.
  • Format : A string describing the audio format of the device connected to with the parent ID option.
  • DeviceStatus : Status (0 or 1) of the device connected to with the parent ID option.
  • DeviceName : A string with the name of the device connected to with the parent ID option.
  • DeviceID : A string with the Windows ID of the device connected to with the parent ID option.
  • DeviceList : A string with a list of all available device IDs for the specified Port This can be used to identify a desired device ID for use in the parent ID option.

Example: Type=RMS

FFTIdx Default: 0

Specifies which FFT point you want to extract from the parent. FFTSize must be enabled on the parent measure to use this option.

Valid values range from 0 to (FFTSize/2).

BandIdx Default: 0

Specifies which frequency band number, starting with 0, you want to extract from the parent. FFTSize and Bands must be enabled on the parent measure to use this option.

Valid values range from 0 to (Bands-1).

Examples

[Rainmeter]
Update=16
DynamicWindowSize=1
AccurateText=1

[MeasureAudio]
Measure=Plugin
Plugin=AudioLevel
Port=Output
RMSAttack=100
RMSDecay=300
RMSGain=2.5

[MeasureL]
Measure=Plugin
Plugin=AudioLevel
Parent=MeasureAudio
Channel=L
Type=RMS

[MeasureR]
Measure=Plugin
Plugin=AudioLevel
Parent=MeasureAudio
Channel=R
Type=RMS

[MeterBack]
Meter=Image
W=52
H=77
SolidColor=47,47,47,255
UpdateDivider=-1
LeftMouseUpAction=[Play "#@#Sounds\AudioTest.wav"]

[MeterL]
Meter=BitMap
MeasureName=MeasureL
X=5
Y=5
BitMapImage=#@#Images\LevelBitmap.png
BitMapFrames=15
BitmapZeroFrame=1

[MeterR]
Meter=BitMap
MeasureName=MeasureR
X=3R
Y=5
BitMapImage=#@#Images\LevelBitmap.png
BitMapFrames=15
BitmapZeroFrame=1

[MeterLText]
Meter=String
X=12
Y=1R
FontFace=Trebuchet MS
FontSize=8
FontColor=200,200,200,255
AntiAlias=1
Text=L
UpdateDivider=-1

[MeterRText]
Meter=String
X=35
Y=0r
FontFace=Trebuchet MS
FontSize=8
FontColor=200,200,200,255
AntiAlias=1
Text=R
UpdateDivider=-1

Simple Left/Right volume levels using RMS and Bitmap meters:

[Rainmeter]
Update=40
DynamicWindowSize=1
AccurateText=1

[MeasureAudio]
Measure=Plugin
Plugin=AudioLevel
Port=Output
FFTSize=1024
FFTAttack=15
FFTDecay=250
Bands=10

[MeasureBand0]
Measure=Plugin
Plugin=AudioLevel
Parent=MeasureAudio
Type=Band
BandIdx=0

[MeasureBand1]
Measure=Plugin
Plugin=AudioLevel
Parent=MeasureAudio
Type=Band
BandIdx=1

[MeasureBand2]
Measure=Plugin
Plugin=AudioLevel
Parent=MeasureAudio
Type=Band
BandIdx=2

[MeasureBand3]
Measure=Plugin
Plugin=AudioLevel
Parent=MeasureAudio
Type=Band
BandIdx=3

[MeasureBand4]
Measure=Plugin
Plugin=AudioLevel
Parent=MeasureAudio
Type=Band
BandIdx=4

[MeasureBand5]
Measure=Plugin
Plugin=AudioLevel
Parent=MeasureAudio
Type=Band
BandIdx=5

[MeasureBand6]
Measure=Plugin
Plugin=AudioLevel
Parent=MeasureAudio
Type=Band
BandIdx=6

[MeasureBand7]
Measure=Plugin
Plugin=AudioLevel
Parent=MeasureAudio
Type=Band
BandIdx=7

[MeasureBand8]
Measure=Plugin
Plugin=AudioLevel
Parent=MeasureAudio
Type=Band
BandIdx=8

[MeasureBand9]
Measure=Plugin
Plugin=AudioLevel
Parent=MeasureAudio
Type=Band
BandIdx=9

[MeterBackground]
Meter=Image
W=127
H=110
SolidColor=47,47,47,255

[MeterBand0]
Meter=Bar
MeasureName=MeasureBand0
X=5
Y=5
W=10
H=100
BarImage=#@#Images\SpecBar.jpg
SolidColor=100,100,100,255
BarOrientation=Vertical

[MeterBand1]
Meter=Bar
MeasureName=MeasureBand1
X=2R
Y=0r
W=10
H=100
BarImage=#@#Images\SpecBar.jpg
SolidColor=100,100,100,255
BarOrientation=Vertical

[MeterBand2]
Meter=Bar
MeasureName=MeasureBand2
X=2R
Y=0r
W=10
H=100
BarImage=#@#Images\SpecBar.jpg
SolidColor=100,100,100,255
BarOrientation=Vertical

[MeterBand3]
Meter=Bar
MeasureName=MeasureBand3
X=2R
Y=0r
W=10
H=100
BarImage=#@#Images\SpecBar.jpg
SolidColor=100,100,100,255
BarOrientation=Vertical

[MeterBand4]
Meter=Bar
MeasureName=MeasureBand4
X=2R
Y=0r
W=10
H=100
BarImage=#@#Images\SpecBar.jpg
SolidColor=100,100,100,255
BarOrientation=Vertical

[MeterBand5]
Meter=Bar
MeasureName=MeasureBand5
X=2R
Y=0r
W=10
H=100
BarImage=#@#Images\SpecBar.jpg
SolidColor=100,100,100,255
BarOrientation=Vertical

[MeterBand6]
Meter=Bar
MeasureName=MeasureBand6
X=2R
Y=0r
W=10
H=100
BarImage=#@#Images\SpecBar.jpg
SolidColor=100,100,100,255
BarOrientation=Vertical

[MeterBand7]
Meter=Bar
MeasureName=MeasureBand7
X=2R
Y=0r
W=10
H=100
BarImage=#@#Images\SpecBar.jpg
SolidColor=100,100,100,255
BarOrientation=Vertical

[MeterBand8]
Meter=Bar
MeasureName=MeasureBand8
X=2R
Y=0r
W=10
H=100
BarImage=#@#Images\SpecBar.jpg
SolidColor=100,100,100,255
BarOrientation=Vertical

[MeterBand9]
Meter=Bar
MeasureName=MeasureBand9
X=2R
Y=0r
W=10
H=100
BarImage=#@#Images\SpecBar.jpg
SolidColor=100,100,100,255
BarOrientation=Vertical

Simple spectrum visualization using FFT/Bands and Bar meters: