eyeD3(1)
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>.
Opportunity
Personal Opportunity - Free software gives you access to billions of dollars of software at no cost. Use this software for your business, personal use or to develop a profitable skill. Access to source code provides access to a level of capabilities/information that companies protect though copyrights. Open source is a core component of the Internet and it is available to you. Leverage the billions of dollars in resources and capabilities to build a career, establish a business or change the world. The potential is endless for those who understand the opportunity.
Business Opportunity - Goldman Sachs, IBM and countless large corporations are leveraging open source to reduce costs, develop products and increase their bottom lines. Learn what these companies know about open source and how open source can give you the advantage.
Free Software
Free Software provides computer programs and capabilities at no cost but more importantly, it provides the freedom to run, edit, contribute to, and share the software. The importance of free software is a matter of access, not price. Software at no cost is a benefit but ownership rights to the software and source code is far more significant.
Free Office Software - The Libre Office suite provides top desktop productivity tools for free. This includes, a word processor, spreadsheet, presentation engine, drawing and flowcharting, database and math applications. Libre Office is available for Linux or Windows.
Free Books
The Free Books Library is a collection of thousands of the most popular public domain books in an online readable format. The collection includes great classical literature and more recent works where the U.S. copyright has expired. These books are yours to read and use without restrictions.
Source Code - Want to change a program or know how it works? Open Source provides the source code for its programs so that anyone can use, modify or learn how to write those programs themselves. Visit the GNU source code repositories to download the source.
Education
Study at Harvard, Stanford or MIT - Open edX provides free online courses from Harvard, MIT, Columbia, UC Berkeley and other top Universities. Hundreds of courses for almost all major subjects and course levels. Open edx also offers some paid courses and selected certifications.
Linux Manual Pages - A man or manual page is a form of software documentation found on Linux/Unix operating systems. Topics covered include computer programs (including library and system calls), formal standards and conventions, and even abstract concepts.
