![Gem Version][gem version] [License: MIT][license] ![Ruby Code Style][code style]

Ruby Wrapper Around the Voicemeeter Remote API

This gem offers a Ruby interface for the Voicemeeter Remote API.

For an outline of past/future changes refer to: CHANGELOG

Tested against

  • Basic 1.1.1.1
  • Banana 2.1.1.1
  • Potato 3.1.1.1

Requirements

Installation

Bundler

bundle add voicemeeter
bundle install

Use

Simplest use case, request a Remote class of a kind, then pass a block to run.

Login and logout are handled for you in this scenario.

main.rb

require "voicemeeter"

class Main
  def run
    Voicemeeter::Remote.new(:banana).run do |vm|
      vm.strip[0].label = "podmic"
      vm.strip[0].mute = true
      puts "strip 0 #{vm.strip[0].label} mute was set to #{vm.strip[0].mute}"

      vm.bus[3].gain = -6.3
      vm.bus[4].eq.on = true
      info = [
        "bus 3 gain has been set to #{vm.bus[3].gain}",
        "bus 4 eq has been set to #{vm.bus[4].eq.on}"
      ]
      puts info
    end
  end
end

Main.new.run if $PROGRAM_NAME == __FILE__

Otherwise you must remember to call vm.login vm.logout at the start/end of your code.

KIND_ID

Pass the kind of Voicemeeter as an argument. KIND_ID may be:

  • :basic
  • :banana
  • :potato

Available commands

Strip

The following attributes are available.

  • mono: boolean
  • solo: boolean
  • mute: boolean
  • gain: float, from -60.0 to 12.0
  • audibility: float, from 0.0 to 10.0
  • limit: int, from -40 to 12
  • A1 - A5, B1 - B3: boolean
  • label: string
  • mc: boolean
  • karaoke: int, from 0 to 4
  • bass: float, from -12.0 to 12.0
  • mid: float, from -12.0 to 12.0
  • treble: float, from -12.0 to 12.0
  • reverb: float, from 0.0 to 10.0
  • delay: float, from 0.0 to 10.0
  • fx1: float, from 0.0 to 10.0
  • fx2: float, from 0.0 to 10.0
  • pan_x: float, from -0.5 to 0.5
  • pan_y: float, from 0.0 to 1.0
  • color_x: float, from -0.5 to 0.5
  • color_y: float, from 0.0 to 1.0
  • fx_x: float, from -0.5 to 0.5
  • fx_y: float, from 0.0 to 1.0
  • postreverb: boolean
  • postdelay: boolean
  • postfx1: boolean
  • postfx2: boolean

example:

vm.strip[3].gain = 3.7
puts vm.strip[0].label

The following methods are available.

  • appgain(name, value): string, float, from 0.0 to 1.0

Set the gain in db by value for the app matching name.

  • appmute(name, value): string, bool

Set mute state as value for the app matching name.

example:

vm.strip[5].appgain("Spotify", 0.5)
vm.strip[5].appmute("Spotify", true)

Comp

The following attributes are available.

  • knob: float, from 0.0 to 10.0
  • gainin: float, from -24.0 to 24.0
  • ratio: float, from 1.0 to 8.0
  • threshold: float, from -40.0 to -3.0
  • attack: float, from 0.0 to 200.0
  • release: float, from 0.0 to 5000.0
  • knee: float, from 0.0 to 1.0
  • gainout: float, from -24.0 to 24.0
  • makeup: boolean

example:

puts vm.strip[4].comp.knob

Strip Comp parameters are defined for PhysicalStrips.

knob defined for all versions, all other parameters potato only.

Gate

The following attributes are available.

  • knob: float, from 0.0 to 10.0
  • threshold: float, from -60.0 to -10.0
  • damping: float, from -60.0 to -10.0
  • bpsidechain: int, from 100 to 4000
  • attack: float, from 0.0 to 1000.0
  • hold: float, from 0.0 to 5000.0
  • release: float, from 0.0 to 5000.0

example:

vm.strip[2].gate.attack = 300.8

Strip Gate parameters are defined for PhysicalStrips.

knob defined for all versions, all other parameters potato only.

Denoiser

The following attributes are available.

  • knob: float, from 0.0 to 10.0

example:

vm.strip[0].denoiser.knob = 0.5

Strip Denoiser parameters are defined for PhysicalStrips, potato version only.

EQ

The following attributes are available.

  • on: boolean
  • ab: boolean

example:

vm.strip[0].eq.ab = true

Strip EQ parameters are defined for PhysicalStrips, potato version only.

Gainlayers
  • gain: float, from -60.0 to 12.0

example:

vm.strip[3].gainlayer[3].gain = 3.7

Gainlayers are defined for potato version only.

Levels

The following attributes are available.

  • prefader
  • postfader
  • postmute

example:

puts vm.strip[3].levels.prefader

Level properties will return -200.0 if no audio detected.

Bus

The following attributes are available.

  • mono: boolean
  • mute: boolean
  • sel: boolean
  • gain: float, from -60.0 to 12.0
  • label: string
  • returnreverb: float, from 0.0 to 10.0
  • returndelay: float, from 0.0 to 10.0
  • returnfx1: float, from 0.0 to 10.0
  • returnfx2: float, from 0.0 to 10.0
  • monitor: boolean

example:

vm.bus[3].gain = 3.7
puts vm.bus[0].label

vm.bus[4].mono = true
EQ

The following attributes are available.

  • on: boolean
  • ab: boolean

example:

vm.bus[4].eq.on = true
Modes

The following attributes are available.

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

The following methods are available.

  • get

example:

vm.bus[4].mode.amix = true
puts vm.bus[3].mode.get
Levels

The following attributes are available.

  • all

example:

puts vm.bus[0].levels.all

levels.all will return -200.0 if no audio detected.

Strip | Bus

The following 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.

example:

vm.strip[0].fadeto(-10.3, 1000)
vm.bus[3].fadeby(-5.6, 500)

Strip.Device | Bus.Device

The following attributes are available

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

example:

puts vm.strip[0].device.name
vm.bus[0].device.asio = "Audient USB Audio ASIO Driver"

strip|bus device parameters are defined for physical channels only.

name, sr are read only. wdm, ks, mme, asio are write only.

Macrobuttons

Three modes defined: state, stateonly and trigger.

  • state: boolean
  • stateonly: boolean
  • trigger: boolean

example:

vm.button[37].state = true
vm.button[55].trigger = false

Recorder

The following attributes accept boolean values.

  • loop: boolean
  • A1 - A5: boolean
  • B1 - A3: boolean

The following methods are available

  • play
  • stop
  • pause
  • record
  • ff
  • rew
  • load(filepath): string

example:

vm.recorder.play
vm.recorder.stop

# Enable loop play
vm.recorder.loop = true

# Disable recorder out channel B2
vm.recorder.B2 = false

# filepath as string
vm.recorder.load('C:\music\mytune.mp3')

VBAN

  • vm.vban.enable | vm.vban.disable Turn VBAN on or off
Instream | Outstream

The following attributes are available.

  • on: boolean
  • name: string
  • ip: string
  • port: int, range from 1024 to 65535
  • sr: int, (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

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.

example:

# turn VBAN on
vm.vban.enable

# turn on vban instream 0
vm.vban.instream[0].on = true

# set bit property for outstream 3 to 24
vm.vban.outstream[3].bit = 24

Command

Certain 'special' commands are defined by the API as performing actions rather than setting values. The following methods are available:

  • show : Bring Voiceemeter GUI to the front
  • hide : Hide Voicemeeter GUI
  • shutdown : Shuts down the GUI
  • restart : Restart the audio engine

The following attributes are write only and accept boolean values.

  • showvbanchat: boolean
  • lock: boolean

example:

vm.command.restart
vm.command.showvbanchat = true

Device

  • ins outs : Returns the number of input/output devices
  • input(i) output(i) : Returns a hash of device properties for device[i]

example:

vm.run { |vm| (0...vm.device.ins).each { puts vm.device.input(_1) } }

FX

Fx.Reverb | Fx.Delay

The following attributes are available:

  • on: boolean
  • ab: boolean

example:

vm.fx.reverb.on = true
vm.fx.delay.ab = true

Patch

The following attributes are available:

  • postfadercomposite: boolean
  • postfxinsert: boolean

example:

vm.patch.postfxinsert = false
asio[i]
  • get: int
  • set(patch_in): int, valid range determined by connected device.

example:

vm.patch.asio[3].set(4)

i, from 0 to 10

A2[i] - A5[i]
  • get: int
  • set(patch_out): int, valid range determined by connected device.

example:

vm.patch.A3[5].set(3)

i, from 0 to 8.

composite[i]
  • get: int
  • set(channel): int, from 0 up to number of channels depending on version.

example:

vm.patch.composite[7].set(4)

i, from 0 to 8.

insert[i]
  • on: boolean

example:

vm.patch.insert[18].on = true

i, from 0 up to number of channels depending on version.

Option

The following attributes are available:

  • sr: int
  • asiosr: boolean
  • monitoronsel: boolean
  • slidermode: boolean

example:

vm.option.sr = 48_000

Option.buffer

The following attributes are available:

  • mme: int
  • wdm: int
  • ks: int
  • asio: int

example:

vm.option.buffer.wdm = 512
delay[i]
  • get: int
  • set(delay): int, from 0 to 500

example:

vm.option.delay[4].set(30)

i, from 0 up to 4.

Midi

The following attributes are available:

  • channel: int, returns the midi channel
  • current: int, returns the current (or most recently pressed) key

The following methods are available:

  • get(key): int, returns most recent velocity value for a key

example:

puts vm.midi.get(12)

get may return nil if no value for requested key in midi cache

Multiple parameters

  • apply Set many strip/bus/macrobutton/vban parameters at once, for example:
vm.apply(
  {
    "strip-0" => {mute: true, gain: 3.2, A1: true},
    "bus-3" => {gain: -3.2, eq: {on: true}},
    "button-39" => {stateonly: true},
    "vban-outstream-3" => {on: true, bit: 24}
  }
)

Or for each class you may do:

vm.strip[0].apply(mute: true, gain: 3.2, A1: true)
vm.vban.outstream[0].apply(on: true, name: "streamname", bit: 24)

Config Files

vm.apply_config(<configname>)

You may load config files in YAML format. Three example configs have been included with the package. Remember to save current settings before loading a config. To set one you may do:

require "voicemeeter"
Voicemeeter::Remote.new(:banana).run { |vm| vm.apply_config(:example) }

will load a config file at mydir/configs/banana/example.yml for Voicemeeter Banana.

Events

By default, NO events listened for.

Use keyword args pdirty, mdirty, midi, ldirty to initialize event updates.

example:

require 'voicemeeter'
# Set updates to occur every 50ms
# Listen for level updates
Voicemeeter::Remote.new(:banana, ratelimit: 0.05, ldirty: true).run do
  ...

vm.on

Use the on method to register blocks on the vm object to be called back later.

example:

# register a block with the on method
class App():
    def initialize(vm)
        @vm = vm
        @vm.on :pdirty do
          ...
        end

vm.event

Use the event class to toggle updates as necessary.

The following attributes are available:

  • pdirty: boolean
  • mdirty: boolean
  • midi: boolean
  • ldirty: boolean

example:

vm.event.ldirty = true

vm.event.pdirty = false

Or add, remove an array of events.

The following methods are available:

  • add(events)
  • remove(events)
  • get

example:

vm.event.add(%i[pdirty mdirty midi ldirty])

vm.event.remove(%i[pdirty mdirty midi ldirty])

# get a list of currently subscribed
p vm.event.get

Voicemeeter Module

Voicemeeter::Remote

You may pass the following optional keyword arguments:

  • sync: boolean=false, force the getters to wait for dirty parameters to clear. For most cases leave this as false.
  • ratelimit: float=0.033, how often to check for updates in ms.
  • pdirty: boolean=true, parameter updates
  • mdirty: boolean=true, macrobutton updates
  • midi: boolean=true, midi updates
  • ldirty: boolean=false, level updates
  • bits: int=64, (may be one of 32 or 64), overrides the type of Voicemeeter GUI Remote.run_voicemeeter will launch.

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

  • vm.get(param, string=false): For getting the value of any parameter. Set string to true if getting a property value expected to return a string.
  • vm.set(param, value): For setting the value of any parameter.

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

  • vm.pdirty?: Returns true iff a parameter has been updated.
  • vm.mdirty?: Returns true iff a macrobutton has been updated.

example:

vm.get("Strip[2].Mute")
vm.set("Strip[4].Label", "stripname")
vm.set("Strip[0].Gain", -3.6)

Errors

  • Errors::VMError: Base Voicemeeter error class.
  • Errors::VMInstallError: Raised when errors occur during installation.
  • Errors::VMCAPIError: Raised when the C-API returns error codes.
    • The following attributes are available:
    • fn_name: name of the C-API function that failed.
    • code: error code.
    • For a full list of error codes check the [VoicemeeterRemote header file][voicemeeter remote header].

Logging

To enable logging set an environmental variable VM_LOG_LEVEL to the appropriate level.

example in powershell:

$env:VM_LOG_LEVEL="DEBUG"

Tests

To run all tests:

Bundle exec rake

Official Documentation

[license]: https://github.com/onyx-and-iris/voicemeeter-rb/blob/dev/LICENSE [voicemeeter remote header]: https://github.com/onyx-and-iris/Voicemeeter-SDK/blob/main/VoicemeeterRemote.h [code style]: https://img.shields.io/badge/code_style-standard-violet.svg [gem version]: https://badge.fury.io/rb/voicemeeter.svg