add doc comments

add link defs

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 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.

README.md

@@ -1,4 +1,4 @@
-# VMRCLI Command Line Utility
+# Voicemeeter Remote Command Line Utility
 
 ## `Tested against`
 
@@ -13,15 +13,16 @@
 ## `Use`
 
 ```powershell
-./vmrcli.exe [-h] [-i] [-k] [-D] <api commands>
+./vmrcli.exe [-h] [-i] [-k] [-D] [-v] <api commands>
 ```
 
 Where:
 
-- `h`: Prints the help dialogue.
+- `h`: Prints the help message.
 - `i`: Enable interactive mode. If set, any api commands passed on the command line will be ignored.
 - `k`: The kind of Voicemeeter (basic, banana or potato). Use this to launch the GUI.
 - `D`: Set log level 0=TRACE, 1=DEBUG, 2=INFO, 3=WARN, 4=ERROR, 5=FATAL
+- `v`: Enable extra console output (toggle, set messages)
 
 ## `API Commands`
 
@@ -68,18 +69,25 @@ Scripts can be loaded from text files, for example in Powershell:
 ./vmrcli.exe -D1 $(Get-Content .\example_commands.txt)
 ```
 
+Multiple API commands can be in a single line but they should be space separated.
+
 ## `Build`
 
 Run the included `makefile` with [GNU Make](https://www.gnu.org/software/make/).
 
-By default the log.c module is built with coloured logging enabled. To disable this you can override the `LOG_USE_COLOR` variable, for example:
+The binary in [Releases][releases] is compiled with coloured logging enabled. To disable this you can override the `LOG_USE_COLOR` variable, for example:
 
 `make LOG_USE_COLOR=no`
 
 ## `Official Documentation`
 
-- [Voicemeeter Remote C API](https://github.com/onyx-and-iris/Voicemeeter-SDK/blob/main/VoicemeeterRemoteAPI.pdf)
+- [Voicemeeter Remote C API][remoteapi-docs]
 
 ## `Special Thanks`
 
-- [rxi](https://github.com/rxi) for writing the [log.c](https://github.com/rxi/log.c) package
+- [rxi][rxi-user] for writing the [log.c][log-c] package
+
+[releases]: https://github.com/onyx-and-iris/vmrcli/releases
+[remoteapi-docs]: https://github.com/onyx-and-iris/Voicemeeter-SDK/blob/main/VoicemeeterRemoteAPI.pdf
+[rxi-user]: https://github.com/rxi
+[log-c]: https://github.com/rxi/log.c

example_commands.txt

@@ -1,8 +1,3 @@
-strip[0].mute 
+strip[0].mute !strip[0].mute strip[0].mute strip[0].gain strip[0].label=podmic strip[0].label
-!strip[0].mute 
+strip[1].mute=1 strip[1].mute
-strip[0].mute
+bus[0].label bus[0].gain=-8.3
-strip[1].mute=1
-strip[1].mute
-strip[0].gain
-strip[0].label=podmic
-strip[0].label

include/vmr.h

@@ -14,23 +14,23 @@ enum kind
     POTATOX64,
 };
 
-long login(T_VBVMR_INTERFACE *iVMR, int kind);
+long login(T_VBVMR_INTERFACE *vmr, int kind);
-long logout(T_VBVMR_INTERFACE *iVMR);
+long logout(T_VBVMR_INTERFACE *vmr);
-long run_voicemeeter(T_VBVMR_INTERFACE *iVMR, int kind);
+long run_voicemeeter(T_VBVMR_INTERFACE *vmr, int kind);
-long type(T_VBVMR_INTERFACE *iVMR, long *type);
+long type(T_VBVMR_INTERFACE *vmr, long *type);
-long version(T_VBVMR_INTERFACE *iVMR, long *version);
+long version(T_VBVMR_INTERFACE *vmr, long *version);
 
-bool is_pdirty(T_VBVMR_INTERFACE *iVMR);
+bool is_pdirty(T_VBVMR_INTERFACE *vmr);
-long get_parameter_float(T_VBVMR_INTERFACE *iVMR, char *param, float *f);
+long get_parameter_float(T_VBVMR_INTERFACE *vmr, char *param, float *f);
-long get_parameter_string(T_VBVMR_INTERFACE *iVMR, char *param, unsigned short *s);
+long get_parameter_string(T_VBVMR_INTERFACE *vmr, char *param, unsigned short *s);
-long set_parameter_float(T_VBVMR_INTERFACE *iVMR, char *param, float val);
+long set_parameter_float(T_VBVMR_INTERFACE *vmr, char *param, float val);
-long set_parameter_string(T_VBVMR_INTERFACE *iVMR, char *param, char *s);
+long set_parameter_string(T_VBVMR_INTERFACE *vmr, char *param, char *s);
-long set_parameters(T_VBVMR_INTERFACE *iVMR, char *command);
+long set_parameters(T_VBVMR_INTERFACE *vmr, char *command);
 
-bool is_mdirty(T_VBVMR_INTERFACE *iVMR);
+bool is_mdirty(T_VBVMR_INTERFACE *vmr);
-long macrobutton_getstatus(T_VBVMR_INTERFACE *iVMR, long n, float *val, long mode);
+long macrobutton_getstatus(T_VBVMR_INTERFACE *vmr, long n, float *val, long mode);
-long macrobutton_setstatus(T_VBVMR_INTERFACE *iVMR, long n, float val, long mode);
+long macrobutton_setstatus(T_VBVMR_INTERFACE *vmr, long n, float val, long mode);
 
-void clear_dirty(T_VBVMR_INTERFACE *iVMR);
+void clear_dirty(T_VBVMR_INTERFACE *vmr);
 
-#endif
+#endif /* __VMR_H__ */

src/util.c

@@ -3,6 +3,11 @@
 #include "vmr.h"
 #include "util.h"
 
+/**
+ * @brief Removes the last part of a path
+ *
+ * @param szPath
+ */
 void remove_name_in_path(char *szPath)
 {
     char *p = szPath;
@@ -57,6 +62,14 @@ int replace_multiple_space_with_one(char *s, size_t len)
     return j;
 }
 
+/**
+ * @brief
+ *
+ * @param s Pointer to a character buffer
+ * @param kind The kind of Voicemeeter.
+ * @param n maximum number of characters to be written to the buffer
+ * @return char* The kind of Voicemeeter as a string
+ */
 char *kind_as_string(char *s, enum kind kind, int n)
 {
     char *kinds[] = {

src/vmr.c

@@ -8,6 +8,15 @@
 #define VERSION_STR_LEN 128
 #define KIND_STR_LEN 64
 
+/**
+ * @brief Logs into the API.
+ * Tests for valid connection for up to 2 seconds.
+ * If successful initializes the dirty parameters.
+ *
+ * @param vmr
+ * @param kind
+ * @return long
+ */
 long login(T_VBVMR_INTERFACE *vmr, int kind)
 {
     int rep;
@@ -45,6 +54,13 @@ long login(T_VBVMR_INTERFACE *vmr, int kind)
     return rep;
 }
 
+/**
+ * @brief Logs out of the API giving a short wait to allow a
+ * final instruction to complete.
+ *
+ * @param vmr The API interface as a struct
+ * @return long VBVMR_Logout return value
+ */
 long logout(T_VBVMR_INTERFACE *vmr)
 {
     int rep;

src/vmrcli.c

@@ -9,12 +9,21 @@
 
 #define MAX_LINE 512
 
+/**
+ * @brief An enum used to define the kind of value
+ * a 'get' call returns.
+ *
+ */
 enum
 {
     FLOAT_T,
     STRING_T,
 };
 
+/**
+ * @brief A struct holding the result of a get call.
+ *
+ */
 struct result
 {
     int type;
@@ -29,9 +38,12 @@ void help(void);
 enum kind set_kind(char *kval);
 int init_voicemeeter(T_VBVMR_INTERFACE *vmr, int kind);
 void interactive(T_VBVMR_INTERFACE *vmr);
+void parse_input(T_VBVMR_INTERFACE *vmr, char *input, int len);
 void parse_command(T_VBVMR_INTERFACE *vmr, char *command);
 void get(T_VBVMR_INTERFACE *vmr, char *command, struct result *res);
 
+bool vflag = false;
+
 int main(int argc, char *argv[])
 {
     bool iflag = false;
@@ -48,7 +60,7 @@ int main(int argc, char *argv[])
 
     log_set_level(LOG_WARN);
 
-    while ((opt = getopt(argc, argv, "k:ihD:")) != -1)
+    while ((opt = getopt(argc, argv, "k:ihD:v")) != -1)
     {
         switch (opt)
         {
@@ -75,6 +87,9 @@ int main(int argc, char *argv[])
                     "Log level will default to LOG_WARN (3).\n");
             }
             break;
+        case 'v':
+            vflag = true;
+            break;
         default:
             abort();
         }
@@ -98,7 +113,7 @@ int main(int argc, char *argv[])
     {
         for (int i = optind; i < argc; i++)
         {
-            parse_command(vmr, argv[i]);
+            parse_input(vmr, argv[i], strlen(argv[i]));
         }
     }
 
@@ -110,18 +125,19 @@ int main(int argc, char *argv[])
 }
 
 /**
- * @brief prints the help dialogue
+ * @brief prints the help message
  *
  */
 void help()
 {
     puts(
-        "Usage: ./vmrcli.exe [-h] [-i] [-k] [-D] <api commands>\n"
+        "Usage: ./vmrcli.exe [-h] [-i] [-k] [-D] [-v] <api commands>\n"
         "Where: \n"
-        "\th: Prints the help dialogue\n"
+        "\th: Prints the help message\n"
         "\ti: Enable interactive mode\n"
         "\tk: The kind of Voicemeeter (basic, banana, potato)\n"
-        "\tD: Set log level 0=TRACE, 1=DEBUG, 2=INFO, 3=WARN, 4=ERROR, 5=FATAL");
+        "\tD: Set log level 0=TRACE, 1=DEBUG, 2=INFO, 3=WARN, 4=ERROR, 5=FATAL\n"
+        "\tv: Enable extra console output (toggle, set messages)");
 }
 
 /**
@@ -160,6 +176,14 @@ enum kind set_kind(char *kval)
     }
 }
 
+/**
+ * @brief Defines the DLL interface as a struct.
+ * Logs into the API.
+ *
+ * @param vmr The API interface as a struct
+ * @param kind
+ * @return int
+ */
 int init_voicemeeter(T_VBVMR_INTERFACE *vmr, int kind)
 {
     int rep = initialize_dll_interfaces(vmr);
@@ -186,11 +210,16 @@ int init_voicemeeter(T_VBVMR_INTERFACE *vmr, int kind)
     return 0;
 }
 
+/**
+ * @brief Continuously read lines from stdin.
+ * Break if 'Q' is entered on the interactive prompt.
+ * Each line is passed to parse_input()
+ *
+ * @param vmr The API interface as a struct
+ */
 void interactive(T_VBVMR_INTERFACE *vmr)
 {
-    char input[MAX_LINE], command[MAX_LINE];
+    char input[MAX_LINE];
-    char *p = input;
-    int i;
     size_t len;
 
     printf(">> ");
@@ -201,33 +230,42 @@ void interactive(T_VBVMR_INTERFACE *vmr)
         if (len == 1 && toupper(input[0]) == 'Q')
             break;
 
-        replace_multiple_space_with_one(input, len);
+        parse_input(vmr, input, len);
-        while (*p)
-        {
-            if (isspace(*p))
-            {
-                p++;
-                continue;
-            }
-            log_trace("commands still in buffer: %s", p);
 
-            i = 0;
-            while (*p && !isspace(*p))
-                command[i++] = *p++;
-            command[i] = '\0';
-            p++; /* shift to next char */
-
-            if (command[0] != '\0')
-                parse_command(vmr, command);
-            memset(command, '\0', MAX_LINE);
-        }
-
-        p = input;                     /* reset pointer */
         memset(input, '\0', MAX_LINE); /* reset input buffer */
         printf(">> ");
     }
 }
 
+/**
+ * @brief Walks through each line split by a space delimiter.
+ * Each token is passed to parse_command()
+ *
+ * @param vmr The API interface as a struct
+ * @param input Each input line, from stdin or CLI args
+ * @param len The length of the input line
+ */
+void parse_input(T_VBVMR_INTERFACE *vmr, char *input, int len)
+{
+    char *token;
+
+    replace_multiple_space_with_one(input, len);
+    token = strtok(input, " ");
+    while (token != NULL)
+    {
+        parse_command(vmr, token);
+        token = strtok(NULL, " ");
+    }
+}
+
+/**
+ * @brief Execute each command according to type.
+ * See command type definitions in:
+ * https://github.com/onyx-and-iris/vmrcli?tab=readme-ov-file#api-commands
+ *
+ * @param vmr The API interface as a struct
+ * @param command Each token from the input line as its own command string
+ */
 void parse_command(T_VBVMR_INTERFACE *vmr, char *command)
 {
     log_debug("Parsing %s", command);
@@ -241,7 +279,13 @@ void parse_command(T_VBVMR_INTERFACE *vmr, char *command)
         if (res.type == FLOAT_T)
         {
             if (res.val.f == 1 || res.val.f == 0)
+            {
                 set_parameter_float(vmr, command, 1 - res.val.f);
+                if (vflag)
+                {
+                    printf("Toggling %s\n", command);
+                }
+            }
             else
                 log_warn("%s does not appear to be a boolean parameter", command);
         }
@@ -251,6 +295,10 @@ void parse_command(T_VBVMR_INTERFACE *vmr, char *command)
     if (strchr(command, '=') != NULL) /* set */
     {
         set_parameters(vmr, command);
+        if (vflag)
+        {
+            printf("Setting %s\n", command);
+        }
     }
     else /* get */
     {
@@ -260,10 +308,10 @@ void parse_command(T_VBVMR_INTERFACE *vmr, char *command)
         switch (res.type)
         {
         case FLOAT_T:
-            printf("%.1f\n", res.val.f);
+            printf("%s: %.1f\n", command, res.val.f);
             break;
         case STRING_T:
-            printf("%ls\n", res.val.s);
+            printf("%s: %ls\n", command, res.val.s);
             break;
         default:
             break;
@@ -271,6 +319,13 @@ void parse_command(T_VBVMR_INTERFACE *vmr, char *command)
     }
 }
 
+/**
+ * @brief
+ *
+ * @param vmr The API interface as a struct
+ * @param command A parsed 'get' command as a string
+ * @param res A struct holding the result of the API call.
+ */
 void get(T_VBVMR_INTERFACE *vmr, char *command, struct result *res)
 {
     clear_dirty(vmr);