1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19 package entagged.audioformats;
20
21 import java.util.Iterator;
22 import java.util.List;
23
24 import entagged.audioformats.generic.TagField;
25
26 /***
27 * This interface represents the basic data structure for the default
28 * audiolibrary functionality.<br>
29 * <br>
30 * Some audio file tagging systems allow to specify multiple values for one type
31 * of information. The artist for example. Some songs may be a cooperation of
32 * two or more artists. Sometimes a tagging user wants to specify them in the
33 * tag without making one long text string.<br>
34 * For that kind of fields, the <b>commonly</b> used fields have adequate
35 * methods for adding values. But it is possible the underlying implementation
36 * does not support that kind of storing multiple values.<br>
37 * <br>
38 * <b>Code Examples:</b><br>
39 *
40 * <pre>
41 * <code>
42 * AudioFile file = AudioFileIO.read(new File("C://test.mp3"));
43 *
44 * Tag tag = file.getTag();
45 * </code>
46 * </pre>
47 *
48 * @author Raphaël Slinckx
49 */
50 public interface Tag {
51 /***
52 * This final field contains all the tags that id3v1 supports. The list has
53 * the same order as the id3v1 genres. To be perfectly compatible (with
54 * id3v1) the genre field should match one of these genre (case ignored).
55 * You can also use this list to present a list of basic (modifiable)
56 * possible choices for the genre field.
57 */
58 public static final String[] DEFAULT_GENRES = { "Blues", "Classic Rock",
59 "Country", "Dance", "Disco", "Funk", "Grunge", "Hip-Hop", "Jazz",
60 "Metal", "New Age", "Oldies", "Other", "Pop", "R&B", "Rap",
61 "Reggae", "Rock", "Techno", "Industrial", "Alternative", "Ska",
62 "Death Metal", "Pranks", "Soundtrack", "Euro-Techno", "Ambient",
63 "Trip-Hop", "Vocal", "Jazz+Funk", "Fusion", "Trance", "Classical",
64 "Instrumental", "Acid", "House", "Game", "Sound Clip", "Gospel",
65 "Noise", "AlternRock", "Bass", "Soul", "Punk", "Space",
66 "Meditative", "Instrumental Pop", "Instrumental Rock", "Ethnic",
67 "Gothic", "Darkwave", "Techno-Industrial", "Electronic",
68 "Pop-Folk", "Eurodance", "Dream", "Southern Rock", "Comedy",
69 "Cult", "Gangsta", "Top 40", "Christian Rap", "Pop/Funk", "Jungle",
70 "Native American", "Cabaret", "New Wave", "Psychadelic", "Rave",
71 "Showtunes", "Trailer", "Lo-Fi", "Tribal", "Acid Punk",
72 "Acid Jazz", "Polka", "Retro", "Musical", "Rock & Roll",
73 "Hard Rock", "Folk", "Folk-Rock", "National Folk", "Swing",
74 "Fast Fusion", "Bebob", "Latin", "Revival", "Celtic", "Bluegrass",
75 "Avantgarde", "Gothic Rock", "Progressive Rock",
76 "Psychedelic Rock", "Symphonic Rock", "Slow Rock", "Big Band",
77 "Chorus", "Easy Listening", "Acoustic", "Humour", "Speech",
78 "Chanson", "Opera", "Chamber Music", "Sonata", "Symphony",
79 "Booty Bass", "Primus", "Porn Groove", "Satire", "Slow Jam",
80 "Club", "Tango", "Samba", "Folklore", "Ballad", "Power Ballad",
81 "Rhythmic Soul", "Freestyle", "Duet", "Punk Rock", "Drum Solo",
82 "A capella", "Euro-House", "Dance Hall" };
83
84 /***
85 * Adds a tagfield to the structure.<br>
86 * It is not recommended to use this method for normal use of the
87 * audiolibrary. The developer will circumvent the underlying
88 * implementation. For example, if one adds a field with the field id
89 * "TALB" for an mp3 file, and the given {@link TagField}
90 * implementation does not return a text field compliant data with
91 * {@link TagField#getRawContent()} other software and the audio library
92 * won't read the file correctly, if they do read it at all. <br>
93 * So for short:<br>
94 * <uil>
95 * <li>The field is stored withoud validation</li>
96 * <li>No conversion of data is perfomed</li>
97 * </ul>
98 *
99 * @param field
100 * The field to add.
101 */
102 public void add(TagField field);
103
104 /***
105 * Adds an album to the tag.<br>
106 *
107 * @param album
108 * Album description
109 */
110 public void addAlbum(String album);
111
112 /***
113 * Adds an artist to the tag.<br>
114 *
115 * @param artist
116 * Artist's name
117 */
118 public void addArtist(String artist);
119
120 /***
121 * Adds a comment to the tag.<br>
122 *
123 * @param comment
124 * Comment.
125 */
126 public void addComment(String comment);
127
128 /***
129 * Adds a genre to the tag.<br>
130 *
131 * @param genre
132 * Genre
133 */
134 public void addGenre(String genre);
135
136 /***
137 * Adds a title to the tag.<br>
138 *
139 * @param title
140 * Title
141 */
142 public void addTitle(String title);
143
144 /***
145 * Adds a track to the tag.<br>
146 *
147 * @param track
148 * Track
149 */
150 public void addTrack(String track);
151
152 /***
153 * Adds a year to the Tag.<br>
154 *
155 * @param year
156 * Year
157 */
158 public void addYear(String year);
159
160 /***
161 * Returns a {@linkplain List list} of {@link TagField} objects whose "{@linkplain TagField#getId() id}"
162 * is the specified one.<br>
163 *
164 * @param id
165 * The field id.
166 * @return A list of {@link TagField} objects with the given "id".
167 */
168 public List get(String id);
169
170 public List getAlbum();
171
172 public List getArtist();
173
174 public List getComment();
175
176 public Iterator getFields();
177
178 public String getFirstAlbum();
179
180 public String getFirstArtist();
181
182 public String getFirstComment();
183
184 public String getFirstGenre();
185
186 public String getFirstTitle();
187
188 public String getFirstTrack();
189
190 public String getFirstYear();
191
192 public List getGenre();
193
194 public List getTitle();
195
196 public List getTrack();
197
198 public List getYear();
199
200 /***
201 * Returns <code>true</code>, if at least one of the contained
202 * {@linkplain TagField fields} is a common field ({@link TagField#isCommon()}).
203 *
204 * @return <code>true</code> if a {@linkplain TagField#isCommon() common}
205 * field is present.
206 */
207 public boolean hasCommonFields();
208
209 /***
210 * Determines whether the tag has at least one field with the specified
211 * "id".
212 *
213 * @param id
214 * The field id to look for.
215 * @return <code>true</code> if tag contains a {@link TagField} with the
216 * given {@linkplain TagField#getId() id}.
217 */
218 public boolean hasField(String id);
219
220 /***
221 * Determines whether the tag has no fields specified.<br>
222 *
223 * @return <code>true</code> if tag contains no field.
224 */
225 public boolean isEmpty();
226
227 public void merge(Tag tag);
228
229 public void set(TagField field);
230
231 public void setAlbum(String s);
232
233 public void setArtist(String s);
234
235 public void setComment(String s);
236
237 public boolean setEncoding(String enc);
238
239 public void setGenre(String s);
240
241 public void setTitle(String s);
242
243 public void setTrack(String s);
244
245 public void setYear(String s);
246
247 public String toString();
248 }