GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages


Manual Reference Pages  -  TAGUTIL (1)

NAME

tagutil - edit and display music files tags

CONTENTS

Synopsis
Description
Options
Actions
Backends
Output Formats
Environment
Exit Status
Examples
Authors
Bugs

SYNOPSIS

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

DESCRIPTION

tagutil 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, output 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 -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 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 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: nbsp;%

 %key Is replaced by the value of the first "key" tag found in the tag list. This syntax is used when "key" does 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 a tag expanded) contains a "/" character, tagutil will check the destination directory. If the destination 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 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. While this section describe each music file format supported, the complete list supported by the installed version should be checked with -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 several popular audio formats (http://taglib.github.io/). This backend 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 FORMATS

tagutil is designed in a modular way, making it very easy to add support for any output format. While this section describe each format implemented, the complete list supported by the installed version should be checked with -h .
yml YAML is the default format because it is both human friendly for edit and print and have 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 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


.Ex -std

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


.An Alexandre Perrin Aq alex@kaworu.ch
.An Baptiste Daroussin Aq 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.

Search for    or go to Top of page |  Section 1 |  Main Index


Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.