Provided by: eyed3_0.8.10-4_all bug

NAME

       eyeD3 - displays and manipulates id3-tags on mp3 files

SYNOPSIS

       eyeD3 [options] PATH [PATH...]

DESCRIPTION

       eyeD3  Manipulates ID3 tags in mp3 files and is able to read/write and convert between ID3
       v1.0, v1.1, v2.3 and v2.4 tags.  High-level access is provided to most  frames,  including
       APIC (i.e., images) frames.

       The  eyeD3 command line interface is based on plugins that operates on files.  To list the
       available plugins use the --plugins option and to select a  plugin  pass  its  name  using
       --plugin=NAME.

       The  PATH  argument(s)  along with optional usage of --exclude are used to tell eyeD3 what
       files or directories to process. Directories  are  searched  recursively  and  every  file
       encountered is passed to the selected plugin until no more files are found.

BASE OPTIONS

       -h, --help
              Show a brief help string and exit.

       --version
              Display version information and exit

       --exclude=PATTERN
              A regular expression for path exclusion. May be specified multiple times.

       -L, --plugins
              List all available plugins.

       -P NAME, --plugin=NAME
              Specify which plugin to use. The default is ´classic'

       -C FILE, --config=FILE
              Supply  a  configuration file.  The default is ´~/.eyeD3/config.ini', although even
              that is optional.

       --no-config
              Do not load the default user config ´~/.eyeD3/config.ini'.  The -c/--config options
              are still honored if present.

       --backup
              Plugins  should  honor this option such that a backup is made of any file modified.
              The backup is made in same directory with a ´.orig' extension added.

       -Q, --quiet
              A hint to plugins to output less.

       --fs-encoding=ENCODING
              Use the specified file system encoding for filenames.  Default is detected from the
              current  locale,  overriding  is  useful for example when reading from mounted file
              systems.

       --no-color
              Suppress color codes in console output.  This  will  happen  automatically  if  the
              output is not a TTY (e.g.  when redirecting to a file)

DEBUGGING

       -l LEVEL[:LOGGER], --log-level=LEVEL[:LOGGER]
              Set  a log level. This option may be specified multiple times.  If a logger name is
              specified than the level applies only to that logger, otherwise the level is set on
              the  top-level logger. Acceptable levels are ´debug', ´verbose', ´info', ´warning',
              ´error', ´critical'.

       --profiler
              Run using python profiler.

       --debugger
              Drop into python debugger when errors occur.

`CLASSIC` PLUGIN

       This plugin is the classic eyeD3 interface for viewing and editing tags.

       All PATH arguments are parsed and displayed. Directory paths are searched recursively. Any
       editing options (--artist, --title) are applied to each file read.

       All  date  options  (--release-year  excepted)  follow  ISO 8601 format. This is ´yyyy-mm-
       ddThh:mm:ss'. The year is  required,  and  each  component  thereafter  is  optional.  For
       example, "2012-03" is valid, "2012--12" is not.

       -a STRING, --artist=STRING
              Set the artist name.

       -A STRING, --album=STRING
              Set the album name.

       -b STRING, --album-artist=STRING
              Set  the  album  artist  name.  "Various  Artists", for example. Another example is
              collaborations when the track artist might be "Eminem featuring  Proof"  the  album
              artist would be "Eminem".

       -t STRING, --title=STRING
              Set the track title.

       -n NUM, --track=NUM
              Set the track number. Use 0 to clear.

       -N NUM, --track-total=NUM
              Set total number of tracks. Use 0 to clear.

       --track-offset=N
              Increment/decrement  the  track  number  by  [-]N.  This  option  is  applied after
              --track=N is set.

       -d NUM, --disc-num=NUM
              Set the disc number. Use 0 to clear.

       -G GENRE, --genre=GENRE
              Set the genre. If the argument is a standard ID3 genre name or number both will  be
              set.  Otherwise, any string can be used. Use --plugin=genres for a list of standard
              ID3 genre names/ids.

       -Y YEAR, --release-year=YEAR
              Set the year the track was released. Use the date options for more  precise  values
              or dates other than release.

       -c STRING, --comment=STRING
              Set  a  comment.  In  ID3  tags  this is the comment with an empty description. See
              --add-comment to add multiple comment frames.

       --rename=PATTERN
              Rename file (the extension is  not  affected)  based  on  data  in  the  tag  using
              substitution     variables:    $album,    $album_artist,    $artist,    $best_date,
              $best_date:prefer_recording,                      $best_date:prefer_recording:year,
              $best_date:prefer_release,     $best_date:prefer_release:year,     $best_date:year,
              $disc:num,     $disc:total,     $file,      $file:ext,      $original_release_date,
              $original_release_date:year,  $recording_date, $recording_date:year, $release_date,
              $release_date:year, $title, $track:num, $track:total.

   ID3 options
       -1, --v1 Only read and write ID3 v1.x tags. By default, v1.x tags are only read or written
       if there is not a v2 tag in the file.

       -2, --v2
              Only  read/write ID3 v2.x tags. This is the default unless the file only contains a
              v1 tag.

       --to-v1.1
              Convert the file's tag to ID3 v1.1 (Or 1.0 if there is no track number).

       --to-v2.3
              Convert the file's tag to ID3 v2.3.

       --to-v2.4
              Convert the file's tag to ID3 v2.4

       --release-date=DATE
              Set the date the track/album was released

       --orig-release-date=DATE
              Set the original date the track/album was released.

       --recording-date=DATE
              Set the date the track/album was recorded

       --encoding-date=DATE
              Set the date the file was encoded

       --tagging-date=DATE
              Set the date the file was tagged

       --publisher=STRING
              Set the publisher/label name

       --play-count=[+]N
              Set the number of times played counter. If the argument value begins with  ´+'  the
              tag's play count is incremented by N, otherwise the value is set to exactly N.

       --bpm=N
              Set the beats per minute value.

       --unique-file-id=OWNER_ID:ID
              Add  a  unique  file  ID  frame.  If  the ID arg is empty the frame is removed.  An
              OWNER_ID is required. The ID may be no more than 64 bytes.

       --add-comment=COMMENT[:DESCRIPTION[:LANG]]
              Add or replace a comment. There may be more than one comment in a tag, as  long  as
              the  DESCRIPTION and LANG values are unique.  The default DESCRIPTION is ´' and the
              default language code is ´eng'.

       --remove-comment=DESCRIPTION[:LANG]
              Remove comment matching DESCRIPTION and LANG. The default language code is ´eng'.

       --remove-all-comments
              Remove all comments from the tag.

       --add-lyrics=LYRICS_FILE[:DESCRIPTION[:LANG]]
              Add or replace a lyrics. There may be more than one set of lyrics in a tag, as long
              as  the  DESCRIPTION  and LANG values are unique. The default DESCRIPTION is '' and
              the default language code is 'eng'.

       --remove-lyrics=DESCRIPTION[:LANG]
              Remove lyrics matching DESCRIPTION and LANG. The default language code is 'eng'.

       --remove-all-lyrics
              Remove all lyrics from the tag.

       --text-frame=FID:TEXT
              Set the value of a text frame. To remove the frame, specify an  empty  value.   For
              example, --text-frame="TDRC:"

       --user-text-frame=DESC:TEXT
              Set  the  value  of a user text frame (i.e., TXXX). To remove the frame, specify an
              empty value. e.g., --user-text-frame="SomeDesc:"

       --user-url-frame=DESCRIPTION:URL
              Set the value of a user URL frame (i.e., WXXX). To remove  the  frame,  specify  an
              empty value. e.g., --user-url-frame="SomeDesc:"

       --add-image=IMG_PATH:TYPE[:DESCRIPTION]
              Add  or replace an image. There may be more than one image in a tag, as long as the
              DESCRIPTION values are unique. The default DESCRIPTION is ´'. If PATH  begins  with
              ´http[s]://'  then  it  is  interpreted as a URL instead of a file containing image
              data. The TYPE must be one of the following: OTHER, ICON, OTHER_ICON,  FRONT_COVER,
              BACK_COVER,   LEAFLET,  MEDIA,  LEAD_ARTIST,  ARTIST,  CONDUCTOR,  BAND,  COMPOSER,
              LYRICIST,   RECORDING_LOCATION,   DURING_RECORDING,   DURING_PERFORMANCE,    VIDEO,
              BRIGHT_COLORED_FISH, ILLUSTRATION, BAND_LOGO, PUBLISHER_LOGO.

       --remove-image=DESCRIPTION
              Remove image matching DESCRIPTION.

       --remove-all-images
              Remove all images from the tag

       --write-images=DIR
              Causes all attached images (APIC frames) to be written to the specified directory.

       --add-object=OBJ_PATH:MIME-TYPE[:DESCRIPTION[:FILENAME]]
              Add  or  replace  an object. There may be more than one object in a tag, as long as
              the DESCRIPTION values are unique. The default DESCRIPTION is ´'.

       --remove-object=DESCRIPTION
              Remove object matching DESCRIPTION.

       --remove-all-objects
              Remove all objects from the tag

       --add-popularity=EMAIL:RATING[:PLAY_COUNT]
              Adds a pupularity metric. There may be multiples popularity values, but  each  must
              have a unique email address component. The rating is a number between 0 (worst) and
              255 (best). The play count is optional, and defaults to 0, since there is already a
              dedicated play count frame.

       --remove-popularity=EMAIL
              Removes the popularity frame with the specified email key.

       --remove-v1
              Remove ID3 v1.x tag.

       --remove-v2
              Remove ID3 v2.x tag.

       --remove-all
              Remove ID3 v1.x and v2.x tags.

       --remove-frame=FID
              Remove all frames with the given ID. This option may be specified multiple times.

       --max-padding=UM_BYTES
              Shrink  file  if  tag  padding  (unused  space)  exceeds the given number of bytes.
              (Useful e.g. after removal of large cover art.) Default is 64  KiB,  file  will  be
              rewritten with default padding (1 KiB) or max padding, whichever is smaller.

       --encoding=latin1|utf8|utf16|utf16-be
              Set  the encoding that is used for all text frames.  This option is only applied if
              the tag is updated as the result of an edit option (e.g. --artist,  --title,  etc.)
              or --force-update is specified.

   Misc options
       --force-update Rewrite the tag despite there being no edit options.

       --preserve-file-times
              When writing, do not update file modification times.

OTHER PLUGINS

       Execution of a plugin other than ´classic' is possible through the --plugin option.

   art
       This plugin manages art files and tags for albums, artists, etc...

       Options --update-files and --update-tags are mutually exclusive.

       --update-files
              Write art files from tag images.

       --update-tags
              Write tag image from art files.

   fixup
       Performs various checks and fixes to directories of audio files.

       Operates  on  directories  at a time, fixing each as a unit (album, compilation, live set,
       etc.). All of these should have common dates, for example but  other  characteristics  may
       vary. The --type should be used whenever possible, ´lp' is the default.

       The following tests and fixes always apply:

         1.  Every file will be given an ID3 tag if one is missing.
         2.  Set ID3 v2.4.
         3.  Set a consistent album name for all files in the directory.
         4.  Set  a  consistent  artist name for all files, unless the type is ´various' in which
             case the artist may vary  (but must exist).
         5.  Ensure each file has a title.
         6.  Ensure each file has a track # and track total.
         7.  Ensure all files have a release and original release date, unless the type is ´live'
             in which case the recording date is set.
         8.  All ID3 frames of the following types are removed: USER, PRIV
         9.  All ID3 files have TLEN (track length in ms) set (or updated).
         10. The  album/dir  type is set in the tag. Types of ´lp' and ´various' do not have this
             field set since the latter is the default and the former can  be  determined  during
             sync. In ID3 terms the value is in TXXX (description: ´eyeD3#album_type').
         11. Files are renamed as follows:
             •  Type ´various': ${track:num} - ${artist} - ${title}
             •  Type ´single': ${artist} - ${title}
             •  All other types: ${artist} - ${track:num} - ${title}
             •  A rename template can be supplied in --file-rename-pattern
         12. Directories are renamed as follows:
             •  Type ´live': ${best_date:prefer_recording} - ${album}
             •  All other types: ${best_date:prefer_release} - ${album}
             •  A rename template can be supplied in --dir-rename-pattern

       Album types

         • ´lp': A traditinal "album" of songs from a single artist.  No extra info is written to
           the tag since this is the default.
         • ´ep': A short collection of songs from a single artist. The string "ep" is written  to
           the tag's ´eyeD3#album_type' field.
         • ´various':  A  collection  of  songs  from  different artists. The string "various" is
           written to the tag's ´eyeD3#album_type' field.
         • ´live': A collection of live recordings from a single artist.  The  string  "live"  is
           written to the tag's ´eyeD3#album_type' field.
         • ´compilation':  A  collection of songs from various recordings by a single artist. The
           string "compilation'"is written to the  tag's  ´eyeD3#album_type'  field.  Compilation
           dates, unlike other types, may differ.
         • ´demo': A demo recording by a single artist. The string "demo" is written to the tag's
           ´eyeD3#album_type' field.
         • ´single': A track that should no be associated with an album (even  if  it  has  album
           metadata). The string "single" is written to the tag's ´eyeD3#album_type' field.

       -t TYPE, --type TYPE
              One  of  the album types. How to treat each directory. The default is "lp" although
              you may be prompted for an alternate choice if the files look like another type.

       --fix-case
              Fix casing on each string field by capitalizing each word.

       -n, --dry-run
              Only print the operations that would take place, but do not execute them.

       --no-prompt
              Exit if prompted.

       --dotted-dates
              Separate date with ´.' instead of ´-' when naming directories.

       --file-rename-pattern FILE_RENAME_PATTERN
              Rename file (the extension is  not  affected)  based  on  data  in  the  tag  using
              substitution     variables:    $album,    $album_artist,    $artist,    $best_date,
              $best_date:prefer_recording,                      $best_date:prefer_recording:year,
              $best_date:prefer_release,     $best_date:prefer_release:year,     $best_date:year,
              $disc:num,     $disc:total,     $file,      $file:ext,      $original_release_date,
              $original_release_date:year,  $recording_date, $recording_date:year, $release_date,
              $release_date:year, $title, $track:num, $track:total

       --dir-rename-pattern DIR_RENAME_PATTERN
              Rename directory based on data in the tag using substitution variables.   Available
              substitution are the same as in --file-rename-pattern

   genres
       Display the full list of standard ID3 genres.

       ID3 v1 defined a list of genres and mapped them to to numeric values so they can be stored
       as a single byte. It is recommended  that  these  genres  are  used  although  most  newer
       software (including eyeD3) does not care.

   itunes-podcast
       Adds (or removes) the tags necessary for Apple iTunes to identify the file as a podcast.

       --add  Add the podcast frames.

       --remove
              Remove the podcast frames.

   lameinfo
       Outputs  lame header (if one exists) for file.  The ´lame' (or xing) header provides extra
       information about the mp3 that is useful to players and encoders but not  officially  part
       of the mp3 specification. Variable bit rate mp3s, for example, use this header.

       For more details see <http://gabriel.mp3-tech.org/mp3infotag.html>.

       ´xing' is an alias for this plugin.

   nfo
       Create  NFO  files  for  each  directory scanned.  Each directory scanned is treated as an
       album and a NFO (<http://en.wikipedia.org/wiki/.nfo>) file is written to standard out.

       NFO files are often found in music archives.

   stats
       Computes statistics for all audio files scanned.

       --verbose
              Show details for each file with rule violations.

   xep-118
       Outputs all tags in XEP-118 XML format.

       See: <http://xmpp.org/extensions/xep-0118.html>

CONFIGURATION FILE

       Command line options can be read from a configuration file using the  -C/--config  option.
       It  expects  a  path to an Ini (<http://docs.python.org/2/library/configparser.html>) file
       contain   sections   with   option   values.   For    a    sample    config    file    see
       /usr/share/doc/eyeD3/examples/config.ini.

       If the file ´${HOME}/.eyeD3/config.ini' exists it is loaded each time eyeD3 is run and the
       values take effect. This can be disabled with ´--no-config'.

SEE ALSO

       http://eyed3.nicfit.net/

AUTHOR

       eyeD3 was written by Travis Shirk <travis@pobox.com>.