voicemeeter-api-powershell/README.md

Powershell Wrapper for Voicemeeter API

This module offers a Powershell interface for the Voicemeeter Remote C API.

For past/future changes to this project refer to: CHANGELOG

Tested against

• Basic 1.1.1.9
• Banana 2.1.1.9
• Potato 3.1.1.9

Requirements

• Voicemeeter
• Powershell 5.1+ or Powershell 7.2+

Installation

PowerShellGet:

In Powershell as admin:

Install-Module Voicemeeter

In Powershell as current user:

Install-Module -Name Voicemeeter -Scope CurrentUser

You may be asked to install NuGet provider required by PowerShellGet if you don't have it already.

When prompted you will need to accept PSGallery as a trusted repository.

More Info:

• PowerShellGet
• NuGet
• PSGallery

Direct download:

git clone https://github.com/onyx-and-iris/voicemeeter-api-powershell.git

All examples in this readme assume you've installed as a module. If you decide to direct download see alternative instructions.

Use

Script files

When you instantiate Remote class you will automatically be logged in. Use a try finally block to ensure you logout at the end of your code.

Import-Module Voicemeeter

try {
    # Run the factory function for required Voicemeeter type
    $vmr = Get-RemoteBanana

    # Set strip and bus params
    $vmr.strip[0].mono = $true
    $vmr.strip[0].mono  '=> $true'
    $vmr.bus[1].mute = $false
    $vmr.bus[1].mute    '=> $false'

    # Set macrobutton with id 4, mode state to 1
    $vmr.button[4].state = $true
    $vmr.button[4].state    '=> $true'
}
finally { $vmr.Logout() }

Voicemeeter factory function can be:

• Get-RemoteBasic
• Get-RemoteBanana
• Get-RemotePotato

Added in v3 you may also use the following entry/exit points:

• Connect-Voicemeeter
• Disconnect-Voicemeeter

Connect-Voicemeeter takes a single parameter Kind.

for example:

$vmr = Connect-Voicemeeter -Kind "potato"
...
Disconnect-Voicemeeter

Through the Shell

One liners should be run through a subshell, you may pipe the Remote object to a script block, for example:

powershell { Get-RemoteBanana | % { $_.strip[0].mute=$true; $_.Logout() } }

You may also save the object returned by a factory function to a local variable, then invoke any commands through the shell, for example:

$vmr = Get-RemoteBanana
$vmr.strip[0].mute=1
$vmr.strip[0].mute
$vmr.Logout()

Strip

The following Strip properties are available:

• mute: bool
• mono: bool
• mc: bool
• k/karaoke: int, from 0 to 4
• solo: bool
• A1-A5: bool
• B1-B3: bool
• vaio: bool
• limit: float, from -40.00 to 12.00
• gain: float, from -60.00 to 12.00
• label: string
• reverb: float, from 0.00 to 10.00
• delay: float, from 0.00 to 10.00
• fx1: float, from 0.00 to 10.00
• fx2: float, from 0.00 to 10.00
• pan_x: float, from -0.50 to 0.50
• pan_y: float, physical: from 0.00 to 1.00, virtual: from -0.50 to 0.50
• color_x: float, from -0.50 to 0.50
• color_y: float, from 0.00 to 1.00
• fx_x: float, from -0.50 to 0.50
• fx_y: float, from 0.00 to 1.00
• postreverb: bool
• postdelay: bool
• postfx1: bool
• postfx2: bool
• eqgain1/bass/low: float, from -12.00 to 12.00
• eqgain2/mid/med: float, from -12.00 to 12.00
• eqgain3/treble/high: float, from -12.00 to 12.00

for example:

$vmr.strip[6].karaoke = 3
$vmr.strip[0].limit = 4.5
$vmr.strip[2].label = 'example'
$vmr.strip[7].pan_y = -0.38
$vmr.strip[5].treble = -2.43

The following Strip methods are available:

• AppGain($appname or $appindex, $gain) : string or int, float, from 0.00 to 1.00
• AppMute($appname or $appindex, $mutestate) : string or int, bool

for example:

$vmr.strip[5].AppGain("Spotify", 0.5)
$vmr.strip[5].AppMute("Spotify", $true)
$vmr.strip[7].AppGain(0, 0.28)
$vmr.strip[6].AppMute(2, $false)

A,B properties depend on Voicemeeter type. mc, k for virtual strips only.

comp

The following Strip.comp properties are available:

• knob: float, from 0.00 to 10.00
• gainin: float, from -24.00 to 24.00
• ratio: float, from 1.00 to 8.00
• threshold: float, from -40.00 to -3.00
• attack: float, from 0.00 to 200.00
• release: float, from 0.00 to 5000.00
• knee: float, 0.00 to 1.00
• gainout: float, from -24.00 to 24.00
• makeup: bool

for example:

$vmr.strip[3].comp.attack = 8.5

gate

The following Strip.gate properties are available:

• knob: float, from 0.00 to 10.00
• threshold: float, from -60.00 to -10.00
• damping: float, from -60.00 to -10.00
• bpsidechain: float, from 100.00 to 4000.00
• attack: float, from 0.00 to 1000.00
• hold: float, from 0.00 to 5000.00
• release: float, from 0.00 to 5000.00

for example:

$vmr.strip[3].gate.threshold = -40.5

denoiser

The following Strip.denoiser properties are available:

• knob: float, from 0.00 to 10.00
• threshold: float, from 0.00 to 10.00

for example:

$vmr.strip[3].denoiser.knob = 5

pitch

The following Strip.pitch properties are available:

• on: bool
• drywet: float, from -100.00 to 100.00
• pitchvalue: float, from -12.00 to 12.00
• loformant: float, from -12.00 to 12.00
• medformant: float, from -12.00 to 12.00
• hiformant: float, from -12.00 to 12.00

The following Strip.pitch methods are available:

• RecallPreset($presetIndex) : int, from 0 to 7

for example:

$vmr.strip[2].pitch.recallpreset(4)
$vmr.strip[4].pitch.drywet = -22.86
$vmr.strip[1].pitch.medformant = 2.1

audibility

The following Strip.audibility properties are available:

• knob: float, from 0.00 to 10.00

for example:

$vmr.strip[1].audibility.knob = 2.66

gainlayer[i]

The following Strip.gainlayer[i] methods are available:

• Set($val) : float, from -60.00 to 12.00
• Get()

for example:

$vmr.strip[4].gainlayer[7].set(-26.81)

levels

The following Strip.levels methods are available:

• PreFader()
• PostFader()
• PostMute()

for example:

$vmr.strip[2].levels.PreFader() -Join ', ' | Write-Host

Bus

The following Bus properties are available:

• mute: bool
• sel: bool
• monitor: bool
• vaio: bool
• mono: int, 0 off, 1 mono, 2 stereo reverse
• gain: float, from -60.00 to 12.00
• label: string
• returnreverb: float, from 0.00 to 10.00
• returndelay: float, from 0.00 to 10.00
• returnfx1: float, from 0.00 to 10.00
• returnfx2: float, from 0.00 to 10.00

for example:

$vmr.bus[3].returnreverb = 5.7

modes

The following Bus.mode members are available:

• normal: bool
• amix: bool
• bmix: bool
• repeat: bool
• composite: bool
• tvmix: bool
• upmix21: bool
• upmix41: bool
• upmix61: bool
• centeronly: bool
• lfeonly: bool
• rearonly: bool

The following Bus.mode methods are available:

• Set($mode) : string, sets the current bus mode
• Get() : returns the current bus mode

for example:

$vmr.bus[0].mode.centeronly = $true
$vmr.bus[0].mode.Set('tvmix')

levels

The following Bus.levels methods are available:

• All()

for example:

$vmr.bus[2].levels.All() -Join ', ' | Write-Host

Strip|Bus

The following Strip | Bus methods are available:

• FadeTo(amount, time) : float, int
• FadeBy(amount, time) : float, int

Modify gain to or by the selected amount in db over a time interval in ms.

for example:

$vmr.strip[3].FadeTo(-18.75, 1000)
$vmr.bus[0].FadeBy(-10, 500)

device

The following Strip.device | Bus.device properties are available:

• name: string
• sr: int
• wdm: string
• ks: string
• mme: string
• asio: string

for example:

$vmr.strip[0].device.wdm = "Mic|Line|Instrument 1 (Audient EVO4)"
$vmr.bus[0].device.name | Write-Host

name, sr are defined as read only. wdm, ks, mme, asio are defined as write only. asio only defined for Bus[0].Device

eq

The following Strip.eq | Bus.eq properties are available:

• on: bool
• ab: bool

The following Strip.eq | Bus.eq methods are available:

• Load($filepath) : string
• Save($filepath) : string

for example:

$vmr.strip[0].eq.on = $true
$vmr.bus[0].eq.ab = $false

channel.cell

The following eq.channel.cell properties are available:

• on: bool
• type: int, from 0 to 6
• f: float, from 20.00 to 20000.00
• gain: float, from -12.00 to 12.00
• q: float, from 0.30 to 100.00

for example:

$vmr.strip[2].eq.channel[1].cell[4].type = 1
$vmr.bus[5].eq.channel[6].cell[3].on = $false

Macrobuttons

The following Button properties are available:

• state: bool, runs associated scripts
• stateonly: bool, does not run associated scripts
• trigger: bool

$vmr.button[3].state = $true
$vmr.button[4].stateonly = $false
$vmr.button[5].trigger = $true

Index range (0, 79)

VBAN

The following Vban properties are available:

• enable: bool
• port: int, from 1024 - 65535

for example:

$vmr.vban.enable = $true
$vmr.vban.port = 6990

instream[i]|outstream[i]

The following Vban.instream | Vban.outstream properties are available:

• on: bool
• name: string
• ip: string
• sr: in, (11025, 16000, 22050, 24000, 32000, 44100, 48000, 64000, 88200, 96000)
• channel: int from 1 to 8
• bit: int, 16 or 24
• quality: int, from 0 to 4
• route: int, from 0 to 8

for example:

$vmr.vban.instream[0].on = $true
$vmr.vban.outstream[3].bit = 16

SR, channel and bit are defined as readonly for instreams. Attempting to write to those parameters will throw an error. They are read and write for outstreams.

Command

Certain 'special' commands are defined by the API as performing actions rather than setting values.

The following Command methods are available:

• Show()
• Hide()
• Lock()
• Unlock()
• ShowVBANChat()
• HideVBANChat()
• Restart()
• Shutdown()
• Reset() : Reset all config
• Save($filepath) : string
• Load($filepath) : string
• StorePreset($index, $name) : (int, string)
• RecallPreset($index or $name) : (int or string)
• RunMacrobuttons() : Launches the macrobuttons app
• CloseMacrobuttons() : Closes the macrobuttons app

for example:

$vmr.command.Show()
$vmr.command.Lock()
$vmr.command.Load("path/to/filename.xml")
$vmr.command.RunMacrobuttons()

$vmr.command.StorePreset(63, 'example')
$vmr.command.StorePreset('example')
$vmr.command.StorePreset(63)                # same as StorePreset(63, '')
$vmr.command.StorePreset()                  # same as StorePreset(''), overwrites last recalled

$vmr.command.RecallPreset('example')
$vmr.command.RecallPreset(63)
$vmr.command.RecallPreset()                 # same as RecallPreset(''), recalls last recalled

StorePreset('') and RecallPreset('') interact with the 'selected' preset. This is highlighted green in the GUI. Recalling a preset selects it. Storing a preset via GUI also selects it. Storing a preset with StorePreset does not select it.

Fx

The following Fx properties are available:

• Reverb.on: bool
• Reverb.ab: bool
• Delay.on: bool
• Delay.ab: bool

for example:

$vmr.fx.reverb.ab = $false

Patch

The following Patch properties are available:

• postFaderComposite: bool
• postFxInsert: bool

The following Patch members have methods Set($val) | Get() available:

• asio[i]: int, from 0 to ASIO input channels
• OutA2[i]-OutA5[i]: int, from 0 to ASIO output channels
• composite[i]: int, from 0 to strip channels
• insert[i]: bool

for example:

$vmr.patch.asio[3].set(2)        # patches ASIO input channel 2 (2) to strip 2, channel 2 (3)
$vmr.patch.OutA3[0].set(24)      # patches bus A3, channel 1 (0) to ASIO output channel 24
$vmr.patch.composite[5].set(0)   # sets composite channel 6 (5) to default bus channel
$vmr.patch.insert[4].get()

Option

The following Option properties are available:

• sr: int, (32000, 44100, 48000, 88200, 96000, 176400, 192000)
• asiosr: bool
• monitorOnSel: bool
• sliderMode: bool
• monitoringBus: int, from 0 to bus index

for example:

$vmr.Option.sliderMode = $false   # sets slider mode to absolute

buffers

The following Option.buffer properties are available:

• mme: int, (441, 480, 512, 576, 640, 704, 768, 896, 1024, 1536, 2048)
• wdm: int, (128, 160, 192, 224, 256, 288, 320, 352, 384, 416, 441, 448, 480, 512, 576, 640, 704, 768, 1024, 1536, 2048)
• ks: int, (128, 160, 192, 224, 256, 288, 320, 352, 384, 416, 441, 448, 480, 512, 576, 640, 704, 768, 1024, 1536, 2048)
• asio: int, (0, 64, 96, 128, 160, 192, 224, 256, 288, 320, 352, 384, 416, 441, 448, 480, 512, 576, 640, 704, 768, 1024)

for example:

$vmr.Option.buffer.wdm = 512
$vmr.Option.buffer.asio = 0    # to use default buffer size

delay[i]

The following Option.delay[i] methods are available:

• Set($val) : float, from 0.00 to 500.00
• Get()

for example:

$vmr.Option.delay[2].set(30.26)   # sets the delay for the third (2) bus

Recorder

The following Recorder properties are available:

• A1 - A5: bool
• B1 - B3: bool
• gain: float, from -60.00 to 12.00
• armedbus: int, from 0 to bus index
• state: string, ('play', 'stop', 'record', 'pause')
• prerectime: int, from 0 to 20 seconds
• prefix: string, write-only
• filetype: string, write-only, ('wav', 'aiff', 'bwf', 'mp3')
• samplerate: int, (22050, 24000, 32000, 44100, 48000, 88200, 96000, 176400, 192000)
• bitresolution: int, (8, 16, 24, 32)
• channel: int, (2, 4, 6, 8)
• kbps: int, (32, 40, 48, 56, 64, 80, 96, 112, 128, 160, 192, 224, 256, 320)

for example:

$vmr.recorder.A1 = $true
$vmr.recorder.filetype = 'mp3'
$vmr.recorder.kbps = 256

The following Recorder methods are available:

• Play()
• Stop()
• Replay()
• FF()
• Rew()
• Record()
• Pause()
• Eject()
• Load($filepath) : string
• GoTo($timestring) : string, must match the format 'hh:mm:ss'

for example:

$vmr.recorder.play()
$vmr.recorder.GoTo("00:01:15")  # go to 1min 15sec into track

mode

The following Recorder.mode properties are available:

• recbus: bool
• playonload: bool
• loop: bool
• multitrack: bool

for example:

$vmr.recorder.mode.loop = $true

armstrip[i]|armbus[i]

The following Recorder.armstrip | Recorder.armbus methods are available:

• Set($val) : bool
• Get()

for example:

$vmr.recorder.armstrip[0].Set($true)

Multiple parameters

Set many strip/bus/macrobutton/vban parameters at once, for Example

Import-Module Voicemeeter

try {
    $vmr = Get-RemoteBanana

    $hash = @{
        strip_0 = @{mute = $true; mono = $true};
        strip_2 = @{mute = $true; mono = $true};
        bus_1 = @{mute = $true; mono = $true};

        button_34 = @{state = $true};
        button_12 = @{trigger = $false};

        vban_instream_3 = @{name = 'streamname'};
        vban_outstream_0 = @{on = $false};
    }

    $vmr.Set_Multi($hash)
}
finally { $vmr.Logout() }

Config Files

$vmr.Set_Profile(<configname>)

You may load config files in psd1 format. An example profile has been included with the package. Remember to save current settings before loading a profile. To test simply rename _profiles directory to profiles. It will be loaded into memory but not set. To set one you may do:

Import-Module Voicemeeter
try {
    $vmr = Get-RemoteBanana
    $vmr.Set_Profile("config")
}
finally { $vmr.Logout() }

will load a config file at profiles/banana/config.psd1 for Voicemeeter Banana.

Remote class

Access to lower level Getters and Setters are provided with these functions:

• $vmr.Getter(param): For getting the value of a parameter expected to return a value other than string.
• $vmr.Getter_String(param): For getting the value of any parameter expected to return a string.
• $vmr.Setter(param, value): For setting the value of any parameter.

$vmr.Getter('Strip[2].Mute')
$vmr.Getter_String('Bus[1].Label')
$vmr.Setter('Strip[4].Label', 'stripname')
$vmr.Setter('Strip[0].Gain', -3.6)

• $vmr.SendText: Set parameters by script

 $vmr.SendText("strip[0].mute=1;strip[2].gain=3.8;bus[1].eq.On=1")

Access to lower level polling functions are provided with these functions:

• $vmr.PDirty: Returns true if a parameter has been updated.
• $vmr.MDirty: Returns true if a macrobutton has been updated.

Errors

• VMRemoteError: Base custom error class.
• LoginError: Raised when a login error occurs.
• CAPIError: Raised when a C-API function returns an error code.
  • The following class properties are available:
    • function: The name of the C-API function that returned the error code.
    • code: The error code.

Run tests

Parameters:

• kind: Run tests of this kind
• tag: Run tests tagged with this marker (currently higher or lower)

with Task

task test -- -t "higher" -k "banana"

Official Documentation

• Voicemeeter Remote C API