~ubuntu-branches/ubuntu/precise/python-id3/precise : revision 1

1

README for ID3.py, version 1.2

2

3

4

--------------------------------------------------------------

5

6

This is a simple Python module for retrieving and setting so-called

7

ID3 tags on MP3 compressed audio files through an object-oriented

8

interface. MP3 players generally use this simple information for

9

display track title, artist name, and album title while playing

10

the sound file.

11

12

ID3.py supports ID3 version 1.1, including the track number field.

13

I have no current plans to code up the monstrosity that is ID3v2

14

(http://www.id3.org/id3v2.3.0.html) but if someone wants to add

15

that functionality, feel free!

16

17

ID3.py is hosted by SourceForge.Net, and the latest release will

18

always be available from:

19

20

http://id3-py.sourceforge.net/

21

22

To install ID3.py, either simply copy the ID3.py file to your

23

site-wide Python module installation directory

24

(/usr/local/lib/python/site-python, for instance) or, if you have

25

Python v1.6 or later (or have Distutils installed), you can simply

26

run:

27

28

# python setup.py install

29

30

from the command-line.

31

32

Here's a simple example of using the ID3 module. This example prints

33

the current ID3 information (nicely formatted) of a given MP3, changes

34

the title and artist tags, and then (implicitly, when the object is

35

destroyed) writes out the changes to the file.

36

37

from ID3 import *

38

try:

39

filename = '/some/path/moxy.mp3'

40

id3info = ID3(filename)

41

42

# alternatively, can pass in a file or equivalent if opened in r+b mode

43

# id3info = ID3(open(filename, 'r+b'), filename)

44

45

print id3info

46

id3info.title = "Green Eggs and Ham"

47

id3info.artist = "Moxy Fr�vous"

48

except InvalidTagError, message:

49

print "Invalid ID3 tag:", message

50

51

Notice that simply changing the value of the fields is enough; no

52

special functions need to be called.

53

54

NEW DICTIONARY-BASED INTERFACE

55

------------------------------

56

57

As of ID3.py version 1.2, a new dictionary-based interface compatible

58

with ogg.vorbis is available. You can now use ID3 objects just like

59

a dictionary:

60

61

from ID3 import *

62

try:

63

filename = '/some/path/moxy.mp3'

64

id3info = ID3(filename)

65

66

id3info['TITLE'] = "Green Eggs and Ham"

67

id3info['ARTIST'] = "Moxy Fr�vous"

68

69

for k, v in id3info.items():

70

print k, ":", v

71

except InvalidTagError, message:

72

print "Invalid ID3 tag:", message

73

74

Note that ID3.py (by default) stores just a string in each value in

75

the dictionary-based interface. ogg.vorbis uses a *list*, not a

76

single string, so if you want compatibility with ogg.vorbis, call the

77

ID3 constructor with as_tuple=1:

78

79

from ID3 import *

80

try:

81

id3info = ID3("moxy.mp3", as_tuple=1)

82

for k, v in id3info.items()

83

print k, ":", v[0]

84

except InvalidTagError, message:

85

print "Invalid ID3 tag:", message

86

87

Of course, all the tuples will only have one string value inside them,

88

as that's all the ID3 version 1.1 standard supports.

89

90

ID3 OBJECT FIELDS

91

-----------------

92

93

Here's a list of all the fields in an ID3 object that are interesting.

94

Note that all ID3 fields, unless otherwise specified, are a maximum of

95

30 characters in length. If a field is set to a string longer than the

96

maximum, it will be truncated when it's written to disk.

97

98

If any of the fields are not defined in the ID3 tag, the dictionary

99

based interface will not contain a key for that field! Test with

100

ID3.has_key('ARTIST') etc. first.

101

102

ID3.title or ID3['TITLE']

103

Title of the song.

104

ID3.artist or ID3['ARTIST']

105

Artist/creator of the song.

106

ID3.album or ID3['ALBUM']

107

Title of the album the song is from.

108

ID3.year or ID3['YEAR']

109

Year the song was released. Maximum of 4 characters (Y10K bug!)

110

ID3.genre

111

Genre of the song. Integer value from 0 to 255. Genre specification

112

comes from (sorry) WinAMP. http://mp3.musichall.cz/id3master/faq.htm

113

has a list of current genres; I spell-checked this list against

114

WinAMP's by running strings(1) on the file Winamp/Plugins/in_mp3.dll

115

and made a few corrections.

116

ID3['GENRE']

117

String value corresponding to the integer in ID3.genre. If there

118

is no genre string available for the ID3.genre number, this will

119

be set to "Unknown Genre".

120

ID3.comment or ID3['COMMENT']

121

Comment about the song.

122

ID3.track or ID3['TRACKNUMBER']

123

Track number of the song. None if undefined.

124

NOTE: ID3['TRACKNUMBER'] will return a *string* containing the

125

track number, for compatibility with ogg.vorbis.

126

127

This field shouldn't be changed, but might be of use:

128

129

ID3.genres

130

List of all genres. ID3.genre above is used to index into this

131

list. ID3.genres is current as of WinAMP 1.92.

132

133

Here are the methods of interest that the ID3 module contains:

134

135

write()

136

If the class data above have changed, opens the file given

137

to the constructor read-write and writes out the new header.

138

If the header is flagged for deletion (see delete() below)

139

truncates the last 128 bytes of the file to remove the header.

140

141

NOTE: write() is called from ID3's deconstructor, so it's technically

142

unnecessary to call it. However, write() can raise an InvalidTagError,

143

which can't be caught during deconstruction, so generally it's

144

nicer to call it when writing is desired.

145

146

delete()

147

Flags the ID3 tag for deletion upon destruction of the object

148

149

find_genre(genre_string)

150

Searches for the numerical value of the given genre string in the

151

ID3.genres table. The search is performed case-insensitively. Returns

152

an integer from 0 to len(ID3.genres).

153

154

legal_genre(genre_number)

155

Checks if genre_number is a legal index into ID3.genres. Returns

156

true if so, false otherwise.

157

158

as_dict()

159

Returns just the dictionary containing the ID3 tag fields.

160

See the notes above for the dictionary interface.

161

162

The only exception is ID3.InvalidTagError; this exception will be

163

raised from the constructor when the given file cannot be opened, when

164

an IOError is raised while reading the file, and when an IOError occurs

165

during a write, after the tag has been modified.