Base+Utilities: Add the asctl audio utility, replacing avol

The new asctl (audio server control) utility expands on avol with a
completely new command line interface (documented in the man page) that
supports retrieving and setting all exposed audio server settings, like
volume and sample rate. This is currently the only user-facing way of
changing the sample rate.

Base/usr/share/man/man1/asctl.md

@@ -0,0 +1,61 @@
+## Name
+
+asctl - Send control signals to the audio server and hardware
+
+## Synopsis
+
+```**sh
+$ asctl [--human-readable] <command> [args...]
+```
+
+## Description
+
+This program is used to send control signals to the AudioServer and the sound hardware. This allows changing audio server variables like volume and mute state, as well as querying the state of these variables.
+
+## Options
+
+* `-h`, `--human-readable`: Print human-readable output. If this option is not given, the output of `get` will be machine-readable and only consist of one line.
+
+## Arguments
+
+* `command`: The command to execute, either `get` or `set`.
+* `args`: The arguments to the command.
+
+There are two commands available: `get` reports the state of audio variables, and `set` changes these variables.
+
+`get` expects a list of variables to report back, and it will report them in the order given. The exact format of the report depends on the `--human-readable` flag. If no variables are given, `get` will report all available variables, in the order that they are listed below.
+
+`set` expects one or more variables followed by a value to set them to, and will set the variables to the given values. A variable can be given multiple times and the last specified value will remain with the audio server.
+
+The available variables are:
+* `(v)olume`: Audio server volume, in percent. Integer value.
+* `(m)ute`: Mute state. Boolean value, may be set with `0`, `false` or `1`, `true`.
+* `sample(r)ate`: Sample rate of the sound card. **Attention:** Most audio applications need to be restarted after changing the sample rate. Integer value.
+
+Both commands and arguments can be abbreviated: Commands by their first letter, arguments by the letter in parenthesis.
+
+## Examples
+
+```**sh
+Get the current volume (machine format)
+$ asctl get volume
+100
+
+Get all variables
+$ asctl -h get
+Volume: 100
+Muted: No
+Sample rate: 48000 Hz
+
+Set the volume to 100%
+$ asctl set volume 100
+
+Mute all audio
+$ asctl set mute true
+
+Unmute all audio, set volume to 80%
+$ asctl s m 0 v 80
+
+Set sample rate
+$ asctl s samplerate 48000
+```

Base/usr/share/man/man1/avol.md

@@ -1,36 +0,0 @@
-## Name
-
-avol - Change system sound volume
-
-## Synopsis
-
-```**sh
-$ avol [-m] [-M] [volume]
-```
-
-## Description
-
-This program is used to control the AudioServer volume and muted state.
-
-## Options
-
-* `-m`: Mute all audio.
-* `-M`: Unmute all audio.
-
-## Examples
-
-```sh
-# Set the volume to 100
-$ avol 100
-Volume: 100
-
-# Get the current volume
-$ avol
-Volume: 80
-
-# Mute all audio
-$ avol -m
-
-# Unmute all audio
-$ avol -M
-```

Userland/Utilities/CMakeLists.txt

@@ -7,7 +7,7 @@ list(APPEND REQUIRED_TARGETS
     touch tr true umount uname uniq uptime w wc which whoami xargs yes less
 )
 list(APPEND RECOMMENDED_TARGETS
-    adjtime aplay avol bt checksum chres cksum copy fortune gunzip gzip init keymap lsirq lsof lspci man mknod mktemp
+    adjtime aplay asctl bt checksum chres cksum copy fortune gunzip gzip init keymap lsirq lsof lspci man mknod mktemp
     modload modunload nc netstat notify ntpquery open pape passwd pls printf pro shot tar tt unzip zip
 )
 
@@ -52,7 +52,7 @@ foreach(CMD_SRC ${CMD_SOURCES})
 endforeach()
 
 target_link_libraries(aplay LibAudio)
-target_link_libraries(avol LibAudio)
+target_link_libraries(asctl LibAudio)
 target_link_libraries(bt LibSymbolication)
 target_link_libraries(checksum LibCrypto)
 target_link_libraries(chres LibGUI)

Userland/Utilities/asctl.cpp

@@ -0,0 +1,156 @@
+/*
+ * Copyright (c) 2018-2020, Andreas Kling <kling@serenityos.org>
+ * Copyright (c) 2021, kleines Filmröllchen <malu.bertsch@gmail.com>
+ *
+ * SPDX-License-Identifier: BSD-2-Clause
+ */
+
+#include <AK/Variant.h>
+#include <AK/Vector.h>
+#include <LibAudio/Buffer.h>
+#include <LibAudio/ClientConnection.h>
+#include <LibCore/ArgsParser.h>
+#include <LibCore/EventLoop.h>
+#include <LibCore/File.h>
+#include <stdio.h>
+#include <sys/ioctl.h>
+
+enum AudioVariable : u32 {
+    Volume,
+    Mute,
+    SampleRate
+};
+
+// asctl: audio server control utility
+int main(int argc, char** argv)
+{
+    Core::EventLoop loop;
+    auto audio_client = Audio::ClientConnection::construct();
+
+    String command = String::empty();
+    Vector<String> arguments;
+    bool human_mode = false;
+
+    Core::ArgsParser args_parser;
+    args_parser.set_general_help("Send control signals to the audio server and hardware.");
+    args_parser.add_option(human_mode, "Print human-readable output", "human-readable", 'h');
+    args_parser.add_positional_argument(command, "Command, either (g)et or (s)et\n\n\tThe get command accepts a list of variables to print.\n\tThey are printed in the given order.\n\tIf no value is specified, all are printed.\n\n\tThe set command accepts a any number of variables\n\tfollowed by the value they should be set to.\n\n\tPossible variables are (v)olume, (m)ute, sample(r)ate.\n", "command");
+    args_parser.add_positional_argument(arguments, "Arguments for the command", "args", Core::ArgsParser::Required::No);
+    args_parser.parse(argc, argv);
+
+    if (command.equals_ignoring_case("get") || command == "g") {
+        // Get variables
+        Vector<AudioVariable> values_to_print;
+        if (arguments.is_empty()) {
+            values_to_print.append(AudioVariable::Volume);
+            values_to_print.append(AudioVariable::Mute);
+            values_to_print.append(AudioVariable::SampleRate);
+        } else {
+            for (auto& variable : arguments) {
+                if (variable.is_one_of("v"sv, "volume"sv))
+                    values_to_print.append(AudioVariable::Volume);
+                else if (variable.is_one_of("m"sv, "mute"sv))
+                    values_to_print.append(AudioVariable::Mute);
+                else if (variable.is_one_of("r"sv, "samplerate"sv))
+                    values_to_print.append(AudioVariable::SampleRate);
+                else {
+                    warnln("Error: Unrecognized variable {}", variable);
+                    return 1;
+                }
+            }
+        }
+
+        for (auto to_print : values_to_print) {
+            switch (to_print) {
+            case AudioVariable::Volume: {
+                i16 volume = audio_client->get_main_mix_volume();
+                if (human_mode)
+                    outln("Volume: {:3d}%", volume);
+                else
+                    out("{} ", volume);
+                break;
+            }
+            case AudioVariable::Mute: {
+                bool muted = audio_client->get_muted();
+                if (human_mode)
+                    outln("Muted: {}", muted ? "Yes" : "No");
+                else
+                    out("{} ", muted ? 1 : 0);
+                break;
+            }
+            case AudioVariable::SampleRate: {
+                u16 sample_rate = audio_client->get_sample_rate();
+                if (human_mode)
+                    outln("Sample rate: {:5d} Hz", sample_rate);
+                else
+                    out("{} ", sample_rate);
+                break;
+            }
+            }
+        }
+        if (!human_mode)
+            outln();
+    } else if (command.equals_ignoring_case("set") || command == "s") {
+        // Set variables
+        HashMap<AudioVariable, Variant<int, bool>> values_to_set;
+        for (size_t i = 0; i < arguments.size(); ++i) {
+            if (i == arguments.size() - 1) {
+                warnln("Error: value missing for last variable");
+                return 1;
+            }
+            auto& variable = arguments[i];
+            if (variable.is_one_of("v"sv, "volume"sv)) {
+                auto volume = arguments[++i].to_int();
+                if (!volume.has_value()) {
+                    warnln("Error: {} is not an integer volume", arguments[i - 1]);
+                    return 1;
+                }
+                values_to_set.set(AudioVariable::Volume, volume.value());
+            } else if (variable.is_one_of("m"sv, "mute"sv)) {
+                String& mute_text = arguments[++i];
+                bool mute;
+                if (mute_text.equals_ignoring_case("true") || mute_text == "1") {
+                    mute = true;
+                } else if (mute_text.equals_ignoring_case("false") || mute_text == "0") {
+                    mute = false;
+                } else {
+                    warnln("Error: {} is not one of {{0, 1, true, false}}", mute_text);
+                    return 1;
+                }
+                values_to_set.set(AudioVariable::Mute, mute);
+            } else if (variable.is_one_of("r"sv, "samplerate"sv)) {
+                auto sample_rate = arguments[++i].to_int();
+                if (!sample_rate.has_value()) {
+                    warnln("Error: {} is not an integer sample rate", arguments[i - 1]);
+                    return 1;
+                }
+                values_to_set.set(AudioVariable::SampleRate, sample_rate.value());
+            } else {
+                warnln("Error: Unrecognized variable {}", arguments[i]);
+                return 1;
+            }
+        }
+
+        for (auto to_set : values_to_set) {
+            switch (to_set.key) {
+            case AudioVariable::Volume: {
+                int& volume = to_set.value.get<int>();
+                audio_client->set_main_mix_volume(volume);
+                break;
+            }
+            case AudioVariable::Mute: {
+                bool& mute = to_set.value.get<bool>();
+                audio_client->set_muted(mute);
+                break;
+            }
+            case AudioVariable::SampleRate: {
+                int& sample_rate = to_set.value.get<int>();
+                audio_client->set_sample_rate(sample_rate);
+                break;
+            }
+            }
+        }
+    }
+
+    return 0;
+}

Userland/Utilities/avol.cpp

@@ -1,49 +0,0 @@
-/*
- * Copyright (c) 2018-2020, Andreas Kling <kling@serenityos.org>
- *
- * SPDX-License-Identifier: BSD-2-Clause
- */
-
-#include <LibAudio/Buffer.h>
-#include <LibAudio/ClientConnection.h>
-#include <LibCore/ArgsParser.h>
-#include <LibCore/EventLoop.h>
-#include <stdio.h>
-
-int main(int argc, char** argv)
-{
-    Core::EventLoop loop;
-    auto audio_client = Audio::ClientConnection::construct();
-
-    bool mute = false;
-    bool unmute = false;
-    // FIXME: What is a good way to have an optional int argument?
-    const char* volume = nullptr;
-
-    Core::ArgsParser args_parser;
-    args_parser.add_option(mute, "Mute volume", "mute", 'm');
-    args_parser.add_option(unmute, "Unmute volume", "unmute", 'M');
-    args_parser.add_positional_argument(volume, "Volume to set", "volume", Core::ArgsParser::Required::No);
-    args_parser.parse(argc, argv);
-
-    if (!mute && !unmute && !volume) {
-        auto volume = audio_client->get_main_mix_volume();
-        outln("Volume: {}", volume);
-        return 0;
-    }
-    if (!(mute ^ unmute ^ (volume != nullptr))) {
-        warnln("Only one of mute, unmute or volume must be used");
-        return 1;
-    }
-    if (mute) {
-        audio_client->set_muted(true);
-        outln("Muted.");
-    } else if (unmute) {
-        audio_client->set_muted(false);
-        outln("Unmuted.");
-    } else {
-        auto new_volume = atoi(volume);
-        audio_client->set_main_mix_volume(new_volume);
-    }
-    return 0;
-}