mirror of
https://github.com/fmang/opustags.git
synced 2024-11-10 07:27:22 +01:00
118 lines
4.8 KiB
Groff
118 lines
4.8 KiB
Groff
.TH opustags 1 "November 2018" "@PROJECT_NAME@ @PROJECT_VERSION@"
|
||
.SH NAME
|
||
opustags \- Opus comment editor
|
||
.SH SYNOPSIS
|
||
.B opustags --help
|
||
.br
|
||
.B opustags
|
||
.RI [ OPTIONS ]
|
||
.I INPUT
|
||
.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 editing.
|
||
.PP
|
||
In read-only mode, only the beginning of \fIINPUT\fP is read, and the tags are
|
||
printed on standard output.
|
||
\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
|
||
In editing mode, you need to specify an output file with \fB--output\fP, or use \fB--in-place\fP to
|
||
overwrite the input file. 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 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.
|
||
.PP
|
||
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.
|
||
.SH OPTIONS
|
||
.TP
|
||
.B \-h, \-\-help
|
||
Display a brief description of the options.
|
||
.TP
|
||
.B \-o, \-\-output \fIFILE\fI
|
||
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
|
||
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 \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 one of them, though usually
|
||
there is only one of each type.
|
||
.TP
|
||
.B \-a, \-\-add \fIFIELD=VALUE\fP
|
||
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
|
||
type that may already exist, then adds it with the wanted value.
|
||
This is strictly equivalent to \fB--delete\fP \fIFIELD\fP \fB--add\fP
|
||
\fIFIELD=VALUE\fP. You can combine it with \fB--add\fP to add tags of the same
|
||
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 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 standard input.
|
||
Each line must specify a \fIFIELD=VALUE\fP pair and be separated with line feeds.
|
||
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 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
|
||
.SH SEE ALSO
|
||
.BR vorbiscomment (1),
|
||
.BR sed (1)
|
||
.SH AUTHOR
|
||
Frédéric Mangano-Tarumi <fmang@mg0.fr>
|
||
.PP
|
||
Report bugs at <https://github.com/fmang/opustags/issues>
|