Utilities: Add aconv for converting between audio formats

The intention for this utility is to eventually become a general-purpose
multimedia conversion tool like ffmpeg (except probably not with as many
supported formats, stream mappings and filters). For now, we can not
write any video format so the added complexity is not necessary at the
moment.

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

@@ -0,0 +1,67 @@
+## Name
+
+aconv - convert between audio formats
+
+## Synopsis
+
+```**sh
+$ aconv -i input [--input-audio-codec input-codec] [--audio-codec output-codec] [--audio-format sample-format] -o output
+```
+
+## Description
+
+`aconv` converts between different audio formats, or more precisely, between containers and codecs. `aconv` can both read from and write to the standard input and output streams. Depending on the audio format used, `aconv` may or may not act as a streaming converter; that is, `aconv` may require to read until EOF of the input file to start writing to the output. More details can be found with the encoders and decoders that `aconv` supports.
+
+The input file option is always required. `aconv` will try to guess which container and codec the input has, unless the `--input-audio-codec` option is provided. Note that guessing the codec is not possible for raw formats such as raw PCM streams, therefore such formats always require specifying the input codec option.
+
+The output file may be omitted, in which case `aconv` does not write any data. If an output codec is provided via `--audio-codec`, `aconv` will internally still perform the conversion without writing data. If `--audio-codec` is not provided, `aconv` will decode the input and not do anything else. It is recommended that [`abench`](help://man/1/abench) be used for audio input testing purposes.
+
+`aconv` will try to guess the output container and codec based on the file name specified. The codec can be overwritten with the aforementioned `--audio-codec` option; this is mandatory for the standard output stream where the container and codec cannot be guessed.
+
+By specifying `--audio-format`, `aconv` will use a different sample format for the output than what the input file provides. The sample format is the format of the PCM stream that is encoded with the codec, and it specifies multiple parameters such as bit depth, data type, and endiannness. The supported sample formats depend on the codec, but they have common names shared across codecs.
+
+### Supported Codecs and Containers
+
+Note that `aconv` currently only supports codecs which have their own bespoke container. Therefore, the distinction does not currently matter. The names given below are the only recognized names for this codec for the command line options `--audio-codec` and `--input-audio-codec`. Some codecs can only be decoded or both encoded and decoded. 
+
+* `mp3` (decode): MPEG Layer III audio codec and container.
+* `wav` (decode, encode): RIFF WAVE audio codec and container. Supports sample formats `u8` and `s16le` for writing.
+* `flac` (decode): Free Lossless Audio Codec and container.
+* `qoa` (decode): Quite Okay Audio codec and container.
+
+### Supported Sample Formats
+
+* `u8`: Unsigned 8-bit integer
+* `s16le`: Signed 16-bit integer, little endian
+* `s24le`: Signed 24-bit integer, little endian
+* `s32le`: Signed 32-bit integer, little endian
+* `f32le`: 32-bit IEEE 754 floating-point number (normalized to the range [-1, 1]), little endian
+* `f64le`: 64-bit IEEE 754 floating-point number (normalized to the range [-1, 1]), little endian
+
+## Options
+
+The option format follows this general pattern: `--input_or_output-stream-parameter`, where `input_or_output` is either `input` when concerning the input stream, or omitted for the output stream (since this is the more common use case), `stream` currently is always `audio`, and `parameter` is the parameter of the stream that is changed.
+
+* `-i`, `--input`: The input file to convert from. Use `-` to read from standard input.
+* `-o`, `--output`: The output file to write to. Use `-` to write to standard output.
+* `--input-audio-codec`: Overwrite the used codec and/or sample format of the input file.
+* `--audio-codec`: The codec to use for the output file.
+* `--audio-format`: The sample format to use for the output file.
+
+## Examples
+
+```sh
+# Decode a FLAC file to WAV
+$ aconv -i ~/sound.flac -o ~/sound.wav
+
+# Decode an MP3 file stored in a metadata block of a FLAC file to WAV
+$ aconv -i ~/has-mp3-contents.flac --input-audio-codec mp3 -o ~/weird.wav
+
+# Recode WAV to 8-bit and output it to stdout
+$ aconv -i ~/music.wav --audio-format u8 -o -
+```
+
+## See Also
+
+* [`abench`(1)](help://man/1/abench) to test audio decoders and measure their performance
+* [`aplay`(1)](help://man/1/aplay) to play audio files from the command line

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
 )
 list(APPEND RECOMMENDED_TARGETS
-    adjtime aplay abench asctl bt checksum chres cksum copy fortune gunzip gzip init install keymap lsirq lsof lspci lzcat man mknod mktemp
+    aconv adjtime aplay abench asctl bt checksum chres cksum copy fortune gunzip gzip init install keymap lsirq lsof lspci lzcat man mknod mktemp
     nc netstat notify ntpquery open passwd pixelflut pls printf pro shot strings tar tt unzip wallpaper xzcat zip
 )
 
@@ -72,6 +72,7 @@ install(CODE "file(CREATE_LINK grep ${CMAKE_INSTALL_PREFIX}/bin/fgrep SYMBOLIC)"
 install(CODE "file(CREATE_LINK grep ${CMAKE_INSTALL_PREFIX}/bin/rgrep SYMBOLIC)")
 
 target_link_libraries(abench PRIVATE LibAudio LibFileSystem)
+target_link_libraries(aconv PRIVATE LibAudio)
 target_link_libraries(aplay PRIVATE LibAudio LibFileSystem LibIPC)
 target_link_libraries(asctl PRIVATE LibAudio LibIPC)
 target_link_libraries(bt PRIVATE LibSymbolication)

Userland/Utilities/aconv.cpp

@@ -0,0 +1,148 @@
+/*
+ * Copyright (c) 2023, kleines Filmröllchen <filmroellchen@serenityos.org>
+ *
+ * SPDX-License-Identifier: BSD-2-Clause
+ */
+
+#include <AK/LexicalPath.h>
+#include <AK/Types.h>
+#include <LibAudio/Loader.h>
+#include <LibAudio/WavWriter.h>
+#include <LibCore/ArgsParser.h>
+#include <LibCore/DeprecatedFile.h>
+#include <LibCore/System.h>
+#include <LibMain/Main.h>
+#include <stdio.h>
+
+static ErrorOr<StringView> guess_format_from_extension(StringView path)
+{
+    if (path == "-"sv)
+        return Error::from_string_view("Cannot guess format for standard stream, please specify format manually"sv);
+
+    LexicalPath lexical_path { path };
+    auto extension = lexical_path.extension();
+    if (extension.is_empty())
+        return Error::from_string_view("Cannot guess format for file without file extension"sv);
+
+    // Note: Do not return the `extension` StringView in any case, since that will possibly lead to UAF.
+    if (extension == "wav"sv || extension == "wave"sv)
+        return "wav"sv;
+    if (extension == "flac"sv)
+        return "flac"sv;
+    if (extension == "mp3"sv || extension == "mpeg3"sv)
+        return "mp3"sv;
+    if (extension == "qoa"sv)
+        return "qoa"sv;
+
+    return Error::from_string_view("Cannot guess format for the given file extension"sv);
+}
+
+static ErrorOr<Audio::PcmSampleFormat> parse_sample_format(StringView textual_format)
+{
+    if (textual_format == "u8"sv)
+        return Audio::PcmSampleFormat::Uint8;
+    if (textual_format == "s16le"sv)
+        return Audio::PcmSampleFormat::Int16;
+    if (textual_format == "s24le"sv)
+        return Audio::PcmSampleFormat::Int24;
+    if (textual_format == "s32le"sv)
+        return Audio::PcmSampleFormat::Int32;
+    if (textual_format == "f32le"sv)
+        return Audio::PcmSampleFormat::Float32;
+    if (textual_format == "f64le"sv)
+        return Audio::PcmSampleFormat::Float64;
+    return Error::from_string_view("Unknown sample format"sv);
+}
+
+ErrorOr<int> serenity_main(Main::Arguments arguments)
+{
+    TRY(Core::System::pledge("stdio rpath wpath cpath"));
+
+    StringView input {};
+    StringView output {};
+    StringView input_format {};
+    StringView output_format {};
+    StringView output_sample_format;
+
+    Core::ArgsParser args_parser;
+    args_parser.set_general_help("Convert between audio formats");
+    args_parser.add_option(input, "Audio file to convert (or '-' for standard input)", "input", 'i', "input");
+    args_parser.add_option(input_format, "Force input codec and container (see manual for supported codecs and containers)", "input-audio-codec", 0, "input-codec");
+    args_parser.add_option(output_format, "Set output codec", "audio-codec", 0, "output-codec");
+    args_parser.add_option(output_sample_format, "Set output sample format (see manual for supported formats)", "audio-format", 0, "sample-format");
+    args_parser.add_option(output, "Target file (or '-' for standard output)", "output", 'o', "output");
+    args_parser.parse(arguments);
+
+    if (input.is_empty())
+        return Error::from_string_view("Input file is required, use '-' to read from standard input"sv);
+
+    if (output_format.is_empty() && output == "-"sv)
+        return Error::from_string_view("Output format must be specified manually when writing to standard output"sv);
+
+    if (input != "-"sv)
+        TRY(Core::System::unveil(Core::DeprecatedFile::absolute_path(input), "r"sv));
+    if (output != "-"sv)
+        TRY(Core::System::unveil(Core::DeprecatedFile::absolute_path(output), "rwc"sv));
+    TRY(Core::System::unveil(nullptr, nullptr));
+
+    RefPtr<Audio::Loader> input_loader;
+    // Use normal loader infrastructure to guess input format.
+    if (input_format.is_empty()) {
+        auto loader_or_error = Audio::Loader::create(input);
+        if (loader_or_error.is_error()) {
+            warnln("Could not guess codec for input file '{}'. Try forcing a codec with '--i:c:a'", input);
+            return 1;
+        }
+        input_loader = loader_or_error.release_value();
+    } else {
+        warnln("Forcing input codec is not supported");
+        return 1;
+    }
+    VERIFY(input_loader);
+
+    if (output_format.is_empty())
+        output_format = TRY(guess_format_from_extension(output));
+    VERIFY(!output_format.is_empty());
+
+    if (output_format == "wav"sv) {
+        Optional<NonnullOwnPtr<Audio::WavWriter>> writer;
+        if (!output.is_empty()) {
+            auto parsed_output_sample_format = input_loader->pcm_format();
+            if (!output_sample_format.is_empty())
+                parsed_output_sample_format = TRY(parse_sample_format(output_sample_format));
+
+            writer.emplace(TRY(Audio::WavWriter::create_from_file(
+                output,
+                static_cast<int>(input_loader->sample_rate()),
+                input_loader->num_channels(),
+                parsed_output_sample_format)));
+        }
+        if (output != "-"sv)
+            out("Writing: \033[s");
+
+        while (input_loader->loaded_samples() < input_loader->total_samples()) {
+            auto samples_or_error = input_loader->get_more_samples();
+            if (samples_or_error.is_error()) {
+                warnln("Error while loading samples: {} (at {})", samples_or_error.error().description, samples_or_error.error().index);
+                return 1;
+            }
+            auto samples = samples_or_error.release_value();
+            if (writer.has_value())
+                TRY((*writer)->write_samples(samples.span()));
+            // TODO: Show progress updates like aplay by moving the progress calculation into a common utility function.
+            if (output != "-"sv) {
+                out("\033[u{}/{}", input_loader->loaded_samples(), input_loader->total_samples());
+                fflush(stdout);
+            }
+        }
+
+        if (writer.has_value())
+            (*writer)->finalize();
+        if (output != "-"sv)
+            outln();
+    } else {
+        warnln("Codec {} is not supported for encoding", output_format);
+    }
+
+    return 0;
+}