Version 1.1
[xdg-specs:xdg-specs.git] / specifications / FMPSpecs / specification.txt
1 Free Media Player Specifications
2
3 Tag Specification
4
5 version 1.1; October 16, 2010
6
7 Copyright 2009-2010 by Jeff Mitchell [mitchell@kde.org]
8
9 Abstract
10
11 This specification describes various audio file tag metadata 
12 intended to increase interoperability between free music players 
13 for things such as ratings, playcounts, performer roles, and 
14 more. It does this by proposing standards for common 
15 functionality needs where none currently exist, and doing so in a 
16 way that is easily adoptable cross-player and cross-format. It is 
17 designed to be robust against future needs and to prevent 
18 possible conflicts with other tag identifiers and values.
19
20 Table of Contents
21
22     1 Front Matter
23         1.1 License
24         1.2 Terminology
25     2 Audio Metadata Tags
26         2.1 Common Data and Tag Information
27             2.1.1 MP3
28             2.1.2 VorbisComments
29             2.1.3 APEv2
30             2.1.4 MP4
31             2.1.5 Windows Media
32         2.2 Rating Tags
33             2.2.1 All Rating Tags
34             2.2.2 FMPS_Rating
35             2.2.3 FMPS_Rating_User
36         2.3 FMPS_Rating_Critic
37             2.3.1 FMPS_Rating_Algorithm
38         2.4 Playcount Tags
39             2.4.1 All Playcount Tags
40             2.4.2 User Playcount Criteria
41             2.4.3 FMPS_Playcount
42             2.4.4 FMPS_Playcount_User
43             2.4.5 FMPS_Playcount_Algorithm
44         2.5 Performer Roles
45         2.6 Lyrics
46         2.7 Album/Compilation (“Various Artists”) Identifier
47
48
49 1 Front Matter
50
51 1.1 License
52
53 You may use this specification under either of the following 
54 licenses, at your discretion. Most will want to use it under 
55 Creative Commons; the GPL alternative is in case future versions 
56 of the spec contain e.g. code snippets that you would like to use 
57 in GPL programs:
58
59 1. This specification is licensed under the Creative Commons 
60   Attribution-Share Alike 3.0 Unported License. You are free to 
61   copy, distribute and transmit this work, provided that the 
62   copyright information and full URL to the license information 
63   page (http://creativecommons.org/licenses/by-nd/3.0/) remain 
64   intact. If you alter, transform, or build upon this work, you 
65   may distribute the resulting work only under the same or 
66   similar license to this one. 
67
68 2. This program is free software; you can redistribute it and/or 
69   modify it under the terms of the GNU General Public License as 
70   published by the Free Software Foundation; either version 2 of 
71   the License, or (at your option) any later version. This 
72   program is distributed in the hope that it will be useful, but 
73   WITHOUT ANY WARRANTY; without even the implied warranty of 
74   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 
75   GNU General Public License for more details. See http://www.gnu.org/licenses/
76   . 
77
78 1.2 Terminology
79
80 Terminology follws that specified in RFC2119, “Key words for use 
81 in RFCs to Indicate Requirement Levels”. See http://www.ietf.org/rfc/rfc2119.txt
82  for more information.
83
84 2 Audio Metadata Tags
85
86 The metadata tag formats evolved from Quod Libet's VorbisComments 
87 suggestions at http://code.google.com/p/quodlibet/wiki/Specs_VorbisComments
88 , however this attempts to not only address ambiguities and 
89 incompatibilities with the specification at that URL, but also to 
90 define how this functionality should be applied across formats. 
91 It is intended that as usable ways of inserting the metadata 
92 described become available for formats not currently specified, 
93 that this document will be updated to meet those needs.
94
95 All newly-specified tags carry an identifier “FMPS_” to tie the 
96 tags to this specification. The reason is simple: since the 
97 official metadata specifications either fail to define or define 
98 unusable tags, these values are only official to the extent that 
99 this specification is adopted. Without an identifier to give 
100 context to the meanings and limitations of the values, there is a 
101 real possibility that a noncompliant media player will use the 
102 same tag names in an incompatible fashion, whether intentionally 
103 or not, and there is no way to determine whether a seemingly 
104 compatible use of the tags by a noncompliant player actually 
105 results in user-intended behavior. The “FMPS_” identifier and 
106 this specification document is therefore used in a similar 
107 fashion to XML schema declarations.
108
109 As these identifiers are read and modified only by players and 
110 advanced users, it is not expected to be a hindrance to adoption 
111 or to cause undue burden on either.
112
113 2.1 Common Data and Tag Information
114
115 This section provides “up-front” information that is pertinent to 
116 all tags described below, such as what encoding to use and which 
117 tags to use in various formats.
118
119 For all tag formats, the following is defined:
120
121 • All identifiers are ASCII strings, and defined in the sections 
122   below. All identifier strings must escape each colon (':'), 
123   semicolon (';') and backslash ('\') with a backslash.
124
125 • All values (including numeric values) are stored as strings, 
126   which MUST adhere to the allowed encoding and length limits in 
127   the relevant tag format specifications, but SHOULD use Unicode 
128   whenever possible.
129
130   – To keep the specification simple, no ranges of control 
131     characters are defined which should never be included in a 
132     string. It is assumed that the used string-handling library 
133     will properly handle any such characters encountered. It is 
134     highly recommended, however, that no such control characters 
135     are used, except when specified below.
136
137   – All value strings must escape each colon (':'), semicolon 
138     (';') and backslash ('\') with a backslash. 
139
140 • Although identifier case is specified for the different types 
141   of tags, comparisons against identifier strings MUST be 
142   case-insensitive.
143
144 • A period/full stop is used to separate the digits in a float 
145   value from the fractional part of the float. All float values 
146   MUST include a period/full stop (1 is not acceptable; 1.0 is 
147   correct).
148
149 • Float values SHOULD be limited to six decimal places.
150
151 • All lists are value strings. For any lists, entries MUST be 
152   separated with a double semicolon ';;' and fields within an 
153   entry MUST be separated with a double colon '::' (examples in 
154   following sections). These separation markers MUST NOT be 
155   escaped with backslashes. This allows for easy splitting of 
156   list entries and entry fields with most string libraries; the 
157   entries and fields can be split by double semicolon/double 
158   colon, and the ensuing fields can have any escaped values 
159   substituted.
160
161 The following sections describe where the information should be 
162 stored in specific tag formats.
163
164 2.1.1 MP3
165
166 MP3 values MUST be stored in a TXXX frame with the Description 
167 set to the specified identifier and the Text set to the string 
168 representation of the value. The Description SHOULD be in 
169 CamelCase as specified in the following sections, e.g. 
170 FMPS_Rating.
171
172 2.1.2 VorbisComments
173
174 Any file supporting VorbisComments (Vorbis, FLAC, Theora, Speex) 
175 MUST use a comment with the Key set to the specified identifier 
176 and the Value set to the string representation of the value. The 
177 Key SHOULD be in all upper-case, e.g. FMPS_RATING.
178
179 2.1.3 APEv2
180
181 Any file supporting APEv2 MUST add a comment with the Key set to 
182 the specified identifier and the Value set to the string 
183 representation of the value. The Key SHOULD be in all upper-case, 
184 e.g. FMPS_RATING.
185
186 2.1.4 MP4
187
188 MP4 values MUST be stored at ----:com.apple.iTunes:Identifier 
189 with the value a string representation of the tag's value. The 
190 Identifier SHOULD be in CamelCase as specified in the following 
191 sections, e.g. FMPS_Rating.
192
193 2.1.5 Windows Media
194
195 Windows Media values MUST be stored in the FMPS/Identifier 
196 namespace with the value a string representation of the tag's 
197 value. The Identifier SHOULD be in CamelCase as specified in the 
198 following sections, e.g. FMPS_Rating.
199
200 2.2 Rating Tags
201
202 Most media players support the notion of rating content, however 
203 standards for storing ratings in files do not exist. Some file 
204 metadata formats completely lack rating fields; others require 
205 personally identifiable information to be used as an identifier 
206 (such as a user's email address) or an organizational identifier 
207 (which reduces cross-player compatibility). The goal therefore is 
208 simple: to avoid any personally identifying information but to 
209 avoid tying the rating to a specific player.
210
211 Three types of ratings are currently defined: user ratings, 
212 critic ratings, and automatic (or algorithmic) ratings.
213
214 Although users are more naturally able to understand integer 
215 ratings, only advanced users will interact with these tags 
216 directly; otherwise they will be presented to the user via a 
217 conforming application. Meanwhile, there are tangible benefits to 
218 storing ratings as floating-point numbers, mainly due to the fact 
219 that the increased precision allows for a number of interesting 
220 and useful algorithmic rating schemes to be used. However, using 
221 both integer and floating-point values unnecessarily increases 
222 complexity of both this spec and application code. Therefore, 
223 both values are stored as floating-point numbers. Conversion to 
224 and from these and an integer scale presented to the user in an 
225 application is easily accomplished in the application's code if 
226 it is so desired.
227
228 Four tags are defined, corresponding to the three types of 
229 defined ratings, plus a canonical value: FMPS_Rating_User; 
230 FMPS_Rating_Critic; FMPS_Rating_Algorithm; and FMPS_Rating (the 
231 canonical value). A file that has no rating tag for a specific 
232 purpose is to be considered unrated for that purpose (user, 
233 critic or algorithm).
234
235 2.2.1 All Rating Tags
236
237 • Ratings SHALL be a float value between 0.0 and 1.0, inclusive. 
238   0.0 SHALL be the lowest possible rating; 1.0 is the highest 
239   possible rating.
240
241 • Ratings SHOULD only be rounded when necessary, in order to 
242   increase cross-player compatibility.
243
244 2.2.2 FMPS_Rating
245
246 • The canonical rating value in FMPS_Rating SHOULD be set 
247   whenever a user rates the track. This is in addition to any 
248   value stored for that particular user in FMPS_Rating_User. This 
249   value is canonical because if a player does not support 
250   multiple users (or if no user identifier is set), this is the 
251   value that MUST be returned.
252
253 • If a user removes ratings from a track in the media player's 
254   database, the value of the FMPS_Rating tag SHOULD be cleared as 
255   well.
256
257 2.2.3 FMPS_Rating_User
258
259 • If a player supports the notion of multiple users (perhaps from 
260   discovery of the current user from the operating system) and 
261   wishes to allow the users to keep separate ratings, it MUST 
262   store these values in the FMPS_Rating_User tag.
263
264 • Applications supporting multiple user ratings SHOULD have a way 
265   for users to define their preferred identifier. 
266
267 • The values are in the form of a list as defined in Section 2.1, 
268   with list entries in the format of UserIdentifier::Value. There 
269   MUST NOT be empty value strings.
270
271 Example: “Alice Abba::0.6;;Bob Beatles::0.8”.
272
273 2.3 FMPS_Rating_Critic
274
275 • The values MUST be in the form of a list as defined in Section 
276   2.1, with list entries in the format of 
277   Publication::Critic::Rating. If the critic is unaffiliated, or 
278   if the rating is by a publication with no byline, the special 
279   value “FMPS_Nothing” MUST be used to denote this; there MUST 
280   NOT be empty strings.
281
282 Example: “Rolling Stone::Ralph 
283 Gleason::0.83;;musicOMH.com::FMPS_Nothing::0.76;;Metacritic::FMPS_Nothing::0.8;;FMPS_Nothing::Some 
284 Dude::0.9”
285
286 2.3.1 FMPS_Rating_Algorithm
287
288 • The values MUST be in the form of a list as defined in Section 
289   2.1, with list entries in the format of 
290   Application::Algorithm::Rating. All fields MUST be defined; 
291   fields MUST NOT be left empty.
292
293 • In cases where the algorithm is intended to be 
294   global/collaborative/cross-application, the Application value 
295   SHOULD be set to some agreed-upon value. In other words, it is 
296   RECOMMENDED to use the application name for the Application 
297   part of the identifier, but it MAY also be used to identify a “
298   group” of algorithms, or some arbitrary other value that can be 
299   used for identification.
300
301 Example: “
302 Amarok::AutoRate::0.52;;VLC::Standard::0.6;;QuodLibet::RatingPlugin\:X::0.35;;The 
303 Free Music Player Alliance::Rating Algorithm 1::0.5”
304
305 A note on the floating point values: some players may only allow 
306 users to rate in increments of whole numbers between 1 and 5; 
307 others 0 and 10; and so on. However, players SHOULD ensure that 
308 the rating they display and use for any purpose adheres to that 
309 saved in the tag whenever possible, only rounding this number 
310 when absolutely necessary.
311
312 For instance, if a track has a rating of 0.9 and an application 
313 only shows ratings using five star icons in full-star increments, 
314 this would be rounded within the application to five stars. 
315 Howeer, if the player also shows the rating numerically, the 
316 application would display 4.5 in the numeric field instead of the 
317 same 5 shown in the star icons, thus more accurately reflecting 
318 the user's set rating.
319
320 2.4 Playcount Tags
321
322 As with ratings, there are multiple kinds of playcount tags (user 
323 and algorithmic) in addition to a canonical value. The user tag 
324 tracks how many times a song has been played for a user. The 
325 auto/algorithmic value can be used in an application-specific way 
326 to do interesting things; for instance, to cumulatively track 
327 exact percentages of tracks played, in order to display to the 
328 user the number of days/hous/minutes/seconds they have spent 
329 listening to a particular song. 
330
331 Three tags are defined, corresponding to the two types of defined 
332 playcounts, plus a canonical value: FMPS_Playcount_User; 
333 FMPS_Playcount_Algorithm; and FMPS_Playcount (the canonical 
334 value). A file that has no playcount tag for a specific purpose 
335 is to be considered unplayed for that purpose (user or 
336 algorithm).
337
338 2.4.1 All Playcount Tags
339
340 • Playcounts MUST be a float value not less than 0.0. 0.0 is 
341   valid and means unplayed.
342
343 • The maximum value SHALL be 0.000001 less than the largest value 
344   able to be stored in a 32-bit unsigned integer: 
345   4,294,967,294.999999. This is so that playcount values can be 
346   rounded to an integer equivalent, if necessary (e.g. for 
347   display to the user).
348
349 2.4.2 User Playcount Criteria
350
351 The user playcount isn't meant to be set by the user, but rather 
352 to follow these rules that define user behavior. A file is to be 
353 considered “played” if it meets the following criteria, inspired 
354 by Last.fm's scrobbling rules:
355
356 • If the track is less than thirty seconds long, the entire song 
357   MUST be played.
358
359 • If the track is more than thirty seconds long but less than 
360   eight minutes long, at least fifty percent of the file MUST be 
361   played, calculated via length of track. For instance, if a 
362   track is one minute long, at least thirty seconds of the track 
363   must have been played, although if the user skips backwards 
364   multiple times and listens to the same ten seconds of the track 
365   three times in a row, this may be considered a valid playcount.
366
367 • If the track is longer than eight minutes, at least four 
368   minutes of the track MUST be played.
369
370 User playcounts have an additional restriction in that they MUST 
371 be float values representing integers (1.0, 141.0, etc.). They 
372 are never fractional values; a song was either played, or it 
373 wasn't.
374
375 2.4.3 FMPS_Playcount
376
377 • The canonical playcount value in FMPS_Playcount SHOULD be set 
378   whenever a user plays a track. This is in addition to any value 
379   stored for that user in FMPS_Playcount_User. This value is 
380   canonical because if a player does not support multiple users 
381   (or if no user identifier is set) this is the value that MUST 
382   be returned.
383
384 • If a user has an identifier set to store per-user playcounts, 
385   when this value is set it MUST be set to the value of that 
386   user's playcount. In other words, the last value held in 
387   FMPS_Playcount will be equivalent to the latest user's personal 
388   playcount, if any.
389
390 • If a user resets the playcount for a track in the media 
391   player's database, the value of the FMPS_Playcount tag SHOULD 
392   be cleared as well.
393
394 • FMPS_Playcount MUST store “full plays” of a track according to 
395   the rules in Section 2.4.2.
396
397 2.4.4 FMPS_Playcount_User
398
399 • If a player supports the notion of multiple users (perhaps from 
400   discovery of the current user from the operating system) and 
401   wishes to allow the users to keep separate playcounts, it MUST 
402   store these values in the FMPS_Playcount_User tag.
403
404 • Applications supporting multiple user playcounts SHOULD have a 
405   way for users to define their preferred identifier. 
406
407 • The values MUST be in the form of a list as defined in Section 
408   2.1, with list entries in the format of UserIdentifier::Value. 
409   There MUST NOT be empty strings.
410
411 • FMPS_Playcount_User MUST store “full plays” of a track 
412   according to the rules in Section 2.4.2.
413
414 Example: “Alice Abba::1.0;;Bob Beatles::133.0”.
415
416 2.4.5 FMPS_Playcount_Algorithm
417
418 • The values MUST be in the form of a list as defined in Section 
419   2.3.1, with list entries in the format of 
420   Application::Algorithm::Playcount. All fields MUST be defined; 
421   fields MUST NOT be left empty.
422
423 • In cases where the algorithm is intended to be 
424   global/collaborative/cross-application, the Application value 
425   SHOULD be set to some agreed-upon value. In other words, it is 
426   RECOMMENDED to use the application name for the Application 
427   part of the identifier, but it MAY also be used to identify a “
428   group” of algorithms, or some arbitrary other value that can be 
429   used for identification.
430
431 • For algorithms, a track's length MUST be considered to be worth 
432   1.0 playcounts; the user skipping parts of the track MAY 
433   decrease the value below 1.0, and the user repeating parts of 
434   the track MAY increase this value past 1.0.
435
436 Example: “
437 Amarok::AutoPlaycount::152.69;;VLC::Standard::198.0;;QuodLibet::PlaycountPlugin\:X::1652.19;;The 
438 Music Player Alliance::Playcount Algorithm 1::0.5”
439
440 2.5 Performer Roles
441
442 Performer roles allow you to describe the performers in a track. 
443 Current support for these roles in tag formats is often sporadic 
444 or difficult to parse. As many of these tags as desired can be 
445 specified, to include all relevant performer information.
446
447 • Performer roles use the identifier “FMPS_Performers”. The value 
448   MUST be a list in the form of Performer::Role, where Role is 
449   the user-defined role (“Guitar”, “Guitar (Backup)”, “Vocals”).
450
451 Example: “Willy Nelson::Guitar;;Eric Clapton::Guitar 
452 (Backup);;B.B. King::Vocals”
453
454 2.6 Lyrics
455
456 Embedding lyrics into a file allows users to save custom lyrics 
457 and to still see the lyrics when not connected to the Internet. 
458 Since different users may wish to have different sets of lyrics 
459 (for example, if customizing lyrics against a music-only track) 
460 and different Internet sources may have different lyrics, it is 
461 possible to store multiple lyrics values by specifying a source.
462
463 • The identifier for the (canonical) lyrics text is “FMPS_Lyrics”
464   . The value MUST be a string. Spaces, tabs, and newlines SHOULD 
465   be preserved when saving the string, and SHOULD be displayed 
466   properly to the user.
467
468 • Lyrics MAY also be stored in FMPS_Lyrics_Sources as a list (as 
469   defined in Section 2.1), in which case the form MUST be 
470   Source::Data.
471
472 Example: “Alice Aardvark::[lyrics];;Bob 
473 Baboon::[lyrics];;http\://www.lyricssite.net::[lyrics]”
474
475 2.7 Album/Compilation (“Various Artists”) Identifier
476
477 Compilations (or “Various Artists” albums) can be difficult for 
478 music players to discover. Sometimes the user places all files 
479 from a compilation in one directory and expects that the music 
480 player will understand this; sometimes the user has them in 
481 different directories but with the same album name and expects 
482 that the music player will understand this; and so on.
483
484 Although there are existing solutions to identify albums and 
485 songs that belong to the same album (such as MusicBrainz 
486 identifiers) many users have not or do not want to tag their 
487 songs with MusicBrainz information. This tag therefore provides a 
488 simple way for an application to assign a album identifier to a 
489 track, indicating to what album a track belongs. It also provides 
490 a simple way of marking the album as a compilation or not.
491
492 This enables such use-cases as allowing a user to mark multiple 
493 tracks that are part of a single compilation, and then have those 
494 tracks show up as being together in a compilation the next time 
495 the user adds the tracks to the music player.
496
497 This section purposefully does not define information about the 
498 album/compilation; it is expected that the user must supply that 
499 information in appropriate existing tags, e.g. ALBUM and 
500 ALBUMARTIST for VorbisComments.
501
502 • The identifier for the album/compilation tag is 
503   FMPS_Albums_Compilations. Although this tag will be most useful 
504   for compilation/Various Artists albums, there may still be 
505   significant utility for a player in using this tag to identify 
506   single-artist albums. As a result, players MUST NOT make 
507   assumptions about whether the presence of this tag identifies 
508   the track as belonging to a compilation/Various Artists album 
509   and MUST explicitly derive this information from the tag value.
510
511 • Values MUST be a list (as defined in Section 2.1) in the form 
512   of Application::Type::Identifier. Applications MAY have more 
513   than one identifier, if the user wants to mark a track as being 
514   present in multiple compilations, or to give user-defined names 
515   to a compilation. However, each list entry MUST be unique. 
516   Similarly to other tags in this specification, there may be 
517   significant utility in interoperating on the application names.
518
519 • Type MUST be one of the following values, without quotes: “
520   Album” (indicating a general-purpose album, usually by a single 
521   artist) or “Compilation” (indicating a compilation album, 
522   usually by multiple/various artists). Checks against this value 
523   MUST be case-insensitive. More values may be added in the 
524   future; if a player encounters an unknown value it SHOULD 
525   default to type “Album”. 
526
527 Example: “Amarok::Album::2982ab29ef;;AmarokUser::Compilation::My 
528 Compilation;;Banshee::Compilation::ad8slpbzl229zier;;FMPSAlliance::Album::de9f2c7fd25e1b3afad3e85a0bd17d9b100db4b3”
529