voicemeeter_api_ruby 2.0.4 → 3.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: feb89f841882b2ece4f1bc959c8a5a728a738b054798635d2937ff9dceacf37c
-  data.tar.gz: 382ba6af1cde36e8b450d0549e383f9e6c68040d8385923ec8b2c413ddfc3d1b
+  metadata.gz: 74364d7c7210a1b080f7903862f4a1811105a3b7cb69fb572cbc729325e577ca
+  data.tar.gz: 87289218250b0177ed6064777edf199f02d40c69d84458185d6cff5f798d2fe0
 SHA512:
-  metadata.gz: 719e6d87cf5514dc7d759bdf15bf75ae32a533686894c172e4c1d4151dc2b7c480e8967a0d0d41a4187a0df2ff7f4094a3bc9520f86cf7f75c0604f00b711b7e
-  data.tar.gz: 728b8458b2897592282c24b944a0d1a3dca0af14791c0c3c73a1d1eb474a9462f4f24eecd5aa3caad2fec024f111998dedac8e057b5d092f727a763feda6ab5e
+  metadata.gz: be94880faab9294919932abc5b1dc61177798f60deb2847c7672e6be0e7ca6dcc770e0a70983ab003ca098d8b08705b397ca3db3062b0756534dc881e5ed5725
+  data.tar.gz: 46f0cc75b33f53a4b35ac4f72064ac75f88dca55437b8c5727ae44c615bc0207546c9af8b9d83846750b777e186dc364008033b19c6688dfc55743ed73da2f9d

data/CHANGELOG.md

@@ -0,0 +1,271 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+Before any major/minor/patch is released all test units will be run to verify they pass.
+
+## [Unreleased] - These changes have not been added to RubyGems yet
+
+-   [ ] Update Readme for version 3 changes.
+
+## [3.0.0] - 2022-01-24
+
+### Added
+
+-   Added strip_levels, bus_levels to base class. They return the entire level array (before math conversion).
+-   Added fadeto, fadeby methods for strips/buses.
+-   Added appgain, appmute methods to Virtualstrip class
+-   Bus modes added to bus class.
+-   Gainlayers added to strip class.
+-   Added pre-commit.ps1 for git hook
+-   cdll proc object added to base class. This is now used to call a c dll function.
+-   hide method added to command class
+
+### Changed
+
+-   Kinds, Profiles moved into their own modules.
+-   Kind maps now defined as structs.
+-   Randomised unit tests. A single run may test any kind.
+-   Polling paramters now defined as single line endless functions
+-   Major version bump due to backwards incompatible changes. Ruby required version changed.
+
+### Fixed
+
+-   Minor delay added before logout, allow a final operation to complete.
+-   Polling function sped up, sync kwarg added.
+
+### Removed
+
+-   Removed bounds checking for certain strip/bus properties.
+
+## [2.0.4] - 2022-01-24
+
+### Added
+
+-   Ability to load config files in TOML format
+-   Add option to pass keyword arguments to Remote class.
+-   Voicemeeter.start added for starting voicemeeter independently of Remote class
+
+### Changed
+
+-   Use of VBVMR_RunVoicemeeter instead of open3 when starting voicemeeter.
+-   Functions in low level modules set to private.
+-   version 2.0.4 added to RubyGems.
+
+### Fixed
+
+-   Fix timing issue affecting macrobutton multi_set
+
+## [2.0.3] - 2022-01-20
+
+### Added
+
+-   runmany.ps1 added. easy access to many test runs with logging and summary file.
+-   link to official documentation in readme.
+-   section regarding lower level functions, setters, getters and polling functions added to readme.
+
+### Changed
+
+-   Adjustment to polling function, now accepts getter logic as a block. Param caching
+    now done in polling function
+-   Small delay added to setters, except for set_parameter_multi function.
+-   Added initialize to Remote class, building of class objects done now done in Remote.
+-   version 2.0.3 added to RubyGems.
+
+### Fixed
+
+-   Fixed an issue with the action type property meta function in Command class.
+-   Added ensure logout if block passed to run, will logout regardless of exception raised.
+
+## [2.0.2] - 2022-01-18
+
+### IMPORTANT
+
+The code for this wrapper has been revised and reworked from the ground up. Earlier versions
+are still available for download on RubyGems.org but that version will not be updated further.
+Most of the updates documented here do not apply to version 2.0 onwards but will be kept for
+reference use only.
+
+All of the core features including strip, bus, macrobutton, recorder, vban and command classes
+work exactly the same. An effort has been made to include every property previously available,
+for each of those classes.
+
+README is up to date with version 2.0.2 onwards.
+
+### Added
+
+-   Special command lock added
+-   showvbanchat chat is now a boolean function.
+-   Functions vmr.vban.enable and vmr.vban.disable for toggling VBAN now added.
+
+### Changed
+
+-   Each class for each of the core features has been put into its own module. Classes such as
+    strip, bus and vban are now subclassed into physical/virtual and instream/outstream respectively.
+-   Error classes have been simplified into a smaller number of classes.
+-   remote class is now callable through Voicemeeter module. It is also now a factory function that
+    returns a Remote class for the kind of Voicemeeter specified by the user.
+-   Rake tests now simplified and reduced. They are now organised into higher and lower tests.
+
+### Fixed
+
+-   Writer validation logic has been moved into meta module. There is a base module for generic
+    meta functions but where appropriate this is mixed in with a submodule.
+-   set_multi function for setting many parameters at once now uses tokens for hash keys.
+-   Polling dirty parameters works similarly but the cache is purged upon successful fetch.
+
+---
+
+## [1.0.10] - 2021-05-12
+
+### Added
+
+-   More settable commands for VBAN parameters
+
+### Changed
+
+-   Update unit tests to reflect changes
+-   Updated README to reflect changes.
+-   define_types moved into utils.rb since it defines types for channels,
+    macrobuttons and vban
+-   number set int and real_number added to utils.rb to better define different
+    value types.
+
+### Fixed
+
+-   Alias functions that accept boolean values now return true or false
+-   Bug in boundary test fixed by resetting match attributes m1,m2,m3 if no current match found
+
+## [1.0.9] - 2021-04-30
+
+### Added
+
+-   Support for other types of parameters in multi_set
+-   Automate running of every test for every version
+-   Settable delay before logout to avoid race condition on last command
+-   Delay for save/load special commands is now settable.
+-   Delay for shutdown special command is now settable.
+
+### Changed
+
+-   Remote subclass moved into 'voicemeeter.rb'.
+-   All tests updated to reflect changes.
+-   Updated README to reflect changes.
+
+## [1.0.8] - 2021-04-18
+
+### Added
+
+-   Several attributes that define delays within the wrapper are now settable. This includes:
+    setdelay - A delay between each call to a setter
+    getdelay - A delay between each call to a getter
+    rundelay - A delay after the function runvb. (which starts Voicemeeter if a type is passed to Remote as an argument)
+-   Constants now define default values for delays:
+    ACCESSOR_DELAY = 0.001
+    RUNDELAY = 1
+
+## [1.0.7] - 2021-04-18
+
+### Added
+
+-   Added base0 test units for alias functions. This includes:
+    SetParamMultiBase0
+    MacroButtonStatusWithAliasBase0
+    SetParamMultiWithAliasBase0
+    -Added test/<vbtype>/minitest_helper_base0.rb to call multiple parameters with base0 index.
+
+### Changed
+
+-Test types multi, base0 can now be isolated. Params added to runmany to call these tests.
+
+## [1.0.6] - 2021-04-18
+
+### Added
+
+-   Base0 test units for each type.
+-   README updated to demonstrate set_multi, Macrobutton commands,
+    Special commands and a brief description on how to run tests.
+
+### Changed
+
+-   Validate moved into Utils module. Since this no longer exclusively boundary tests params pertaining to strips/buses it seems appropriate to move this to a more generic module.
+
+### Fixed
+
+-   Fixed an error in unit tests that prevented potato:macros from passing due
+    to loading different minitest_helpers from base0 tests. Test unit files that match
+    macrobutton_status\*.rb are now isolated.
+-   Blueprint layout :composite and :patch_insert absolute values fixed.
+
+## [1.0.5] - 2021-04-17
+
+### Added
+
+-   VBAN commands:
+    vban - Turn vban on/off
+    vban.enable - Turn off an instream/oustream
+-   Output channels settable for recorder commands eg:
+    recorder.A1
+    recorder.B3
+
+## [1.0.4] - 2021-04-17
+
+### Added
+
+-   test/<vbtype>/errors/errors_minitest.rb test unit files added to test
+    custom error classes for each type of voicemeeter. Errors tests:
+    APIError
+    LoginError
+    LogoutError
+    VBTypeError
+    BoundsError
+    CommandError
+    ValueTypeError
+
+### Changed
+
+-   Print outs for raised errors modified to include error.class as well
+    as the calling function. In the case of APIError the caller of the caller
+    is printed.
+
+## [1.0.3] - 2021-04-16
+
+### Added
+
+-   set_multi alias function for setting many parameters at once.
+-   test/other/set_multi.rb to demonstrate set_multi
+-   keyword arguments for setting various parameters on wrapper intialization
+
+### Changed
+
+-   spec.metadata github source code url added to gemspec
+
+## [1.0.1] - 2021-04-16
+
+### Added
+
+-   gemspec
+-   release on rubygems
+-   Special commands:
+    command.shutdown - Close application
+    command.show - Bring Voicemeeter to foreground
+    command.restart - Restart audio engine
+    command.eject - Eject file form Recorder
+    command.reset - Reset prams to initial state
+    command.save - Save a config file in xml format
+    command.load - Load a config file in xml format
+    command.showvbanchat - Bring vban chatroom to foreground
+
+-   test/other/special.rb to demonstrate a special command
+
+## [0.0.1] - 2021-04-16
+
+### Added
+
+-   Initial Commit
+-   Core of API
+-   Test units
+-   README.md

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2022 Onyx and Iris
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,308 @@
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/onyx-and-iris/voicemeeter-api-ruby/blob/dev/LICENSE)
+[![code style: prettier](https://img.shields.io/badge/code_style-prettier-ff69b4.svg?style=flat-square)](https://github.com/prettier/plugin-ruby)
+![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)
+
+# Ruby Wrapper for Voicemeeter API
+
+This gem offers a Ruby interface for the Voicemeeter Remote C API.
+
+For an outline of past/future changes refer to: [CHANGELOG](CHANGELOG.md)
+
+## Tested against
+
+-   Basic 1.0.8.2
+-   Banana 2.0.6.2
+-   Potato 3.0.2.2
+
+## Requirements
+
+-   [Voicemeeter](https://voicemeeter.com/)
+-   Ruby 3.0 or greater
+
+## Installation
+
+### Gem
+
+Install voicemeeter_api_ruby gem from your console
+
+`gem install voicemeeter_api_ruby`
+
+### Bundler
+
+Put this in your Gemfile:
+
+`gem 'voicemeeter_api_ruby', require: false`
+
+or use bundlers built in git functionality:
+
+`gem "voicemeeter_api_ruby", :git => "git://github.com/onyx-and-iris/voicemeeter-api-ruby"`
+
+## `Use`
+
+Simplest use case, request a Remote class of a kind, then pass a block to run:
+
+as gem:
+`ruby .\main.rb`
+with bundler:
+`bundle exec ruby .\main.rb`
+
+```ruby
+require 'voicemeeter'
+
+kind_id = 'banana'
+
+# start Voicemeeter GUI
+Voicemeeter.start(kind_id)
+
+vmr = Voicemeeter.remote(kind_id)
+
+# vmr.run accepts a block
+vmr.run do
+    # mute the leftmost strip
+    vmr.strip[0].mute = true
+    puts vmr.strip[0].mute
+
+    # disable eq for second from left bus
+    vmr.bus[1].eq = false
+    puts vmr.bus[1].eq
+end
+```
+
+Login and logout are handled for you in this scenario.
+
+## `kind_id`
+
+Pass the kind of Voicemeeter as an argument. kind_id may be:
+
+-   `basic`
+-   `banana`
+-   `potato`
+
+## `Available commands`
+
+### Channels (strip/bus)
+
+The following properties exist for audio channels.
+
+-   `mono`: boolean
+-   `mute`: boolean
+-   `gain`: float, from -60 to 12
+-   `mc`, `k`: boolean
+-   `comp`, `gate`: float, from 0 to 10
+-   `limit`: int, from -40 to 12
+-   `A1 - A5`, `B1 - B3`: boolean
+-   `eq`: boolean
+-   `label`: string
+-   `device`: string
+-   `sr`: int
+
+example:
+
+```ruby
+vmr.strip[3].gain = 3.7
+puts strip[0].label
+
+vmr.bus[4].mono = true
+```
+
+### Macrobuttons
+
+Three modes defined: state, stateonly and trigger.
+
+-   `state`: boolean
+-   `stateonly`: boolean
+-   `trigger`: boolean
+
+example:
+
+```ruby
+vmr.button[37].state = true
+vmr.button[55].trigger = false
+```
+
+### Recorder
+
+The following methods are Available
+
+-   `play`
+-   `stop`
+-   `pause`
+-   `record`
+-   `ff`
+-   `rew`
+    The following properties accept boolean values.
+-   `loop`: boolean
+-   `A1 - A5`: boolean
+-   `B1 - A3`: boolean
+    Load accepts a string:
+-   `load`: string
+
+example:
+
+```ruby
+vmr.recorder.play
+vmr.recorder.stop
+
+# Enable loop play
+vmr.recorder.loop = True
+
+# Disable recorder out channel B2
+vmr.recorder.B2 = False
+
+# filepath as string
+vmr.recorder.load('C:\music\mytune.mp3')
+```
+
+### VBAN
+
+-   `vmr.vban.enable` `vmr.vban.disable` Turn VBAN on or off
+
+For each vban in/out stream the following properties are defined:
+
+-   `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:
+
+```ruby
+# turn VBAN on
+vmr.vban.enable
+
+# turn on vban instream 0
+vmr.vban.instream[0].on = True
+
+# set bit property for outstream 3 to 24
+vmr.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
+-   `shutdown` : Shuts down the GUI
+-   `restart` : Restart the audio engine
+
+The following properties are write only and accept boolean values.
+
+-   `showvbanchat`: boolean
+-   `lock`: boolean
+
+example:
+
+```ruby
+vmr.command.restart
+vmr.command.showvbanchat = true
+```
+
+### Multiple parameters
+
+-   `set_multi`
+    Set many strip/bus/macrobutton/vban parameters at once, for example:
+
+```ruby
+vmr.set_multi(
+    {
+        strip_0: {
+            mute: true,
+            gain: 3.2,
+            A1: true,
+        },
+        bus_3: {
+            gain: -3.2,
+            eq: true,
+        },
+        button_39: {
+            stateonly: true,
+        },
+        vban_outstream_3: {
+            on: true,
+            bit: 24,
+        },
+    },
+)
+```
+
+Or for each class you may do:
+
+```ruby
+vmr.strip[0].set_multi(mute: true, gain: 3.2, A1: true)
+vmr.vban.outstream[0].set_multi(on: true, name: 'streamname', bit: 24)
+```
+
+## `Voicemeeter Module`
+
+### Remote class
+
+Access to lower level Getters and Setters are provided with these functions:
+
+-   `vmr.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.
+-   `vmr.set(param, value)`: For setting the value of any parameter.
+
+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.
+
+example:
+
+```ruby
+vmr.get('Strip[2].Mute')
+vmr.set('Strip[4].Label', 'stripname')
+vmr.set('Strip[0].Gain', -3.6)
+```
+
+#### Voicemeeter::start
+
+Use this function to start Voicemeeter of a kind independently of Remote class.
+for example:
+
+```ruby
+require 'voicemeeter'
+Voicemeeter.start('banana')
+```
+
+## Config Files
+
+`vmr.set_profile('config')`
+
+You may load config files in TOML format.
+Three example profiles have been included with the package. Remember to save
+current settings before loading a profile. To test them simply rename \_profiles
+directory to profiles. They will be loaded into memory but not set. To set one
+you may do:
+
+```ruby
+require 'voicemeeter'
+vmr = Voicemeeter.remote('banana')
+vmr.run { vmr.set_profile('config') }
+```
+
+will load a config file at profiles/banana/config.toml for Voicemeeter Banana.
+
+### Run tests
+
+To run all tests:
+
+```
+Bundle exec rspec
+```
+
+You can use tags to run only certain tests, for example:
+
+```
+Bundle exec rspec --tag 'higher'
+```
+
+### Official Documentation
+
+-   [Voicemeeter Remote C API](https://forum.vb-audio.com/viewtopic.php?f=8&t=346)