voicemeeter_api_ruby 2.0.3 → 4.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
data/README.md ADDED
@@ -0,0 +1,413 @@
1
+ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/onyx-and-iris/voicemeeter-api-ruby/blob/dev/LICENSE)
2
+ [![code style: prettier](https://img.shields.io/badge/code_style-prettier-ff69b4.svg?style=flat-square)](https://github.com/prettier/plugin-ruby)
3
+ ![tests: failed count](https://img.shields.io/badge/dynamic/json?color=blue&label=tests&query=summary.failure_count&suffix=%20failed&url=https%3A%2F%2Fraw.githubusercontent.com%2Fonyx-and-iris%2Fvoicemeeter-api-ruby%2Fdev%2Fspec%2Frspec.json)
4
+ [![Gem Version](https://badge.fury.io/rb/voicemeeter_api_ruby.svg)](https://badge.fury.io/rb/voicemeeter_api_ruby)
5
+ ![](https://ruby-gem-downloads-badge.herokuapp.com/voicemeeter_api_ruby?type=total&color=red)
6
+
7
+ # Ruby Wrapper for Voicemeeter API
8
+
9
+ This gem offers a Ruby interface for the Voicemeeter Remote C API.
10
+
11
+ For an outline of past/future changes refer to: [CHANGELOG](CHANGELOG.md)
12
+
13
+ ## Tested against
14
+
15
+ - Basic 1.0.8.2
16
+ - Banana 2.0.6.2
17
+ - Potato 3.0.2.2
18
+
19
+ ## Requirements
20
+
21
+ - [Voicemeeter](https://voicemeeter.com/)
22
+ - Ruby 3.0 or greater
23
+
24
+ ## Installation
25
+
26
+ ### Gem
27
+
28
+ Install voicemeeter_api_ruby gem from your console
29
+
30
+ `gem 'voicemeeter_api_ruby'`
31
+
32
+ ### Bundler
33
+
34
+ Put this in your Gemfile:
35
+
36
+ `gem 'voicemeeter_api_ruby'`
37
+
38
+ or use bundlers built in git functionality:
39
+
40
+ `gem "voicemeeter_api_ruby", :git => "git://github.com/onyx-and-iris/voicemeeter-api-ruby"`
41
+
42
+ ## `Use`
43
+
44
+ Simplest use case, request a Remote class of a kind, then pass a block to run.
45
+
46
+ Login and logout are handled for you in this scenario.
47
+
48
+ #### `main.rb`
49
+
50
+ ```ruby
51
+ require 'voicemeeter'
52
+
53
+ kind_id = 'banana'
54
+
55
+ # start Voicemeeter GUI
56
+ Voicemeeter.start(kind_id)
57
+
58
+ vm = Voicemeeter.remote(kind_id)
59
+
60
+ # vm.run accepts a block
61
+ vm.run do
62
+ # mute the leftmost strip
63
+ vm.strip[0].mute = true
64
+ puts vm.strip[0].mute
65
+
66
+ # disable eq for second from left bus
67
+ vm.bus[1].eq = false
68
+ puts vm.bus[1].eq
69
+ end
70
+ ```
71
+
72
+ Otherwise you must remember to call `vm.login` `vm.logout` at the start/end of your code.
73
+
74
+ ## `kind_id`
75
+
76
+ Pass the kind of Voicemeeter as an argument. kind_id may be:
77
+
78
+ - `basic`
79
+ - `banana`
80
+ - `potato`
81
+
82
+ ## `Available commands`
83
+
84
+ ### Strip
85
+
86
+ The following properties are available.
87
+
88
+ - `mono`: boolean
89
+ - `solo`: boolean
90
+ - `mute`: boolean
91
+ - `gain`: float, from -60.0 to 12.0
92
+ - `comp`: float, from 0.0 to 10.0
93
+ - `gate`: float, from 0.0 to 10.0
94
+ - `audibility`: float, from 0.0 to 10.0
95
+ - `limit`: int, from -40 to 12
96
+ - `A1 - A5`, `B1 - B3`: boolean
97
+ - `label`: string
98
+ - `device`: string
99
+ - `sr`: int
100
+ - `mc`: boolean
101
+ - `k`: int, from 0 to 4
102
+ - `bass`: float, from -12.0 to 12.0
103
+ - `mid`: float, from -12.0 to 12.0
104
+ - `treble`: float, from -12.0 to 12.0
105
+
106
+ example:
107
+
108
+ ```ruby
109
+ vm.strip[3].gain = 3.7
110
+ puts vm.strip[0].label
111
+ ```
112
+
113
+ The following methods are Available.
114
+
115
+ - `appgain(name, value)`: string, float, from 0.0 to 1.0
116
+
117
+ Set the gain in db by value for the app matching name.
118
+
119
+ - `appmute(name, value)`: string, bool
120
+
121
+ Set mute state as value for the app matching name.
122
+
123
+ example:
124
+
125
+ ```ruby
126
+ vm.strip[5].appmute('Spotify', true)
127
+ vm.strip[5].appgain('Spotify', 0.5)
128
+ ```
129
+
130
+ ##### Gainlayers
131
+
132
+ - `gain`: float, from -60.0 to 12.0
133
+
134
+ example:
135
+
136
+ ```ruby
137
+ vm.strip[3].gainlayer[3].gain = 3.7
138
+ ```
139
+
140
+ Gainlayers are defined for potato version only.
141
+
142
+ ### Bus
143
+
144
+ The following properties are available.
145
+
146
+ - `mono`: boolean
147
+ - `mute`: boolean
148
+ - `eq`: boolean
149
+ - `eq_ab`: boolean
150
+ - `sel`: boolean
151
+ - `gain`: float, from -60.0 to 12.0
152
+ - `label`: string
153
+ - `device`: string
154
+ - `sr`: int
155
+
156
+ example:
157
+
158
+ ```ruby
159
+ vm.bus[3].gain = 3.7
160
+ puts vm.bus[0].label
161
+
162
+ vm.bus[4].mono = true
163
+ ```
164
+
165
+ ##### Modes
166
+
167
+ - `normal`: boolean
168
+ - `amix`: boolean
169
+ - `bmix`: boolean
170
+ - `composite`: boolean
171
+ - `tvmix`: boolean
172
+ - `upmix21`: boolean
173
+ - `upmix41`: boolean
174
+ - `upmix61`: boolean
175
+ - `centeronly`: boolean
176
+ - `lfeonly`: boolean
177
+ - `rearonly`: boolean
178
+
179
+ example:
180
+
181
+ ```ruby
182
+ vm.bus[4].mode.amix = true
183
+ ```
184
+
185
+ ### Strip | Bus
186
+
187
+ The following methods are Available
188
+
189
+ - `fadeto(amount, time)`: float, int
190
+ - `fadeby(amount, time)`: float, int
191
+
192
+ Modify gain to or by the selected amount in db over a time interval in ms.
193
+
194
+ example:
195
+
196
+ ```ruby
197
+ vm.strip[0].fadeto(-10.3, 1000)
198
+ vm.bus[3].fadeby(-5.6, 500)
199
+ ```
200
+
201
+ ### Macrobuttons
202
+
203
+ Three modes defined: state, stateonly and trigger.
204
+
205
+ - `state`: boolean
206
+ - `stateonly`: boolean
207
+ - `trigger`: boolean
208
+
209
+ example:
210
+
211
+ ```ruby
212
+ vm.button[37].state = true
213
+ vm.button[55].trigger = false
214
+ ```
215
+
216
+ ### Recorder
217
+
218
+ The following properties accept boolean values.
219
+
220
+ - `loop`: boolean
221
+ - `A1 - A5`: boolean
222
+ - `B1 - A3`: boolean
223
+
224
+ The following methods are Available
225
+
226
+ - `play`
227
+ - `stop`
228
+ - `pause`
229
+ - `record`
230
+ - `ff`
231
+ - `rew`
232
+ - `load(filepath)`: string
233
+
234
+ example:
235
+
236
+ ```ruby
237
+ vm.recorder.play
238
+ vm.recorder.stop
239
+
240
+ # Enable loop play
241
+ vm.recorder.loop = True
242
+
243
+ # Disable recorder out channel B2
244
+ vm.recorder.B2 = False
245
+
246
+ # filepath as string
247
+ vm.recorder.load('C:\music\mytune.mp3')
248
+ ```
249
+
250
+ ### VBAN
251
+
252
+ - `vm.vban.enable` `vm.vban.disable` Turn VBAN on or off
253
+
254
+ ##### Instream | Outstream
255
+
256
+ The following properties are available.
257
+
258
+ - `on`: boolean
259
+ - `name`: string
260
+ - `ip`: string
261
+ - `port`: int, range from 1024 to 65535
262
+ - `sr`: int, (11025, 16000, 22050, 24000, 32000, 44100, 48000, 64000, 88200, 96000)
263
+ - `channel`: int, from 1 to 8
264
+ - `bit`: int, 16 or 24
265
+ - `quality`: int, from 0 to 4
266
+ - `route`: int, from 0 to 8
267
+
268
+ 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.
269
+
270
+ example:
271
+
272
+ ```ruby
273
+ # turn VBAN on
274
+ vm.vban.enable
275
+
276
+ # turn on vban instream 0
277
+ vm.vban.instream[0].on = True
278
+
279
+ # set bit property for outstream 3 to 24
280
+ vm.vban.outstream[3].bit = 24
281
+ ```
282
+
283
+ ### Command
284
+
285
+ Certain 'special' commands are defined by the API as performing actions rather than setting values. The following methods are available:
286
+
287
+ - `show` : Bring Voiceemeter GUI to the front
288
+ - `shutdown` : Shuts down the GUI
289
+ - `restart` : Restart the audio engine
290
+
291
+ The following properties are write only and accept boolean values.
292
+
293
+ - `showvbanchat`: boolean
294
+ - `lock`: boolean
295
+
296
+ example:
297
+
298
+ ```ruby
299
+ vm.command.restart
300
+ vm.command.showvbanchat = true
301
+ ```
302
+
303
+ ### Device
304
+
305
+ - `ins` `outs` : Returns the number of input/output devices
306
+ - `input(i)` `output(i)` : Returns a hash of device properties for device[i]
307
+
308
+ example:
309
+
310
+ ```ruby
311
+ vm.run { (0...vm.device.ins).each { |i| puts vm.device.input(i) } }
312
+ ```
313
+
314
+ ### Multiple parameters
315
+
316
+ - `set_multi`
317
+ Set many strip/bus/macrobutton/vban parameters at once, for example:
318
+
319
+ ```ruby
320
+ vm.set_multi(
321
+ {
322
+ strip_0: {
323
+ mute: true,
324
+ gain: 3.2,
325
+ A1: true,
326
+ },
327
+ bus_3: {
328
+ gain: -3.2,
329
+ eq: true,
330
+ },
331
+ button_39: {
332
+ stateonly: true,
333
+ },
334
+ vban_outstream_3: {
335
+ on: true,
336
+ bit: 24,
337
+ },
338
+ },
339
+ )
340
+ ```
341
+
342
+ Or for each class you may do:
343
+
344
+ ```ruby
345
+ vm.strip[0].set_multi(mute: true, gain: 3.2, A1: true)
346
+ vm.vban.outstream[0].set_multi(on: true, name: 'streamname', bit: 24)
347
+ ```
348
+
349
+ ## Config Files
350
+
351
+ `vm.set_config(<configname>)`
352
+
353
+ You may load config files in TOML format.
354
+ Three example configs have been included with the package. Remember to save
355
+ current settings before loading a config. To set one you may do:
356
+
357
+ ```ruby
358
+ require 'voicemeeter'
359
+ vm = Voicemeeter.remote('banana')
360
+ vm.run { vm.set_profile('example') }
361
+ ```
362
+
363
+ will load a config file at configs/banana/example.toml for Voicemeeter Banana.
364
+
365
+ ## `Voicemeeter Module`
366
+
367
+ ### Remote class
368
+
369
+ Access to lower level Getters and Setters are provided with these functions:
370
+
371
+ - `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.
372
+ - `vm.set(param, value)`: For setting the value of any parameter.
373
+
374
+ Access to lower level polling functions are provided with these functions:
375
+
376
+ - `vm.pdirty?`: Returns true if a parameter has been updated.
377
+ - `vm.mdirty?`: Returns true if a macrobutton has been updated.
378
+
379
+ example:
380
+
381
+ ```ruby
382
+ vm.get('Strip[2].Mute')
383
+ vm.set('Strip[4].Label', 'stripname')
384
+ vm.set('Strip[0].Gain', -3.6)
385
+ ```
386
+
387
+ #### Voicemeeter::start
388
+
389
+ Use this function to start Voicemeeter of a kind independently of Remote class.
390
+ for example:
391
+
392
+ ```ruby
393
+ require 'voicemeeter'
394
+ Voicemeeter.start('banana')
395
+ ```
396
+
397
+ ### Run tests
398
+
399
+ To run all tests:
400
+
401
+ ```
402
+ Bundle exec rspec
403
+ ```
404
+
405
+ You can use tags to run only certain tests, for example:
406
+
407
+ ```
408
+ Bundle exec rspec --tag 'higher'
409
+ ```
410
+
411
+ ### Official Documentation
412
+
413
+ - [Voicemeeter Remote C API](https://github.com/onyx-and-iris/Voicemeeter-SDK/blob/main/VoicemeeterRemoteAPI.pdf)