classic - Tag Viewer/Editor¶
Classic eyeD3 interface for viewing and editing tags.
Names¶
classic
Description¶
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 (-Y, –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.
Options¶
-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.
-D NUM, --disc-total NUM
Set total number of discs in set. 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. Run 'eyeD3 --plugin=genres' for a list of
standard ID3 genre names/ids.
--non-std-genres Disables certain ID3 genre standards, such as the
mapping of numeric value to genre names.
-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:'
--url-frame FID:URL Set the value of a URL frame. To remove the frame,
specify an empty value. e.g., --url-frame='WCOM:'
--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.
--write-objects DIR Causes all attached objects (GEOB frames) to be
written to the specified directory.
--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 NUM_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.
--no-max-padding Disable --max-padding altogether.
--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.
-v, --verbose Show all available tag data
--preserve-file-times
When writing, do not update file modification times.
Examples¶
eyeD3 can do more than edit exiting tags, it can also create new tags from nothing. For these examples we’ll make a dummy file to work with.
$ rm -f example.id3
$ touch example.id3
$ ls -o example.id3
-rw-r--r-- 1 travis 0 Feb 26 17:14 example.id3
Now let’s set some common attributes like artist and title.
Most options have a shorter name that can be used to save typing. Let’s add
the album name (-A), the genre (-G), and the year (-Y) the
record was released.
Notice how the genre displayed as “Hardcore (id 129)” in the above tag listing. This happens because the genre is a recognized value as defined by the ID3 v1 standard. eyeD3 used to be very strict about genres, but no longer. You can store any value you’d like. For a list of recognized genres and their respective IDs see the genres plugin.
By default writes ID3 v2.4 tags. This is the latest standard and supports UTF-8 which is a very nice thing. Some players are not caught up with the latest standards (iTunes, pfft) so it may be necessary to convert amongst the various versions. In some cases this can be a lossy operation if a certain data field is not supported, but eyeD3 does its best to convert when the data whenever possible.
# Convert the current v2.4 frame to v2.3
$ eyeD3 --to-v2.3 example.id3 -Q
/home/travis/devel/eyeD3/git/example.id3 [ 0.00 Bytes ]
-------------------------------------------------------------------------------
ID3 v2.4: 0 frames
Writing ID3 version v2.3
-------------------------------------------------------------------------------
# Convert back
$ eyeD3 --to-v2.4 example.id3 -Q
/home/travis/devel/eyeD3/git/example.id3 [ 266.00 Bytes ]
-------------------------------------------------------------------------------
ID3 v2.3: 0 frames
Writing ID3 version v2.4
-------------------------------------------------------------------------------
# Convert to v1, this will lose all the more advanced data members ID3 v2 offers
$ eyeD3 --to-v1.1 example.id3 -Q
/home/travis/devel/eyeD3/git/example.id3 [ 266.00 Bytes ]
-------------------------------------------------------------------------------
ID3 v2.4: 0 frames
Writing ID3 version v1.1
-------------------------------------------------------------------------------
The last conversion above converted to v1.1, or so the output says. The
final listing shows that the tag is version 2.4. This is because tags can
contain both versions at once and eyeD3 will always show/load v2 tags first.
To select the version 1 tag use the -1 option. Also note how the
the non-standard genre was lost by the conversion, thankfully it is still
in the v2 tag.
$ eyeD3 -1 example.id3
/home/travis/devel/eyeD3/git/example.id3 [ 394.00 Bytes ]
-------------------------------------------------------------------------------
ID3 v1.0:
title:
artist:
album:
album artist: None
track: genre: Other (id 12)
-------------------------------------------------------------------------------
The -1 and -2 options also determine which tag will be edited, or even
which tag will be converted when one of the conversion options is passed.
# Set an artist value in the ID3 v1 tag
$ eyeD3 -1 example.id3 -a id3v1
/home/travis/devel/eyeD3/git/example.id3 [ 394.00 Bytes ]
-------------------------------------------------------------------------------
Setting artist: id3v1
ID3 v1.0:
title:
artist: id3v1
album:
album artist: None
track: genre: Other (id 12)
Writing ID3 version v1.0
-------------------------------------------------------------------------------
# The file now has a v1 and v2 tag, change the v2 artist
$ eyeD3 -2 example.id3 -a id3v2
/home/travis/devel/eyeD3/git/example.id3 [ 394.00 Bytes ]
-------------------------------------------------------------------------------
Setting artist: id3v2
ID3 v2.4:
title:
artist: id3v2
album:
album artist: None
track:
Writing ID3 version v2.4
-------------------------------------------------------------------------------
# Take all the values from v2.4 tag (the default) and set them in the v1 tag.
$ eyeD3 -2 --to-v1.1 example.id3
/home/travis/devel/eyeD3/git/example.id3 [ 394.00 Bytes ]
-------------------------------------------------------------------------------
ID3 v2.4:
title:
artist: id3v2
album:
album artist: None
track:
Writing ID3 version v1.1
-------------------------------------------------------------------------------
# Take all the values from v1 tag and convert to ID3 v2.3
$ eyeD3 -1 --to-v2.3 example.id3
/home/travis/devel/eyeD3/git/example.id3 [ 394.00 Bytes ]
-------------------------------------------------------------------------------
ID3 v1.0:
title:
artist: id3v2
album:
album artist: None
track: genre: Other (id 12)
Writing ID3 version v2.3
-------------------------------------------------------------------------------
At this point the tag is all messed up with by these experiments, you can always remove the tags to start again.
$ eyeD3 --remove-all example.id3
/home/travis/devel/eyeD3/git/example.id3 [ 394.00 Bytes ]
-------------------------------------------------------------------------------
Removing ID3 v1.x and/or v2.x tag: SUCCESS
No ID3 v1.x/v2.x tag found!
Complex Options¶
Some of the command line options contain multiple pieces of information in
a single value. Take for example the --add-image option:
--add-image IMG_PATH:TYPE[:DESCRIPTION]
This option has 3 pieced of information where one (DESCRIPTION) is optional (denoted by the square brackets). Each invidual value is seprated by a ‘:’ like so:
$ eyeD3 --add-image cover.png:FRONT_COVER
This will load the image data from cover.png and store it in the tag with
the type value for FRONT_COVER images. The list of valid image types are
listed in the --help usage information which also states that the IMG_PATH
value may be a URL so that the image data does not have to be stored in the
the tag itself. Let’s try that now.
$ eyeD3 --add-image http://example.com/cover.jpg:FRONT_COVER
eyeD3: error: argument --add-image: invalid ImageArg value: 'http://example.com/cover.jpg:FRONT_COVER'
The problem is the ':' character in the the URL, it confuses the format description of the option value. To solve this escape all delimeter characters in
option values with '\\' (for linux and macOS), single '\' for Windows).
Linux/MacOS:
$ eyeD3 --add-image http\\://example.com/cover.jpg:FRONT_COVER example.id3
/home/travis/devel/eyeD3/git/example.id3 [ 0.00 Bytes ]
-------------------------------------------------------------------------------
Adding image http://example.com/cover.jpg
ID3 v2.4:
title:
artist:
album:
album artist: None
track:
FRONT_COVER Image: [Type: -->] [URL: b'http://example.com/cover.jpg']
Description:
Writing ID3 version v2.4
-------------------------------------------------------------------------------
Windows:
$ eyeD3 --add-image http\://example.com/cover.jpg:FRONT_COVER example.id3
C:\Users\user\Downloads\example.id3 [ 0.00 Bytes ]
-------------------------------------------------------------------------------
Adding image http://example.com/cover.jpg
ID3 v2.4:
title:
artist:
album:
album artist: None
track:
FRONT_COVER Image: [Type: -->] [URL: b'http://example.com/cover.jpg']
Description:
Writing ID3 version v2.4
-------------------------------------------------------------------------------