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