TAGUTIL(1)

💖 NAME 💖

okay so bestie, this is TAGUTIL(1) from the General Commands Manual — and it's literally tagutil, the icon who edits and displays music files tags. 💅 No cap, tagutil can support most music file formats (including FLAC, Ogg/Vorbis and MP3) and multiple output formats including YAML (the default), so it stays both human and script friendly. periodt.

🌸 SYNOPSIS 🌸

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

✨ DESCRIPTION ✨

tagutil displays and modifies tags stored in music files. It 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, output 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 contains 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 an expanded tag) contains a / character, tagutil will check the destination directory. If the destination 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 intermediate directories before the rename. If the destination directory 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. This section describes each music file format supported, but 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 uses 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, unlimited set of tags allowing duplicate keys.

TagLib

TagLib is a library for reading and editing the meta-data of several 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 have 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. This section describes each implemented format, but 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 languages. 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 formats. 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 trims every tag value:

#!/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 makes the interface inconsistent with other backends.

---

xoxo, your Debian bestie 💖 — this page is from Debian, dated December 18, 2015, and it's literally TAGUTIL(1). periodt. 🎀