opustags(1)

NAME
opustags - Ogg Opus tag editor

SYNOPSIS
opustags --help
opustags [OPTIONS] INPUT
opustags OPTIONS -i FILE...
opustags OPTIONS -o OUTPUT INPUT

DESCRIPTION

opustags can read and edit the comment header of an Ogg Opus file. It basically has two modes: read-only, and read-write for tag editing.

In read-only mode, only the beginning of INPUT is read, and the tags are printed on standard output. INPUT can either be the name of a file or - 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.

In editing mode, you need to specify an output file with --output, or use --in-place 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.

Tag editing can be performed with the --add, --delete and --set 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.

You can delete all the tags with --delete-all. This operation can be combined with --add to set new tags without being bothered by the old ones.

If you want to replace all the tags, you can use the --set-all option which will cause opustags to read tags from standard input. The format is the same as the one used for output: newline-separated FIELD=Value assignment. All the previously existing tags as deleted.

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 the conversion is lossy, the incompatible characters are transliterated and a warning is displayed. Even if 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.

OPTIONS

-h, --help
    Display a brief description of the options.

-o, --output FILE
    Specify the output file. The input file will be read, its tags edited, then written to the specified output file. If FILE is - then the resulting Opus file will be written to standard output. The output file can’t be the same as the input file.

-i, --in-place
    Overwrite the input file instead of creating a separate output file. It has the same effect as setting --output to the same path as the input file and enabling --overwrite. This option conflicts with --output.

-y, --overwrite
    By default, opustags refuses to overwrite an already-existent file. Use -y to allow overwriting. Note that this option is not needed when the output is a special file like /dev/null.

-d, --delete FIELD[=VALUE]
    If value is not specified, delete all the tags whose field name is FIELD. Otherwise, delete all the comments whose field name is FIELD and value is VALUE. In both cases, the field names are case-insensitive, and expected to be ASCII.

-a, --add FIELD=VALUE
    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 --delete is used with the same FIELD, only the older tags are deleted.

-s, --set FIELD=VALUE
    This option is provided for convenience. It delete all the fields of the same type that may already exist, then adds it with the wanted value. This is strictly equivalent to --delete FIELD --add FIELD=VALUE. You can combine it with --add to add tags of the same type. As deletion occurs before adding, --set won’t erase the tags added with --add.

-D, --delete-all
    Delete all the previously existing tags.

-S, --set-all
    Sets the tags from scratch. All the original tags are deleted and new ones are read from standard input. Each line must specify a FIELD=VALUE pair and be separated with line feeds. Blank lines and lines starting with # are ignored.

-e, --edit
    Edit tags interactively by spawning the program specified by the EDITOR environment variable. The allowed format is the same as --set-all. If TERM and VISUAL are set, VISUAL takes precedence over EDITOR.

--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.

EXAMPLES

List all the tags in file foo.opus:

    opustags foo.opus

Copy in.opus to out.opus, with the TITLE tag added:

    opustags in.opus --output out.opus --add "TITLE=Hello world!"

Replace all the tags in dest.opus with the ones from src.opus:

    opustags src.opus | opustags --in-place dest.opus --set-all

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:

    opustags in.opus --add ARTIST=X --add ARTIST=Y --delete ARTIST

Edit tags interactively in Vim:

    EDITOR=vim opustags --in-place --edit file.opus

CAVEATS

opustags currently has the following limitations:

•   The total size of all tags cannot exceed 64 kB, the maximum size of one Ogg page.

•   Multiplexed streams are not supported.

•   Newlines inside tags are not supported by `--set-all`.

•   Newlines and control characters are not escaped when printing tags.

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.

If you need a feature not currently supported, feel free to open an issue or send an email with your use case.

AUTHOR
Frédéric Mangano-Tarumi <fmang+opustags@mg0.fr>

Report bugs at <https://github.com/fmang/opustags/issues>