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 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.  Lines prefixed by tabs are continuation of the previous tag.  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 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 explicitly 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.   Empty  lines and lines starting with # are ignored.
              Multiline tags must have their continuation lines prefixed  by  a  single  tab  (in
              other words, every \n must be replaced by \n\t).

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

       --output-cover FILE
              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  --overwrite.  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 - for standard output, in which
              case the regular output will be suppressed.

       --set-cover FILE
              Replace or set the cover art to the specified  picture.   Specify  -  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.

       --vendor
              Print the vendor string from the OpusTags packet and do nothing else. Standard tags
              operations are not supported when specifying this flag.

       --set-vendor VALUE
              Replace the vendor string by the specified value.  This  action  can  be  performed
              alongside tag edition.

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

       •      Multiplexed streams are not supported.

       •      Control characters inside tags are printed raw rather than being escaped.

       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 <fmang+opustags@mg0.fr>

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