Release 1.8.0

getline may return bytes in a non-ASCII compatible encoding, so it’s safer to look for the key
characters after the conversion than before.

.editorconfig

@@ -0,0 +1,8 @@
+root = true
+
+[*]
+end_of_line = lf
+insert_final_newline = true
+charset = utf-8
+ident_style = tab
+max_line_length = 100

.gitignore

@@ -0,0 +1 @@
+/build

CHANGELOG.md

@@ -0,0 +1,89 @@
+opustags changelog
+==================
+
+1.8.0 - 2023-03-07
+------------------
+
+- Introduce --set-cover and --output-cover.
+
+opustags is now able to extract and edit the cover art of Opus files. The underlying
+METADATA_BLOCK_PICTURE tag will still appear as a regular tag, but you won’t have to handle it
+manually anymore.
+
+1.7.0 - 2023-02-13
+------------------
+
+- Support arbitrary large OpusTags headers.
+- Handle multiline tags by prefixing their continuation lines with tabs.
+
+1.6.0 - 2021-01-01
+------------------
+
+- UTF-8 conversion errors are now fatal.
+- Introduce --raw for disabling encoding conversions.
+- Improve platform compatibility.
+
+This also happens to be opustags’s 8-year anniversary!
+
+1.5.1 - 2020-11-21
+------------------
+
+- Improve BSD support.
+
+1.5.0 - 2020-11-08
+------------------
+
+- Introduce --edit for interactive edition.
+
+1.4.0 - 2020-10-04
+------------------
+
+- Preserve permissions when overwriting files.
+- Support multiple files with --in-place.
+- Fix BSD support.
+
+Thanks to Reuben Thomas for contributing the pièce de résistance of this
+release!
+
+1.3.0 - 2019-02-02
+------------------
+
+- Support for non-Unicode systems. Tags are automatically converted to and from the system locale.
+- It is now possible to delete specific NAME=VALUE pairs.
+- Option `--set-all` is now stricter and aborts with an error if the input is not valid.
+- Printing tags will display a warning if the tags contain control characters.
+
+opustags is now more aware of its limitations, and will print more helpful error messages when
+trying to edit an unsupported file. It is also more cautious against corrupted streams.
+
+1.2.0 - 2018-11-25
+------------------
+
+- Preserve extra data in OpusTags past the comments.
+- Improve error reporting.
+- Fix various bugs.
+
+This is the biggest release for opustags. The whole code base was reviewed for robustness and
+clarity. The program is now built as C++14, and the code refactored without sacrificing the
+original simplicity. It is shipped with a new test suite.
+
+1.1.1 - 2018-10-24
+------------------
+
+- Mac OS X support.
+- Tolerate but truncate the data in the OpusTags packet past the comments.
+
+1.1 - 2013-01-02
+----------------
+
+- Add the --in-place option.
+- Fix a bug is --set-all where the last unterminated line was ignored.
+- Remove broken output files on failure.
+
+1.0 - 2013-01-01
+----------------
+
+This is the first release of opustags. It supports all the main feature for basic tag editing.
+
+It was written in a day, and the code is quick and dirty, though the program is simple and
+efficient.

CMakeLists.txt

@@ -0,0 +1,55 @@
+cmake_minimum_required(VERSION 3.11)
+
+project(
+	opustags
+	VERSION 1.8.0
+	LANGUAGES CXX
+)
+
+set(CMAKE_CXX_STANDARD 20)
+set(CMAKE_CXX_STANDARD_REQUIRED ON)
+
+# opustags is mainly developed with glibc, which introduces a few
+# incompatibilites with BSDs, like getline not being defined by default.
+# _GNU_SOURCE should trigger BSD’s libc GNU compatibility mode to fix that.
+add_definitions(-D_GNU_SOURCE)
+
+find_package(PkgConfig REQUIRED)
+pkg_check_modules(OGG REQUIRED ogg)
+add_compile_options(${OGG_CFLAGS})
+link_directories(${OGG_LIBRARY_DIRS})
+
+include(FindIconv)
+
+# We need endian.h on Linux, and sys/endian.h on BSD.
+include(CheckIncludeFileCXX)
+check_include_file_cxx(endian.h HAVE_ENDIAN_H)
+check_include_file_cxx(sys/endian.h HAVE_SYS_ENDIAN_H)
+
+include(CheckStructHasMember)
+check_struct_has_member("struct stat" st_mtim sys/stat.h HAVE_STAT_ST_MTIM LANGUAGE CXX)
+check_struct_has_member("struct stat" st_mtimespec sys/stat.h HAVE_STAT_ST_MTIMESPEC LANGUAGE CXX)
+
+configure_file(src/config.h.in config.h @ONLY)
+include_directories(BEFORE src "${CMAKE_BINARY_DIR}" ${OGG_INCLUDE_DIRS} ${Iconv_INCLUDE_DIRS})
+
+add_library(
+	ot
+	STATIC
+	src/base64.cc
+	src/cli.cc
+	src/ogg.cc
+	src/opus.cc
+	src/system.cc
+)
+target_link_libraries(ot PUBLIC ${OGG_LIBRARIES} ${Iconv_LIBRARIES})
+
+add_executable(opustags src/opustags.cc)
+target_link_libraries(opustags ot)
+
+include(GNUInstallDirs)
+install(TARGETS opustags DESTINATION "${CMAKE_INSTALL_BINDIR}")
+configure_file(opustags.1 . @ONLY)
+install(FILES "${CMAKE_BINARY_DIR}/opustags.1" DESTINATION "${CMAKE_INSTALL_MANDIR}/man1")
+
+add_subdirectory(t)

CONTRIBUTING.md

@@ -0,0 +1,71 @@
+# Contributing to opustags
+
+opustags should now be mature enough, and contributions for new features are
+welcome.
+
+Before you open a pull request, you might want to talk about the change you'd
+like to make to make sure it's relevant. In that case, feel free to open an
+issue. You can expect a response within a week.
+
+## Submitting pull requests
+
+opustags has nothing really special, so basic git etiquette is just enough.
+
+Please make focused pull requests, one feature at a time. Don't make huge
+commits. Give clear names to your commits and pull requests. Extended
+descriptions are welcome.
+
+Stay objective in your changes. Adding a feature or fixing a bug is a clear
+improvement, but stylistic changes like renaming a function or moving a few
+braces around won't help the project move forward.
+
+You should check that your changes don't break the test suite by running
+`make check`
+
+Following these practices is important to keep the history clean, and to allow
+for better code reviews.
+
+## History of opustags
+
+opustags is originally a small project made to fill a need to edit tags in Opus
+audio files when most taggers didn't support Opus at all. It was written in C
+with libogg, and should be very light and fast compared to most alternatives.
+However, because it was written on a whim, the code is hardly structured and
+might even be fragile, who knows.
+
+An ambitious desire to rewrite it in C++ with bells and whistles gave birth to
+the `next` branch, but sadly it wasn't finalized and is currently not usable,
+though it contains good pieces of code.
+
+With the growing support of Opus in tag editors, the usefulness of opustags was
+questioned, and it was thus abandoned for a few years. Judging by the
+inquiries and contributions, albeit few, on GitHub, it looks like it remains
+relevant, so let's dust it off a bit.
+
+Today, opustags is written in C++ and features a unit test suite in C++, and
+an integration test suite in Perl. The code was refactored, organized into
+modules, and reviewed for safety.
+
+1.3.0 was focused on correctness, and detects edge cases as early as possible,
+instead of hoping something will eventually fail if something is weird.
+
+## Candidate features
+
+The code contains a few `\todo` markers where something could be improved in the
+code.
+
+More generally, here are a few features that could be added in the future:
+
+- Discouraging non-ASCII field names.
+- Logicial stream listing and selection for multiplexed files.
+- Escaping control characters with --escape.
+- Dump binary packets with --binary.
+- Edition of the vendor string.
+- Edition of the arbitrary binary block past the comments.
+- Support for OpusTags packets spanning multiple pages (> 64 kB).
+- Interactive edition of comments inside the EDITOR (--edit).
+- Support for cover arts.
+- Load tags from a file with --set-all=tags.txt.
+- Colored output.
+
+Don't hesitate to contact me before you do anything, I'll give you directions.

LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2013, Frédéric Mangano
+Copyright (c) 2013-2018, Frédéric Mangano-Tarumi
 All rights reserved.
 
 Redistribution and use in source and binary forms, with or without modification,

Makefile

@@ -1,23 +0,0 @@
-DESTDIR=/usr/local
-MANDEST=share/man
-CFLAGS=-Wall
-LDFLAGS=-logg
-
-all: opustags
-
-opustags: opustags.c
-
-man: opustags.1
-	gzip <opustags.1 >opustags.1.gz
-
-install: opustags man
-	mkdir -p $(DESTDIR)/bin $(DESTDIR)/$(MANDEST)/man1
-	install -m 755 opustags $(DESTDIR)/bin/
-	install -m 644 opustags.1.gz $(DESTDIR)/$(MANDEST)/man1/
-
-uninstall:
-	rm -f $(DESTDIR)/bin/opustags
-	rm -f $(DESTDIR)/$(MANDEST)/man1/opustags.1.gz
-
-clean:
-	rm -f opustags opustags.1.gz

README.md

@@ -1,55 +1,69 @@
 opustags
 ========
 
-View and edit Opus comments.
+View and edit Ogg Opus comments.
 
-**Please note this project is old and not actively maintained.**
-Maybe you should use something else.
+opustags supports the following features:
 
-It was built because at the time nothing supported Opus, but now things have
-changed for the better.
+- interactive editing using your preferred text editor,
+- batch editing with command-line flags,
+- tags exporting and importing through text files.
 
-For alternative, check out these projects:
+opustags is designed to be fast and as conservative as possible, to the point that if you edit tags
+then edit them again to their previous values, you should get a bit-perfect copy of the original
+file. No under-the-cover operation like writing "edited with opustags" or timestamp tagging will
+ever be performed.
 
-- [EasyTAG](https://wiki.gnome.org/Apps/EasyTAG)
-- [Beets](http://beets.io/)
-- [Picard](https://picard.musicbrainz.org/)
-- [puddletag](http://docs.puddletag.net/)
-- [Quod Libet](https://quodlibet.readthedocs.io/en/latest/)
-- [Goggles Music Manager](https://gogglesmm.github.io/)
-
-See also these libraries if you need a lower-level access:
-
-- [TagLib](http://taglib.org/)
-- [mutagen](https://mutagen.readthedocs.io/en/latest/)
+opustags is tag-agnostic: you can write arbitrary key-value tags, and none of them will be treated
+specially. After all, common tags like TITLE or ARTIST are nothing more than conventions.
 
 Requirements
 ------------
 
-* A POSIX-compliant system,
-* libogg.
+* a POSIX-compliant system,
+* a C++20 compiler,
+* CMake ≥ 3.11,
+* libogg 1.3.3.
+
+The version numbers are indicative, and it's very likely opustags will build and work fine with
+other versions too, as CMake and libogg are quite mature.
 
 Installing
 ----------
 
+opustags is a commonplace CMake project.
+
+Here's how to install it in your `.local`, under your home:
+
+    mkdir build
+    cd build
+    cmake -DCMAKE_INSTALL_PREFIX=~/.local ..
     make
-    make DESTDIR=/usr/local install
+    make install
+
+Note that you don't need to install opustags in order to run it, as the executable is standalone.
 
 Documentation
 -------------
 
     Usage: opustags --help
            opustags [OPTIONS] FILE
+           opustags OPTIONS -i FILE...
            opustags OPTIONS FILE -o FILE
 
     Options:
-      -h, --help              print this help
-      -o, --output            write the modified tags to a file
-      -y, --overwrite         overwrite the output file if it already exists
-      -d, --delete FIELD      delete all the fields of a specified type
-      -a, --add FIELD=VALUE   add a field
-      -s, --set FIELD=VALUE   delete then add a field
-      -D, --delete-all        delete all the fields!
-      -S, --set-all           read the fields from stdin
+      -h, --help                    print this help
+      -o, --output FILE             specify the output file
+      -i, --in-place                overwrite the input files
+      -y, --overwrite               overwrite the output file if it already exists
+      -a, --add FIELD=VALUE         add a comment
+      -d, --delete FIELD[=VALUE]    delete previously existing comments
+      -D, --delete-all              delete all the previously existing comments
+      -s, --set FIELD=VALUE         replace a comment
+      -S, --set-all                 import comments from standard input
+      -e, --edit                    edit tags interactively in VISUAL/EDITOR
+      --output-cover FILE           extract and save the cover art, if any
+      --set-cover FILE              sets the cover art
+      --raw                         disable encoding conversion
 
 See the man page, `opustags.1`, for extensive documentation.

opustags.1

@@ -1,6 +1,6 @@
-.TH opustags 1 "January 2013"
+.TH opustags 1 "March 2023" "@PROJECT_NAME@ @PROJECT_VERSION@"
 .SH NAME
-opustags \- Opus comment editor
+opustags \- Ogg Opus tag editor
 .SH SYNOPSIS
 .B opustags --help
 .br
@@ -10,77 +10,76 @@ opustags \- Opus comment editor
 .br
 .B opustags
 .I OPTIONS
+.B -i
+.R \fIFILE\fP...
+.br
+.B opustags
+.I OPTIONS
 .B -o
 .I OUTPUT INPUT
 .SH DESCRIPTION
 .PP
-\fBopustags\fP can read and edit the comment header of an Opus file.
-It basically has two modes: read-only and read-write (for tag edition).
+\fBopustags\fP can read and edit the comment header of an Ogg Opus file.
+It has two modes: read-only, and read-write for tag editing.
 .PP
 In read-only mode, only the beginning of \fIINPUT\fP is read, and the tags are
-printed on \fBstdout\fP.
-\fIINPUT\fP can either be the name of a file or \fB-\fP to read from \fBstdin\fP.
+printed on standard output. Lines prefixed by tabs are continuation of the previous tag.
+\fIINPUT\fP can either be the name of a file or \fB-\fP to read from standard input.
 You can use the options below to edit the tags before printing them.
 This could be useful to preview some changes before writing them.
 .PP
-As for the edition mode, you need to specify an output file (or \fB-\fP for
-\fBstdout\fP). It must be different from the input file.
-You may want to use \fB--overwrite\fP if you know what you’re doing.
-To overwrite the input file, use \fB--in-place\fP.
+In editing mode, you need to specify an output file with \fB--output\fP, or use \fB--in-place\fP to
+overwrite the input files. If the output is a regular file, the result is first written to a
+temporary file and then moved to its final location on success. On error, the temporary output file
+is deleted.
 .PP
-Tag edition can be made with the \fB--add\fP, \fB--delete\fP and \fB--set\fP
-options. They can be written in any order and don’t conflict with each other.
-However, they aren’t executed in any order: first the specified tags are
-deleted, then the new tags are added. “Set” operations are mere convenience
-for delete/add.
+Tag editing can be performed with the \fB--add\fP, \fB--delete\fP and \fB--set\fP
+options. Options can be specified in any order and don’t conflict with each other.
+First the specified tags are deleted, then the new tags are added.
 .PP
-You can delete all the tags with \fB--delete-all\fP. This operation can be
-combined with \fB--add\fP to set new tags without being bothered by the old
-ones. Another way to do this is to use \fB--set-all\fP as explained below.
+You can delete all the tags with \fB--delete-all\fP. This operation can be combined with \fB--add\fP
+to set new tags without being bothered by the old ones.
 .PP
-If you want to process tags yourself, you can use the \fB--set-all\fP option
-which will cause \fBopustags\fP to read tags from \fBstdin\fP.
-The format is the same as the one used for output; that is to say,
-newline-separated \fIFIELD=Value\fP assignment. Note that this implies
-\fB--delete-all\fP.
+If you want to replace all the tags, you can use the \fB--set-all\fP option which will cause
+\fBopustags\fP to read tags from standard input.
+The format is the same as the one used for output: newline-separated \fIFIELD=Value\fP assignment.
+All the previously existing tags as deleted.
 .PP
-\fBWarning:\fP the Opus format specifications requires tags to be encoded in
-\fBUTF-8\fP. This tool ignores the system locale, assuming the encoding is
-set to UTF-8, and assume that tags are already encoded in UTF-8.
+The Opus format specifications requires that tags are encoded in UTF-8, so that's the only encoding
+opustags supports. If your system encoding is different, the tags are automatically converted to and
+from your system locale. When you edit an Opus file whose tags contains characters unsupported by
+your system encoding, the original UTF-8 values will be preserved for the tags you don't explictly
+modify.
 .SH OPTIONS
 .TP
 .B \-h, \-\-help
 Display a brief description of the options.
 .TP
 .B \-o, \-\-output \fIFILE\fI
-Edition mode. The input file will be read, its tags edited, then written to the
-specified output file. If \fIFILE\fP is \fB-\fP then the resulting Opus file
-will be written to \fBstdout\fP. As the input file is read incrementally, the
-output file can’t be the same as the input file.
+Specify the output file.
+The input file will be read, its tags edited, then written to the specified output file. If
+\fIFILE\fP is \fB-\fP then the resulting Opus file will be written to standard output.
+The output file can’t be the same as the input file.
 .TP
-.B \-i, \-\-in-place \fR[\fP\fISUFFIX\fP\fR]\fP
-Use this when you want to modify the input file in-place. This creates a
-temporary file with the specified suffix (.otmp by default). This implies
-\fB--overwrite\fP in that if a file with the same temporary name already
-exists, it will be overwritten without warning. Of course, this overwrites
-the input file too. You cannot use this option when the input file is actually
-\fBstdin\fP.
+.B \-i, \-\-in-place
+Overwrite the input file instead of creating a separate output file. It has the same effect as
+setting \fB--output\fP to the same path as the input file and enabling \fB--overwrite\fP.
+This option conflicts with \fB--output\fP.
 .TP
 .B \-y, \-\-overwrite
-By default, \fBopustags\fP refuses to overwrite an already existent file. Use
-this option to allow that. Note that this doesn’t allow in-place edition, the
-output file needs to be different from the input file.
+By default, \fBopustags\fP refuses to overwrite an already-existent file.
+Use \fB-y\fP to allow overwriting.
+Note that this option is not needed when the output is a special file like \fI/dev/null\fP.
 .TP
-.B \-d, \-\-delete \fIFIELD\fP
-Delete all the tags whose field name is \fIFIELD\fP (they may be several, though
-usually there is only one of each type). You can use this option as many times
-as you want.
+.B \-d, \-\-delete \fIFIELD[=VALUE]\fP
+If value is not specified, delete all the tags whose field name is \fIFIELD\fP.
+Otherwise, delete all the comments whose field name is \fIFIELD\fP and value is \fIVALUE\fP.
+In both cases, the field names are case-insensitive, and expected to be ASCII.
 .TP
 .B \-a, \-\-add \fIFIELD=VALUE\fP
-Add a tag. It doesn’t matter if a tag of the same type already exist (think
-the case where there are several artists). You can use this option as many
-times as needed, with the same field names or not. When the \fB--delete\fP
-is used with the same \fIFIELD\fP, only the older tags are deleted.
+Add a tag. Note that multiple tags with the same field name are perfectly acceptable, so you can add
+multiple fields with the same name, and previously existing tags will also be preserved.
+When the \fB--delete\fP is used with the same \fIFIELD\fP, only the older tags are deleted.
 .TP
 .B \-s, \-\-set \fIFIELD=VALUE\fP
 This option is provided for convenience. It delete all the fields of the same
@@ -91,18 +90,80 @@ type. As deletion occurs before adding, \fB--set\fP won’t erase the tags
 added with \fB--add\fP.
 .TP
 .B \-D, \-\-delete-all
-Delete all the tags before adding any. When this option is specified, the
-\fB--delete\fP options are ignored. Tags then can be added using \fB--add\fP
-or \fB--set\fP, which, in that case, are equivalent.
+Delete all the previously existing tags.
 .TP
 .B \-S, \-\-set-all
-Sets the tags from scratch. All the original tags are deleted and new ones are
-read from \fBstdin\fP. Each line must specify a \fIFIELD=VALUE\fP pair and be
-LF-terminated (except for the last line). Invalid lines are skipped and cause
-a warning to be issued. Blank lines are ignored. This mode could be useful for
-batch processing tags through an utility like \fBsed\fP.
-.SH SEE ALSO
-.BR vorbiscomment (1),
-.BR sed (1)
+Sets the tags from scratch.
+All the original tags are deleted and new ones are read from standard input.
+Each line must specify a \fIFIELD=VALUE\fP pair and be separated with line feeds.
+Empty lines and lines starting with \fI#\fP are ignored.
+Multiline tags must have their continuation lines prefixed by a single tab (in other words, every
+\fI\\n\fP must be replaced by \fI\\n\\t\fP).
+.TP
+.B \-e, \-\-edit
+Edit tags interactively by spawning the program specified by the EDITOR
+environment variable. The allowed format is the same as \fB--set-all\fP.
+If TERM and VISUAL are set, VISUAL takes precedence over EDITOR.
+.TP
+.B \-\-output-cover \fIFILE\fP
+Save the cover art of the input Opus file to the specified location.
+If the input file does not contain any cover art, this option has no effect.
+To allow overwriting the target location, specify \fB--overwrite\fP.
+In the case of multiple pictures embedded in the Opus tags, only the first one is saved.
+Note that the since the image format is not fixed, you should consider an extension-less file name
+and rely on the magic number to deduce the type. opustags does not add or check the target file’s
+extension.
+You can specify \fB-\fP for standard output, in which case the regular output will be suppressed.
+.TP
+.B \-\-set-cover \fIFILE\fP
+Replace or set the cover art to the specified picture.
+Specify \fB-\fP to read the picture from standard input.
+In theory, an Opus file may contain multiple pictures with different roles, though in practice only
+the front cover really matters. opustags can currently only handle one front cover and nothing else.
+.TP
+.B \-\-raw
+OpusTags metadata should always be encoded in UTF-8, as per RFC 7845. However, some files may be
+corrupted or possibly even contain intentional binary data. In that case, --raw lets you edit that
+kind of binary data without ensuring the validity of the tags encoding. This option may also be
+useful when your system encoding is different from UTF-8 and you wish to preserve the full UTF-8
+character set even though your system cannot display it.
+.SH EXAMPLES
+.PP
+List all the tags in file foo.opus:
+.PP
+	opustags foo.opus
+.PP
+Copy in.opus to out.opus, with the TITLE tag added:
+.PP
+	opustags in.opus --output out.opus --add "TITLE=Hello world!"
+.PP
+Replace all the tags in dest.opus with the ones from src.opus:
+.PP
+	opustags src.opus | opustags --in-place dest.opus --set-all
+.PP
+Remove the previously existing ARTIST tags and add the two X and Y ARTIST tags, then display the new
+tags without writing them to the Opus file:
+.PP
+	opustags in.opus --add ARTIST=X --add ARTIST=Y --delete ARTIST
+.PP
+Edit tags interactively in Vim:
+.PP
+	EDITOR=vim opustags --in-place --edit file.opus
+.SH CAVEATS
+.PP
+\fBopustags\fP currently has the following limitations:
+.IP \[bu]
+Multiplexed streams are not supported.
+.IP \[bu]
+Control characters inside tags are printed raw rather than being escaped.
+.PP
+Internally, the OpusTags packet in an Ogg Opus file may contain extra arbitrary binary data after
+the comments.  This block of data is currently not editable, but is always preserved. The same
+applies for the vendor string.
+.PP
+If you need a feature not currently supported, feel free to open an issue or send an email with your
+use case.
 .SH AUTHOR
-Frédéric Mangano <fmang@mg0.fr>
+Frédéric Mangano <fmang+opustags@mg0.fr>
+.PP
+Report bugs at <https://github.com/fmang/opustags/issues>

opustags.c

@@ -1,513 +0,0 @@
-#include <errno.h>
-#include <getopt.h>
-#include <limits.h>
-#include <stdio.h>
-#include <stdlib.h>
-#include <string.h>
-#include <unistd.h>
-#include <ogg/ogg.h>
-
-#ifdef __APPLE__
-#include <libkern/OSByteOrder.h>
-#define htole32(x) OSSwapHostToLittleInt32(x)
-#define le32toh(x) OSSwapLittleToHostInt32(x)
-#endif
-
-typedef struct {
-    uint32_t vendor_length;
-    const char *vendor_string;
-    uint32_t count;
-    uint32_t *lengths;
-    const char **comment;
-} opus_tags;
-
-int parse_tags(char *data, long len, opus_tags *tags){
-    long pos;
-    if(len < 8+4+4)
-        return -1;
-    if(strncmp(data, "OpusTags", 8) != 0)
-        return -1;
-    // Vendor
-    pos = 8;
-    tags->vendor_length = le32toh(*((uint32_t*) (data + pos)));
-    tags->vendor_string = data + pos + 4;
-    pos += 4 + tags->vendor_length;
-    if(pos + 4 > len)
-        return -1;
-    // Count
-    tags->count = le32toh(*((uint32_t*) (data + pos)));
-    if(tags->count == 0)
-        return 0;
-    tags->lengths = calloc(tags->count, sizeof(uint32_t));
-    if(tags->lengths == NULL)
-        return -1;
-    tags->comment = calloc(tags->count, sizeof(char*));
-    if(tags->comment == NULL){
-        free(tags->lengths);
-        return -1;
-    }
-    pos += 4;
-    // Comment
-    uint32_t i;
-    for(i=0; i<tags->count; i++){
-        tags->lengths[i] = le32toh(*((uint32_t*) (data + pos)));
-        tags->comment[i] = data + pos + 4;
-        pos += 4 + tags->lengths[i];
-        if(pos > len)
-            return -1;
-    }
-
-    if(pos < len)
-        fprintf(stderr, "warning: %ld unused bytes at the end of the OpusTags packet\n", len - pos);
-
-    return 0;
-}
-
-int render_tags(opus_tags *tags, ogg_packet *op){
-    // Note: op->packet must be manually freed.
-    op->b_o_s = 0;
-    op->e_o_s = 0;
-    op->granulepos = 0;
-    op->packetno = 1;
-    long len = 8 + 4 + tags->vendor_length + 4;
-    uint32_t i;
-    for(i=0; i<tags->count; i++)
-        len += 4 + tags->lengths[i];
-    op->bytes = len;
-    char *data = malloc(len);
-    if(!data)
-        return -1;
-    op->packet = (unsigned char*) data;
-    uint32_t n;
-    memcpy(data, "OpusTags", 8);
-    n = htole32(tags->vendor_length);
-    memcpy(data+8, &n, 4);
-    memcpy(data+12, tags->vendor_string, tags->vendor_length);
-    data += 12 + tags->vendor_length;
-    n = htole32(tags->count);
-    memcpy(data, &n, 4);
-    data += 4;
-    for(i=0; i<tags->count; i++){
-        n = htole32(tags->lengths[i]);
-        memcpy(data, &n, 4);
-        memcpy(data+4, tags->comment[i], tags->lengths[i]);
-        data += 4 + tags->lengths[i];
-    }
-    return 0;
-}
-
-int match_field(const char *comment, uint32_t len, const char *field){
-    size_t field_len;
-    for(field_len = 0; field[field_len] != '\0' && field[field_len] != '='; field_len++);
-    if(len <= field_len)
-        return 0;
-    if(comment[field_len] != '=')
-        return 0;
-    if(strncmp(comment, field, field_len) != 0)
-        return 0;
-    return 1;
-
-}
-
-void delete_tags(opus_tags *tags, const char *field){
-    uint32_t i;
-    for(i=0; i<tags->count; i++){
-        if(match_field(tags->comment[i], tags->lengths[i], field)){
-            tags->count--;
-            tags->lengths[i] = tags->lengths[tags->count];
-            tags->comment[i] = tags->comment[tags->count];
-            // No need to resize the arrays.
-        }
-    }
-}
-
-int add_tags(opus_tags *tags, const char **tags_to_add, uint32_t count){
-    if(count == 0)
-        return 0;
-    uint32_t *lengths = realloc(tags->lengths, (tags->count + count) * sizeof(uint32_t));
-    const char **comment = realloc(tags->comment, (tags->count + count) * sizeof(char*));
-    if(lengths == NULL || comment == NULL)
-        return -1;
-    tags->lengths = lengths;
-    tags->comment = comment;
-    uint32_t i;
-    for(i=0; i<count; i++){
-        tags->lengths[tags->count + i] = strlen(tags_to_add[i]);
-        tags->comment[tags->count + i] = tags_to_add[i];
-    }
-    tags->count += count;
-    return 0;
-}
-
-void print_tags(opus_tags *tags){
-    if(tags->count == 0)
-        puts("no tags");
-    int i;
-    for(i=0; i<tags->count; i++){
-        fwrite(tags->comment[i], 1, tags->lengths[i], stdout);
-        puts("");
-    }
-}
-
-void free_tags(opus_tags *tags){
-    if(tags->count > 0){
-        free(tags->lengths);
-        free(tags->comment);
-    }
-}
-
-int write_page(ogg_page *og, FILE *stream){
-    if(fwrite(og->header, 1, og->header_len, stream) < og->header_len)
-        return -1;
-    if(fwrite(og->body, 1, og->body_len, stream) < og->body_len)
-        return -1;
-    return 0;
-}
-
-const char *version = "opustags version 1.1.1\n";
-
-const char *usage =
-    "Usage: opustags --help\n"
-    "       opustags [OPTIONS] FILE\n"
-    "       opustags OPTIONS FILE -o FILE\n";
-
-const char *help =
-    "Options:\n"
-    "  -h, --help              print this help\n"
-    "  -o, --output            write the modified tags to a file\n"
-    "  -i, --in-place [SUFFIX] use a temporary file then replace the original file\n"
-    "  -y, --overwrite         overwrite the output file if it already exists\n"
-    "  -d, --delete FIELD      delete all the fields of a specified type\n"
-    "  -a, --add FIELD=VALUE   add a field\n"
-    "  -s, --set FIELD=VALUE   delete then add a field\n"
-    "  -D, --delete-all        delete all the fields!\n"
-    "  -S, --set-all           read the fields from stdin\n";
-
-struct option options[] = {
-    {"help", no_argument, 0, 'h'},
-    {"output", required_argument, 0, 'o'},
-    {"in-place", optional_argument, 0, 'i'},
-    {"overwrite", no_argument, 0, 'y'},
-    {"delete", required_argument, 0, 'd'},
-    {"add", required_argument, 0, 'a'},
-    {"set", required_argument, 0, 's'},
-    {"delete-all", no_argument, 0, 'D'},
-    {"set-all", no_argument, 0, 'S'},
-    {NULL, 0, 0, 0}
-};
-
-int main(int argc, char **argv){
-    if(argc == 1){
-        fputs(version, stdout);
-        fputs(usage, stdout);
-        return EXIT_SUCCESS;
-    }
-    char *path_in, *path_out = NULL, *inplace = NULL;
-    const char* to_add[argc];
-    const char* to_delete[argc];
-    int count_add = 0, count_delete = 0;
-    int delete_all = 0;
-    int set_all = 0;
-    int overwrite = 0;
-    int print_help = 0;
-    int c;
-    while((c = getopt_long(argc, argv, "ho:i::yd:a:s:DS", options, NULL)) != -1){
-        switch(c){
-            case 'h':
-                print_help = 1;
-                break;
-            case 'o':
-                path_out = optarg;
-                break;
-            case 'i':
-                inplace = optarg == NULL ? ".otmp" : optarg;
-                break;
-            case 'y':
-                overwrite = 1;
-                break;
-            case 'd':
-                if(strchr(optarg, '=') != NULL){
-                    fprintf(stderr, "invalid field: '%s'\n", optarg);
-                    return EXIT_FAILURE;
-                }
-                to_delete[count_delete++] = optarg;
-                break;
-            case 'a':
-            case 's':
-                if(strchr(optarg, '=') == NULL){
-                    fprintf(stderr, "invalid comment: '%s'\n", optarg);
-                    return EXIT_FAILURE;
-                }
-                to_add[count_add++] = optarg;
-                if(c == 's')
-                    to_delete[count_delete++] = optarg;
-                break;
-            case 'S':
-                set_all = 1;
-            case 'D':
-                delete_all = 1;
-                break;
-            default:
-                return EXIT_FAILURE;
-        }
-    }
-    if(print_help){
-        puts(version);
-        puts(usage);
-        puts(help);
-        puts("See the man page for extensive documentation.");
-        return EXIT_SUCCESS;
-    }
-    if(optind != argc - 1){
-        fputs("invalid arguments\n", stderr);
-        return EXIT_FAILURE;
-    }
-    if(inplace && path_out){
-        fputs("cannot combine --in-place and --output\n", stderr);
-        return EXIT_FAILURE;
-    }
-    path_in = argv[optind];
-    if(path_out != NULL && strcmp(path_in, "-") != 0){
-        char canon_in[PATH_MAX+1], canon_out[PATH_MAX+1];
-        if(realpath(path_in, canon_in) && realpath(path_out, canon_out)){
-            if(strcmp(canon_in, canon_out) == 0){
-                fputs("error: the input and output files are the same\n", stderr);
-                return EXIT_FAILURE;
-            }
-        }
-    }
-    FILE *in;
-    if(strcmp(path_in, "-") == 0){
-        if(set_all){
-            fputs("can't open stdin for input when -S is specified\n", stderr);
-            return EXIT_FAILURE;
-        }
-        if(inplace){
-            fputs("cannot modify stdin 'in-place'\n", stderr);
-            return EXIT_FAILURE;
-        }
-        in = stdin;
-    }
-    else
-        in = fopen(path_in, "r");
-    if(!in){
-        perror("fopen");
-        return EXIT_FAILURE;
-    }
-    FILE *out = NULL;
-    if(inplace != NULL){
-        path_out = malloc(strlen(path_in) + strlen(inplace) + 1);
-        if(path_out == NULL){
-            fputs("failure to allocate memory\n", stderr);
-            fclose(in);
-            return EXIT_FAILURE;
-        }
-        strcpy(path_out, path_in);
-        strcat(path_out, inplace);
-    }
-    if(path_out != NULL){
-        if(strcmp(path_out, "-") == 0)
-            out = stdout;
-        else{
-            if(!overwrite && !inplace){
-                if(access(path_out, F_OK) == 0){
-                    fprintf(stderr, "'%s' already exists (use -y to overwrite)\n", path_out);
-                    fclose(in);
-                    return EXIT_FAILURE;
-                }
-            }
-            out = fopen(path_out, "w");
-            if(!out){
-                perror("fopen");
-                fclose(in);
-                if(inplace)
-                    free(path_out);
-                return EXIT_FAILURE;
-            }
-        }
-    }
-    ogg_sync_state oy;
-    ogg_stream_state os, enc;
-    ogg_page og;
-    ogg_packet op;
-    opus_tags tags;
-    ogg_sync_init(&oy);
-    char *buf;
-    size_t len;
-    char *error = NULL;
-    int packet_count = -1;
-    while(error == NULL){
-        // Read until we complete a page.
-        if(ogg_sync_pageout(&oy, &og) != 1){
-            if(feof(in))
-                break;
-            buf = ogg_sync_buffer(&oy, 65536);
-            if(buf == NULL){
-                error = "ogg_sync_buffer: out of memory";
-                break;
-            }
-            len = fread(buf, 1, 65536, in);
-            if(ferror(in))
-                error = strerror(errno);
-            ogg_sync_wrote(&oy, len);
-            if(ogg_sync_check(&oy) != 0)
-                error = "ogg_sync_check: internal error";
-            continue;
-        }
-        // We got a page.
-        // Short-circuit when the relevant packets have been read.
-        if(packet_count >= 2 && out){
-            if(write_page(&og, out) == -1){
-                error = "write_page: fwrite error";
-                break;
-            }
-            continue;
-        }
-        // Initialize the streams from the first page.
-        if(packet_count == -1){
-            if(ogg_stream_init(&os, ogg_page_serialno(&og)) == -1){
-                error = "ogg_stream_init: couldn't create a decoder";
-                break;
-            }
-            if(out){
-                if(ogg_stream_init(&enc, ogg_page_serialno(&og)) == -1){
-                    error = "ogg_stream_init: couldn't create an encoder";
-                    break;
-                }
-            }
-            packet_count = 0;
-        }
-        if(ogg_stream_pagein(&os, &og) == -1){
-            error = "ogg_stream_pagein: invalid page";
-            break;
-        }
-        // Read all the packets.
-        while(ogg_stream_packetout(&os, &op) == 1){
-            packet_count++;
-            if(packet_count == 1){ // Identification header
-                if(strncmp((char*) op.packet, "OpusHead", 8) != 0){
-                    error = "opustags: invalid identification header";
-                    break;
-                }
-            }
-            else if(packet_count == 2){ // Comment header
-                if(parse_tags((char*) op.packet, op.bytes, &tags) == -1){
-                    error = "opustags: invalid comment header";
-                    break;
-                }
-                if(delete_all)
-                    tags.count = 0;
-                else{
-                    int i;
-                    for(i=0; i<count_delete; i++)
-                        delete_tags(&tags, to_delete[i]);
-                }
-                char *raw_tags = NULL;
-                if(set_all){
-                    raw_tags = malloc(16384);
-                    if(raw_tags == NULL){
-                        error = "malloc: not enough memory for buffering stdin";
-                        free(raw_tags);
-                        break;
-                    }
-                    else{
-                        char *raw_comment[256];
-                        size_t raw_len = fread(raw_tags, 1, 16383, stdin);
-                        if(raw_len == 16383)
-                            fputs("warning: truncating comment to 16 KiB\n", stderr);
-                        raw_tags[raw_len] = '\0';
-                        uint32_t raw_count = 0;
-                        size_t field_len = 0;
-                        int caught_eq = 0;
-                        size_t i = 0;
-                        char *cursor = raw_tags;
-                        for(i=0; i <= raw_len && raw_count < 256; i++){
-                            if(raw_tags[i] == '\n' || raw_tags[i] == '\0'){
-                                if(field_len == 0)
-                                    continue;
-                                if(caught_eq)
-                                    raw_comment[raw_count++] = cursor;
-                                else
-                                    fputs("warning: skipping malformed tag\n", stderr);
-                                cursor = raw_tags + i + 1;
-                                field_len = 0;
-                                caught_eq = 0;
-                                raw_tags[i] = '\0';
-                                continue;
-                            }
-                            if(raw_tags[i] == '=')
-                                caught_eq = 1;
-                            field_len++;
-                        }
-                        add_tags(&tags, (const char**) raw_comment, raw_count);
-                    }
-                }
-                add_tags(&tags, to_add, count_add);
-                if(out){
-                    ogg_packet packet;
-                    render_tags(&tags, &packet);
-                    if(ogg_stream_packetin(&enc, &packet) == -1)
-                        error = "ogg_stream_packetin: internal error";
-                    free(packet.packet);
-                }
-                else
-                    print_tags(&tags);
-                free_tags(&tags);
-                if(raw_tags)
-                    free(raw_tags);
-                if(error || !out)
-                    break;
-                else
-                    continue;
-            }
-            if(out){
-                if(ogg_stream_packetin(&enc, &op) == -1){
-                    error = "ogg_stream_packetin: internal error";
-                    break;
-                }
-            }
-        }
-        if(error != NULL)
-            break;
-        if(ogg_stream_check(&os) != 0)
-            error = "ogg_stream_check: internal error (decoder)";
-        // Write the page.
-        if(out){
-            ogg_stream_flush(&enc, &og);
-            if(write_page(&og, out) == -1)
-                error = "write_page: fwrite error";
-            else if(ogg_stream_check(&enc) != 0)
-                error = "ogg_stream_check: internal error (encoder)";
-        }
-        else if(packet_count >= 2) // Read-only mode
-            break;
-    }
-    if(packet_count >= 0){
-        ogg_stream_clear(&os);
-        if(out)
-            ogg_stream_clear(&enc);
-    }
-    ogg_sync_clear(&oy);
-    fclose(in);
-    if(out)
-        fclose(out);
-    if(!error && packet_count < 2)
-        error = "opustags: invalid file";
-    if(error){
-        fprintf(stderr, "%s\n", error);
-        if(path_out != NULL && out != stdout)
-            remove(path_out);
-        if(inplace)
-            free(path_out);
-        return EXIT_FAILURE;
-    }
-    else if(inplace){
-        if(rename(path_out, path_in) == -1){
-            perror("rename");
-            free(path_out);
-            return EXIT_FAILURE;
-        }
-        free(path_out);
-    }
-    return EXIT_SUCCESS;
-}

src/base64.cc

@@ -0,0 +1,97 @@
+/**
+ * \file src/base64.cc
+ * \brief Base64 encoding/decoding (RFC 4648).
+ *
+ * Inspired by Jouni Malinen’s BSD implementation at
+ * <http://web.mit.edu/freebsd/head/contrib/wpa/src/utils/base64.c>.
+ *
+ * This implementation is used to decode the cover arts embedded in the tags. According to
+ * <https://wiki.xiph.org/VorbisComment>, line feeds are not allowed and padding is required.
+ */
+
+#include <opustags.h>
+
+#include <string.h>
+
+static const char8_t base64_table[65] =
+	u8"ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
+
+std::u8string ot::encode_base64(ot::byte_string_view src)
+{
+	size_t len = src.size();
+	size_t num_blocks = (len + 2) / 3; // Count of 3-byte blocks, rounded up.
+	size_t olen = num_blocks * 4; // Each 3-byte block becomes 4 base64 bytes.
+	if (olen < len)
+		throw std::overflow_error("failed to encode excessively long base64 block");
+
+	std::u8string out;
+	out.resize(olen);
+
+	const uint8_t* in = src.data();
+	const uint8_t* end = in + len;
+	char8_t* pos = out.data();
+	while (end - in >= 3) {
+		*pos++ = base64_table[in[0] >> 2];
+		*pos++ = base64_table[((in[0] & 0x03) << 4) | (in[1] >> 4)];
+		*pos++ = base64_table[((in[1] & 0x0f) << 2) | (in[2] >> 6)];
+		*pos++ = base64_table[in[2] & 0x3f];
+		in += 3;
+	}
+
+	if (end - in) {
+		*pos++ = base64_table[in[0] >> 2];
+		if (end - in == 1) {
+			*pos++ = base64_table[(in[0] & 0x03) << 4];
+			*pos++ = '=';
+		} else { // end - in == 2
+			*pos++ = base64_table[((in[0] & 0x03) << 4) | (in[1] >> 4)];
+			*pos++ = base64_table[(in[1] & 0x0f) << 2];
+		}
+		*pos++ = '=';
+	}
+
+	return out;
+}
+
+ot::byte_string ot::decode_base64(std::u8string_view src)
+{
+	// Remove the padding and rely on the string length instead.
+	while (src.back() == u8'=')
+		src.remove_suffix(1);
+
+	size_t olen = src.size() / 4 * 3; // Whole blocks;
+	switch (src.size() % 4) {
+		case 1: throw status {st::error, "invalid base64 block size"};
+		case 2: olen += 1; break;
+		case 3: olen += 2; break;
+	}
+
+	ot::byte_string out;
+	out.resize(olen);
+	uint8_t* pos = out.data();
+
+	unsigned char dtable[256];
+	memset(dtable, 0x80, 256);
+	for (size_t i = 0; i < sizeof(base64_table) - 1; ++i)
+		dtable[(size_t) base64_table[i]] = (unsigned char) i;
+
+	unsigned char block[4];
+	size_t count = 0;
+	for (unsigned char c : src) {
+		unsigned char tmp = dtable[c];
+		if (tmp == 0x80)
+			throw status {st::error, "invalid base64 character"};
+
+		block[count++] = tmp;
+		if (count == 2) {
+			*pos++ = (block[0] << 2) | (block[1] >> 4);
+		} else if (count == 3) {
+			*pos++ = (block[1] << 4) | (block[2] >> 2);
+		} else if (count == 4) {
+			*pos++ = (block[2] << 6) | block[3];
+			count = 0;
+		}
+	}
+
+	return out;
+}

src/cli.cc

@@ -0,0 +1,602 @@
+/**
+ * \file src/cli.cc
+ * \ingroup cli
+ *
+ * Provide all the features of the opustags executable from a C++ API. The main point of separating
+ * this module from the main one is to allow easy testing.
+ */
+
+#include <opustags.h>
+
+#include <errno.h>
+#include <getopt.h>
+#include <limits.h>
+#include <stdlib.h>
+#include <string.h>
+#include <sys/stat.h>
+#include <unistd.h>
+
+static const char help_message[] =
+PROJECT_NAME " version " PROJECT_VERSION
+R"raw(
+
+Usage: opustags --help
+       opustags [OPTIONS] FILE
+       opustags OPTIONS -i FILE...
+       opustags OPTIONS FILE -o FILE
+
+Options:
+  -h, --help                    print this help
+  -o, --output FILE             specify the output file
+  -i, --in-place                overwrite the input files
+  -y, --overwrite               overwrite the output file if it already exists
+  -a, --add FIELD=VALUE         add a comment
+  -d, --delete FIELD[=VALUE]    delete previously existing comments
+  -D, --delete-all              delete all the previously existing comments
+  -s, --set FIELD=VALUE         replace a comment
+  -S, --set-all                 import comments from standard input
+  -e, --edit                    edit tags interactively in VISUAL/EDITOR
+  --output-cover FILE           extract and save the cover art, if any
+  --set-cover FILE              sets the cover art
+  --raw                         disable encoding conversion
+
+See the man page for extensive documentation.
+)raw";
+
+static struct option getopt_options[] = {
+	{"help", no_argument, 0, 'h'},
+	{"output", required_argument, 0, 'o'},
+	{"in-place", optional_argument, 0, 'i'},
+	{"overwrite", no_argument, 0, 'y'},
+	{"delete", required_argument, 0, 'd'},
+	{"add", required_argument, 0, 'a'},
+	{"set", required_argument, 0, 's'},
+	{"delete-all", no_argument, 0, 'D'},
+	{"set-all", no_argument, 0, 'S'},
+	{"edit", no_argument, 0, 'e'},
+	{"output-cover", required_argument, 0, 'c'},
+	{"set-cover", required_argument, 0, 'C'},
+	{"raw", no_argument, 0, 'r'},
+	{NULL, 0, 0, 0}
+};
+
+ot::options ot::parse_options(int argc, char** argv, FILE* comments_input)
+{
+	options opt;
+	const char* equal;
+	ot::status rc;
+	std::list<std::string> local_to_add; // opt.to_add before UTF-8 conversion.
+	std::list<std::string> local_to_delete; // opt.to_delete before UTF-8 conversion.
+	bool set_all = false;
+	std::optional<std::string> set_cover;
+	opt = {};
+	if (argc == 1)
+		throw status {st::bad_arguments, "No arguments specified. Use -h for help."};
+	int c;
+	optind = 0;
+	while ((c = getopt_long(argc, argv, ":ho:iyd:a:s:DSe", getopt_options, NULL)) != -1) {
+		switch (c) {
+		case 'h':
+			opt.print_help = true;
+			break;
+		case 'o':
+			if (opt.path_out)
+				throw status {st::bad_arguments, "Cannot specify --output more than once."};
+			opt.path_out = optarg;
+			break;
+		case 'i':
+			opt.in_place = true;
+			opt.overwrite = true;
+			break;
+		case 'y':
+			opt.overwrite = true;
+			break;
+		case 'd':
+			local_to_delete.emplace_back(optarg);
+			break;
+		case 'a':
+		case 's':
+			equal = strchr(optarg, '=');
+			if (equal == nullptr)
+				throw status {st::bad_arguments, "Comment does not contain an equal sign: "s + optarg + "."};
+			if (c == 's')
+				local_to_delete.emplace_back(optarg, equal - optarg);
+			local_to_add.emplace_back(optarg);
+			break;
+		case 'S':
+			opt.delete_all = true;
+			set_all = true;
+			break;
+		case 'D':
+			opt.delete_all = true;
+			break;
+		case 'e':
+			opt.edit_interactively = true;
+			break;
+		case 'c':
+			if (opt.cover_out)
+				throw status {st::bad_arguments, "Cannot specify --output-cover more than once."};
+			opt.cover_out = optarg;
+			break;
+		case 'C':
+			if (set_cover)
+				throw status {st::bad_arguments, "Cannot specify --set-cover more than once."};
+			set_cover = optarg;
+			break;
+		case 'r':
+			opt.raw = true;
+			break;
+		case ':':
+			throw status {st::bad_arguments, "Missing value for option '"s + argv[optind - 1] + "'."};
+		default:
+			throw status {st::bad_arguments, "Unrecognized option '" +
+			              (optopt ? "-"s + static_cast<char>(optopt) : argv[optind - 1]) + "'."};
+		}
+	}
+	if (opt.print_help)
+		return opt;
+
+	// All non-option arguments are input files.
+	size_t stdin_uses = 0;
+	for (int i = optind; i < argc; i++) {
+		if (strcmp(argv[i], "-") == 0)
+			++stdin_uses;
+		opt.paths_in.emplace_back(argv[i]);
+	}
+	bool stdin_as_input = stdin_uses > 0;
+
+	if (set_cover == "-")
+		++stdin_uses;
+	if (set_all)
+		++stdin_uses;
+	if (stdin_uses > 1)
+		throw status { st::bad_arguments, "Cannot use standard input more than once." };
+
+	// Convert arguments to UTF-8.
+	if (opt.raw) {
+		// Cast the user data without any encoding conversion.
+		auto cast_to_utf8 = [](std::string_view in)
+			{ return std::u8string(reinterpret_cast<const char8_t*>(in.data()), in.size()); };
+		std::transform(local_to_add.begin(), local_to_add.end(),
+			       std::back_inserter(opt.to_add), cast_to_utf8);
+		std::transform(local_to_delete.begin(), local_to_delete.end(),
+			       std::back_inserter(opt.to_delete), cast_to_utf8);
+	} else {
+		try {
+			std::transform(local_to_add.begin(), local_to_add.end(),
+			               std::back_inserter(opt.to_add), encode_utf8);
+			std::transform(local_to_delete.begin(), local_to_delete.end(),
+			               std::back_inserter(opt.to_delete), encode_utf8);
+		} catch (const ot::status& rc) {
+			throw status {st::bad_arguments, "Could not encode argument into UTF-8: " + rc.message};
+		}
+	}
+
+	if (opt.in_place && opt.path_out)
+		throw status {st::bad_arguments, "Cannot combine --in-place and --output."};
+
+	if (opt.in_place && stdin_as_input)
+		throw status {st::bad_arguments, "Cannot modify standard input in place."};
+
+	if ((!opt.in_place || opt.edit_interactively) && opt.paths_in.size() != 1)
+		throw status {st::bad_arguments, "Exactly one input file must be specified."};
+
+	if (opt.edit_interactively && (stdin_as_input || opt.path_out == "-" || opt.cover_out == "-"))
+		throw status {st::bad_arguments, "Cannot edit interactively when standard input or standard output are already used."};
+
+	if (opt.edit_interactively && !opt.path_out.has_value() && !opt.in_place)
+		throw status {st::bad_arguments, "Cannot edit interactively when no output is specified."};
+
+	if (opt.edit_interactively && (opt.delete_all || !opt.to_add.empty() || !opt.to_delete.empty()))
+		throw status {st::bad_arguments, "Cannot mix --edit with -adDsS."};
+
+	if (opt.cover_out == "-" && opt.path_out == "-")
+		throw status {st::bad_arguments, "Cannot specify standard output for both --output and --output-cover."};
+
+	if (opt.cover_out && opt.paths_in.size() > 1)
+		throw status {st::bad_arguments, "Cannot use --output-cover with multiple input files."};
+
+	if (set_cover) {
+		byte_string picture_data = ot::slurp_binary_file(set_cover->c_str());
+		opt.to_delete.push_back(u8"METADATA_BLOCK_PICTURE"s);
+		opt.to_add.push_back(ot::make_cover(picture_data));
+	}
+
+	if (set_all) {
+		// Read comments from stdin and prepend them to opt.to_add.
+		std::list<std::u8string> comments = read_comments(comments_input, opt.raw);
+		opt.to_add.splice(opt.to_add.begin(), std::move(comments));
+	}
+	return opt;
+}
+
+/** Format a UTF-8 string by adding tabulations (\t) after line feeds (\n) to mark continuation for
+ *  multiline values. */
+static std::u8string format_value(const std::u8string& source)
+{
+	auto newline_count = std::count(source.begin(), source.end(), u8'\n');
+
+	// General case: the value fits on a single line. Use std::string’s copy constructor for the
+	// most efficient copy we could hope for.
+	if (newline_count == 0)
+		return source;
+
+	std::u8string formatted;
+	formatted.reserve(source.size() + newline_count);
+	for (auto c : source) {
+		formatted.push_back(c);
+		if (c == '\n')
+			formatted.push_back(u8'\t');
+	}
+	return formatted;
+}
+
+/**
+ * Print comments in a human readable format that can also be read back in by #read_comment.
+ *
+ * To disambiguate between a newline embedded in a comment and a newline representing the start of
+ * the next tag, continuation lines always have a single TAB (^I) character added to the beginning.
+ */
+void ot::print_comments(const std::list<std::u8string>& comments, FILE* output, bool raw)
+{
+	bool has_control = false;
+	for (const std::u8string& source_comment : comments) {
+		if (!has_control) { // Don’t bother analyzing comments if the flag is already up.
+			for (unsigned char c : source_comment) {
+				if (c < 0x20 && c != '\n') {
+					has_control = true;
+					break;
+				}
+			}
+		}
+
+		std::u8string utf8_comment = format_value(source_comment);
+		// Convert the comment from UTF-8 to the system encoding if relevant.
+		if (raw) {
+			fwrite(utf8_comment.data(), 1, utf8_comment.size(), output);
+		} else {
+			try {
+				std::string local = decode_utf8(utf8_comment);
+				fwrite(local.data(), 1, local.size(), output);
+			} catch (ot::status& rc) {
+				rc.message += " See --raw.";
+				throw;
+			}
+		}
+		putc('\n', output);
+	}
+	if (has_control)
+		fputs("warning: Some tags contain control characters.\n", stderr);
+}
+
+std::list<std::u8string> ot::read_comments(FILE* input, bool raw)
+{
+	std::list<std::u8string> comments;
+	comments.clear();
+	char* source_line = nullptr;
+	size_t buflen = 0;
+	ssize_t nread;
+	std::u8string* previous_comment = nullptr;
+	while ((nread = getline(&source_line, &buflen, input)) != -1) {
+		if (nread > 0 && source_line[nread - 1] == '\n')
+			--nread; // Chomp.
+
+		std::u8string line;
+		if (raw) {
+			line = std::u8string(reinterpret_cast<char8_t*>(source_line), nread);
+		} else {
+			try {
+				line = encode_utf8(std::string_view(source_line, nread));
+			} catch (const ot::status& rc) {
+				free(source_line);
+				throw ot::status {ot::st::badly_encoded, "UTF-8 conversion error: " + rc.message};
+			}
+		}
+
+		if (line.empty()) {
+			// Ignore empty lines.
+			previous_comment = nullptr;
+		} else if (line[0] == u8'#') {
+			// Ignore comments.
+			previous_comment = nullptr;
+		} else if (line[0] == u8'\t') {
+			// Continuation line: append the current line to the previous tag.
+			if (previous_comment == nullptr) {
+				ot::status rc = {ot::st::error, "Unexpected continuation line: " + std::string(source_line, nread)};
+				free(source_line);
+				throw rc;
+			} else {
+				line[0] = '\n';
+				previous_comment->append(line);
+			}
+		} else if (line.find(u8'=') == decltype(line)::npos) {
+			ot::status rc = {ot::st::error, "Malformed tag: " + std::string(source_line, nread)};
+			free(source_line);
+			throw rc;
+		} else {
+			previous_comment = &comments.emplace_back(std::move(line));
+		}
+	}
+	free(source_line);
+	return comments;
+}
+
+void ot::delete_comments(std::list<std::u8string>& comments, const std::u8string& selector)
+{
+	auto name = selector.data();
+	auto equal = selector.find(u8'=');
+	auto value = (equal == std::u8string::npos ? nullptr : name + equal + 1);
+	auto name_len = value ? equal : selector.size();
+	auto value_len = value ? selector.size() - equal - 1 : 0;
+	auto it = comments.begin(), end = comments.end();
+	while (it != end) {
+		auto current = it++;
+		/** \todo Avoid using strncasecmp because it assumes the system locale is UTF-8. */
+		bool name_match = current->size() > name_len + 1 &&
+		                  (*current)[name_len] == '=' &&
+		                  strncasecmp((const char*) current->data(), (const char*) name, name_len) == 0;
+		if (!name_match)
+			continue;
+		bool value_match = value == nullptr ||
+		                   (current->size() == selector.size() &&
+		                    memcmp(current->data() + equal + 1, value, value_len) == 0);
+		if (value_match)
+			comments.erase(current);
+	}
+}
+
+/** Apply the modifications requested by the user to the opustags packet. */
+static void edit_tags(ot::opus_tags& tags, const ot::options& opt)
+{
+	if (opt.delete_all) {
+		tags.comments.clear();
+	} else for (const std::u8string& name : opt.to_delete) {
+		ot::delete_comments(tags.comments, name);
+	}
+
+	for (const std::u8string& comment : opt.to_add)
+		tags.comments.emplace_back(comment);
+}
+
+/** Spawn VISUAL or EDITOR to edit the given tags. */
+static void edit_tags_interactively(ot::opus_tags& tags, const std::optional<std::string>& base_path, bool raw)
+{
+	const char* editor = nullptr;
+	if (getenv("TERM") != nullptr)
+		editor = getenv("VISUAL");
+	if (editor == nullptr) // without a terminal, or if VISUAL is unset
+		editor = getenv("EDITOR");
+	if (editor == nullptr)
+		throw ot::status {ot::st::error,
+		                 "No editor specified in environment variable VISUAL or EDITOR."};
+
+	// Building the temporary tags file.
+	ot::status rc;
+	std::string tags_path = base_path.value_or("tags") + ".XXXXXX.opustags";
+	int fd = mkstemps(const_cast<char*>(tags_path.data()), 9);
+	ot::file tags_file;
+	if (fd == -1 || (tags_file = fdopen(fd, "w")) == nullptr)
+		throw ot::status {ot::st::standard_error,
+		                  "Could not open '" + tags_path + "': " + strerror(errno)};
+	ot::print_comments(tags.comments, tags_file.get(), raw);
+	tags_file.reset();
+
+	// Spawn the editor, and watch the modification timestamps.
+	timespec before = ot::get_file_timestamp(tags_path.c_str());
+	ot::status editor_rc;
+	try {
+		ot::run_editor(editor, tags_path);
+		editor_rc = ot::st::ok;
+	} catch (const ot::status& rc) {
+		editor_rc = rc;
+	}
+	timespec after = ot::get_file_timestamp(tags_path.c_str());
+	bool modified = (before.tv_sec != after.tv_sec || before.tv_nsec != after.tv_nsec);
+	if (editor_rc != ot::st::ok) {
+		if (modified)
+			fprintf(stderr, "warning: Leaving %s on the disk.\n", tags_path.c_str());
+		else
+			remove(tags_path.c_str());
+		throw editor_rc;
+	} else if (!modified) {
+		remove(tags_path.c_str());
+		fputs("Cancelling edition because the tags file was not modified.\n", stderr);
+		throw ot::status {ot::st::cancel};
+	}
+
+	// Applying the new tags.
+	tags_file = fopen(tags_path.c_str(), "re");
+	if (tags_file == nullptr)
+		throw ot::status {ot::st::standard_error, "Error opening " + tags_path + ": " + strerror(errno)};
+	try {
+		tags.comments = ot::read_comments(tags_file.get(), raw);
+	} catch (const ot::status& rc) {
+		fprintf(stderr, "warning: Leaving %s on the disk.\n", tags_path.c_str());
+		throw;
+	}
+	tags_file.reset();
+
+	// Remove the temporary tags file only on success, because unlike the
+	// partial Ogg file that is irrecoverable, the edited tags file
+	// contains user data, so let’s leave users a chance to recover it.
+	remove(tags_path.c_str());
+}
+
+static void output_cover(const ot::opus_tags& tags, const ot::options &opt)
+{
+	std::optional<ot::picture> cover = extract_cover(tags);
+	if (!cover) {
+		fputs("warning: No cover found.\n", stderr);
+		return;
+	}
+
+	ot::file output;
+	if (opt.cover_out == "-") {
+		output = stdout;
+	} else {
+		struct stat output_info;
+		if (stat(opt.cover_out->c_str(), &output_info) == 0) {
+			if (S_ISREG(output_info.st_mode) && !opt.overwrite)
+				throw ot::status {ot::st::error, "'" + opt.cover_out.value() + "' already exists. Use -y to overwrite."};
+		} else if (errno != ENOENT) {
+			throw ot::status {ot::st::error, "Could not identify '" + opt.cover_out.value() + "': " + strerror(errno)};
+		}
+
+		output = fopen(opt.cover_out->c_str(), "w");
+		if (output == nullptr)
+			throw ot::status {ot::st::standard_error, "Could not open '" + opt.cover_out.value() + "' for writing: " + strerror(errno)};
+	}
+
+	if (fwrite(cover->picture_data.data(), 1, cover->picture_data.size(), output.get()) < cover->picture_data.size())
+		throw ot::status {ot::st::standard_error, "fwrite error: "s + strerror(errno)};
+}
+
+/**
+ * Main loop of opustags. Read the packets from the reader, and forwards them to the writer.
+ * Transform the OpusTags packet on the fly.
+ *
+ * The writer is optional. When writer is nullptr, opustags runs in read-only mode.
+ */
+static void process(ot::ogg_reader& reader, ot::ogg_writer* writer, const ot::options &opt)
+{
+	bool focused = false; /*< the stream on which we operate is defined */
+	int focused_serialno; /*< when focused, the serialno of the focused stream */
+
+	/** When the number of pages the OpusTags packet takes differs from the input stream to the
+	 *  output stream, we need to renumber all the succeeding pages. If the input stream
+	 *  contains gaps, the offset will naively reproduce the gaps: page numbers 0 (1) 2 4 will
+	 *  become 0 (1 2) 3 5, where (…) is the OpusTags packet, and not 0 (1 2) 3 4. */
+	int pageno_offset = 0;
+
+	while (reader.next_page()) {
+		auto serialno = ogg_page_serialno(&reader.page);
+		auto pageno = ogg_page_pageno(&reader.page);
+		if (!focused) {
+			focused = true;
+			focused_serialno = serialno;
+		} else if (serialno != focused_serialno) {
+			/** \todo Support mixed streams. */
+			throw ot::status {ot::st::error, "Muxed streams are not supported yet."};
+		}
+		if (reader.absolute_page_no == 0) { // Identification header
+			if (!ot::is_opus_stream(reader.page))
+				throw ot::status {ot::st::error, "Not an Opus stream."};
+			if (writer)
+				writer->write_page(reader.page);
+		} else if (reader.absolute_page_no == 1) { // Comment header
+			ot::opus_tags tags;
+			reader.process_header_packet([&tags](ogg_packet& p) { tags = ot::parse_tags(p); });
+			if (opt.cover_out)
+				output_cover(tags, opt);
+			edit_tags(tags, opt);
+			if (writer) {
+				if (opt.edit_interactively) {
+					fflush(writer->file); // flush before calling the subprocess
+					edit_tags_interactively(tags, writer->path, opt.raw);
+				}
+				auto packet = ot::render_tags(tags);
+				writer->write_header_packet(serialno, pageno, packet);
+				pageno_offset = writer->next_page_no - 1 - reader.absolute_page_no;
+			} else {
+				if (opt.cover_out != "-")
+					ot::print_comments(tags.comments, stdout, opt.raw);
+				break;
+			}
+		} else if (writer) {
+			ot::renumber_page(reader.page, pageno + pageno_offset);
+			writer->write_page(reader.page);
+		}
+	}
+	if (reader.absolute_page_no < 1)
+		throw ot::status {ot::st::error, "Expected at least 2 Ogg pages."};
+}
+
+static void run_single(const ot::options& opt, const std::string& path_in, const std::optional<std::string>& path_out)
+{
+	ot::file input;
+	if (path_in == "-")
+		input = stdin;
+	else if ((input = fopen(path_in.c_str(), "re")) == nullptr)
+		throw ot::status {ot::st::standard_error,
+		                  "Could not open '" + path_in + "' for reading: " + strerror(errno)};
+	ot::ogg_reader reader(input.get());
+
+	/* Read-only mode. */
+	if (!path_out) {
+		process(reader, nullptr, opt);
+		return;
+	}
+
+	/* Read-write mode.
+	 *
+	 * The output pointer is set to one of:
+	 *  - stdout for "-",
+	 *  - final_output.get() for special files like /dev/null,
+	 *  - temporary_output.get() for regular files.
+	 *
+	 * We use a temporary output file for the following reasons:
+	 *  1. A partial .opus output would be seen by softwares like media players, but a .part
+	 *     (for partial) won’t.
+	 *  2. If the process crashes badly, or the power cuts off, we don't want to leave a partial
+	 *     file at the final location. The temporary file is going to remain though.
+	 *  3. If we're overwriting a regular file, we'd rather avoid wiping its content before we
+	 *     even started reading the input file. That way, the original file is always preserved
+	 *     on error or crash.
+	 *  4. It is necessary for in-place editing. We can't reliably open the same file as both
+	 *     input and output.
+	 */
+
+	FILE* output = nullptr;
+	ot::partial_file temporary_output;
+	ot::file final_output;
+
+	struct stat output_info;
+	if (path_out == "-") {
+		output = stdout;
+	} else if (stat(path_out->c_str(), &output_info) == 0) {
+		/* The output file exists. */
+		if (!S_ISREG(output_info.st_mode)) {
+			/* Special files are opened for writing directly. */
+			if ((final_output = fopen(path_out->c_str(), "we")) == nullptr)
+				throw ot::status {ot::st::standard_error,
+				                  "Could not open '" + path_out.value() + "' for writing: " + strerror(errno)};
+			output = final_output.get();
+		} else if (opt.overwrite) {
+			temporary_output.open(path_out->c_str());
+			output = temporary_output.get();
+		} else {
+			throw ot::status {ot::st::error, "'" + path_out.value() + "' already exists. Use -y to overwrite."};
+		}
+	} else if (errno == ENOENT) {
+		temporary_output.open(path_out->c_str());
+		output = temporary_output.get();
+	} else {
+		throw ot::status {ot::st::error, "Could not identify '" + path_out.value() + "': " + strerror(errno)};
+	}
+
+	ot::ogg_writer writer(output);
+	writer.path = path_out;
+	process(reader, &writer, opt);
+	temporary_output.commit();
+}
+
+void ot::run(const ot::options& opt)
+{
+	if (opt.print_help) {
+		fputs(help_message, stdout);
+		return;
+	}
+
+	ot::status global_rc = st::ok;
+	for (const auto& path_in : opt.paths_in) {
+		try {
+			run_single(opt, path_in, opt.in_place ? path_in : opt.path_out);
+		} catch (const ot::status& rc) {
+			global_rc = st::error;
+			if (!rc.message.empty())
+				fprintf(stderr, "%s: error: %s\n", path_in.c_str(), rc.message.c_str());
+		}
+	}
+	if (global_rc != st::ok)
+		throw global_rc;
+}

src/config.h.in

@@ -0,0 +1,7 @@
+#cmakedefine PROJECT_NAME "@PROJECT_NAME@"
+#cmakedefine PROJECT_VERSION "@PROJECT_VERSION@"
+
+#cmakedefine HAVE_ENDIAN_H @HAVE_ENDIAN_H@
+#cmakedefine HAVE_SYS_ENDIAN_H @HAVE_SYS_ENDIAN_H@
+#cmakedefine HAVE_STAT_ST_MTIM @HAVE_STAT_ST_MTIM@
+#cmakedefine HAVE_STAT_ST_MTIMESPEC @HAVE_STAT_ST_MTIMESPEC@

src/ogg.cc

@@ -0,0 +1,137 @@
+/**
+ * \file src/ogg.c
+ * \ingroup ogg
+ *
+ * High-level interface for libogg.
+ *
+ * This module is not meant to be a complete libogg wrapper, but rather a convenient and highly
+ * specialized layer above libogg and stdio.
+ */
+
+#include <opustags.h>
+
+#include <errno.h>
+#include <string.h>
+
+bool ot::is_opus_stream(const ogg_page& identification_header)
+{
+	if (ogg_page_bos(&identification_header) == 0)
+		return false;
+	if (identification_header.body_len < 8)
+		return false;
+	return (memcmp(identification_header.body, "OpusHead", 8) == 0);
+}
+
+bool ot::ogg_reader::next_page()
+{
+	int rc;
+	while ((rc = ogg_sync_pageout(&sync, &page)) != 1) {
+		if (rc == -1) {
+			throw status {st::bad_stream,
+			              absolute_page_no == (size_t) -1 ? "Input is not a valid Ogg file."
+			                                              : "Unsynced data in stream."};
+		}
+		if (ogg_sync_check(&sync) != 0)
+			throw status {st::libogg_error, "ogg_sync_check signalled an error."};
+		if (feof(file)) {
+			if (sync.fill != sync.returned)
+				throw status {st::bad_stream, "Unsynced data at end of stream."};
+			return false; // end of sream
+		}
+		char* buf = ogg_sync_buffer(&sync, 65536);
+		if (buf == nullptr)
+			throw status {st::libogg_error, "ogg_sync_buffer failed."};
+		size_t len = fread(buf, 1, 65536, file);
+		if (ferror(file))
+			throw status {st::standard_error, "fread error: "s + strerror(errno)};
+		if (ogg_sync_wrote(&sync, len) != 0)
+			throw status {st::libogg_error, "ogg_sync_wrote failed."};
+	}
+	++absolute_page_no;
+	return true;
+}
+
+void ot::ogg_reader::process_header_packet(const std::function<void(ogg_packet&)>& f)
+{
+	if (ogg_page_continued(&page))
+		throw status {ot::st::error, "Unexpected continued header page."};
+
+	ogg_packet packet;
+	ogg_logical_stream stream(ogg_page_serialno(&page));
+	stream.pageno = ogg_page_pageno(&page);
+
+	for (;;) {
+		if (ogg_stream_pagein(&stream, &page) != 0)
+			throw status {st::libogg_error, "ogg_stream_pagein failed."};
+
+		int rc = ogg_stream_packetout(&stream, &packet);
+		if (ogg_stream_check(&stream) != 0 || rc == -1) {
+			throw status {ot::st::libogg_error, "ogg_stream_packetout failed."};
+		} else if (rc == 0) {
+			// Not enough data: read the next page.
+			if (!next_page())
+				throw status {ot::st::error, "Unterminated header packet."};
+			continue;
+		} else {
+			// The packet was successfully read.
+			break;
+		}
+	}
+
+	f(packet);
+
+	/* Ensure that there are no other segments left in the packet using the lacing state of the
+	 * stream. These are the relevant variables, as far as I understood them:
+	 *  - lacing_vals: extensible array containing the lacing values of the segments,
+	 *  - lacing_fill: number of elements in lacing_vals (not the capacity),
+	 *  - lacing_returned: index of the next segment to be processed. */
+	if (stream.lacing_returned != stream.lacing_fill)
+		throw status {ot::st::error, "Header page contains more than a single packet."};
+}
+
+void ot::ogg_writer::write_page(const ogg_page& page)
+{
+	if (page.header_len < 0 || page.body_len < 0)
+		throw status {st::int_overflow, "Overflowing page length"};
+
+	long pageno = ogg_page_pageno(&page);
+	if (pageno != next_page_no)
+		fprintf(stderr, "Output page number mismatch: expected %ld, got %ld.\n", next_page_no, pageno);
+	next_page_no = pageno + 1;
+
+	auto header_len = static_cast<size_t>(page.header_len);
+	auto body_len = static_cast<size_t>(page.body_len);
+	if (fwrite(page.header, 1, header_len, file) < header_len)
+		throw status {st::standard_error, "fwrite error: "s + strerror(errno)};
+	if (fwrite(page.body, 1, body_len, file) < body_len)
+		throw status {st::standard_error, "fwrite error: "s + strerror(errno)};
+}
+
+void ot::ogg_writer::write_header_packet(int serialno, int pageno, ogg_packet& packet)
+{
+	ogg_logical_stream stream(serialno);
+	stream.b_o_s = (pageno != 0);
+	stream.pageno = pageno;
+	if (ogg_stream_packetin(&stream, &packet) != 0)
+		throw status {ot::st::libogg_error, "ogg_stream_packetin failed"};
+
+	ogg_page page;
+	while (ogg_stream_flush(&stream, &page) != 0)
+		write_page(page);
+
+	if (ogg_stream_check(&stream) != 0)
+		throw status {st::libogg_error, "ogg_stream_check failed"};
+}
+
+void ot::renumber_page(ogg_page& page, long new_pageno)
+{
+	// Quick optimization: don’t bother recomputing the CRC if the pageno did not change.
+	long old_pageno = ogg_page_pageno(&page);
+	if (old_pageno == new_pageno)
+		return;
+
+	/** The pageno field is located at bytes 18 to 21 (0-indexed, little-endian). */
+	uint32_t le_pageno = htole32(new_pageno);
+	memcpy(&page.header[18], &le_pageno, 4);
+	ogg_page_checksum_set(&page);
+}

src/opus.cc

@@ -0,0 +1,211 @@
+/**
+ * \file src/opus.cc
+ * \ingroup opus
+ *
+ * The way Opus is encapsulated into an Ogg stream, and the content of the packets we're dealing
+ * with here is defined by [RFC 7584](https://tools.ietf.org/html/rfc7845.html).
+ *
+ * Section 3 "Packet Organization" is critical for us:
+ *
+ * - The first page contains exactly 1 packet, the OpusHead, and it contains it entirely.
+ * - The second page begins the OpusTags packet, which may span several pages.
+ * - The OpusTags packet must finish the page on which it completes.
+ *
+ * The structure of the OpusTags packet is defined in section 5.2 "Comment Header" of the RFC.
+ *
+ * OpusTags is similar to [Vorbis Comment](https://www.xiph.org/vorbis/doc/v-comment.html), which
+ * gives us some context, but let's stick to the RFC for the technical details.
+ *
+ * \todo Validate that the vendor string and comments are valid UTF-8.
+ * \todo Validate that field names are ASCII: 0x20 through 0x7D, 0x3D ('=') excluded.
+ *
+ */
+
+#include <opustags.h>
+
+#include <string.h>
+
+ot::opus_tags ot::parse_tags(const ogg_packet& packet)
+{
+	if (packet.bytes < 0)
+		throw status {st::int_overflow, "Overflowing comment header length"};
+	size_t size = static_cast<size_t>(packet.bytes);
+	const uint8_t* data = reinterpret_cast<uint8_t*>(packet.packet);
+	size_t pos = 0;
+	opus_tags my_tags;
+
+	// Magic number
+	if (8 > size)
+		throw status {st::cut_magic_number, "Comment header too short for the magic number"};
+	if (memcmp(data, u8"OpusTags", 8) != 0)
+		throw status {st::bad_magic_number, "Comment header did not start with OpusTags"};
+
+	// Vendor
+	pos = 8;
+	if (pos + 4 > size)
+		throw status {st::cut_vendor_length,
+		        "Vendor string length did not fit the comment header"};
+	size_t vendor_length = le32toh(*((uint32_t*) (data + pos)));
+	if (pos + 4 + vendor_length > size)
+		throw status {st::cut_vendor_data, "Vendor string did not fit the comment header"};
+	my_tags.vendor = std::u8string(reinterpret_cast<const char8_t*>(&data[pos + 4]), vendor_length);
+	pos += 4 + my_tags.vendor.size();
+
+	// Comment count
+	if (pos + 4 > size)
+		throw status {st::cut_comment_count, "Comment count did not fit the comment header"};
+	uint32_t count = le32toh(*((uint32_t*) (data + pos)));
+	pos += 4;
+
+	// Comments' data
+	for (uint32_t i = 0; i < count; ++i) {
+		if (pos + 4 > size)
+			throw status {st::cut_comment_length,
+			              "Comment length did not fit the comment header"};
+		uint32_t comment_length = le32toh(*((uint32_t*) (data + pos)));
+		if (pos + 4 + comment_length > size)
+			throw status {st::cut_comment_data,
+			              "Comment string did not fit the comment header"};
+		auto comment_value = reinterpret_cast<const char8_t*>(&data[pos + 4]);
+		my_tags.comments.emplace_back(comment_value, comment_length);
+		pos += 4 + comment_length;
+	}
+
+	// Extra data
+	my_tags.extra_data = byte_string(data + pos, size - pos);
+
+	return my_tags;
+}
+
+ot::dynamic_ogg_packet ot::render_tags(const opus_tags& tags)
+{
+	size_t size = 8 + 4 + tags.vendor.size() + 4;
+	for (const std::u8string& comment : tags.comments)
+		size += 4 + comment.size();
+	size += tags.extra_data.size();
+
+	dynamic_ogg_packet op(size);
+	op.b_o_s = 0;
+	op.e_o_s = 0;
+	op.granulepos = 0;
+	op.packetno = 1;
+
+	unsigned char* data = op.packet;
+	uint32_t n;
+	memcpy(data, "OpusTags", 8);
+	n = htole32(tags.vendor.size());
+	memcpy(data+8, &n, 4);
+	memcpy(data+12, tags.vendor.data(), tags.vendor.size());
+	data += 12 + tags.vendor.size();
+	n = htole32(tags.comments.size());
+	memcpy(data, &n, 4);
+	data += 4;
+	for (const std::u8string& comment : tags.comments) {
+		n = htole32(comment.size());
+		memcpy(data, &n, 4);
+		memcpy(data+4, comment.data(), comment.size());
+		data += 4 + comment.size();
+	}
+	memcpy(data, tags.extra_data.data(), tags.extra_data.size());
+
+	return op;
+}
+
+/**
+ * The METADATA_BLOCK_PICTURE binary data, after base64 decoding, is organized like this:
+ *
+ *  - 4 bytes for the picture type,
+ *  - 4 + n bytes for the MIME type,
+ *  - 4 + n bytes for the description string,
+ *  - 16 bytes of picture attributes,
+ *  - 4 + n bytes for the picture data.
+ *
+ * Integers are all big endian.
+ */
+ot::picture::picture(ot::byte_string block)
+	: storage(std::move(block))
+{
+	size_t mime_offset = 4;
+	if (storage.size() < mime_offset + 4)
+		throw status { st::invalid_size, "missing MIME type in picture block" };
+	uint32_t mime_size = be32toh(*reinterpret_cast<const uint32_t*>(&storage[mime_offset]));
+
+	size_t desc_offset = mime_offset + 4 + mime_size;
+	if (storage.size() < desc_offset + 4)
+		throw status { st::invalid_size, "missing description in picture block" };
+	uint32_t desc_size = be32toh(*reinterpret_cast<const uint32_t*>(&storage[desc_offset]));
+
+	size_t pic_offset = desc_offset + 4 + desc_size + 16;
+	if (storage.size() < pic_offset + 4)
+		throw status { st::invalid_size, "missing picture data in picture block" };
+	uint32_t pic_size = be32toh(*reinterpret_cast<const uint32_t*>(&storage[pic_offset]));
+
+	if (storage.size() != pic_offset + 4 + pic_size)
+		throw status { st::invalid_size, "invalid picture block size" };
+
+	mime_type = byte_string_view(&storage[mime_offset + 4], mime_size);
+	picture_data = byte_string_view(&storage[pic_offset + 4], pic_size);
+}
+
+ot::byte_string ot::picture::serialize() const
+{
+	ot::byte_string bytes;
+	size_t mime_offset = 4;
+	size_t pic_offset = mime_offset + 4 + mime_type.size() + 4 + 0 + 16;
+	bytes.resize(pic_offset + 4 + picture_data.size());
+	*reinterpret_cast<uint32_t*>(&bytes[0]) = htobe32(3); // Picture type: front cover.
+	*reinterpret_cast<uint32_t*>(&bytes[mime_offset]) = htobe32(mime_type.size());
+	std::copy(mime_type.begin(), mime_type.end(), std::next(bytes.begin(), mime_offset + 4));
+	*reinterpret_cast<uint32_t*>(&bytes[pic_offset]) = htobe32(picture_data.size());
+	std::copy(picture_data.begin(), picture_data.end(), std::next(bytes.begin(), pic_offset + 4));
+	return bytes;
+}
+
+/**
+ * \todo Take into account the picture types (first 4 bytes of the tag value).
+ */
+std::optional<ot::picture> ot::extract_cover(const ot::opus_tags& tags)
+{
+	static const std::u8string_view prefix = u8"METADATA_BLOCK_PICTURE="sv;
+	auto is_cover = [](const std::u8string& tag) { return tag.starts_with(prefix); };
+	auto cover_tag = std::find_if(tags.comments.begin(), tags.comments.end(), is_cover);
+	if (cover_tag == tags.comments.end())
+		return {}; // No cover art.
+
+	auto extra_cover_tag = std::find_if(std::next(cover_tag), tags.comments.end(), is_cover);
+	if (extra_cover_tag != tags.comments.end())
+		fputs("warning: Found multiple covers; only the first will be extracted."
+		              " Please report your use case if you need a finer selection.\n", stderr);
+
+	std::u8string_view cover_value = *cover_tag;
+	cover_value.remove_prefix(prefix.size());
+	return picture(decode_base64(cover_value));
+}
+
+/**
+ * Detect the MIME type of the given data block by checking the first bytes. Only the most common
+ * image formats are currently supported. Using magic(5) would give better results but that level of
+ * exhaustiveness is probably not necessary.
+ */
+static ot::byte_string_view detect_mime_type(ot::byte_string_view data)
+{
+	static std::initializer_list<std::pair<ot::byte_string_view, ot::byte_string_view>> magic_numbers = {
+		{ "\xff\xd8\xff"_bsv, "image/jpeg"_bsv },
+		{ "\x89PNG"_bsv, "image/png"_bsv },
+		{ "GIF8"_bsv, "image/gif"_bsv },
+	};
+	for (auto [magic, mime] : magic_numbers) {
+		if (data.starts_with(magic))
+			return mime;
+	}
+	fputs("warning: Could not identify the MIME type of the picture; defaulting to application/octet-stream.\n", stderr);
+	return "application/octet-stream"_bsv;
+}
+
+std::u8string ot::make_cover(ot::byte_string_view picture_data)
+{
+	picture pic;
+	pic.mime_type = detect_mime_type(picture_data);
+	pic.picture_data = picture_data;
+	return u8"METADATA_BLOCK_PICTURE=" + encode_base64(pic.serialize());
+}

src/opustags.cc

@@ -0,0 +1,28 @@
+/**
+ * \file src/opustags.cc
+ * \brief Main function for opustags.
+ *
+ * See opustags.h for the program's documentation.
+ */
+
+#include <opustags.h>
+
+#include <locale.h>
+
+/**
+ * Main function of the opustags binary.
+ *
+ * Does practically nothing but call the cli module.
+ */
+int main(int argc, char** argv) {
+	try {
+		setlocale(LC_ALL, "");
+		ot::options opt = ot::parse_options(argc, argv, stdin);
+		ot::run(opt);
+		return 0;
+	} catch (const ot::status& rc) {
+		if (!rc.message.empty())
+			fprintf(stderr, "error: %s\n", rc.message.c_str());
+		return rc == ot::st::bad_arguments ? 2 : 1;
+	}
+}

src/opustags.h

@@ -0,0 +1,567 @@
+/**
+ * \file src/opustags.h
+ *
+ * Welcome to opustags!
+ *
+ * Let's have a quick tour around. The project is split into the following modules:
+ *
+ * - The system module provides a few generic tools for interating with the system.
+ * - The ogg module reads and writes Ogg files, letting you manipulate Ogg pages and packets.
+ * - The opus module parses the contents of Ogg packets according to the Opus specifications.
+ * - The cli module implements the main logic of the program.
+ * - The opustags module contains the main function, which is a simple wrapper around cli.
+ *
+ * Each module is implemented in its eponymous .cc file. Their interfaces are all defined and
+ * documented together in this header file. Look into the .cc files for implementation-specific
+ * details.
+ *
+ * To understand how this program works, you need to know what an Ogg files is made of, in
+ * particular the streams, pages, and packets. You hardly need any knowledge of the actual Opus
+ * audio codec, but need the RFC 7845 "Ogg Encapsulation for the Opus Audio Codec" that defines the
+ * format of the header packets that are essential to opustags.
+ *
+ */
+
+#pragma once
+
+#include <config.h>
+
+#include <iconv.h>
+#include <ogg/ogg.h>
+#include <stdio.h>
+#include <time.h>
+
+#include <functional>
+#include <list>
+#include <memory>
+#include <optional>
+#include <string>
+#include <string_view>
+#include <vector>
+
+#ifdef HAVE_ENDIAN_H
+#  include <endian.h>
+#endif
+
+#ifdef HAVE_SYS_ENDIAN_H
+#  include <sys/endian.h>
+#endif
+
+#ifdef __APPLE__
+#include <libkern/OSByteOrder.h>
+#define htole32(x) OSSwapHostToLittleInt32(x)
+#define le32toh(x) OSSwapLittleToHostInt32(x)
+#define htobe32(x) OSSwapHostToBigInt32(x)
+#define be32toh(x) OSSwapBigToHostInt32(x)
+#endif
+
+using namespace std::literals;
+
+namespace ot {
+
+/**
+ * Possible return status code, ranging from errors to special statuses. They are usually
+ * accompanied with a message with the #status structure.
+ *
+ * Error codes do not need to be ultra specific, and are mainly used to report special conditions to
+ * the caller function. Ultimately, only the error message in the #status is shown to the user.
+ *
+ * The cut error family means that the end of packet was reached when attempting to read the
+ * overflowing value. For example, cut_comment_count means that after reading the vendor string,
+ * less than 4 bytes were left in the packet.
+ */
+enum class st {
+	/* Generic */
+	ok,
+	error,
+	standard_error, /**< Error raised by the C standard library. */
+	int_overflow,
+	cancel,
+	/* System */
+	badly_encoded,
+	child_process_failed,
+	/* Ogg */
+	bad_stream,
+	libogg_error,
+	/* Opus */
+	bad_magic_number,
+	cut_magic_number,
+	cut_vendor_length,
+	cut_vendor_data,
+	cut_comment_count,
+	cut_comment_length,
+	cut_comment_data,
+	invalid_size,
+	/* CLI */
+	bad_arguments,
+};
+
+/**
+ * Wraps a status code with an optional message. It is implictly converted to and from a
+ * #status_code. It may be thrown on error by any of the ot:: functions.
+ *
+ * All the statuses except #st::ok should be accompanied with a relevant error message, in case it
+ * propagates back to the main function and is shown to the user.
+ */
+struct status {
+	status(st code = st::ok) : code(code) {}
+	template<class T> status(st code, T&& message) : code(code), message(message) {}
+	operator st() const { return code; }
+	st code;
+	std::string message;
+};
+
+using byte_string = std::basic_string<uint8_t>;
+using byte_string_view = std::basic_string_view<uint8_t>;
+
+/***********************************************************************************************//**
+ * \defgroup system System
+ * \{
+ */
+
+/**
+ * Smart auto-closing FILE* handle.
+ *
+ * It implictly converts from an already opened FILE*.
+ */
+struct file : std::unique_ptr<FILE, decltype(&fclose)> {
+	file(FILE* f = nullptr) : std::unique_ptr<FILE, decltype(&fclose)>(f, &fclose) {}
+};
+
+/**
+ * A partial file is a temporary file created to store the result of something. When it is complete,
+ * it is moved to a final destination. Open it with #open and then you can either #commit it to save
+ * it to its destination, or you can #abort to delete the temporary file. When the #partial_file
+ * object is destroyed, it deletes the currently opened temporary file, if any.
+ */
+class partial_file {
+public:
+	~partial_file() { abort(); }
+	/**
+	 * Open a temporary file meant to be moved to the specified destination file path. The
+	 * temporary file is created in the same directory as its destination in order to make the
+	 * final move operation instant.
+	 */
+	void open(const char* destination);
+	/** Close then move the partial file to its final location. */
+	void commit();
+	/** Delete the temporary file. */
+	void abort();
+	/** Get the underlying FILE* handle. */
+	FILE* get() { return file.get(); }
+	/** Get the name of the temporary file. */
+	const char* name() const { return file == nullptr ? nullptr : temporary_name.c_str(); }
+private:
+	std::string temporary_name;
+	std::string final_name;
+	ot::file file;
+};
+
+/** Read a whole file into memory and return the read content. */
+byte_string slurp_binary_file(const char* filename);
+
+/** Convert a string from the system locale’s encoding to UTF-8. */
+std::u8string encode_utf8(std::string_view);
+
+/** Convert a string from UTF-8 to the system locale’s encoding. */
+std::string decode_utf8(std::u8string_view);
+
+/** Escape a string so that a POSIX shell interprets it as a single argument. */
+std::string shell_escape(std::string_view word);
+
+/**
+ * Execute the editor process specified in editor. Wait for the process to exit and
+ * return st::ok on success, or st::child_process_failed if it did not exit with 0.
+ *
+ * editor is passed unescaped to the shell, and may contain CLI options.
+ * path is the name of the file to edit, which will be passed as the last argument to editor.
+ */
+void run_editor(std::string_view editor, std::string_view path);
+
+/**
+ * Return the specified path’s mtime, i.e. the last data modification
+ * timestamp.
+ */
+timespec get_file_timestamp(const char* path);
+
+std::u8string encode_base64(byte_string_view src);
+byte_string decode_base64(std::u8string_view src);
+
+/** \} */
+
+/***********************************************************************************************//**
+ * \defgroup ogg Ogg
+ * \{
+ */
+
+/**
+ * RAII-aware wrapper around libogg's ogg_stream_state. Though it handles automatic destruction, it
+ * does not prevent copying or implement move semantics correctly, so it's your responsibility to
+ * ensure these operations don't happen.
+ */
+struct ogg_logical_stream : ogg_stream_state {
+	ogg_logical_stream(int serialno) {
+		if (ogg_stream_init(this, serialno) != 0)
+			throw std::bad_alloc();
+	}
+	~ogg_logical_stream() {
+		ogg_stream_clear(this);
+	}
+};
+
+/**
+ * Identify the codec of a logical stream based on the first bytes of the first packet of the first
+ * page. For Opus, the first 8 bytes must be OpusHead. Any other signature is assumed to be another
+ * codec.
+ */
+bool is_opus_stream(const ogg_page& identification_header);
+
+/**
+ * Ogg reader, combining a FILE input, an ogg_sync_state reading the pages.
+ *
+ * Call #read_page repeatedly until it returns false to consume the stream, and use #page to check
+ * its content.
+ */
+struct ogg_reader {
+	/**
+	 * Initialize the reader with the given input file handle. The caller is responsible for
+	 * keeping the file handle alive, and to close it.
+	 */
+	ogg_reader(FILE* input) : file(input) { ogg_sync_init(&sync); }
+	/**
+	 * Clear all the internal memory allocated by libogg for the sync and stream state. The
+	 * page and the packet are owned by these states, so nothing to do with them.
+	 *
+	 * The input file is not closed.
+	 */
+	~ogg_reader() { ogg_sync_clear(&sync); }
+	/**
+	 * Read the next page from the input file. The result is made available in the #page field,
+	 * is owned by the Ogg reader, and is valid until the next call to #read_page.
+	 *
+	 * Return true if a page was read, false on end of stream.
+	 */
+	bool next_page();
+	/**
+	 * Read the single packet contained in the last page read, assuming it's a header page, and
+	 * call the function f on it. This function has no side effect, and calling it twice on the
+	 * same page will read the same packet again.
+	 *
+	 * It is currently limited to packets that fit on a single page, and should be later
+	 * extended to support packets spanning multiple pages.
+	 */
+	void process_header_packet(const std::function<void(ogg_packet&)>& f);
+	/**
+	 * Current page from the sync state.
+	 *
+	 * Its memory is managed by libogg, inside the sync state, and is valid until the next call
+	 * to ogg_sync_pageout, wrapped by #read_page.
+	 */
+	ogg_page page;
+	/**
+	 * Page number in the physical stream of the last read page, disregarding multiplexed
+	 * streams. The first page number is 0. When no page has been read, its value is
+	 * (size_t) -1.
+	 */
+	size_t absolute_page_no = -1;
+	/**
+	 * The file is our source of binary data. It is not integrated to libogg, so we need to
+	 * handle it ourselves.
+	 *
+	 * The file is not owned by the ogg_reader instance.
+	 */
+	FILE* file;
+	/**
+	 * The sync layer gets binary data and yields a sequence of pages.
+	 *
+	 * A page contains packets that we can extract using the #stream state, but we only do that
+	 * for the headers. Once we got the OpusHead and OpusTags packets, all the following pages
+	 * are simply forwarded to the Ogg writer.
+	 */
+	ogg_sync_state sync;
+};
+
+/**
+ * An Ogg writer lets you write ogg_page objets to an output file, and assemble packets into pages.
+ *
+ * Its packet writing facility is limited to writing single-page header packets, because that's all
+ * we need for opustags.
+ */
+struct ogg_writer {
+	/**
+	 * Initialize the writer with the given output file handle. The caller is responsible for
+	 * keeping the file handle alive, and to close it.
+	 */
+	explicit ogg_writer(FILE* output) : file(output) {}
+	/**
+	 * Write a whole Ogg page into the output stream.
+	 *
+	 * This is a basic I/O operation and does not even require libogg, or the stream.
+	 */
+	void write_page(const ogg_page& page);
+	/**
+	 * Write a header packet and flush the page. Header packets are always placed alone on their
+	 * pages.
+	 */
+	void write_header_packet(int serialno, int pageno, ogg_packet& packet);
+	/**
+	 * Output file. It should be opened in binary mode. We use it to write whole pages,
+	 * represented as a block of data and a length.
+	 */
+	FILE* file;
+	/**
+	 * Path to the output file.
+	 */
+	std::optional<std::string> path;
+	/**
+	 * Custom counter for the sequential page number to be written. It allows us to detect
+	 * ogg_page_pageno mismatches and renumber the pages if needed.
+	 */
+	long next_page_no = 0;
+};
+
+/**
+ * Ogg packet with dynamically allocated data.
+ *
+ * Provides a wrapper around libogg's ogg_packet with RAII.
+ */
+struct dynamic_ogg_packet : ogg_packet {
+	/** Construct an ogg_packet of the given size. */
+	explicit dynamic_ogg_packet(size_t size) {
+		bytes = size;
+		data = std::make_unique<unsigned char[]>(size);
+		packet = data.get();
+	}
+private:
+	/** Owning reference to the data. Use the packet field from ogg_packet instead. */
+	std::unique_ptr<unsigned char[]> data;
+};
+
+/** Update the Ogg pageno field in the given page. The CRC is recomputed if needed. */
+void renumber_page(ogg_page& page, long new_pageno);
+
+/** \} */
+
+/***********************************************************************************************//**
+ * \defgroup opus Opus
+ * \{
+ */
+
+/**
+ * Faithfully represent *all* the data in an OpusTags packet, exactly as they will be written in the
+ * final stream, disregarding the current system locale or anything else.
+ *
+ * The vendor and comment strings are expected to contain valid UTF-8, but we should keep their
+ * values intact even if the string is not UTF-8 clean, or encoded in any other way.
+ */
+struct opus_tags {
+	/**
+	 * OpusTags packets begin with a vendor string, meant to identify the implementation of the
+	 * encoder. It is expected to be an arbitrary UTF-8 string.
+	 */
+	std::u8string vendor;
+	/**
+	 * Comments are strings in the NAME=Value format. A comment may also be called a field, or a
+	 * tag.
+	 *
+	 * The field name in vorbis comments is usually case-insensitive and ASCII, while the value
+	 * can be any valid UTF-8 string. The specification is not too clear for Opus, but let's
+	 * assume it's the same.
+	 */
+	std::list<std::u8string> comments;
+	/**
+	 * According to RFC 7845:
+	 * > Immediately following the user comment list, the comment header MAY contain
+	 * > zero-padding or other binary data that is not specified here.
+	 *
+	 * The first byte is supposed to indicate whether this data should be kept or not, but let's
+	 * assume it's here for a reason and always keep it. Better safe than sorry.
+	 *
+	 * In the future, we could add options to manipulate this data: view it, edit it, truncate
+	 * it if it's marked as padding, truncate it unconditionally.
+	 */
+	byte_string extra_data;
+};
+
+/**
+ * Read the given OpusTags packet and extract its content into an opus_tags object.
+ */
+opus_tags parse_tags(const ogg_packet& packet);
+
+/**
+ * Serialize an #opus_tags object into an OpusTags Ogg packet.
+ */
+dynamic_ogg_packet render_tags(const opus_tags& tags);
+
+/**
+ * Extracted data from the METADATA_BLOCK_PICTURE tag. See
+ * <https://xiph.org/flac/format.html#metadata_block_picture> for the full specifications.
+ *
+ * It may contain all kinds of metadata but most are not used at all. For now, let’s assume all
+ * pictures have picture type 3 (front cover), and empty metadata.
+ */
+struct picture {
+	picture() = default;
+
+	/** Extract the picture information from serialized binary data.*/
+	picture(byte_string block);
+	byte_string_view mime_type;
+	byte_string_view picture_data;
+
+	/**
+	 * Encode the picture attributes (mime_type, picture_data) into a binary block to be stored
+	 * into METADATA_BLOCK_PICTURE.
+	 */
+	byte_string serialize() const;
+
+	/** To avoid needless copies of the picture data, move the original data block there. The
+	 *  string_view attributes will refer to it. */
+	byte_string storage;
+};
+
+/** Extract the first picture embedded in the tags, regardless of its type. */
+std::optional<picture> extract_cover(const opus_tags& tags);
+
+/**
+ * Return a METADATA_BLOCK_PICTURE tag defining the front cover art to the given picture data (JPEG,
+ * PNG). The MIME type is deduced from the magic number.
+ */
+std::u8string make_cover(byte_string_view picture_data);
+
+/** \} */
+
+/***********************************************************************************************//**
+ * \defgroup cli Command-Line Interface
+ * \{
+ */
+
+/**
+ * Structured representation of the command-line arguments to opustags.
+ */
+struct options {
+	/**
+	 * When true, opustags prints a detailed help and exits. All the other options are ignored.
+	 *
+	 * Option: --help
+	 */
+	bool print_help = false;
+	/**
+	 * Paths to the input files. The special string "-" means stdin.
+	 *
+	 * At least one input file must be given. If `--in-place` is used,
+	 * more than one may be given.
+	 */
+	std::vector<std::string> paths_in;
+	/**
+	 * Optional path to output file. The special string "-" means stdout. For in-place
+	 * editing, the input file name is used. If no output file name is supplied, and
+	 * --in-place is not used, opustags runs in read-only mode.
+	 *
+	 * Options: --output, --in-place
+	 */
+	std::optional<std::string> path_out;
+	/**
+	 * By default, opustags won't overwrite the output file if it already exists. This can be
+	 * forced with --overwrite. It is also enabled by --in-place.
+	 *
+	 * Options: --overwrite, --in-place
+	 */
+	bool overwrite = false;
+	/**
+	 * Process files in-place.
+	 *
+	 * Options: --in-place
+	 */
+	bool in_place = false;
+	/**
+	 * Spawn EDITOR to edit tags interactively.
+	 *
+	 * stdin and stdout must be left free for the editor, so paths_in and
+	 * path_out can’t take `-`, and --set-all is not supported.
+	 *
+	 * Option: --edit
+	 */
+	bool edit_interactively = false;
+	/**
+	 * List of comments to delete. Each string is a selector according to the definition of
+	 * #delete_comments.
+	 *
+	 * When #delete_all is true, this option is meaningless.
+	 *
+	 * #to_add takes precedence over #to_delete, so if the same comment appears in both lists,
+	 * the one in #to_delete applies only to the previously existing tags.
+	 *
+	 * Option: --delete, --set
+	 */
+	std::list<std::u8string> to_delete;
+	/**
+	 * Delete all the existing comments.
+	 *
+	 * Option: --delete-all, --set-all
+	 */
+	bool delete_all = false;
+	/**
+	 * List of comments to add, in the current system encoding. For exemple `TITLE=a b c`. They
+	 * must be valid.
+	 *
+	 * Options: --add, --set, --set-all
+	 */
+	std::list<std::u8string> to_add;
+	/**
+	 * If set, the input file’s cover art is exported to the specified file. - for stdout. Does
+	 * not overwrite the file if it already exists unless -y is specified. Does nothing if the
+	 * input file does not contain a cover art.
+	 *
+	 * Option: --output-cover
+	 */
+	std::optional<std::string> cover_out;
+	/**
+	 * Disable encoding conversions. OpusTags are specified to always be encoded as UTF-8, but
+	 * if for some reason a specific file contains binary tags that someone would like to
+	 * extract and set as-is, encoding conversion would get in the way.
+	 */
+	bool raw = false;
+};
+
+/**
+ * Parse the command-line arguments. Does not perform I/O related validations, but checks the
+ * consistency of its arguments. Comments are read if necessary from the given stream.
+ */
+options parse_options(int argc, char** argv, FILE* comments);
+
+/**
+ * Print all the comments, separated by line breaks. Since a comment may contain line breaks, this
+ * output is not completely reliable, but it fits most cases.
+ *
+ * The comments must be encoded in UTF-8, and are converted to the system locale when printed,
+ * unless raw is true.
+ *
+ * The output generated is meant to be parseable by #ot::read_comments.
+ */
+void print_comments(const std::list<std::u8string>& comments, FILE* output, bool raw);
+
+/**
+ * Parse the comments outputted by #ot::print_comments. Unless raw is true, the comments are
+ * converted from the system encoding to UTF-8, and returned as UTF-8.
+ */
+std::list<std::u8string> read_comments(FILE* input, bool raw);
+
+/**
+ * Remove all comments matching the specified selector, which may either be a field name or a
+ * NAME=VALUE pair. The field name is case-insensitive.
+ */
+void delete_comments(std::list<std::u8string>& comments, const std::u8string& selector);
+
+/**
+ * Main entry point to the opustags program, and pretty much the same as calling opustags from the
+ * command-line.
+ */
+void run(const options& opt);
+
+/** \} */
+
+}
+
+/** Handy literal suffix for building byte strings. */
+ot::byte_string operator""_bs(const char* data, size_t size);
+ot::byte_string_view operator""_bsv(const char* data, size_t size);

src/system.cc

@@ -0,0 +1,275 @@
+/**
+ * \file src/system.cc
+ * \ingroup system
+ *
+ * Provide a high-level interface to system-related features, like filesystem manipulations.
+ *
+ * Ideally, all OS-specific features should be grouped here.
+ *
+ * This modules shoumd not depend on any other opustags module.
+ */
+
+#include <opustags.h>
+
+#include <errno.h>
+#include <fstream>
+#include <stdlib.h>
+#include <string.h>
+#include <sys/stat.h>
+#include <sys/wait.h>
+#include <unistd.h>
+
+ot::byte_string operator""_bs(const char* data, size_t size)
+{
+	return ot::byte_string(reinterpret_cast<const uint8_t*>(data), size);
+}
+
+ot::byte_string_view operator""_bsv(const char* data, size_t size)
+{
+	return ot::byte_string_view(reinterpret_cast<const uint8_t*>(data), size);
+}
+
+void ot::partial_file::open(const char* destination)
+{
+	final_name = destination;
+	temporary_name = final_name + ".XXXXXX.part";
+	int fd = mkstemps(const_cast<char*>(temporary_name.data()), 5);
+	if (fd == -1)
+		throw status {st::standard_error,
+		              "Could not create a partial file for '" + final_name + "': " +
+		              strerror(errno)};
+	file = fdopen(fd, "w");
+	if (file == nullptr)
+		throw status {st::standard_error,
+		              "Could not get the partial file handle to '" + temporary_name + "': " +
+		              strerror(errno)};
+}
+
+static mode_t get_umask()
+{
+	// libc doesn’t seem to provide a way to get umask without changing it, so we need this workaround.
+	// https://www.gnu.org/software/libc/manual/html_node/Setting-Permissions.html
+	mode_t mask = umask(0);
+	umask(mask);
+	return mask;
+}
+
+/**
+ * Try reproducing the file permissions of file `source` onto file `dest`. If
+ * this fails for whatever reason, print a warning and leave the current
+ * permissions. When the source doesn’t exist, use the default file creation
+ * permissions according to umask.
+ */
+static void copy_permissions(const char* source, const char* dest)
+{
+	mode_t target_mode;
+	struct stat source_stat;
+	if (stat(source, &source_stat) == 0) {
+		// We could technically preserve a bit more than that but who
+		// would ever need S_ISUID and friends on an Opus file?
+		target_mode = source_stat.st_mode & 0777;
+	} else if (errno == ENOENT) {
+		target_mode = 0666 & ~get_umask();
+	} else {
+		fprintf(stderr, "warning: Could not read mode of %s: %s\n", source, strerror(errno));
+		return;
+	}
+	if (chmod(dest, target_mode) == -1)
+		fprintf(stderr, "warning: Could not set mode of %s: %s\n", dest, strerror(errno));
+}
+
+void ot::partial_file::commit()
+{
+	if (file == nullptr)
+		return;
+	file.reset();
+	copy_permissions(final_name.c_str(), temporary_name.c_str());
+	if (rename(temporary_name.c_str(), final_name.c_str()) == -1)
+		throw status {st::standard_error,
+		              "Could not move the result file '" + temporary_name + "' to '" +
+		              final_name + "': " + strerror(errno) + "."};
+}
+
+void ot::partial_file::abort()
+{
+	if (file == nullptr)
+		return;
+	file.reset();
+	remove(temporary_name.c_str());
+}
+
+/**
+ * Determine the file size, in bytes, of the given file. Return -1 on for streams.
+ */
+static long get_file_size(FILE* f)
+{
+	if (fseek(f, 0L, SEEK_END) != 0) {
+		clearerr(f); // Recover.
+		return -1;
+	}
+	long file_size = ftell(f);
+	rewind(f);
+	return file_size;
+}
+
+ot::byte_string ot::slurp_binary_file(const char* filename)
+{
+	file f = strcmp(filename, "-") == 0 ? freopen(nullptr, "rb", stdin)
+	                                    : fopen(filename, "rb");
+	if (f == nullptr)
+		throw status { st::standard_error,
+		               "Could not open '"s + filename + "': " + strerror(errno) + "." };
+
+	byte_string content;
+	long file_size = get_file_size(f.get());
+	if (file_size == -1) {
+		// Read the input stream block by block and resize the output byte string as needed.
+		uint8_t buffer[4096];
+		while (!feof(f.get())) {
+			size_t read_len = fread(buffer, 1, sizeof(buffer), f.get());
+			content.append(buffer, read_len);
+			if (ferror(f.get()))
+				throw status { st::standard_error,
+					       "Could not read '"s + filename + "': " + strerror(errno) + "." };
+		}
+	} else {
+		// Lucky! We know the file size, so let’s slurp it at once.
+		content.resize(file_size);
+		if (fread(content.data(), 1, file_size, f.get()) < file_size)
+			throw status { st::standard_error,
+				       "Could not read '"s + filename + "': " + strerror(errno) + "." };
+	}
+
+	return content;
+}
+
+/** C++ wrapper for iconv. */
+class encoding_converter {
+public:
+	/**
+	 * Allocate the iconv conversion state, initializing the given source and destination
+	 * character encodings. If it's okay to have some information lost, make sure `to` ends with
+	 * "//TRANSLIT", otherwise the conversion will fail when a character cannot be represented
+	 * in the target encoding. See the documentation of iconv_open for details.
+	 */
+	encoding_converter(const char* from, const char* to);
+	~encoding_converter();
+	/**
+	 * Convert text using iconv. If the input sequence is invalid, return #st::badly_encoded and
+	 * abort the processing, leaving out in an undefined state.
+	 */
+	template<class InChar, class OutChar>
+	std::basic_string<OutChar> convert(std::basic_string_view<InChar>);
+private:
+	iconv_t cd; /**< conversion descriptor */
+};
+
+encoding_converter::encoding_converter(const char* from, const char* to)
+{
+	cd = iconv_open(to, from);
+	if (cd == (iconv_t) -1)
+		throw std::bad_alloc();
+}
+
+encoding_converter::~encoding_converter()
+{
+	iconv_close(cd);
+}
+
+template<class InChar, class OutChar>
+std::basic_string<OutChar> encoding_converter::convert(std::basic_string_view<InChar> in)
+{
+	iconv(cd, nullptr, nullptr, nullptr, nullptr);
+	std::basic_string<OutChar> out;
+	out.reserve(in.size());
+	const char* in_data = reinterpret_cast<const char*>(in.data());
+	char* in_cursor = const_cast<char*>(in_data);
+	size_t in_left = in.size();
+	constexpr size_t chunk_size = 1024;
+	char chunk[chunk_size];
+	for (;;) {
+		char *out_cursor = chunk;
+		size_t out_left = chunk_size;
+		size_t rc = iconv(cd, &in_cursor, &in_left, &out_cursor, &out_left);
+
+		if (rc == (size_t) -1 && errno == E2BIG) {
+			// Loop normally.
+		} else if (rc == (size_t) -1) {
+			throw ot::status {ot::st::badly_encoded, strerror(errno) + "."s};
+		} else if (rc != 0) {
+			throw ot::status {ot::st::badly_encoded,
+			                 "Some characters could not be converted into the target encoding."};
+		}
+
+		out.append(reinterpret_cast<OutChar*>(chunk), out_cursor - chunk);
+		if (in_cursor == nullptr)
+			break;
+		else if (in_left == 0)
+			in_cursor = nullptr;
+	}
+	return out;
+}
+
+std::u8string ot::encode_utf8(std::string_view in)
+{
+	static encoding_converter to_utf8_cvt("", "UTF-8");
+	return to_utf8_cvt.convert<char, char8_t>(in);
+}
+
+std::string ot::decode_utf8(std::u8string_view in)
+{
+	static encoding_converter from_utf8_cvt("UTF-8", "");
+	return from_utf8_cvt.convert<char8_t, char>(in);
+}
+
+std::string ot::shell_escape(std::string_view word)
+{
+	std::string escaped_word;
+	// Pre-allocate the result, assuming most of the time enclosing it in single quotes is enough.
+	escaped_word.reserve(2 + word.size());
+
+	escaped_word += '\'';
+	for (char c : word) {
+		if (c == '\'')
+			escaped_word += "'\\''";
+		else if (c == '!')
+			escaped_word += "'\\!'";
+		else
+			escaped_word += c;
+	}
+	escaped_word += '\'';
+
+	return escaped_word;
+}
+
+void ot::run_editor(std::string_view editor, std::string_view path)
+{
+	std::string command = std::string(editor) + " " + shell_escape(path);
+	int status = system(command.c_str());
+
+	if (status == -1)
+		throw ot::status {st::standard_error, "waitpid error: "s + strerror(errno)};
+	else if (!WIFEXITED(status))
+		throw ot::status {st::child_process_failed,
+		                 "Child process did not terminate normally: "s + strerror(errno)};
+	else if (WEXITSTATUS(status) != 0)
+		throw ot::status {st::child_process_failed,
+		                  "Child process exited with " + std::to_string(WEXITSTATUS(status))};
+}
+
+timespec ot::get_file_timestamp(const char* path)
+{
+	timespec mtime;
+	struct stat st;
+	if (stat(path, &st) == -1)
+		throw status {st::standard_error, path + ": stat error: "s + strerror(errno)};
+#if defined(HAVE_STAT_ST_MTIM)
+	mtime = st.st_mtim;
+#elif defined(HAVE_STAT_ST_MTIMESPEC)
+	mtime = st.st_mtimespec;
+#else
+	mtime.tv_sec = st.st_mtime;
+	mtime.tv_nsec = st.st_mtimensec;
+#endif
+	return mtime;
+}

t/CMakeLists.txt

@@ -0,0 +1,26 @@
+add_executable(system.t EXCLUDE_FROM_ALL system.cc)
+target_link_libraries(system.t ot)
+
+add_executable(opus.t EXCLUDE_FROM_ALL opus.cc)
+target_link_libraries(opus.t ot)
+
+add_executable(ogg.t EXCLUDE_FROM_ALL ogg.cc)
+target_link_libraries(ogg.t ot)
+
+add_executable(cli.t EXCLUDE_FROM_ALL cli.cc)
+target_link_libraries(cli.t ot)
+
+add_executable(base64.t EXCLUDE_FROM_ALL base64.cc)
+target_link_libraries(base64.t ot)
+
+add_executable(oggdump EXCLUDE_FROM_ALL oggdump.cc)
+target_link_libraries(oggdump ot)
+
+configure_file(gobble.opus . COPYONLY)
+configure_file(pixel.png . COPYONLY)
+
+add_custom_target(
+	check
+	COMMAND prove "${CMAKE_CURRENT_BINARY_DIR}" "${CMAKE_CURRENT_SOURCE_DIR}"
+	DEPENDS opustags gobble.opus system.t opus.t ogg.t cli.t base64.t
+)

t/base64.cc

@@ -0,0 +1,46 @@
+#include <opustags.h>
+#include "tap.h"
+
+static void check_encode_base64()
+{
+	opaque_is(ot::encode_base64(""_bsv), u8"", "empty");
+	opaque_is(ot::encode_base64("a"_bsv), u8"YQ==", "1 character");
+	opaque_is(ot::encode_base64("aa"_bsv), u8"YWE=", "2 characters");
+	opaque_is(ot::encode_base64("aaa"_bsv), u8"YWFh", "3 characters");
+	opaque_is(ot::encode_base64("aaaa"_bsv), u8"YWFhYQ==", "4 characters");
+	opaque_is(ot::encode_base64("\xFF\xFF\xFE"_bsv), u8"///+", "RFC alphabet");
+	opaque_is(ot::encode_base64("\0x"_bsv), u8"AHg=", "embedded null bytes");
+}
+
+static void check_decode_base64()
+{
+	opaque_is(ot::decode_base64(u8""), ""_bsv, "empty");
+	opaque_is(ot::decode_base64(u8"YQ=="), "a"_bsv, "1 character");
+	opaque_is(ot::decode_base64(u8"YWE="), "aa"_bsv, "2 characters");
+	opaque_is(ot::decode_base64(u8"YQ"), "a"_bsv, "padless 1 character");
+	opaque_is(ot::decode_base64(u8"YWE"), "aa"_bsv, "padless 2 characters");
+	opaque_is(ot::decode_base64(u8"YWFh"), "aaa"_bsv, "3 characters");
+	opaque_is(ot::decode_base64(u8"YWFhYQ=="), "aaaa"_bsv, "4 characters");
+	opaque_is(ot::decode_base64(u8"///+"), "\xFF\xFF\xFE"_bsv, "RFC alphabet");
+	opaque_is(ot::decode_base64(u8"AHg="), "\0x"_bsv, "embedded null bytes");
+
+	try {
+		ot::decode_base64(u8"Y===");
+		throw failure("accepted a bad block size");
+	} catch (const ot::status& e) {
+	}
+
+	try {
+		ot::decode_base64(u8"\xFF bad message!");
+		throw failure("accepted an invalid character");
+	} catch (const ot::status& e) {
+	}
+}
+
+int main(int argc, char **argv)
+{
+	std::cout << "1..2\n";
+	run(check_encode_base64, "base64 encoding");
+	run(check_decode_base64, "base64 decoding");
+	return 0;
+}

t/cli.cc

@@ -0,0 +1,230 @@
+#include <opustags.h>
+#include "tap.h"
+
+#include <string.h>
+
+static ot::status read_comments(FILE* input, std::list<std::u8string>& comments, bool raw)
+{
+	try {
+		comments = ot::read_comments(input, raw);
+	} catch (const ot::status& rc) {
+		return rc;
+	}
+	return ot::st::ok;
+}
+
+void check_read_comments()
+{
+	std::list<std::u8string> comments;
+	ot::status rc;
+	{
+		std::string txt = "TITLE=a b c\n\nARTIST=X\nArtist=Y\n"s;
+		ot::file input = fmemopen((char*) txt.data(), txt.size(), "r");
+		rc = read_comments(input.get(), comments, false);
+		if (rc != ot::st::ok)
+			throw failure("could not read comments");
+		auto&& expected = {u8"TITLE=a b c", u8"ARTIST=X", u8"Artist=Y"};
+		if (!std::equal(comments.begin(), comments.end(), expected.begin(), expected.end()))
+			throw failure("parsed user comments did not match expectations");
+	}
+	{
+		std::string txt = "CORRUPTED=\xFF\xFF\n"s;
+		ot::file input = fmemopen((char*) txt.data(), txt.size(), "r");
+		rc = read_comments(input.get(), comments, false);
+		if (rc != ot::st::badly_encoded)
+			throw failure("did not get the expected error reading corrupted data");
+	}
+	{
+		std::string txt = "RAW=\xFF\xFF\n"s;
+		ot::file input = fmemopen((char*) txt.data(), txt.size(), "r");
+		rc = read_comments(input.get(), comments, true);
+		if (rc != ot::st::ok)
+			throw failure("could not read comments");
+		if (comments.front() != (char8_t*) "RAW=\xFF\xFF")
+			throw failure("parsed user comments did not match expectations");
+	}
+	{
+		std::string txt = "MULTILINE=First\n\tSecond\n"s;
+		ot::file input = fmemopen((char*) txt.data(), txt.size(), "r");
+		rc = read_comments(input.get(), comments, true);
+		if (rc != ot::st::ok)
+			throw failure("could not read comments");
+		if (comments.front() != u8"MULTILINE=First\nSecond")
+			throw failure("parsed user comments did not match expectations");
+	}
+	{
+		std::string txt = "MALFORMED\n"s;
+		ot::file input = fmemopen((char*) txt.data(), txt.size(), "r");
+		rc = read_comments(input.get(), comments, false);
+		if (rc != ot::st::error)
+			throw failure("did not get the expected error reading malformed comments");
+	}
+	{
+		std::string txt = "\tBad"s;
+		ot::file input = fmemopen((char*) txt.data(), txt.size(), "r");
+		rc = read_comments(input.get(), comments, true);
+		if (rc != ot::st::error)
+			throw failure("did not get the expected error reading bad continuation line");
+	}
+}
+
+/**
+ * Wrap #ot::parse_options with a higher-level interface much more convenient for testing.
+ * In practice, the argc/argv combo are enough though for the current state of opustags.
+ */
+static ot::status parse_options(const std::vector<const char*>& args, ot::options& opt, FILE *comments)
+{
+	int argc = args.size();
+	char* argv[argc];
+	for (int i = 0; i < argc; ++i)
+		argv[i] = strdup(args[i]);
+	ot::status rc = ot::st::ok;
+	try {
+		opt = ot::parse_options(argc, argv, comments);
+	} catch (const ot::status& e) {
+		rc = e;
+	}
+	for (int i = 0; i < argc; ++i)
+		free(argv[i]);
+	return rc;
+}
+
+void check_good_arguments()
+{
+	auto parse = [](std::vector<const char*> args) {
+		ot::options opt;
+		std::string txt = "N=1\n"s;
+		ot::file input = fmemopen((char*) txt.data(), txt.size(), "r");
+		ot::status rc = parse_options(args, opt, input.get());
+		if (rc.code != ot::st::ok)
+			throw failure("unexpected option parsing error");
+		return opt;
+	};
+
+	ot::options opt;
+	opt = parse({"opustags", "--help", "x", "-o", "y"});
+	if (!opt.print_help)
+		throw failure("did not catch --help");
+
+	opt = parse({"opustags", "x", "--output", "y", "-D", "-s", "X=Y Z", "-d", "a=b"});
+	if (opt.paths_in.size() != 1 || opt.paths_in.front() != "x" || !opt.path_out ||
+	    opt.path_out != "y" || !opt.delete_all || opt.overwrite || opt.to_delete.size() != 2 ||
+	    opt.to_delete.front() != u8"X" || *std::next(opt.to_delete.begin()) != u8"a=b" ||
+	    opt.to_add != std::list<std::u8string>{ u8"X=Y Z" })
+		throw failure("unexpected option parsing result for case #1");
+
+	opt = parse({"opustags", "-S", "x", "-S", "-a", "x=y z", "-i"});
+	if (opt.paths_in.size() != 1 || opt.paths_in.front() != "x" || opt.path_out ||
+	    !opt.overwrite || opt.to_delete.size() != 0 ||
+	    opt.to_add != std::list<std::u8string>{ u8"N=1", u8"x=y z" })
+		throw failure("unexpected option parsing result for case #2");
+
+	opt = parse({"opustags", "-i", "x", "y", "z"});
+	if (opt.paths_in.size() != 3 || opt.paths_in[0] != "x" || opt.paths_in[1] != "y" ||
+	    opt.paths_in[2] != "z" || !opt.overwrite || !opt.in_place)
+		throw failure("unexpected option parsing result for case #3");
+
+	opt = parse({"opustags", "-ie", "x"});
+	if (opt.paths_in.size() != 1 || opt.paths_in[0] != "x" ||
+	    !opt.edit_interactively || !opt.overwrite || !opt.in_place)
+		throw failure("unexpected option parsing result for case #4");
+
+	opt = parse({"opustags", "-a", "X=\xFF", "--raw", "x"});
+	if (!opt.raw || opt.to_add.front() != u8"X=\xFF")
+		throw failure("--raw did not disable transcoding");
+}
+
+void check_bad_arguments()
+{
+	auto error_code_case = [](std::vector<const char*> args, const char* message, ot::st error_code, const std::string& name) {
+		ot::options opt;
+		std::string txt = "N=1\nINVALID"s;
+		ot::file input = fmemopen((char*) txt.data(), txt.size(), "r");
+		ot::status rc = parse_options(args, opt, input.get());
+		if (rc.code != error_code)
+			throw failure("bad error code for case " + name);
+		if (!rc.message.starts_with(message))
+			throw failure("bad error message for case " + name + ", got: " + rc.message);
+	};
+	auto error_case = [&error_code_case](std::vector<const char*> args, const char* message, const std::string& name) {
+		 error_code_case(args, message, ot::st::bad_arguments, name);
+	};
+	error_case({"opustags"}, "No arguments specified. Use -h for help.", "no arguments");
+	error_case({"opustags", "-a", "X"}, "Comment does not contain an equal sign: X.", "bad comment for -a");
+	error_case({"opustags", "--set", "X"}, "Comment does not contain an equal sign: X.", "bad comment for --set");
+	error_case({"opustags", "-a"}, "Missing value for option '-a'.", "short option with missing value");
+	error_case({"opustags", "-x"}, "Unrecognized option '-x'.", "unrecognized short option");
+	error_case({"opustags", "--derp"}, "Unrecognized option '--derp'.", "unrecognized long option");
+	error_case({"opustags", "-x=y"}, "Unrecognized option '-x'.", "unrecognized short option with value");
+	error_case({"opustags", "--derp=y"}, "Unrecognized option '--derp=y'.", "unrecognized long option with value");
+	error_case({"opustags", "-aX=Y"}, "Exactly one input file must be specified.", "no input file");
+	error_case({"opustags", "-i", "-o", "/dev/null", "-"}, "Cannot combine --in-place and --output.", "in-place + output");
+	error_case({"opustags", "-S", "-"}, "Cannot use standard input more than once.", "set all and read opus from stdin");
+	error_case({"opustags", "-i", "-"}, "Cannot modify standard input in place.", "write stdin in-place");
+	error_case({"opustags", "-o", "x", "--output", "y", "z"},
+	           "Cannot specify --output more than once.", "double output");
+	error_code_case({"opustags", "-S", "x"}, "Malformed tag: INVALID", ot::st::error, "attempt to read invalid argument with -S");
+	error_case({"opustags", "-o", "", "--output", "y", "z"},
+	           "Cannot specify --output more than once.", "double output with first filename empty");
+	error_case({"opustags", "-e", "-i", "x", "y"},
+	           "Exactly one input file must be specified.", "editing interactively two files at once");
+	error_case({"opustags", "--edit", "-", "-o", "x"},
+	           "Cannot edit interactively when standard input or standard output are already used.",
+	           "editing interactively from stdandard intput");
+	error_case({"opustags", "--edit", "x", "-o", "-"},
+	           "Cannot edit interactively when standard input or standard output are already used.",
+	           "editing interactively to stdandard output");
+	error_case({"opustags", "--edit", "x"}, "Cannot edit interactively when no output is specified.", "editing without output");
+	error_case({"opustags", "--edit", "x", "-i", "-a", "X=Y"}, "Cannot mix --edit with -adDsS.", "mixing -e and -a");
+	error_case({"opustags", "--edit", "x", "-i", "-d", "X"}, "Cannot mix --edit with -adDsS.", "mixing -e and -d");
+	error_case({"opustags", "--edit", "x", "-i", "-D"}, "Cannot mix --edit with -adDsS.", "mixing -e and -D");
+	error_case({"opustags", "--edit", "x", "-i", "-S"}, "Cannot mix --edit with -adDsS.", "mixing -e and -S");
+	error_case({"opustags", "--output-cover", "x", "--output-cover", "y"},
+	           "Cannot specify --output-cover more than once.", "multiple --output-cover");
+	error_case({"opustags", "x", "-o", "-", "--output-cover", "-"},
+	            "Cannot specify standard output for both --output and --output-cover.", "-o and --output-cover conflict");
+	error_case({"opustags", "-i", "x", "y", "--output-cover", "z"},
+	            "Cannot use --output-cover with multiple input files.", "--output-cover with multiple input");
+	error_case({"opustags", "-d", "\xFF", "x"},
+	           "Could not encode argument into UTF-8:",
+	           "-d with binary data");
+	error_case({"opustags", "-a", "X=\xFF", "x"},
+	           "Could not encode argument into UTF-8:",
+	           "-a with binary data");
+	error_case({"opustags", "-s", "X=\xFF", "x"},
+	           "Could not encode argument into UTF-8:",
+	           "-s with binary data");
+}
+
+static void check_delete_comments()
+{
+	using C = std::list<std::u8string>;
+	C original = {u8"TITLE=X", u8"Title=Y", u8"Title=Z", u8"ARTIST=A", u8"artIst=B"};
+
+	C edited = original;
+	ot::delete_comments(edited, u8"derp");
+	if (!std::equal(edited.begin(), edited.end(), original.begin(), original.end()))
+		throw failure("should not have deleted anything");
+
+	ot::delete_comments(edited, u8"Title");
+	C expected = {u8"ARTIST=A", u8"artIst=B"};
+	if (!std::equal(edited.begin(), edited.end(), expected.begin(), expected.end()))
+		throw failure("did not delete all titles correctly");
+
+	edited = original;
+	ot::delete_comments(edited, u8"titlE=Y");
+	ot::delete_comments(edited, u8"Title=z");
+	expected = {u8"TITLE=X", u8"Title=Z", u8"ARTIST=A", u8"artIst=B"};
+	if (!std::equal(edited.begin(), edited.end(), expected.begin(), expected.end()))
+		throw failure("did not delete a specific title correctly");
+}
+
+int main(int argc, char **argv)
+{
+	std::cout << "1..4\n";
+	run(check_read_comments, "check tags parsing");
+	run(check_good_arguments, "check options parsing");
+	run(check_bad_arguments, "check options parsing errors");
+	run(check_delete_comments, "delete comments");
+	return 0;
+}

t/ogg.cc

@@ -0,0 +1,167 @@
+#include <opustags.h>
+#include "tap.h"
+
+#include <string.h>
+
+static void check_ref_ogg()
+{
+	ot::file input = fopen("gobble.opus", "r");
+	if (input == nullptr)
+		throw failure("could not open gobble.opus");
+
+	ot::ogg_reader reader(input.get());
+
+	if (reader.next_page() != true)
+		throw failure("could not read the first page");
+	if (!ot::is_opus_stream(reader.page))
+		throw failure("failed to identify the stream as opus");
+	reader.process_header_packet([](ogg_packet& p) {
+		if (p.bytes != 19)
+			throw failure("unexpected length for the first packet");
+	});
+
+	if (reader.next_page() != true)
+		throw failure("could not read the second page");
+	reader.process_header_packet([](ogg_packet& p) {
+		if (p.bytes != 62)
+			throw failure("unexpected length for the second packet");
+	});
+
+	while (!ogg_page_eos(&reader.page)) {
+		if (reader.next_page() != true)
+			throw failure("failure reading a page");
+	}
+	if (reader.next_page() != false)
+		throw failure("did not correctly detect the end of stream");
+}
+
+static ogg_packet make_packet(const char* contents)
+{
+	ogg_packet op {};
+	op.bytes = strlen(contents);
+	op.packet = (unsigned char*) contents;
+	return op;
+}
+
+static bool same_packet(const ogg_packet& lhs, const ogg_packet& rhs)
+{
+	return lhs.bytes == rhs.bytes && memcmp(lhs.packet, rhs.packet, lhs.bytes) == 0;
+}
+
+/**
+ * Build an in-memory Ogg stream using ogg_writer, and then read it with ogg_reader.
+ */
+static void check_memory_ogg()
+{
+	ogg_packet first_packet  = make_packet("First");
+	ogg_packet second_packet = make_packet("Second");
+	std::vector<unsigned char> my_ogg(128);
+	size_t my_ogg_size;
+
+	{
+		ot::file output = fmemopen(my_ogg.data(), my_ogg.size(), "w");
+		if (output == nullptr)
+			throw failure("could not open the output stream");
+		ot::ogg_writer writer(output.get());
+		writer.write_header_packet(1234, 0, first_packet);
+		writer.write_header_packet(1234, 1, second_packet);
+		my_ogg_size = ftell(output.get());
+		if (my_ogg_size != 67)
+			throw failure("unexpected output size");
+	}
+
+	{
+		ot::file input = fmemopen(my_ogg.data(), my_ogg_size, "r");
+		if (input == nullptr)
+			throw failure("could not open the input stream");
+		ot::ogg_reader reader(input.get());
+		if (reader.next_page() != true)
+			throw failure("could not read the first page");
+		reader.process_header_packet([&first_packet](ogg_packet &p) {
+			if (!same_packet(p, first_packet))
+				throw failure("unexpected content in the first packet");
+		});
+		if (reader.next_page() != true)
+			throw failure("could not read the second page");
+		reader.process_header_packet([&second_packet](ogg_packet &p) {
+			if (!same_packet(p, second_packet))
+				throw failure("unexpected content in the second packet");
+		});
+		if (reader.next_page() != false)
+			throw failure("unexpected third page");
+	}
+}
+
+void check_bad_stream()
+{
+	auto err_msg = "did not detect the stream is not an ogg stream";
+	ot::file input = fmemopen((void*) err_msg, 20, "r");
+	ot::ogg_reader reader(input.get());
+	try {
+		reader.next_page();
+		throw failure("did not raise an error");
+	} catch (const ot::status& rc) {
+		if (rc != ot::st::bad_stream)
+			throw failure(err_msg);
+	}
+}
+
+void check_identification()
+{
+	auto good_header = (unsigned char*)
+		"\x4f\x67\x67\x53\x00\x02\x00\x00\x00\x00\x00\x00\x00\x00\x42\xf2"
+		"\xe6\xc7\x00\x00\x00\x00\x7e\xc3\x57\x2b\x01\x13";
+	auto good_body = (unsigned char*) "OpusHeadABCD";
+
+	ogg_page id;
+	id.header = good_header;
+	id.header_len = 28;
+	id.body = good_body;
+	id.body_len = 12;
+	if (!ot::is_opus_stream(id))
+		throw failure("could not identify opus header");
+
+	// Bad body
+	id.body_len = 7;
+	if (ot::is_opus_stream(id))
+		throw failure("opus header was too short to be valid");
+	id.body_len = 12;
+	id.body = (unsigned char*) "Not_OpusHead";
+	if (ot::is_opus_stream(id))
+		throw failure("was not an opus header");
+	id.body = good_body;
+
+	// Remove the BoS bit from the header.
+	id.header = (unsigned char*)
+		"\x4f\x67\x67\x53\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x42\xf2"
+		"\xe6\xc7\x00\x00\x00\x00\x7e\xc3\x57\x2b\x01\x13";
+	if (ot::is_opus_stream(id))
+		throw failure("was not the beginning of a stream");
+}
+
+void check_renumber_page()
+{
+	ot::file input = fopen("gobble.opus", "r");
+	if (input == nullptr)
+		throw failure("could not open gobble.opus");
+
+	ot::ogg_reader reader(input.get());
+	if (reader.next_page() != true)
+		throw failure("could not read the first page");
+
+	long new_pageno = 1234;
+	ot::renumber_page(reader.page, new_pageno);
+	if (ogg_page_pageno(&reader.page) != new_pageno)
+		throw failure("renumbering failed");
+}
+
+int main(int argc, char **argv)
+{
+	std::cout << "1..5\n";
+	run(check_ref_ogg, "check a reference ogg stream");
+	run(check_memory_ogg, "build and check a fresh stream");
+	run(check_bad_stream, "read a non-ogg stream");
+	run(check_identification, "stream identification");
+	run(check_renumber_page, "page renumbering");
+	return 0;
+}

t/oggdump.cc

@@ -0,0 +1,42 @@
+/**
+ * \file t/oggdump.cc
+ *
+ * Dump brief information about the pages containted in an Ogg file.
+ *
+ * This tool is not build by default or installed, and is mainly meant to help understand how Ogg
+ * files are built, and to debug.
+ */
+
+#include <opustags.h>
+
+#include <iostream>
+#include <string.h>
+
+int main(int argc, char** argv)
+{
+	if (argc != 2) {
+		std::cerr << "Usage: oggdump FILE\n";
+		return 1;
+	}
+	ot::file input = fopen(argv[1], "r");
+	if (input == nullptr) {
+		std::cerr << "Error opening '" << argv[1] << "': " << strerror(errno) << "\n";
+		return 1;
+	}
+	ot::ogg_reader reader(input.get());
+	ot::status rc;
+	while ((rc = reader.read_page()) == ot::st::ok) {
+		std::cout << "Stream " << ogg_page_serialno(&reader.page) << ", "
+		             "page #" << ogg_page_pageno(&reader.page) << ", "
+		          << ogg_page_packets(&reader.page) << " packet(s)";
+		if (ogg_page_bos(&reader.page)) std::cout << ", BoS";
+		if (ogg_page_eos(&reader.page)) std::cout << ", EoS";
+		if (ogg_page_continued(&reader.page)) std::cout << ", continued";
+		std::cout << "\n";
+	}
+	if (rc != ot::st::ok && rc != ot::st::end_of_stream) {
+		std::cerr << "error: " << rc.message << "\n";
+		return 1;
+	}
+	return 0;
+}

t/opus.cc

@@ -0,0 +1,194 @@
+#include <opustags.h>
+#include "tap.h"
+
+#include <string.h>
+
+static const char standard_OpusTags[] =
+	"OpusTags"
+	"\x14\x00\x00\x00" "opustags test packet"
+	"\x02\x00\x00\x00"
+	"\x09\x00\x00\x00" "TITLE=Foo"
+	"\x0a\x00\x00\x00" "ARTIST=Bar";
+
+static void parse_standard()
+{
+	ogg_packet op;
+	op.bytes = sizeof(standard_OpusTags) - 1;
+	op.packet = (unsigned char*) standard_OpusTags;
+	ot::opus_tags tags = ot::parse_tags(op);
+	if (tags.vendor != u8"opustags test packet")
+		throw failure("bad vendor string");
+	if (tags.comments.size() != 2)
+		throw failure("bad number of comments");
+	auto it = tags.comments.begin();
+	if (*it != u8"TITLE=Foo")
+		throw failure("bad title");
+	++it;
+	if (*it != u8"ARTIST=Bar")
+		throw failure("bad artist");
+	if (tags.extra_data.size() != 0)
+		throw failure("found mysterious padding data");
+}
+
+static ot::status try_parse_tags(const ogg_packet& packet)
+{
+	try {
+		ot::parse_tags(packet);
+		return ot::st::ok;
+	} catch (const ot::status& rc) {
+		return rc;
+	}
+}
+
+/**
+ * Try parse_tags with packets that should not valid, or that might even
+ * corrupt the memory. Run this one with valgrind to ensure we're not
+ * overflowing.
+ */
+static void parse_corrupted()
+{
+	size_t size = sizeof(standard_OpusTags);
+	char packet[size];
+	memcpy(packet, standard_OpusTags, size);
+	ot::opus_tags tags;
+	ogg_packet op;
+	op.packet = (unsigned char*) packet;
+	op.bytes = size;
+
+	char* header_data = packet;
+	char* vendor_length = header_data + 8;
+	char* vendor_string = vendor_length + 4;
+	char* comment_count = vendor_string + *vendor_length;
+	char* first_comment_length = comment_count + 4;
+	char* first_comment_data = first_comment_length + 4;
+	char* end = packet + size;
+
+	op.bytes = 7;
+	if (try_parse_tags(op) != ot::st::cut_magic_number)
+		throw failure("did not detect the overflowing magic number");
+	op.bytes = 11;
+	if (try_parse_tags(op) != ot::st::cut_vendor_length)
+		throw failure("did not detect the overflowing vendor string length");
+	op.bytes = size;
+
+	header_data[0] = 'o';
+	if (try_parse_tags(op) != ot::st::bad_magic_number)
+		throw failure("did not detect the bad magic number");
+	header_data[0] = 'O';
+
+	*vendor_length = end - vendor_string + 1;
+	if (try_parse_tags(op) != ot::st::cut_vendor_data)
+		throw failure("did not detect the overflowing vendor string");
+	*vendor_length = end - vendor_string - 3;
+	if (try_parse_tags(op) != ot::st::cut_comment_count)
+		throw failure("did not detect the overflowing comment count");
+	*vendor_length = comment_count - vendor_string;
+
+	++*comment_count;
+	if (try_parse_tags(op) != ot::st::cut_comment_length)
+		throw failure("did not detect the overflowing comment length");
+	*first_comment_length = end - first_comment_data + 1;
+	if (try_parse_tags(op) != ot::st::cut_comment_data)
+		throw failure("did not detect the overflowing comment data");
+}
+
+static void recode_standard()
+{
+	ogg_packet op;
+	op.bytes = sizeof(standard_OpusTags) - 1;
+	op.packet = (unsigned char*) standard_OpusTags;
+	ot::opus_tags tags = ot::parse_tags(op);
+	auto packet = ot::render_tags(tags);
+	if (packet.b_o_s != 0)
+		throw failure("b_o_s should not be set");
+	if (packet.e_o_s != 0)
+		throw failure("e_o_s should not be set");
+	if (packet.granulepos != 0)
+		throw failure("granule_post should be 0");
+	if (packet.packetno != 1)
+		throw failure("packetno should be 1");
+	if (packet.bytes != sizeof(standard_OpusTags) - 1)
+		throw failure("the packet is not the right size");
+	if (memcmp(packet.packet, standard_OpusTags, packet.bytes) != 0)
+		throw failure("the rendered packet is not what we expected");
+}
+
+static void recode_padding()
+{
+	std::string padded_OpusTags(standard_OpusTags, sizeof(standard_OpusTags));
+	// ^ note: padded_OpusTags ends with a null byte here
+	padded_OpusTags += "hello";
+	ogg_packet op;
+	op.bytes = padded_OpusTags.size();
+	op.packet = (unsigned char*) padded_OpusTags.data();
+
+	ot::opus_tags tags = ot::parse_tags(op);
+	if (tags.extra_data != "\0hello"_bsv)
+		throw failure("corrupted extra data");
+	// recode the packet and ensure it's exactly the same
+	auto packet = ot::render_tags(tags);
+	if (static_cast<size_t>(packet.bytes) < padded_OpusTags.size())
+		throw failure("the packet was truncated");
+	if (static_cast<size_t>(packet.bytes) > padded_OpusTags.size())
+		throw failure("the packet got too big");
+	if (memcmp(packet.packet, padded_OpusTags.data(), packet.bytes) != 0)
+		throw failure("the rendered packet is not what we expected");
+}
+
+static void extract_cover()
+{
+	ot::byte_string_view picture_data = ""_bsv
+		"\x00\x00\x00\x03" // Picture type 3.
+		"\x00\x00\x00\x09" "image/foo" // MIME type.
+		"\x00\x00\x00\x00" "" // Description.
+		"\x00\x00\x00\x00" // Width.
+		"\x00\x00\x00\x00" // Height.
+		"\x00\x00\x00\x00" // Color depth.
+		"\x00\x00\x00\x00" // Palette size.
+		"\x00\x00\x00\x0C" "Picture data";
+
+	ot::opus_tags tags;
+	tags.comments = { u8"METADATA_BLOCK_PICTURE=" + ot::encode_base64(picture_data) };
+	std::optional<ot::picture> cover = ot::extract_cover(tags);
+	if (!cover)
+		throw failure("could not extract the cover");
+	if (cover->mime_type != "image/foo"_bsv)
+		throw failure("bad extracted MIME type");
+	if (cover->picture_data != "Picture data"_bsv)
+		throw failure("bad extracted picture data");
+
+	ot::byte_string_view truncated_data = picture_data.substr(0, picture_data.size() - 1);
+	tags.comments = { u8"METADATA_BLOCK_PICTURE=" + ot::encode_base64(truncated_data) };
+	try {
+		ot::extract_cover(tags);
+		throw failure("accepted a bad picture block");
+	} catch (const ot::status& rc) {}
+}
+
+static void make_cover()
+{
+	ot::byte_string_view picture_block = ""_bsv
+		"\x00\x00\x00\x03" // Picture type 3.
+		"\x00\x00\x00\x09" "image/png" // MIME type.
+		"\x00\x00\x00\x00" "" // Description.
+		"\x00\x00\x00\x00" // Width.
+		"\x00\x00\x00\x00" // Height.
+		"\x00\x00\x00\x00" // Color depth.
+		"\x00\x00\x00\x00" // Palette size.
+		"\x00\x00\x00\x11" "\x89PNG Picture data";
+
+	std::u8string expected = u8"METADATA_BLOCK_PICTURE=" + ot::encode_base64(picture_block);
+	opaque_is(ot::make_cover("\x89PNG Picture data"_bsv), expected, "build the picture tag");
+}
+
+int main()
+{
+	std::cout << "1..6\n";
+	run(parse_standard, "parse a standard OpusTags packet");
+	run(parse_corrupted, "correctly reject invalid packets");
+	run(recode_standard, "recode a standard OpusTags packet");
+	run(recode_padding, "recode a OpusTags packet with padding");
+	run(extract_cover, "extract the cover art");
+	run(make_cover, "encode the cover art");
+	return 0;
+}

t/opustags.t

@@ -0,0 +1,344 @@
+#!/usr/bin/env perl
+
+use strict;
+use warnings;
+use utf8;
+
+use Test::More tests => 59;
+
+use Digest::MD5;
+use File::Basename;
+use File::Copy;
+use IPC::Open3;
+use List::MoreUtils qw(any);
+use Symbol 'gensym';
+
+my $opustags = '../opustags';
+BAIL_OUT("$opustags does not exist or is not executable") if (! -x $opustags);
+
+my $is_utf8;
+open(my $ctype, 'locale -k LC_CTYPE |');
+while (<$ctype>) { $is_utf8 = 1 if (/^charmap="UTF-?8"$/i) }
+close($ctype);
+BAIL_OUT("this test must be run from an UTF-8 environment") unless $is_utf8;
+
+sub opustags {
+	my %opt;
+	%opt = %{pop @_} if ref $_[-1];
+	my ($pid, $pin, $pout, $perr);
+	$perr = gensym;
+	$pid = open3($pin, $pout, $perr, $opustags, @_);
+	binmode($pin, $opt{mode} // ':utf8');
+	binmode($pout, $opt{mode} // ':utf8');
+	binmode($perr, ':utf8');
+	local $/;
+	print $pin $opt{in} if defined $opt{in};
+	close $pin;
+	my $out = <$pout>;
+	my $err = <$perr>;
+	waitpid($pid, 0);
+	[$out, $err, $?]
+}
+
+####################################################################################################
+# Tests related to the overall opustags executable, like the help message.
+# No Opus file is manipulated here.
+
+is_deeply(opustags(), ['', <<EOF, 512], 'no options is a failure');
+error: No arguments specified. Use -h for help.
+EOF
+
+my $help = opustags('--help');
+$help->[0] =~ /^([^\n]*+)/;
+my $version = $1;
+like($version, qr/^opustags version (\d+\.\d+\.\d+)/, 'get the version string');
+
+my $expected_help = <<"EOF";
+$version
+
+Usage: opustags --help
+       opustags [OPTIONS] FILE
+       opustags OPTIONS -i FILE...
+       opustags OPTIONS FILE -o FILE
+
+Options:
+  -h, --help                    print this help
+  -o, --output FILE             specify the output file
+  -i, --in-place                overwrite the input files
+  -y, --overwrite               overwrite the output file if it already exists
+  -a, --add FIELD=VALUE         add a comment
+  -d, --delete FIELD[=VALUE]    delete previously existing comments
+  -D, --delete-all              delete all the previously existing comments
+  -s, --set FIELD=VALUE         replace a comment
+  -S, --set-all                 import comments from standard input
+  -e, --edit                    edit tags interactively in VISUAL/EDITOR
+  --output-cover FILE           extract and save the cover art, if any
+  --set-cover FILE              sets the cover art
+  --raw                         disable encoding conversion
+
+See the man page for extensive documentation.
+EOF
+
+is_deeply(opustags('--help'), [$expected_help, '', 0], '--help displays the help message');
+is_deeply(opustags('-h'), [$expected_help, '', 0], '-h displays the help message too');
+
+is_deeply(opustags('--derp'), ['', <<"EOF", 512], 'unrecognized option shows an error');
+error: Unrecognized option '--derp'.
+EOF
+
+is_deeply(opustags('../opustags'), ['', <<"EOF", 256], 'not an Ogg stream');
+../opustags: error: Input is not a valid Ogg file.
+EOF
+
+####################################################################################################
+# Test the main features of opustags on an Ogg Opus sample file.
+
+sub md5 {
+	my ($file) = @_;
+	open(my $fh, '<', $file) or return;
+	my $ctx = Digest::MD5->new;
+	$ctx->addfile($fh);
+	$ctx->hexdigest
+}
+
+is(md5('gobble.opus'), '111a483596ac32352fbce4d14d16abd2', 'the sample is the one we expect');
+is_deeply(opustags('gobble.opus'), [<<'EOF', '', 0], 'read the initial tags');
+encoder=Lavc58.18.100 libopus
+EOF
+
+unlink('out.opus');
+my $previous_umask = umask(0022);
+is_deeply(opustags(qw(gobble.opus -o out.opus)), ['', '', 0], 'copy the file without changes');
+is(md5('out.opus'), '111a483596ac32352fbce4d14d16abd2', 'the copy is faithful');
+is((stat 'out.opus')[2] & 0777, 0644, 'apply umask on new files');
+umask($previous_umask);
+
+# empty out.opus
+{ my $fh; open($fh, '>', 'out.opus') and close($fh) or die }
+is_deeply(opustags(qw(gobble.opus -o out.opus)), ['', <<'EOF', 256], 'refuse to override');
+gobble.opus: error: 'out.opus' already exists. Use -y to overwrite.
+EOF
+is(md5('out.opus'), 'd41d8cd98f00b204e9800998ecf8427e', 'the output wasn\'t written');
+
+is_deeply(opustags(qw(gobble.opus -o /dev/null)), ['', '', 0], 'write to /dev/null');
+
+chmod(0604, 'out.opus');
+is_deeply(opustags(qw(gobble.opus -o out.opus --overwrite)), ['', '', 0], 'overwrite');
+is(md5('out.opus'), '111a483596ac32352fbce4d14d16abd2', 'successfully overwritten');
+is((stat 'out.opus')[2] & 0777, 0604, 'overwriting preserves output file\'s mode');
+
+chmod(0700, 'out.opus');
+is_deeply(opustags(qw(--in-place out.opus -a A=B --add=A=C --add), "TITLE=Foo Bar",
+                   qw(--delete A --add TITLE=七面鳥 --set encoder=whatever -s 1=2 -s X=1 -a X=2 -s X=3)),
+          ['', '', 0], 'complex tag editing');
+is(md5('out.opus'), '66780307a6081523dc9040f3c47b0448', 'check the footprint');
+is((stat 'out.opus')[2] & 0777, 0700, 'in-place editing preserves file mode');
+
+is_deeply(opustags('out.opus'), [<<'EOF', '', 0], 'check the tags written');
+A=B
+A=C
+TITLE=Foo Bar
+TITLE=七面鳥
+encoder=whatever
+1=2
+X=1
+X=2
+X=3
+EOF
+
+is_deeply(opustags(qw(out.opus -d A -d foo -s X=4 -a TITLE=gobble -d title=七面鳥)), [<<'EOF', '', 0], 'dry editing');
+TITLE=Foo Bar
+encoder=whatever
+1=2
+X=4
+TITLE=gobble
+EOF
+is(md5('out.opus'), '66780307a6081523dc9040f3c47b0448', 'the file did not change');
+
+is_deeply(opustags(qw(-i out.opus -a fatal=yes -a FOO -a BAR)), ['', <<'EOF', 512], 'bad tag with --add');
+error: Comment does not contain an equal sign: FOO.
+EOF
+is(md5('out.opus'), '66780307a6081523dc9040f3c47b0448', 'the file did not change');
+
+is_deeply(opustags('out.opus', '-D', '-a', "X=foobar\tquux"), [<<'END_OUT', <<'END_ERR', 0], 'control characters');
+X=foobar	quux
+END_OUT
+warning: Some tags contain control characters.
+END_ERR
+
+is_deeply(opustags('out.opus', '-D', '-a', "X=foo\n\nbar"), [<<'END_OUT', '', 0], 'newline characters');
+X=foo
+	
+	bar
+END_OUT
+
+is_deeply(opustags(qw(-i out.opus -s fatal=yes -s FOO -s BAR)), ['', <<'EOF', 512], 'bad tag with --set');
+error: Comment does not contain an equal sign: FOO.
+EOF
+is(md5('out.opus'), '66780307a6081523dc9040f3c47b0448', 'the file did not change');
+
+is_deeply(opustags(qw(out.opus --delete-all -a OK=yes)), [<<'EOF', '', 0], 'delete all');
+OK=yes
+EOF
+
+is_deeply(opustags(qw(out.opus --set-all -a A=B -s X=Z -d OK), {in => <<'END_IN'}), [<<'END_OUT', '', 0], 'set all');
+OK=yes again
+ARTIST=七面鳥
+
+A=A
+X=Y
+#IGNORE=COMMENTS
+END_IN
+OK=yes again
+ARTIST=七面鳥
+A=A
+X=Y
+A=B
+X=Z
+END_OUT
+
+is_deeply(opustags(qw(out.opus -S), {in => <<'END_IN'}), [<<'END_OUT', <<'END_ERR', 256], 'set all with bad tags');
+whatever
+wrong=yes
+END_IN
+END_OUT
+error: Malformed tag: whatever
+END_ERR
+
+sub slurp {
+	my ($filename) = @_;
+	local $/;
+	open(my $fh, '<', $filename);
+	binmode($fh);
+	my $data = <$fh>;
+	$data
+}
+
+my $data = slurp 'out.opus';
+is_deeply(opustags('-', '-o', '-', {in => $data, mode => ':raw'}), [$data, '', 0], 'read opus from stdin and write to stdout');
+
+unlink('out.opus');
+
+# Test --in-place
+unlink('out2.opus');
+copy('gobble.opus', 'out.opus');
+is_deeply(opustags(qw(out.opus --add BAR=baz -o out2.opus)), ['', '', 0], 'process multiple files with --in-place');
+is_deeply(opustags(qw(--in-place --add FOO=bar out.opus out2.opus)), ['', '', 0], 'process multiple files with --in-place');
+is(md5('out.opus'), '30ba30c4f236c09429473f36f8f861d2', 'the tags were added correctly (out.opus)');
+is(md5('out2.opus'), '0a4d20c287b2e46b26cb0eee353c2069', 'the tags were added correctly (out2.opus)');
+
+unlink('out.opus');
+unlink('out2.opus');
+
+####################################################################################################
+# Interactive edition
+
+$ENV{EDITOR} = 'sed -i -e y/aeiou/AEIOU/ `sleep 0.1`';
+is_deeply(opustags('gobble.opus', '-eo', "'screaming !'.opus"), ['', '', 0], 'edit a file with EDITOR');
+is(md5("'screaming !'.opus"), '56e85ccaa83a13c15576d75bbd6d835f', 'the tags were modified');
+
+$ENV{EDITOR} = 'true';
+is_deeply(opustags('-ie', "'screaming !'.opus"), ['', "Cancelling edition because the tags file was not modified.\n", 256], 'close -e without saving');
+is(md5("'screaming !'.opus"), '56e85ccaa83a13c15576d75bbd6d835f', 'the tags were not modified');
+
+$ENV{EDITOR} = 'false';
+is_deeply(opustags('-ie', "'screaming !'.opus"), ['', "'screaming !'.opus: error: Child process exited with 1\n", 256], 'editor exiting with an error');
+is(md5("'screaming !'.opus"), '56e85ccaa83a13c15576d75bbd6d835f', 'the tags were not modified');
+
+unlink("'screaming !'.opus");
+
+####################################################################################################
+# Test muxed streams
+
+system('ffmpeg -loglevel error -y -i gobble.opus -c copy -map 0:0 -map 0:0 -shortest muxed.ogg') == 0
+	or BAIL_OUT('could not create a muxed stream');
+
+is_deeply(opustags('muxed.ogg'), ['', <<'END_ERR', 256], 'muxed streams detection');
+muxed.ogg: error: Muxed streams are not supported yet.
+END_ERR
+
+unlink('muxed.ogg');
+
+####################################################################################################
+# Locale
+
+my $locale = 'en_US.iso88591';
+my @all_locales = split(' ', `locale -a`);
+
+SKIP: {
+skip "locale $locale is not present", 5 unless (any { $_ eq $locale } @all_locales);
+
+opustags(qw(gobble.opus -a TITLE=七面鳥 -a ARTIST=éàç -o out.opus -y));
+
+local $ENV{LC_ALL} = $locale;
+local $ENV{LANGUAGE} = '';
+
+is_deeply(opustags(qw(-S out.opus), {in => <<"END_IN", mode => ':raw'}), [<<"END_OUT", '', 0], 'set all in ISO-8859-1');
+T=\xef\xef\xf6
+END_IN
+T=\xef\xef\xf6
+END_OUT
+
+is_deeply(opustags('-i', 'out.opus', "--add=I=\xf9\xce", {mode => ':raw'}), ['', '', 0], 'write tags in ISO-8859-1');
+
+is_deeply(opustags('out.opus', {mode => ':raw'}), [<<"END_OUT", <<"END_ERR", 256], 'read tags in ISO-8859-1 with incompatible characters');
+encoder=Lavc58.18.100 libopus
+END_OUT
+out.opus: error: Invalid or incomplete multibyte or wide character. See --raw.
+END_ERR
+
+is_deeply(opustags(qw(out.opus -d TITLE -d ARTIST), {mode => ':raw'}), [<<"END_OUT", '', 0], 'read tags in ISO-8859-1');
+encoder=Lavc58.18.100 libopus
+I=\xf9\xce
+END_OUT
+
+$ENV{LC_ALL} = '';
+
+is_deeply(opustags('out.opus'), [<<"END_OUT", '', 0], 'read tags in UTF-8');
+encoder=Lavc58.18.100 libopus
+TITLE=七面鳥
+ARTIST=éàç
+I=ùÎ
+END_OUT
+
+unlink('out.opus');
+}
+
+####################################################################################################
+# Raw edition
+
+is_deeply(opustags(qw(-S gobble.opus -o out.opus --raw -a), "U=\xFE", {in => <<"END_IN", mode => ':raw'}), ['', '', 0], 'raw set-all with binary data');
+T=\xFF
+END_IN
+
+is_deeply(opustags(qw(out.opus --raw), { mode => ':raw' }), [<<"END_OUT", '', 0], 'raw read');
+T=\xFF
+U=\xFE
+END_OUT
+
+unlink('out.opus');
+
+####################################################################################################
+# Multiple-page tags
+
+my $big_tags = "DATA=x\n" x 15000; # > 90K, which is over the max page size of 64KiB.
+is_deeply(opustags(qw(-S gobble.opus -o out.opus), {in => $big_tags}), ['', '', 0], 'write multi-page header');
+is_deeply(opustags('out.opus'), [$big_tags, '', 0], 'read multi-page header');
+is_deeply(opustags(qw(out.opus -i -D -a), 'encoder=Lavc58.18.100 libopus'), ['', '', 0], 'shrink the header');
+is(md5('out.opus'), '111a483596ac32352fbce4d14d16abd2', 'the result is identical to the original file');
+unlink('out.opus');
+
+####################################################################################################
+# Cover arts
+
+is_deeply(opustags(qw(-D --set-cover pixel.png gobble.opus -o out.opus)), ['', '', 0], 'set the cover');
+is_deeply(opustags(qw(--output-cover out.png out.opus)), [<<'END_OUT', '', 0], 'extract the cover');
+METADATA_BLOCK_PICTURE=AAAAAwAAAAlpbWFnZS9wbmcAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAEWJUE5HDQoaCgAAAA1JSERSAAAAAQAAAAEIAgAAAJB3U94AAAAMSURBVAjXY/j//z8ABf4C/tzMWecAAAAASUVORK5CYII=
+END_OUT
+is(md5('out.png'), md5('pixel.png'), 'the extracted cover is identical to the one set');
+unlink('out.opus');
+unlink('out.png');
+
+is_deeply(opustags(qw(-D --set-cover - gobble.opus), { in => "GIF8 x" }), [<<'END_OUT', '', 0], 'read the cover from stdin');
+METADATA_BLOCK_PICTURE=AAAAAwAAAAlpbWFnZS9naWYAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAZHSUY4IHg=
+END_OUT

t/system.cc

@@ -0,0 +1,78 @@
+#include <opustags.h>
+#include "tap.h"
+
+#include <string.h>
+#include <unistd.h>
+
+void check_partial_files()
+{
+	static const char* result = "partial_file.test";
+	std::string name;
+	{
+		ot::partial_file bad_tmp;
+		try {
+			bad_tmp.open("/dev/null");
+			throw failure("opening a device as a partial file should fail");
+		} catch (const ot::status& rc) {
+			is(rc, ot::st::standard_error, "opening a device as a partial file fails");
+		}
+
+		bad_tmp.open(result);
+		name = bad_tmp.name();
+		if (name.size() != strlen(result) + 12 ||
+		    name.compare(0, strlen(result), result) != 0)
+			throw failure("the temporary name is surprising: " + name);
+	}
+	is(access(name.c_str(), F_OK), -1, "expect the temporary file is deleted");
+
+	ot::partial_file good_tmp;
+	good_tmp.open(result);
+	name = good_tmp.name();
+	good_tmp.commit();
+	is(access(name.c_str(), F_OK), -1, "expect the temporary file is deleted");
+	is(access(result, F_OK), 0, "expect the final result file");
+	is(remove(result), 0, "remove the result file");
+}
+
+void check_slurp()
+{
+	static const ot::byte_string_view pixel = ""_bsv
+		"\x89\x50\x4e\x47\x0d\x0a\x1a\x0a\x00\x00\x00\x0d"
+		"\x49\x48\x44\x52\x00\x00\x00\x01\x00\x00\x00\x01"
+		"\x08\x02\x00\x00\x00\x90\x77\x53\xde\x00\x00\x00"
+		"\x0c\x49\x44\x41\x54\x08\xd7\x63\xf8\xff\xff\x3f"
+		"\x00\x05\xfe\x02\xfe\xdc\xcc\x59\xe7\x00\x00\x00"
+		"\x00\x49\x45\x4e\x44\xae\x42\x60\x82";
+	opaque_is(ot::slurp_binary_file("pixel.png"), pixel, "loads a whole file");
+}
+
+void check_converter()
+{
+	setlocale(LC_ALL, "");
+	is(ot::decode_utf8(ot::encode_utf8("Éphémère")), "Éphémère", "decode_utf8 reverts encode_utf8");
+	opaque_is(ot::encode_utf8(ot::decode_utf8(u8"Éphémère")), u8"Éphémère",
+	          "encode_utf8 reverts decode_utf8");
+
+	try {
+		ot::decode_utf8((char8_t*) "\xFF\xFF");
+		throw failure("conversion from bad UTF-8 did not fail");
+	} catch (const ot::status&) {}
+}
+
+void check_shell_esape()
+{
+	is(ot::shell_escape("foo"), "'foo'", "simple string");
+	is(ot::shell_escape("a'b"), "'a'\\''b'", "string with a simple quote");
+	is(ot::shell_escape("a!b"), "'a'\\!'b'", "string with a bang");
+	is(ot::shell_escape("a!b'c!d'e"), "'a'\\!'b'\\''c'\\!'d'\\''e'", "string with a bang");
+}
+
+int main(int argc, char **argv)
+{
+	plan(4);
+	run(check_partial_files, "test partial files");
+	run(check_slurp, "file slurping");
+	run(check_converter, "test encoding converter");
+	run(check_shell_esape, "test shell escaping");
+	return 0;
+}

t/tap.h

@@ -0,0 +1,73 @@
+/**
+ * \file t/tap.h
+ *
+ * \brief
+ * Helpers for following the Test Anything Protocol.
+ *
+ * Its interface mimics Test::More from Perl:
+ * https://perldoc.perl.org/Test/More.html
+ *
+ * Unlike Test::More, a test failure raises an exception and aborts the whole subtest.
+ */
+
+#pragma once
+
+#include <exception>
+#include <iostream>
+
+inline namespace tap {
+
+struct failure : std::runtime_error {
+	failure(const std::string& what) : std::runtime_error(what) {}
+};
+
+template <typename F>
+static void run(F test, const char *name)
+{
+	bool ok = false;
+	try {
+		test();
+		ok = true;
+	} catch (failure& e) {
+		std::cerr << "# fail: " << e.what() << "\n";
+	} catch (const ot::status &rc) {
+		std::cerr << "# unexpected error: " << rc.message << "\n";
+	}
+	std::cout << (ok ? "ok" : "not ok") << " - " << name << "\n";
+}
+
+void plan(int tests)
+{
+	std::cout << "1.." << tests << "\n";
+}
+
+template <typename T, typename U>
+void is(const T& got, const U& expected, const char* name)
+{
+	if (got != expected) {
+		std::cerr << "# got: " << got << "\n"
+		             "# expected: " << expected << "\n";
+		throw failure(name);
+	}
+}
+
+template <typename T, typename U>
+void opaque_is(const T& got, const U& expected, const char* name)
+{
+	if (got != expected)
+		throw failure(name);
+}
+
+template <>
+void is(const ot::status& got, const ot::st& expected, const char* name)
+{
+	if (got.code != expected) {
+		if (got.code == ot::st::ok)
+			std::cerr << "# unexpected success\n";
+		else
+			std::cerr << "# unexpected error: " << got.message << "\n";
+		throw failure(name);
+	}
+}
+
+}