diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..5aa2f9a --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,21 @@ +# 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 minor/major patch is released all test units will be run to verify they pass. + +## [Unreleased] +- [ ] + +## [1.3] - 2021-04-30 +### Added +- Updated README to include Installation instructions. +- Added FROM_SOURCE.md to explain alternative loading of scripts if directly +downloaded. +- Set_Multi command for setting many parameters at once. + + +## [1.0] - 2021-04-29 +- Added module to PSGAllery diff --git a/FROM_SOURCE.md b/FROM_SOURCE.md new file mode 100644 index 0000000..1e1848e --- /dev/null +++ b/FROM_SOURCE.md @@ -0,0 +1,34 @@ +#### Direct download: +All commands remain the same, the only difference when you download from source is how you load scripts. +You will need to dot source the Voicemeeter.ps1 since you won't have it installed as a module + +Instead of `Import-Module Voicemeeter` use `. .\lib\voicemeeter.ps1` (from repository root) + +and call remote class directly, so: `$vmr = [Remote]::new('banana')` + +Where you pass it a Voicemeeter type argument. Type can be one of: +- basic +- banana +- potato + +Simple example if using from source: + +```powershell +. .\lib\voicemeeter.ps1 + +try { + # Pass a Voicemeeter type as argument + $vmr = [Remote]::new('banana') + + # 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() } +``` diff --git a/README.md b/README.md index 7eee0b3..6adeec5 100644 --- a/README.md +++ b/README.md @@ -3,6 +3,8 @@ This wrapper was written in response to a request in the VB-AUDIO discord for a way to invoke commands using Powershell. It is designed to be simple to use but not every feature is added. +For past/future changes to this project refer to: [CHANGELOG](.\CHANGELOG.md) + ## Tested against - Basic 1.0.7.8 - Banana 2.0.5.8 @@ -15,15 +17,28 @@ You may have success with many commands in earlier versions but some commands - Voicemeeter: https://voicemeeter.com/ - Powershell 5.1 +## Installation +#### Powershell: +`Install-Module Voicemeeter` + +You will need to add PSGallery as a trusted repository source. +More info: [PSGallery](https://www.powershellgallery.com/) + +#### 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](.\FROM_SOURCE.md). + ## Use 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. ```powershell -. $PSScriptRoot\lib\voicemeeter.ps1 +Import-Module Voicemeeter try { - # pass a Voicemeeter type to class Remote - $vmr = [Remote]::new('banana') + # Run the factory function for required Voicemeeter type + $vmr = Get-RemoteBanana # Set strip and bus params $vmr.strip[0].mono = $true @@ -38,19 +53,20 @@ try { finally { $vmr.Logout() } ``` -Voicemeeter type can be one of: -- basic -- banana -- potato +Voicemeeter factory function can be: +- Get-RemoteBasic +- Get-RemoteBanana +- Get-RemotePotato There is no bounds checking in this wrapper, meaning if you attempt to set a parameter that does not exist for that version of Voicemeeter the wrapper will -throw an error and crash. So make sure what you are settings actually exists. +throw an error. So make sure what you are settings actually exists. ### Multiple parameters Set many strip/bus parameters at once, for Example ```powershell -. $PSScriptRoot\lib\voicemeeter.ps1 +Import-Module Voicemeeter + try { $hash = @{ "Strip[0].Mute" = $true @@ -61,7 +77,7 @@ try { "Strip[2].Mono" = $true } - Param_Set_Multi -HASH $hash + $vmr.Set_Multi($hash) } finally { $vmr.Logout() } ```