.\" Process this file with
.\" groff -man -Tascii vorbiscomment.1
.\"
.TH VORBISCOMMENT 1 "December 30, 2008" "Xiph.Org Foundation" "Ogg Vorbis Tools"

.SH NAME
vorbiscomment \- List or edit comments in Ogg Vorbis files

.SH SYNOPSIS
.B vorbiscomment
.B [-l]
.RB [ -R ]
.RB [ -e ]
.I file.ogg
.br
.B vorbiscomment
.B -a
.B [ -c commentfile | -t \*(lqname=value\*(rq | -d \*(lqname=value\*(rq ]
.RB [ -q ]
.RB [ -R ]
.RB [ -e ]
.I in.ogg
.I [out.ogg]
.br
.B vorbiscomment
.B -w
.B [ -c commentfile | -t \*(lqname=value\*(rq ]
.RB [ -q ]
.RB [ -R ]
.RB [ -e ]
.I in.ogg
.I [out.ogg]

.SH DESCRIPTION
.B vorbiscomment
Reads, modifies, and appends Ogg Vorbis audio file metadata tags.

.SH OPTIONS
.IP "-a, --append"
Updates comments.
.IP "-c file, --commentfile file"
Take comments from a file. The file is the same format as is output by the -l option or given to the -t option: one element per line in 'tag=value' format. If the file is /dev/null and -w was passed, the existing comments will be removed.
.IP "-h, --help"
Show command help.
.IP "-l, --list"
List the comments in the Ogg Vorbis file.
.IP "-t 'name=value', --tag 'name=value'"
Specify a new tag on the command line. Each tag is given as a single string. The part before the '=' is treated as the tag name and the part after as the value.
.IP "-d 'name[=value]', --rm 'name[=value]'"
Specify a tag on the command line for removal. Each tag is given as a single string. The part before the '=' is treated as the tag name and the part after as the value. If no value is given all tags are deleted with the given name. Otherwise only those with matching values are deleted.
.IP "-w, --write"
Replace comments with the new set given either on the command line with -t or from a file with -c. If neither -c nor -t is given, the new set will be read from the standard input.
.IP "-R, --raw"
Read and write comments in UTF-8, rather than converting to the user's character set.
.IP "-e, --escapes"
Quote/unquote newlines and backslashes in the comments. This ensures every comment is exactly one line in the output (or input), allowing to filter and round-trip them. Without it, you can only write multi-line comments by using -t and you can't reliably distinguish them from multiple one-line comments.

Supported escapes are c-style "\en", "\er", "\e\e" and "\e0". A backslash followed by anything else is an error.

Note: currently, anything after the first "\e0" is thrown away while writing.  This is a bug -- the Vorbis format can safely store null characters, but most other tools wouldn't handle them anyway.
.IP "-V, --version"
Display the version of vorbiscomment.

.\" Examples go here
.SH EXAMPLES

To just see what comment tags are in a file:

    vorbiscomment -l file.ogg

To edit those comments:

    vorbiscomment -l file.ogg > file.txt
    [edit the comments in file.txt to your satisfaction]
    vorbiscomment -w -c file.txt file.ogg newfile.ogg

To simply add a comment:

    vorbiscomment -a -t 'ARTIST=No One You Know' file.ogg newfile.ogg

To add a set of comments from the standard input:

    vorbiscomment -a file.ogg
    ARTIST=No One You Know
    ALBUM=The Famous Album
    <ctrl-d>

.SH TAG FORMAT

See https://xiph.org/vorbis/doc/v-comment.html for documentation on the Ogg Vorbis tag format, including a suggested list of canonical tag names.

.SH AUTHORS

.TP
Program Authors:
.br
Michael Smith <msmith@xiph.org>
.br
Ralph Giles <giles@xiph.org>
.br

.TP
Manpage Author:
.br
Christopher L Cheney <ccheney@debian.org>

.SH "SEE ALSO"

.PP
\fBoggenc\fR(1), \fBoggdec\fR(1), \fBogg123\fR(1), \fBogginfo\fR(1)