summaryrefslogtreecommitdiff
path: root/media-player/specification.txt
blob: ac60e8ee8ba676c5f72c360458fe4a5a2be566ae (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
Free Media Player Specifications

Tag Specification

version 1.1; October 16, 2010

Copyright 2009-2010 by Jeff Mitchell [mitchell@kde.org]

Abstract

This specification describes various audio file tag metadata 
intended to increase interoperability between free music players 
for things such as ratings, playcounts, performer roles, and 
more. It does this by proposing standards for common 
functionality needs where none currently exist, and doing so in a 
way that is easily adoptable cross-player and cross-format. It is 
designed to be robust against future needs and to prevent 
possible conflicts with other tag identifiers and values.

Table of Contents

    1 Front Matter
        1.1 License
        1.2 Terminology
    2 Audio Metadata Tags
        2.1 Common Data and Tag Information
            2.1.1 MP3
            2.1.2 VorbisComments
            2.1.3 APEv2
            2.1.4 MP4
            2.1.5 Windows Media
        2.2 Rating Tags
            2.2.1 All Rating Tags
            2.2.2 FMPS_Rating
            2.2.3 FMPS_Rating_User
        2.3 FMPS_Rating_Critic
            2.3.1 FMPS_Rating_Algorithm
        2.4 Playcount Tags
            2.4.1 All Playcount Tags
            2.4.2 User Playcount Criteria
            2.4.3 FMPS_Playcount
            2.4.4 FMPS_Playcount_User
            2.4.5 FMPS_Playcount_Algorithm
        2.5 Performer Roles
        2.6 Lyrics
        2.7 Album/Compilation (“Various Artists”) Identifier


1 Front Matter

1.1 License

You may use this specification under either of the following 
licenses, at your discretion. Most will want to use it under 
Creative Commons; the GPL alternative is in case future versions 
of the spec contain e.g. code snippets that you would like to use 
in GPL programs:

1. This specification is licensed under the Creative Commons 
  Attribution-Share Alike 3.0 Unported License. You are free to 
  copy, distribute and transmit this work, provided that the 
  copyright information and full URL to the license information 
  page (http://creativecommons.org/licenses/by-nd/3.0/) remain 
  intact. If you alter, transform, or build upon this work, you 
  may distribute the resulting work only under the same or 
  similar license to this one. 

2. This program is free software; you can redistribute it and/or 
  modify it under the terms of the GNU General Public License as 
  published by the Free Software Foundation; either version 2 of 
  the License, or (at your option) any later version. This 
  program is distributed in the hope that it will be useful, but 
  WITHOUT ANY WARRANTY; without even the implied warranty of 
  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 
  GNU General Public License for more details. See http://www.gnu.org/licenses/
  . 

1.2 Terminology

Terminology follws that specified in RFC2119, “Key words for use 
in RFCs to Indicate Requirement Levels”. See http://www.ietf.org/rfc/rfc2119.txt
 for more information.

2 Audio Metadata Tags

The metadata tag formats evolved from Quod Libet's VorbisComments 
suggestions at http://code.google.com/p/quodlibet/wiki/Specs_VorbisComments
, however this attempts to not only address ambiguities and 
incompatibilities with the specification at that URL, but also to 
define how this functionality should be applied across formats. 
It is intended that as usable ways of inserting the metadata 
described become available for formats not currently specified, 
that this document will be updated to meet those needs.

All newly-specified tags carry an identifier “FMPS_” to tie the 
tags to this specification. The reason is simple: since the 
official metadata specifications either fail to define or define 
unusable tags, these values are only official to the extent that 
this specification is adopted. Without an identifier to give 
context to the meanings and limitations of the values, there is a 
real possibility that a noncompliant media player will use the 
same tag names in an incompatible fashion, whether intentionally 
or not, and there is no way to determine whether a seemingly 
compatible use of the tags by a noncompliant player actually 
results in user-intended behavior. The “FMPS_” identifier and 
this specification document is therefore used in a similar 
fashion to XML schema declarations.

As these identifiers are read and modified only by players and 
advanced users, it is not expected to be a hindrance to adoption 
or to cause undue burden on either.

2.1 Common Data and Tag Information

This section provides “up-front” information that is pertinent to 
all tags described below, such as what encoding to use and which 
tags to use in various formats.

For all tag formats, the following is defined:

• All identifiers are ASCII strings, and defined in the sections 
  below. All identifier strings must escape each colon (':'), 
  semicolon (';') and backslash ('\') with a backslash.

• All values (including numeric values) are stored as strings, 
  which MUST adhere to the allowed encoding and length limits in 
  the relevant tag format specifications, but SHOULD use Unicode 
  whenever possible.

  – To keep the specification simple, no ranges of control 
    characters are defined which should never be included in a 
    string. It is assumed that the used string-handling library 
    will properly handle any such characters encountered. It is 
    highly recommended, however, that no such control characters 
    are used, except when specified below.

  – All value strings must escape each colon (':'), semicolon 
    (';') and backslash ('\') with a backslash. 

• Although identifier case is specified for the different types 
  of tags, comparisons against identifier strings MUST be 
  case-insensitive.

• A period/full stop is used to separate the digits in a float 
  value from the fractional part of the float. All float values 
  MUST include a period/full stop (1 is not acceptable; 1.0 is 
  correct).

• Float values SHOULD be limited to six decimal places.

• All lists are value strings. For any lists, entries MUST be 
  separated with a double semicolon ';;' and fields within an 
  entry MUST be separated with a double colon '::' (examples in 
  following sections). These separation markers MUST NOT be 
  escaped with backslashes. This allows for easy splitting of 
  list entries and entry fields with most string libraries; the 
  entries and fields can be split by double semicolon/double 
  colon, and the ensuing fields can have any escaped values 
  substituted.

The following sections describe where the information should be 
stored in specific tag formats.

2.1.1 MP3

MP3 values MUST be stored in a TXXX frame with the Description 
set to the specified identifier and the Text set to the string 
representation of the value. The Description SHOULD be in 
CamelCase as specified in the following sections, e.g. 
FMPS_Rating.

2.1.2 VorbisComments

Any file supporting VorbisComments (Vorbis, FLAC, Theora, Speex) 
MUST use a comment with the Key set to the specified identifier 
and the Value set to the string representation of the value. The 
Key SHOULD be in all upper-case, e.g. FMPS_RATING.

2.1.3 APEv2

Any file supporting APEv2 MUST add a comment with the Key set to 
the specified identifier and the Value set to the string 
representation of the value. The Key SHOULD be in all upper-case, 
e.g. FMPS_RATING.

2.1.4 MP4

MP4 values MUST be stored at ----:com.apple.iTunes:Identifier 
with the value a string representation of the tag's value. The 
Identifier SHOULD be in CamelCase as specified in the following 
sections, e.g. FMPS_Rating.

2.1.5 Windows Media

Windows Media values MUST be stored in the FMPS/Identifier 
namespace with the value a string representation of the tag's 
value. The Identifier SHOULD be in CamelCase as specified in the 
following sections, e.g. FMPS_Rating.

2.2 Rating Tags

Most media players support the notion of rating content, however 
standards for storing ratings in files do not exist. Some file 
metadata formats completely lack rating fields; others require 
personally identifiable information to be used as an identifier 
(such as a user's email address) or an organizational identifier 
(which reduces cross-player compatibility). The goal therefore is 
simple: to avoid any personally identifying information but to 
avoid tying the rating to a specific player.

Three types of ratings are currently defined: user ratings, 
critic ratings, and automatic (or algorithmic) ratings.

Although users are more naturally able to understand integer 
ratings, only advanced users will interact with these tags 
directly; otherwise they will be presented to the user via a 
conforming application. Meanwhile, there are tangible benefits to 
storing ratings as floating-point numbers, mainly due to the fact 
that the increased precision allows for a number of interesting 
and useful algorithmic rating schemes to be used. However, using 
both integer and floating-point values unnecessarily increases 
complexity of both this spec and application code. Therefore, 
both values are stored as floating-point numbers. Conversion to 
and from these and an integer scale presented to the user in an 
application is easily accomplished in the application's code if 
it is so desired.

Four tags are defined, corresponding to the three types of 
defined ratings, plus a canonical value: FMPS_Rating_User; 
FMPS_Rating_Critic; FMPS_Rating_Algorithm; and FMPS_Rating (the 
canonical value). A file that has no rating tag for a specific 
purpose is to be considered unrated for that purpose (user, 
critic or algorithm).

2.2.1 All Rating Tags

• Ratings SHALL be a float value between 0.0 and 1.0, inclusive. 
  0.0 SHALL be the lowest possible rating; 1.0 is the highest 
  possible rating.

• Ratings SHOULD only be rounded when necessary, in order to 
  increase cross-player compatibility.

2.2.2 FMPS_Rating

• The canonical rating value in FMPS_Rating SHOULD be set 
  whenever a user rates the track. This is in addition to any 
  value stored for that particular user in FMPS_Rating_User. This 
  value is canonical because if a player does not support 
  multiple users (or if no user identifier is set), this is the 
  value that MUST be returned.

• If a user removes ratings from a track in the media player's 
  database, the value of the FMPS_Rating tag SHOULD be cleared as 
  well.

2.2.3 FMPS_Rating_User

• If a player supports the notion of multiple users (perhaps from 
  discovery of the current user from the operating system) and 
  wishes to allow the users to keep separate ratings, it MUST 
  store these values in the FMPS_Rating_User tag.

• Applications supporting multiple user ratings SHOULD have a way 
  for users to define their preferred identifier. 

• The values are in the form of a list as defined in Section 2.1, 
  with list entries in the format of UserIdentifier::Value. There 
  MUST NOT be empty value strings.

Example: “Alice Abba::0.6;;Bob Beatles::0.8”.

2.3 FMPS_Rating_Critic

• The values MUST be in the form of a list as defined in Section 
  2.1, with list entries in the format of 
  Publication::Critic::Rating. If the critic is unaffiliated, or 
  if the rating is by a publication with no byline, the special 
  value “FMPS_Nothing” MUST be used to denote this; there MUST 
  NOT be empty strings.

Example: “Rolling Stone::Ralph 
Gleason::0.83;;musicOMH.com::FMPS_Nothing::0.76;;Metacritic::FMPS_Nothing::0.8;;FMPS_Nothing::Some 
Dude::0.9”

2.3.1 FMPS_Rating_Algorithm

• The values MUST be in the form of a list as defined in Section 
  2.1, with list entries in the format of 
  Application::Algorithm::Rating. All fields MUST be defined; 
  fields MUST NOT be left empty.

• In cases where the algorithm is intended to be 
  global/collaborative/cross-application, the Application value 
  SHOULD be set to some agreed-upon value. In other words, it is 
  RECOMMENDED to use the application name for the Application 
  part of the identifier, but it MAY also be used to identify a “
  group” of algorithms, or some arbitrary other value that can be 
  used for identification.

Example: “
Amarok::AutoRate::0.52;;VLC::Standard::0.6;;QuodLibet::RatingPlugin\:X::0.35;;The 
Free Music Player Alliance::Rating Algorithm 1::0.5”

A note on the floating point values: some players may only allow 
users to rate in increments of whole numbers between 1 and 5; 
others 0 and 10; and so on. However, players SHOULD ensure that 
the rating they display and use for any purpose adheres to that 
saved in the tag whenever possible, only rounding this number 
when absolutely necessary.

For instance, if a track has a rating of 0.9 and an application 
only shows ratings using five star icons in full-star increments, 
this would be rounded within the application to five stars. 
Howeer, if the player also shows the rating numerically, the 
application would display 4.5 in the numeric field instead of the 
same 5 shown in the star icons, thus more accurately reflecting 
the user's set rating.

2.4 Playcount Tags

As with ratings, there are multiple kinds of playcount tags (user 
and algorithmic) in addition to a canonical value. The user tag 
tracks how many times a song has been played for a user. The 
auto/algorithmic value can be used in an application-specific way 
to do interesting things; for instance, to cumulatively track 
exact percentages of tracks played, in order to display to the 
user the number of days/hous/minutes/seconds they have spent 
listening to a particular song. 

Three tags are defined, corresponding to the two types of defined 
playcounts, plus a canonical value: FMPS_Playcount_User; 
FMPS_Playcount_Algorithm; and FMPS_Playcount (the canonical 
value). A file that has no playcount tag for a specific purpose 
is to be considered unplayed for that purpose (user or 
algorithm).

2.4.1 All Playcount Tags

• Playcounts MUST be a float value not less than 0.0. 0.0 is 
  valid and means unplayed.

• The maximum value SHALL be 0.000001 less than the largest value 
  able to be stored in a 32-bit unsigned integer: 
  4,294,967,294.999999. This is so that playcount values can be 
  rounded to an integer equivalent, if necessary (e.g. for 
  display to the user).

2.4.2 User Playcount Criteria

The user playcount isn't meant to be set by the user, but rather 
to follow these rules that define user behavior. A file is to be 
considered “played” if it meets the following criteria, inspired 
by Last.fm's scrobbling rules:

• If the track is less than thirty seconds long, the entire song 
  MUST be played.

• If the track is more than thirty seconds long but less than 
  eight minutes long, at least fifty percent of the file MUST be 
  played, calculated via length of track. For instance, if a 
  track is one minute long, at least thirty seconds of the track 
  must have been played, although if the user skips backwards 
  multiple times and listens to the same ten seconds of the track 
  three times in a row, this may be considered a valid playcount.

• If the track is longer than eight minutes, at least four 
  minutes of the track MUST be played.

User playcounts have an additional restriction in that they MUST 
be float values representing integers (1.0, 141.0, etc.). They 
are never fractional values; a song was either played, or it 
wasn't.

2.4.3 FMPS_Playcount

• The canonical playcount value in FMPS_Playcount SHOULD be set 
  whenever a user plays a track. This is in addition to any value 
  stored for that user in FMPS_Playcount_User. This value is 
  canonical because if a player does not support multiple users 
  (or if no user identifier is set) this is the value that MUST 
  be returned.

• If a user has an identifier set to store per-user playcounts, 
  when this value is set it MUST be set to the value of that 
  user's playcount. In other words, the last value held in 
  FMPS_Playcount will be equivalent to the latest user's personal 
  playcount, if any.

• If a user resets the playcount for a track in the media 
  player's database, the value of the FMPS_Playcount tag SHOULD 
  be cleared as well.

• FMPS_Playcount MUST store “full plays” of a track according to 
  the rules in Section 2.4.2.

2.4.4 FMPS_Playcount_User

• If a player supports the notion of multiple users (perhaps from 
  discovery of the current user from the operating system) and 
  wishes to allow the users to keep separate playcounts, it MUST 
  store these values in the FMPS_Playcount_User tag.

• Applications supporting multiple user playcounts SHOULD have a 
  way for users to define their preferred identifier. 

• The values MUST be in the form of a list as defined in Section 
  2.1, with list entries in the format of UserIdentifier::Value. 
  There MUST NOT be empty strings.

• FMPS_Playcount_User MUST store “full plays” of a track 
  according to the rules in Section 2.4.2.

Example: “Alice Abba::1.0;;Bob Beatles::133.0”.

2.4.5 FMPS_Playcount_Algorithm

• The values MUST be in the form of a list as defined in Section 
  2.3.1, with list entries in the format of 
  Application::Algorithm::Playcount. All fields MUST be defined; 
  fields MUST NOT be left empty.

• In cases where the algorithm is intended to be 
  global/collaborative/cross-application, the Application value 
  SHOULD be set to some agreed-upon value. In other words, it is 
  RECOMMENDED to use the application name for the Application 
  part of the identifier, but it MAY also be used to identify a “
  group” of algorithms, or some arbitrary other value that can be 
  used for identification.

• For algorithms, a track's length MUST be considered to be worth 
  1.0 playcounts; the user skipping parts of the track MAY 
  decrease the value below 1.0, and the user repeating parts of 
  the track MAY increase this value past 1.0.

Example: “
Amarok::AutoPlaycount::152.69;;VLC::Standard::198.0;;QuodLibet::PlaycountPlugin\:X::1652.19;;The 
Music Player Alliance::Playcount Algorithm 1::0.5”

2.5 Performer Roles

Performer roles allow you to describe the performers in a track. 
Current support for these roles in tag formats is often sporadic 
or difficult to parse. As many of these tags as desired can be 
specified, to include all relevant performer information.

• Performer roles use the identifier “FMPS_Performers”. The value 
  MUST be a list in the form of Performer::Role, where Role is 
  the user-defined role (“Guitar”, “Guitar (Backup)”, “Vocals”).

Example: “Willy Nelson::Guitar;;Eric Clapton::Guitar 
(Backup);;B.B. King::Vocals”

2.6 Lyrics

Embedding lyrics into a file allows users to save custom lyrics 
and to still see the lyrics when not connected to the Internet. 
Since different users may wish to have different sets of lyrics 
(for example, if customizing lyrics against a music-only track) 
and different Internet sources may have different lyrics, it is 
possible to store multiple lyrics values by specifying a source.

• The identifier for the (canonical) lyrics text is “FMPS_Lyrics”
  . The value MUST be a string. Spaces, tabs, and newlines SHOULD 
  be preserved when saving the string, and SHOULD be displayed 
  properly to the user.

• Lyrics MAY also be stored in FMPS_Lyrics_Sources as a list (as 
  defined in Section 2.1), in which case the form MUST be 
  Source::Data.

Example: “Alice Aardvark::[lyrics];;Bob 
Baboon::[lyrics];;http\://www.lyricssite.net::[lyrics]”

2.7 Album/Compilation (“Various Artists”) Identifier

Compilations (or “Various Artists” albums) can be difficult for 
music players to discover. Sometimes the user places all files 
from a compilation in one directory and expects that the music 
player will understand this; sometimes the user has them in 
different directories but with the same album name and expects 
that the music player will understand this; and so on.

Although there are existing solutions to identify albums and 
songs that belong to the same album (such as MusicBrainz 
identifiers) many users have not or do not want to tag their 
songs with MusicBrainz information. This tag therefore provides a 
simple way for an application to assign a album identifier to a 
track, indicating to what album a track belongs. It also provides 
a simple way of marking the album as a compilation or not.

This enables such use-cases as allowing a user to mark multiple 
tracks that are part of a single compilation, and then have those 
tracks show up as being together in a compilation the next time 
the user adds the tracks to the music player.

This section purposefully does not define information about the 
album/compilation; it is expected that the user must supply that 
information in appropriate existing tags, e.g. ALBUM and 
ALBUMARTIST for VorbisComments.

• The identifier for the album/compilation tag is 
  FMPS_Albums_Compilations. Although this tag will be most useful 
  for compilation/Various Artists albums, there may still be 
  significant utility for a player in using this tag to identify 
  single-artist albums. As a result, players MUST NOT make 
  assumptions about whether the presence of this tag identifies 
  the track as belonging to a compilation/Various Artists album 
  and MUST explicitly derive this information from the tag value.

• Values MUST be a list (as defined in Section 2.1) in the form 
  of Application::Type::Identifier. Applications MAY have more 
  than one identifier, if the user wants to mark a track as being 
  present in multiple compilations, or to give user-defined names 
  to a compilation. However, each list entry MUST be unique. 
  Similarly to other tags in this specification, there may be 
  significant utility in interoperating on the application names.

• Type MUST be one of the following values, without quotes: “
  Album” (indicating a general-purpose album, usually by a single 
  artist) or “Compilation” (indicating a compilation album, 
  usually by multiple/various artists). Checks against this value 
  MUST be case-insensitive. More values may be added in the 
  future; if a player encounters an unknown value it SHOULD 
  default to type “Album”. 

Example: “Amarok::Album::2982ab29ef;;AmarokUser::Compilation::My 
Compilation;;Banshee::Compilation::ad8slpbzl229zier;;FMPSAlliance::Album::de9f2c7fd25e1b3afad3e85a0bd17d9b100db4b3”