vorbis-tools/vorbiscomment/vorbiscomment.1

   1 .\" Process this file with
   2 .\" groff -man -Tascii vorbiscomment.1
   3 .\"
   4 .TH VORBISCOMMENT 1 "December 30, 2008" "Xiph.Org Foundation" "Ogg Vorbis Tools"
   5
   6 .SH NAME
   7 vorbiscomment \- List or edit comments in Ogg Vorbis files
   8
   9 .SH SYNOPSIS
  10 .B vorbiscomment
  11 .B [-l]
  12 .RB [ -R ]
  13 .RB [ -e ]
  14 .I file.ogg
  15 .br
  16 .B vorbiscomment
  17 .B -a
  18 .B [ -c commentfile | -t \*(lqname=value\*(rq ]
  19 .RB [ -q ]
  20 .RB [ -R ]
  21 .RB [ -e ]
  22 .I in.ogg
  23 .I [out.ogg]
  24 .br
  25 .B vorbiscomment
  26 .B -w
  27 .B [ -c commentfile | -t \*(lqname=value\*(rq ]
  28 .RB [ -q ]
  29 .RB [ -R ]
  30 .RB [ -e ]
  31 .I in.ogg
  32 .I [out.ogg]
  33
  34 .SH DESCRIPTION
  35 .B vorbiscomment
  36 Reads, modifies, and appends Ogg Vorbis audio file metadata tags.
  37
  38 .SH OPTIONS
  39 .IP "-a, --append"
  40 Append comments.
  41 .IP "-c file, --commentfile file"
  42 Take comments from a file. The file is the same format as is output by the 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.
  43 .IP "-h, --help"
  44 Show command help.
  45 .IP "-l, --list"
  46 List the comments in the Ogg Vorbis file.
  47 .IP "-q, --quiet"
  48 Quiet mode.  No messages are displayed.
  49 .IP "-t 'name=value', --tag 'name=value'"
  50 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.
  51 .IP "-w, --write"
  52 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.
  53 .IP "-R, --raw"
  54 Read and write comments in UTF-8, rather than converting to the user's character set.
  55 .IP "-e, --escapes"
  56 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.
  57
  58 Supported escapes are c-style "\en", "\er", "\e\e" and "\e0". A backslash followed by anything else is an error.
  59
  60 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.
  61 .IP "-V, --version"
  62 Display the version of vorbiscomment.
  63
  64 .\" Examples go here
  65 .SH EXAMPLES
  66
  67 To just see what comment tags are in a file:
  68
  69     vorbiscomment -l file.ogg
  70
  71 To edit those comments:
  72
  73     vorbiscomment -l file.ogg > file.txt
  74     [edit the comments in file.txt to your satisfaction]
  75     vorbiscomment -w -c file.txt file.ogg newfile.ogg
  76
  77 To simply add a comment:
  78
  79     vorbiscomment -a -t 'ARTIST=No One You Know' file.ogg newfile.ogg
  80
  81 To add a set of comments from the standard input:
  82
  83     vorbiscomment -a file.ogg
  84     ARTIST=No One You Know
  85     ALBUM=The Famous Album
  86     <ctrl-d>
  87
  88 .SH TAG FORMAT
  89
  90 See http://xiph.org/vorbis/doc/v-comment.html for documentation on the Ogg Vorbis tag format, including a suggested list of canonical tag names.
  91
  92 .SH AUTHORS
  93
  94 .TP
  95 Program Authors:
  96 .br
  97 Michael Smith <msmith@xiph.org>
  98 .br
  99 Ralph Giles <giles@xiph.org>
 100 .br
 101
 102 .TP
 103 Manpage Author:
 104 .br
 105 Christopher L Cheney <ccheney@debian.org>
 106
 107 .SH "SEE ALSO"
 108
 109 .PP
 110 \fBoggenc\fR(1), \fBoggdec\fR(1), \fBogg123\fR(1), \fBogginfo\fR(1)