TAGUTIL(1) BSD General Commands Manual TAGUTIL(1)NAMEtagutil — edit and display music files tags
SYNOPSIStagutil [-hpYN] [-F format] [action ...] file ...
DESCRIPTIONtagutil displays and modify tags stored in musics files. tagutil can
support most music files format (including FLAC, ogg/vorbis and mp3) and
multiple output formats including YAML (the default) to be both human and
script friendly.
OPTIONS-h Show tagutil help displaying the version, OPTIONS, ACTIONS, out‐
put FORMATS, and BACKENDS.
-p Create intermediate directories as required on rename. Useful
when the rename pattern expand to a path in a directory that does
not exist. It is ignored when there is no “rename” action. This
option is inspired by the -p option from mdkir(1).
-Y answer “yes” to all questions.
-N answer “no” to all questions.
-F format
Use format for tags output and parsing. The list of supported
values for format can be seen by invoking tagutil-h. see also
the FORMATS section.
ACTIONS
Each given actions are executed in order for each file. If no actions
are given, print will be executed.
print Display the list of tags (default). See also FORMATS.
backend
Display the backend used. See also BACKENDS.
clear:TAGNAME
Erase all TAGNAME. if TAGNAME is empty, all tags are erased.
add:TAGNAME=value
Add a new tag at the end of the tag list.
set:TAGNAME=value
Replace the first instance of TAGNAME and clear the following.
Equivalent to add:TAGNAME=value if there is no TAGNAME in the tag
list.
edit Execute EDITOR to prompt for tag editing in a temporary file, and
then load the temporary file. The load action is cancelled if the
editing process exited with a non-zero status code or if the tem‐
porary file was left unmodified.
load:fmtfile
Parse the given file at fmtfile and load the tags into the music
file. fmtfile has to honor the given format (or the default) in
order to be successfully parsed. If fmtfile is empty or “-”, the
standard input is used.
rename:pattern
rename files expanding given pattern. The pattern can contain
TAGNAME keywords expanded with their value. To avoid accidental
rename, confirmation is asked before rename (see -Y and -N
options).
The pattern use % for TAGNAME expansion. A litteral % can be
escaped with a backslash: \%
%key Is replaced by the value of the first “key” tag found in
the tag list. This syntax is used when “key” does con‐
tains only alphanumeric character(s).
%{key} Is replaced by the value of the first “key” tag found in
the tag list. Any character can be enclosed into the
delimiting braces (to enclose the “}” character, escape
it with a backslash).
NOTE: if the pattern (or a tag expanded) contains a “/” charac‐
ter, tagutil will check the destination directory. If the desti‐
nation directory exists, tagutil will rename the file and its
parent directoy will change. If the destination directory does
not exist and -p was given, tagutil will try to create the inter‐
mediate directories before the rename. If the destination direc‐
tory does not exist and -p was not given, tagutil will display an
error message and exit.
BACKENDStagutil is designed in a modular way, making it very easy to add support
for any file format. While this section describe each music file format
supported, the complete list supported by the installed version should be
checked with tagutil-h.
libFLAC
Free Lossless Audio Codec (FLAC) files format
(https://xiph.org/flac/). The FLAC format use Vorbis Comment to
store tags. This means that, like Ogg/Vorbis, FLAC supports an
ordered, unlimited set of tags allowing duplicate keys.
libvorbis
Ogg/Vorbis files format (http://www.vorbis.com/). Ogg/Vorbis use
Vorbis Comment to store tags and supports an ordered, unlimited
set of tags allowing duplicate keys.
TagLib TagLib is a library for reading and editing the meta-data of sev‐
eral popular audio formats (http://taglib.github.io/). This back‐
end only support a limited set of tags : “title”, “artist”,
“album”, “comment”, “genre”, “year” and “track”.
ID3V1 A simple ID3v1.1 backend (built-in). ID3v1.0 and ID3v1.1 are only
used by old mp3 files and has been superseded by ID3v2 more than
ten years ago. It simplicity makes it a good example for backend
implementation and it is disabled by default.
OUTPUT FORMATStagutil is designed in a modular way, making it very easy to add support
for any output format. While this section describe each format imple‐
mented, the complete list supported by the installed version should be
checked with tagutil-h.
yml YAML is the default format because it is both human friendly for
edit and print and have good support in popular scripting lan‐
guages. It is implemented using libyaml
(http://pyyaml.org/wiki/LibYAML), which can produce very detailed
error messages (useful to debug scripts).
json JSON is intended to be used for scripting as an alternative to
YAML.
ENVIRONMENT
The LC_ALL, EDITOR and TMPDIR environment variables affect the execution
of tagutil.
LC_ALL Note that both standard YAML and JSON require UTF-8 and so will
tagutil when using one of these format. Command line actions like
“add” will honor LC_ALL by encoding the TAGNAME and “value”
action arguments in UTF-8 if needed.
EDITOR required when the edit action is invoked.
TMPDIR used to store the temporary file used by the edit action.
EXIT STATUS
The tagutil utility exits 0 on success, and >0 if an error occurs.
EXAMPLES
Print the tags of file.flac:
% tagutil file.flac
Set the title "foo" to file.ogg:
% tagutil set:title=foo file.ogg
Interactivly edit the file.flac's tags:
% tagutil edit file.flac
Rename file.flac using its artist, album, tracknumber and title tags:
% tagutil rename:"%artist - %album - [%tracknumber] - %title"
file.flac
Clear all tags and then add an artist and album tag.
% tagutil clear: add:artist="Pink Floyd" add:album="Meddle" *.flac
Switch all tag keys “track” to “trackname”
% tagutil file.flac | sed -e 's/^- track:/- tracknumber:/' |
tagutil load: file.flac
A Ruby script that trim every tag values:
#!/usr/bin/env ruby
require 'yaml'
require 'open3'
ARGV.each do |arg|
Open3.popen3('tagutil', arg) do |_, pstdout, pstderr|
$s = pstdout.read
$e = pstderr.read
end
yaml = YAML.load($s)
if not yaml
STDERR.puts($e)
else
stripped = Array.new
yaml.each do |hash|
hash.each do |key, val|
newval = if val.respond_to?(:strip) then val.to_s.strip else val end
stripped << { key => newval }
end
end
Open3.popen3('tagutil', 'load:-', arg) do |pstdin, pstdout, pstderr|
pstdin << stripped.to_yaml
pstdin.close
STDERR.puts($e) unless ($e = pstderr.read).strip.empty?
end
end
end
AUTHORS
Alexandre Perrin ⟨alex@kaworu.ch⟩
Baptiste Daroussin ⟨bapt@FreeBSD.org⟩
BUGS
All current implemented output format will force UTF-8 for both output
and parsing.
When the TagLib backend is used with mp3 files it will interprete integer
values for the “genre” tag as index for the ID3 Tag Genre ID (extended)
list. Although this is intended as a feature, it make the interface
inconsistant with other backends.
BSD December 16, 2013 BSD
