Documentation and BREAKING CHANGES

- REMOVED play_rs in favor of play:rs
 - REMOVED setpitchrange in favor of set:pitch
 - REMOVED volume in favor of set:volume
 - RENAMED dump to dbg:dump

sfxd.5

@@ -0,0 +1,83 @@
+.\" Generated by scdoc 1.11.3
+.\" Complete documentation for this program is not available as a GNU info page
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.nh
+.ad l
+.\" Begin generated content:
+.TH "sfxd" "5" "2024-02-25"
+.PP
+.SH NAME
+.PP
+sfxd - configuration file and client commands list
+.PP
+.SH DESCRIPTION
+.PP
+Both configuration file and sfxc(1) commands use the same set of instructions.\&
+.PP
+Configuration file is \fBnot\fR loaded automatically, unless specified with `-C [path]` flag, but it can be loaded at a run-time via \fBsource\fR command.\&
+.PP
+.SH COMMANDS LIST
+.PP
+\fBload NAME FILE\fR Loads specified sound file and stores it under given key.\& 
+.br
+    When given key is already in use, it SHOULD be replaced with the new sound file.\& 
+.br
+    \fB\fRNAME\fB\fR is a string with no spaces, does not support escaping and used as a primary key for accessing loaded sound later.\& 
+.br
+    \fB\fRFILE\fB\fR is an absolute path to a sound file to be loaded.\& Only WAV and MP3 files are supported.\&
+.PP
+\fBplay NAME\fR Plays the sound with default pitch and volume.\& 
+.br
+    \fB\fRNAME\fB\fR is a key, used when \fBload\fRing a file.\&
+.PP
+\fBplay:rs NAME\fR Plays the sound with randomized pitch.\& 
+.br
+    Pitch range is specified with \fBset:pitch\fR command.\& 
+.br
+    \fB\fRNAME\fB\fR is a key, used when \fBload\fRing a file.\&
+.PP
+\fBset:pitch NAME MIN MAX\fR Sets the pitch range for \fBplay:rs\fR 
+.br
+    \fB\fRNAME\fB\fR is a key, used when \fBload\fRing a file.\& 
+.br
+    \fB\fRMIN\fB\fR is the minimum pitch.\& Can'\&t be less than 0.\& 
+.br
+    \fB\fRMAX\fB\fR is the maximum pitch.\& Can'\&t be less than 0.\& 
+.br
+    NOTE: if MAX is smaller than MIN, they are swapped.\&
+.PP
+\fBset:volume NAME VOLUME\fR Changes loudness for \fBplay\fR and \fBplay:rs\fR commands.\& 
+.br
+    \fB\fRNAME\fB\fR is a key, used when \fBload\fRing a file.\& 
+.br
+    \fB\fRVOLUME\fB\fR is the volume to be set.\& Can'\&t be outside of 0.\&.\&1 range
+.PP
+\fBsource PATH\fR Loads instructions from the configuration file.\& 
+.br
+    \fB\fRPATH\fB\fR is the file path for the configuration file.\& 
+.br
+    NOTE: there is a limit on how deep inclusion can go.\& By default it'\&s set to 32.\&
+.PP
+.SH DEBUG COMMANDS
+.PP
+\fBdbg:dump\fR Dumps contents of the hashmap.\& 
+.br
+    Prints each position of allocated hashmap and corresponding contents.\& 
+.br
+    Empty areas are shown as `(unused)`, while used ones contain volume, pitch range, calculated hash, key and file path.\&
+.PP
+\fBdbg:counters\fR Shows internal counters.\& Can be disabled at the compile-time.\& 
+.br
+    - `.\&pool_read` - number of reads 
+.br
+    - `.\&pool_write` - number of writes 
+.br
+    - `.\&hash_misses_read` - number of missed reads due to collision 
+.br
+    - `.\&hash_misses_write` - number of collisions in the map 
+.br
+    - `.\&pool.\&use` - number of used cells 
+.br
+    - `.\&pool.\&cap` - hashmap capacity
+.PP

sfxd.5.scd

@@ -0,0 +1,54 @@
+sfxd(5)
+
+# NAME
+
+sfxd - configuration file and client commands list
+
+# DESCRIPTION
+
+Both configuration file and sfxc(1) commands use the same set of instructions.
+
+Configuration file is *not* loaded automatically, unless specified with `-C [path]` flag, but it can be loaded at a run-time via *source* command.
+
+# COMMANDS LIST
+
+*load NAME FILE* Loads specified sound file and stores it under given key. ++
+    When given key is already in use, it SHOULD be replaced with the new sound file. ++
+    **NAME** is a string with no spaces, does not support escaping and used as a primary key for accessing loaded sound later. ++
+    **FILE** is an absolute path to a sound file to be loaded. Only WAV and MP3 files are supported.
+
+*play NAME* Plays the sound with default pitch and volume. ++
+    **NAME** is a key, used when *load*ing a file.
+
+*play:rs NAME* Plays the sound with randomized pitch. ++
+    Pitch range is specified with *set:pitch* command. ++
+    **NAME** is a key, used when *load*ing a file.
+
+*set:pitch NAME MIN MAX* Sets the pitch range for *play:rs* ++
+    **NAME** is a key, used when *load*ing a file. ++
+    **MIN** is the minimum pitch. Can't be less than 0. ++
+    **MAX** is the maximum pitch. Can't be less than 0. ++
+    NOTE: if MAX is smaller than MIN, they are swapped.
+
+*set:volume NAME VOLUME* Changes loudness for *play* and *play:rs* commands. ++
+    **NAME** is a key, used when *load*ing a file. ++
+    **VOLUME** is the volume to be set. Can't be outside of 0..1 range
+
+*source PATH* Loads instructions from the configuration file. ++
+    **PATH** is the file path for the configuration file. ++
+    NOTE: there is a limit on how deep inclusion can go. By default it's set to 32.
+
+# DEBUG COMMANDS
+
+*dbg:dump* Dumps contents of the hashmap. ++
+    Prints each position of allocated hashmap and corresponding contents. ++
+    Empty areas are shown as `(unused)`, while used ones contain volume, pitch range, calculated hash, key and file path.
+
+*dbg:counters* Shows internal counters. Can be disabled at the compile-time. ++
+    - `.pool_read` - number of reads ++
+    - `.pool_write` - number of writes ++
+    - `.hash_misses_read` - number of missed reads due to collision ++
+    - `.hash_misses_write` - number of collisions in the map ++
+    - `.pool.use` - number of used cells ++
+    - `.pool.cap` - hashmap capacity
+

src/sfxd.c

@@ -225,7 +225,7 @@ void execute_command(struct msg_target tgt, const char *command, const char *par
     ma_sound_set_pitch(sfx, sound->pitch_min);
     ma_sound_set_volume(sfx, sound->volume);
     ma_sound_start(sfx);
-  } else if (0 == strcmp(command, "play:rs") || 0 == strcmp(command, "play_rs")) {
+  } else if (0 == strcmp(command, "play:rs")) {
     struct sfx_pool_item *sound = sfx_pool_lookup(params);
     if (!sound) {
       send_txt(tgt, "ERR: No such sound: '%s'\n", params);
@@ -239,7 +239,7 @@ void execute_command(struct msg_target tgt, const char *command, const char *par
     ma_sound_set_pitch(sfx, pitch);
     ma_sound_set_volume(sfx, sound->volume);
     ma_sound_start(sfx);
-  } else if (0 == strcmp(command, "set:pitch") || 0 == strcmp(command, "setpitchrange")) {
+  } else if (0 == strcmp(command, "set:pitch")) {
     float min, max;
     char *key;
     sscanf(params, "%ms %f %f", &key, &min, &max);
@@ -265,7 +265,7 @@ void execute_command(struct msg_target tgt, const char *command, const char *par
 
     sound->pitch_min = min;
     sound->pitch_max = max;
-  } else if (0 == strcmp(command, "set:volume") || 0 == strcmp(command, "volume")) {
+  } else if (0 == strcmp(command, "set:volume")) {
     float vol;
     char *key;
     sscanf(params, "%ms %f", &key, &vol);
@@ -277,11 +277,13 @@ void execute_command(struct msg_target tgt, const char *command, const char *par
     }
 
     if (vol < 0 || vol > 1) {
-      send_txt(tgt, "ERR: Volume out of range: 0 <= %f < 1\n", vol);
+      send_txt(tgt, "ERR: Volume out of range: 0 <= %f <= 1\n", vol);
     }
 
     sound->volume = vol;
-  } else if (0 == strcmp(command, "dump")) {
+  } else if (0 == strcmp(command, "source")) {
+    execute_file(tgt, params, 0);
+  } else if (0 == strcmp(command, "dbg:dump")) {
     for (int i = 0; i < sounds_pool.cap; i++) {
       struct sfx_pool_item item = sounds_pool.sounds[i];
       if (item.key[0] == '\0') {
@@ -291,8 +293,6 @@ void execute_command(struct msg_target tgt, const char *command, const char *par
             i, item.volume, item.pitch_min, item.pitch_max, adler32(item.key, strlen(item.key)), item.key, item.path);
       }
     }
-  } else if (0 == strcmp(command, "source")) {
-    execute_file(tgt, params, 0);
   } else if (0 == strcmp(command, "dbg:counters")) {
 #ifdef NO_COUNTERS
     send_txt(tgt, "ERR: counters are disabled at compile-time with NO_COUNTERS feature flag.");