Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
TAGUTIL(1)		FreeBSD	General	Commands Manual		    TAGUTIL(1)

NAME
     tagutil --	edit and display music files tags

SYNOPSIS
     tagutil [-hpYN] [-F format] [action ...] file ...

DESCRIPTION
     tagutil displays and modifies tags	stored in music	files.	tagutil	can
     support most music	file formats (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 expands 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 mkdir(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 action is executed in	order for each file.  If no action is 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
	     temporary 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 according to the given pattern.  The pattern can
	     contain TAGNAME keywords which will be expanded with their	value.
	     tagutil will ask for confirmation to avoid	accidental renames
	     (see -Y and -N options).

	     The pattern language uses % for TAGNAME expansion.	 A literal %
	     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 de-
		     limiting braces (to enclose the "}" character, escape it
		     with a backslash).

	     NOTE: If the pattern (or an expanded tag) contains	a "/" charac-
	     ter, tagutil will check the destination directory.	 If the	desti-
	     nation directory exists, tagutil will rename the file and its
	     parent directory 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.

BACKENDS
     tagutil 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 Comments 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
	     uses Vorbis Comments to store tags	and supports an	ordered, un-
	     limited 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
	     backend only supports 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.  Its simplicity makes it a good example for
	     backend implementation and	it is disabled by default.

OUTPUT FORMATS
     tagutil is	designed in a modular way, making it very easy to add support
     for any output format.  While this	section	describes each implemented
     format, 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	has 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

     Interactively edit	the file.flac's	tags:
	   % tagutil edit file.flac

     Rename file.flac using its	artist,	album, track number 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 formats will force UTF-8 for both output
     and parsing.

     When the TagLib backend is	used with MP3 files it will interpret 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 in-
     consistent	with other backends.

FreeBSD	13.0		       December	18, 2015		  FreeBSD 13.0

NAME | SYNOPSIS | DESCRIPTION | OPTIONS | ACTIONS | BACKENDS | OUTPUT FORMATS | ENVIRONMENT | EXIT STATUS | EXAMPLES | AUTHORS | BUGS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=tagutil&sektion=1&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help