taged(1)

NAME
taged - a command line ID3 tag manipulation utility

SYNOPSIS
taged [ options ] [ file | directory ... ]

DESCRIPTION
taged is a command line utility that can create and modify ID3 data, usually found in .mp3 files. Besides supporting text frames like artist, title, track number and so on, taged also supports attached pictures, play counters and generated playlists. Taged aims at being quick and easy to use when many tags needs to be created/updated, and handles regular expression matching of tag data from filenames, as well as renaming files based on the tag.

If no files are given, taged reads all *.mp3 files in the current directory.

The default action is to print the ID3 information of each file found. If a directory is given on the command line, all *.mp3 files in that directory are processed, unless the --directory option is given.

OPTIONS
In the following list, an EXPR argument is an expression as defined in the EXPRESSIONS section below. FRAME arguments are described in section FRAME CODES.

-a STRING, --artist=STRING
    Set artist

-A STRING, --album=STRING
    Set album

-t STRING, --title=STRING
    Set song title

-T NUMBER, --track=NUMBER
    Set track number

--track-total[=NUMBER]
    Set the total number of tracks. Without argument, the total number of tracks is reset. If the total number of tracks is set, the track number field will change to the form "X/y", where "X" is the track number and "y" is the total number of tracks.

-g STRING, --genre=STRING
    Set genre. STRING can be either a free form text string or a number mapped to the predefined genre numbers. Use --list-genres to display all predefined genres. ID3v1 only supports the predefined genres (given either as a number or the corresponding text string). For ID3v2 tags, you can specify more than one genre, use --append-frames to append a new genre.

-y NUMBER, --year=NUMBER
    Set the year for the recording time.

-c [LANGUAGE]:[DESCRIPTION]:[COMMENT], --comment=[LANGUAGE]:[DESCRIPTION]:[COMMENT]

    Set a comment. All parts are optional. If LANGUAGE or DESCRIPTION is omitted, they will be set to an empty string. Only one comment with the same LANGUAGE and DESCRIPTION are allowed (this also applies to comments where the language and description are empty, thus you can only have one comment with both empty language and description). If the COMMENT part is empty, the comment with the specified language and description are removed, if one existed. An empty comment are never added to the tag.

    The comment can include these escape codes:

    \\n - a newline character

    \\r - a carriage return character

    \\t - a tab character

-f ID:STRING, --set-frame=ID:STRING
    Set any text frame. The ID is the four character name of the frame to set. Only text frames (names beginning with T) can be set this way.

-m EXPR, --match=EXPR
    Match tag info from filename. EXPR is actually a regular expression, where you can think of the format specifiers (described below) as a subexpression (a group within paranthesis). If this doesn't makes sense to you, look at the following example:

        --match="%T - %t\.mp3" matches track 4 and title "Hotel Noir" from the filename "04 - Hotel Noir.mp3". The compiled regular expression is in this case "([0-9]*) - (.*)\.mp3" and the track number is subexpresison 1 and the title subexpresion 2. The dot in ".mp3" is quoted so it really matches a dot.

    Besides the format specifiers below, an additional %i can be used to ignore parts of the filename.

-r[EXPR], --rename[=EXPR]
    Rename filename from tag info. If EXPR includes slashes it is treated as a pathname rather than a filename. See the EXPRESSIONS section below. Without an argument, the default rename expression given by the configuration file directive default-rename-string is used. If any of the format specifiers in EXPR is unresolved, ie the frame doesn't exist in the tag, a warning is printed and the file is not renamed.

-S, --sanitize-filename
    When creating filenames (with the --rename, --playlist and --export options), this option tries to sanitize the filename by replacing and removing strange characters. The action taken is controlled by the filename-replace-chars and filename-remove-chars configuration file directives. See section CONFIGURATION FILE below.

-s[FRAME(S)], --strip[=FRAME(S)]
    Strip frames from the tag. With no argument, --strip strips all frames from the tag.

--remove-v1
    Remove ID3v1 tag

--remove-v2
    Remove ID3v2 tag(s)

--remove-all
    Remove all tag(s)

-U[FRAME(S)], --underscore[=FRAME(S)]
    Convert underscores to spaces in the specified frames. Without argument the frames specified in default-underscore-frames (see CONFIGURATION FILE below) are affected.

-C[FRAME(S)], --capitalize[=FRAME(S)]
    Capitalize the specified text frames. Without argument the frames specified in default-capitalize-frames (see CONFIGURATION FILE below) are affected.

--append-frames
    Append rather than replace frames

--attach-picture=[MIMETYPE]:[TYPE]:[DESCRIPTION]:FILE
    Attach a picture. All parts but the FILE are optional. If they are omitted, they are given the following default values: DESCRIPTION is empty, TYPE is 0 ("Other") and MIMETYPE is "image/".

    There may be several pictures attached to one file, but only one with the same content descriptor. There may only be one picture with the picture type declared as picture type 01 and 02 (file icons) respectively.

--play-counter=NUMBER
    Set play counter value

-u, --update
    Update to id3 tag version 2.4.0

-i[FRAME(S)], --interactive[=FRAME(S)]
    Prompt interactively for each frame. Without argument the frames specified in default-interactive-frames (see CONFIGURATION FILE below) are affected.

-p[EXPR], --playlist[=EXPR]
    Create a playlist for all files found. The playlist file is named after EXPR and consists of one filename per line. If EXPR is not given, a default expression is used from the default-playlist-file configuration file directive. If EXPR contains format specifiers, they are expanded by the first file that completely resolves it. Thus it might not be the desired action to include %a (the artist) format specifier in a playlist for a "various artists" album, since %a will be set by the first file that resolves it (and other files would resolve it to something else).

-B[FRAME(S)], --save-binary[=FRAME(S)]
    Save binary frame(s). If no FRAME(S) are specified, all binary frames will be saved. The binary frames are: UFID, MCDI, ETCO, MLLT, SYTC, SYLT, RVA2, EQU2, APIC, GEOB, AENC, POSS, COMR, ENCR, GRID, PRIV, SIGN and ASPI. The found binary frames will be saved in different files, ending with the name of the frame. A picture frame in the file mysong.mp3 would be saved in the file mysing.mp3.APIC.

-E[EXPR], --export[=EXPR]
    Export an ID3v2 tag to a file. The EXPR argument is the name of the file in which the tag is saved. Without argument, a default filename is constructed as the original filename stripped with any mp3 extension and .id3 appended.

-F, --force-create
    Create new tag even if the file is not an mp3 file. If this flag is not specified, taged will refuse to add a tag to non-mp3 file.

-P, --force-padding
    Enforce padding of tag data. Normally, the padding is not changed if a tag is updated, as long as the new tag fits within the old padded size.

--padded-size
    Set the padded minimum size of tags. This overrides the padded-size configuration file option. If set to zero, no padding is applied.

-1, --id3v1
    Only render ID3v1 tags

-2, --id3v2
    Only render ID3v2 tags

-v, --verbose
    Show all available information in the ID3 tag. By default only title, artist, album, track number, year of release and comments without a description are shown.

-w, --no-text-wrap
    Don't wrap long text frames.

--no-colors
    Don't use colors

-l, --list-genres
    Show list of valid genres

-L, --list-frames
    Show list of valid ID3v2 frames

--list-picture-types
    Show list of valid picture types

-x, --show-all-tags
    Show all found tags

-n, --no-mp3-info
    Don't show technical mp3 info

--config-file=FILENAME
    Parse alternative configuration file

--no-config-file
    Don't parse any config file

-d, --directory
    Don't recurse into directories

-h, --help
    Display a short summary of accepted options.

-V, --version
    Display the version number.

FRAME CODES
Frames are what a tag consists of. A frame has a name (four uppercase characters) and one or more values associated with it. All valid frames are listed with the --list-frames command line option.

Frames can be specified either by a shorthand notation or the complete four character name. Different frames are separated by a colon (however, shorthand codes can be grouped together). The shorthand codes are:

    a - artist

    A - album

    t - title

    T - track number

    g - genre

    y - year

For example, the following list of frames specifies the artist, track number and copyright message: "aT:TCOP".

EXPRESSIONS
An expression is a string with certain format specifiers that is mapped to the content of a frame. A format specifier consists of a percent sign and a character code. The valid format specifiers are:

    %x where x is one of the shorthand frame codes described in the FRAME CODES section above.

    %% - a percent sign

    %(Txyz) - the contents of the text frame Txyz. If there are multiple Txyz frames in the tag, only the first frame will be used. Frames that begin with the character T are text frames.

For example, the expression "%a - %T - %t - %(TCON).mp3" will expand to "artist - track - title - genre.mp3". In this example, %(TCON) was used instead of the shorter %g expression.

CONFIGURATION FILE
Unless the --no-config-file option is given, taged reads configuration from ~/.taged.conf, or from a file specified by a --config-file option.

The format of the configuration file is simple: each directive consists of a variable, an equal sign and the value. Strings containing spaces should be enclosed within quotation marks. Lists are written as comma-separated values within curly braces. To append values to a list, use the += operator instead of the equal sign. Numbers are assumed to be in hexadecimal notation if they begin with 0x and in octal notation if they begin with a zero. Booleans are written either as true/false, yes/no or on/off.

Options given on the command line override the options set in the configuration file.

  Recognized configuration file variables

default-rename-string (string)
    Default expression used by the --rename option.

default-playlist-file (string)
    Default filename for playlists created by the --playlist option.

default-capitalize-frames (string)
    Default list of frames used by the --capitalize option.

default-interactive-frames (string)
    Default list of frames used by the --interactive option.

default-underscore-frames (string)
    Default list of frames used by the --underscore option.

verbose (boolean)
    Same as the --verbose command line option.

use-colors (boolean)
    Same as the --no-colors command line option.

no-text-wrap (boolean)
    Same as the --no-text-wrap command line option.

append-frames (boolean)
    Same as the --append-frames command line option.

show-all-tags (boolean)
    Same as the --show-all-tags command line option.

no-recurse-directories (boolean)
    Same as the --directory command line option.

no-mp3-info (boolean)
    Same as the --no-mp3-info command line option.

padded-size (integer)
    This is the minimum size in bytes of a new tag. If the tag is smaller than this value, the tag is padded upto this size. If the tag is larger than padded-size, the size of the tag will be a multiple of this value, just enough to store the tag.

    The padding is normally not changed if a tag is updated, as long as the new tag fits with the old padded size. Use the --force-padding command line option to override this behaviour. However, changing the padding requires a rewrite of the whole file, since the ID3v2 tag resides in the beginning of the file.

force-padding (boolean)
    Same as the --force-padding command line option.

color-normal (string)
    Normal color string.

color-warning (string)
    Color string used when printing warnings.

color-header (string)
    Color string used for the header (filename and mp3 data).

color-frame (string)
    Color string used when printing the content of frames.

color-message (string)
    Color string used in some other messages.

lower-case-words (string list)
    Those words are made lower case with the --capitalize option.

upper-case-words (string list)
    Those words are made upper case with the --capitalize option.

filename-replace-chars (string list)
    Used in conjunction with --sanitize-filename. This is a list of two-character strings where the first character is the character to replace with the second character in the string.

    For example, setting filename-replace-chars to {"/-", "\\-"} will replace all slashes and backslashed with dashes.

filename-remove-chars (string)
    Used in conjunction with --sanitize-filename. All characters found in this string are removed when creating filenames, for example with the --rename and --playlist options.

sanitize-filename (boolean)
    Same as the --sanitize-filename command line option.

AUTHOR
Written by Martin Hedenfalk.

Using lidid3tag written by Robert Leslie.

BUGS
taged can only write ID3v2 tags at the beginning of files (ie, at offset 0).

Play counters larger than 32 bits wide are not supported.

The created playlists are sorted alphabetically by filename, not track number.

COPYRIGHT
Copyright (C) 2002 Martin Hedenfalk <mhe@home.se>