Updates to spec (see changelog)
[xdg-specs:xdg-specs.git] / specifications / FMPSpecs / specification.lyx
1 #LyX 1.6.4 created this file. For more info see http://www.lyx.org/
2 \lyxformat 345
3 \begin_document
4 \begin_header
5 \textclass docbook
6 \use_default_options false
7 \language english
8 \inputencoding auto
9 \font_roman default
10 \font_sans default
11 \font_typewriter default
12 \font_default_family default
13 \font_sc false
14 \font_osf false
15 \font_sf_scale 100
16 \font_tt_scale 100
17
18 \graphics default
19 \paperfontsize default
20 \use_hyperref false
21 \papersize default
22 \use_geometry false
23 \use_amsmath 0
24 \use_esint 0
25 \cite_engine basic
26 \use_bibtopic false
27 \paperorientation portrait
28 \secnumdepth 3
29 \tocdepth 3
30 \paragraph_separation indent
31 \defskip medskip
32 \quotes_language english
33 \papercolumns 1
34 \papersides 1
35 \paperpagestyle default
36 \tracking_changes false
37 \output_changes false
38 \author "" 
39 \author "" 
40 \end_header
41
42 \begin_body
43
44 \begin_layout Title
45 Free Media Player Specifications
46 \end_layout
47
48 \begin_layout Title
49 Tag Specification
50 \end_layout
51
52 \begin_layout Date
53 January 25th, 2010
54 \end_layout
55
56 \begin_layout Author
57 Copyright 2009-2010 by 
58 \begin_inset Flex Element:Firstname
59 status collapsed
60
61 \begin_layout Plain Layout
62 Jeff
63 \end_layout
64
65 \end_inset
66
67  
68 \begin_inset Flex Element:Surname
69 status collapsed
70
71 \begin_layout Plain Layout
72 Mitchell
73 \end_layout
74
75 \end_inset
76
77
78 \end_layout
79
80 \begin_layout Author
81 To be released under an appropriate license when one is selected
82 \end_layout
83
84 \begin_layout Abstract
85 This specification describes various audio file tag metadata intended to
86  increase interoperability between free music players for things such as
87  ratings, playcounts, performer roles, and more.
88  It does this by proposing standards for common functionality needs where
89  none currently exist, and doing so in a way that is easily adoptable cross-play
90 er and cross-format.
91  It is designed to be robust against future needs and to prevent possible
92  conflicts with other tag identifiers and values.
93 \end_layout
94
95 \begin_layout Section
96 Metadata Tags
97 \end_layout
98
99 \begin_layout Standard
100 The metadata tag formats evolved from Quod Libet's VorbisComments suggestions
101  at 
102 \begin_inset Flex URL
103 status collapsed
104
105 \begin_layout Plain Layout
106
107 http://code.google.com/p/quodlibet/wiki/Specs_VorbisComments
108 \end_layout
109
110 \end_inset
111
112 , however this attempts to not only address ambiguities and incompatibilities
113  with the specification at that URL, but also to define how this functionality
114  should be applied cross-format.
115  It is intended that as usable ways of inserting the metadata described
116  become available for formats not currently specified, that this document
117  will be updated to meet those needs.
118 \end_layout
119
120 \begin_layout Standard
121 All newly-specified tags carry an identifier 
122 \begin_inset Quotes eld
123 \end_inset
124
125 FMPS_
126 \begin_inset Quotes erd
127 \end_inset
128
129  to tie the tags to this specification.
130  The reason is simple.
131  Since the official metadata specifications either fail to define or define
132  unusable tags, these value are only official to the extent that this specificat
133 ion is adopted.
134  Without an identifier to give context to the meanings and limitations of
135  the values, there is a real possibility that a noncompliant media player
136  will use the same tag names in an incompatible fashion, whether intentionally
137  or not, and there is no way to determine whether a seemingly compatible
138  use of the tags by a noncompliant player actually results in user-intended
139  behavior.
140  The 
141 \begin_inset Quotes eld
142 \end_inset
143
144 FMPS_
145 \begin_inset Quotes erd
146 \end_inset
147
148  identifier and this specification document is therefore used in a similar
149  fashion to XML schema declarations.
150 \end_layout
151
152 \begin_layout Standard
153 As these identifiers are read and modified only by players and advanced
154  users, it is not expected to be a hindrance to adoption or to cause undue
155  burden on either.
156 \end_layout
157
158 \begin_layout Subsection
159 Common Data and Tag Information
160 \end_layout
161
162 \begin_layout Standard
163 This section provides 
164 \begin_inset Quotes eld
165 \end_inset
166
167 up-front
168 \begin_inset Quotes erd
169 \end_inset
170
171  information that is pertinent to all tags described below, such as what
172  encoding to use and which tags to use in various formats.
173 \end_layout
174
175 \begin_layout Standard
176 For all tag formats, the following is defined:
177 \end_layout
178
179 \begin_layout Itemize
180 All identifers and values are strings in UTF-8 encoding.
181  To keep the specification simple, no ranges of control characters are defined
182  which should never be included in a string.
183  It is assumed that the used string-handling library will properly handle
184  any such characters encountered.
185 \end_layout
186
187 \begin_layout Itemize
188 A period/full stop is used to separate the digits in a float value from
189  the fractional part of the float.
190  All float values must include a period/full stop (1 is not acceptable;
191  1.0 is correct).
192 \end_layout
193
194 \begin_layout Itemize
195 Float values should be limited to six decimal places.
196 \end_layout
197
198 \begin_layout Itemize
199 Any spaces in identifiers should be represented using underscores ( _ )
200  instead, although this can be converted to spaces for display to the user.
201 \end_layout
202
203 \begin_layout Itemize
204 Although identifier case is specified for the different types of tags, it
205  is probably a good idea to do comparisons against identifier strings converted
206  to all upper- or lower-case in case some implementations do not properly
207  adhere to the case specified.
208  Note that where identifiers also store other information (for instance
209  FMPS_RATING_CRITIC_Metacritic), proper capitalization for the variable
210  part of the identifier should be used, as this should be displayed as-is
211  to the user.
212 \end_layout
213
214 \begin_layout Itemize
215 Variable parts of identifiers should use equal signs (
216 \begin_inset Quotes eld
217 \end_inset
218
219 =
220 \begin_inset Quotes erd
221 \end_inset
222
223 ) to denote spaces when the variable is a person's name, and underscores
224  (
225 \begin_inset Quotes eld
226 \end_inset
227
228 _
229 \begin_inset Quotes erd
230 \end_inset
231
232 ) to denote spaces when the variable is the name of a publication or site.
233 \end_layout
234
235 \begin_layout Standard
236 The following sections describe where the information should be stored in
237  specific tag formats.
238 \end_layout
239
240 \begin_layout Subsubsection
241 MP3
242 \end_layout
243
244 \begin_layout Standard
245 MP3 values should be stored in a TXXX frame with the Description set to
246  the specified identifier and the Text set to the string representation
247  of the value.
248  The Description should be in CamelCase as specified in the following sections,
249  e.g.
250  FMPS_Rating.
251 \end_layout
252
253 \begin_layout Subsubsection
254 VorbisComments
255 \end_layout
256
257 \begin_layout Standard
258 Any file supporting VorbisComments (Vorbis, FLAC, Theora, Speex) should
259  add a comment with the Key set to the specified identifier and the Value
260  set to the string representation of the value.
261  The Key should be in all upper-case, e.g.
262  FMPS_RATING.
263 \end_layout
264
265 \begin_layout Subsubsection
266 APEv2
267 \end_layout
268
269 \begin_layout Standard
270 Any file supporting APEv2 should add a comment with the Key set to the specified
271  identifier and the Value set to the string representation of the value.
272  The Key should be in all upper-case, e.g.
273  FMPS_RATING.
274 \end_layout
275
276 \begin_layout Subsubsection
277 MP4
278 \end_layout
279
280 \begin_layout Standard
281 MP4 values should be stored at ----:com.apple.iTunes:Identifier with the value
282  a string representation of the tag's value.
283  The Identifier should be in CamelCase as specified in the following sections,
284  e.g.
285  FMPS_Rating.
286 \end_layout
287
288 \begin_layout Subsubsection
289 Windows Media
290 \end_layout
291
292 \begin_layout Standard
293 Windows Media values should be stored in the FMPS/Identifier namespace with
294  the value a string representation of the tag's value.
295  The Identifier should be in CamelCase as specified in the following sections,
296  e.g.
297  FMPS_Rating.
298 \end_layout
299
300 \begin_layout Subsection
301 Song Rating Tags
302 \end_layout
303
304 \begin_layout Standard
305 Most media players support the notion of rating content, however standards
306  for storing ratings in files do not exist.
307  Some file metadata formats completely lack rating fields; others require
308  personal information to be used as an identifier (such as a user's email
309  address) or an organizational identifier (which reduces cross-player compatibil
310 ity).
311  The goal therefore is simple: to avoid any personal identifying information
312  but avoid tying the rating to a specific player.
313 \end_layout
314
315 \begin_layout Standard
316 Three types of ratings are currently defined: user ratings, critic ratings,
317  and automatic (or algorithmic) ratings.
318 \end_layout
319
320 \begin_layout Standard
321 Although users are more naturally able to understand integer ratings, only
322  advanced users will interact with these tags directly; otherwise they will
323  be presented to the user via a conforming application.
324  Meanwhile, there are tangible benefits to storing ratings as floating-point
325  numbers, mainly due to the fact that the increased precision allows for
326  a number of interesting and useful algorithmic rating schemes to be used.
327  However, using both integer and floating-point values unnecessarily increases
328  complexity of both this spec and application code.
329  Therefore, both values are stored as floating-point numbers.
330  Conversion to and from these and an integer scale presented to the user
331  in an application is easily accomplished in the application's code if it
332  is so desired.
333 \end_layout
334
335 \begin_layout Standard
336 If a combination of rating tags exist when a file is being imported or read
337  into a player's library, the user rating is considered canonical and takes
338  precedence, meaning that if only a single value is being shown to the user
339  it should be the user-defined value.
340 \end_layout
341
342 \begin_layout Standard
343 For all tag formats, the following is defined:
344 \end_layout
345
346 \begin_layout Itemize
347 A file that has no such tag is to be considered unrated for that purpose
348  (user or algorithm).
349 \end_layout
350
351 \begin_layout Itemize
352 If a user removes ratings from a track in the media player, the user rating
353  tag should be removed as well.
354  The algorithmic rating tag does not have to be removed in this instance.
355 \end_layout
356
357 \begin_layout Itemize
358 The identifier for the (canonical) user rating is 
359 \begin_inset Quotes eld
360 \end_inset
361
362 FMPS_Rating
363 \begin_inset Quotes erd
364 \end_inset
365
366 .
367  This should be set whenever a user rates the track, regardless of whether
368  they are also using user-specific ratings as described below.
369 \end_layout
370
371 \begin_layout Itemize
372 If a player supports the notion of multiple users (perhaps from discovery
373  of the current user from the operating system) and wishes to allow the
374  users to keep separate ratings, the identifier should be in the form 
375 \begin_inset Quotes eld
376 \end_inset
377
378 FMPS_Rating_User_Identifier
379 \begin_inset Quotes erd
380 \end_inset
381
382  where identifier is a user-defined value.
383  Any spaces in the username should be converted to = signs, e.g.
384  
385 \begin_inset Quotes eld
386 \end_inset
387
388 FMPS_Rating_User_Jeff=Mitchell
389 \begin_inset Quotes erd
390 \end_inset
391
392 .
393 \end_layout
394
395 \begin_layout Itemize
396 The identifier for critic ratings is 
397 \begin_inset Quotes eld
398 \end_inset
399
400 FMPS_Rating_Critic_X
401 \begin_inset Quotes erd
402 \end_inset
403
404  where X names either a publication/site (
405 \begin_inset Quotes eld
406 \end_inset
407
408 Rolling_Stone
409 \begin_inset Quotes erd
410 \end_inset
411
412
413 \begin_inset Quotes eld
414 \end_inset
415
416 Metacritic
417 \begin_inset Quotes erd
418 \end_inset
419
420 ) or a person in Firstname=Lastname format (
421 \begin_inset Quotes eld
422 \end_inset
423
424 Ralph=Gleason
425 \begin_inset Quotes erd
426 \end_inset
427
428 ).
429 \end_layout
430
431 \begin_layout Itemize
432 The identifier for the algorithmic rating is 
433 \begin_inset Quotes eld
434 \end_inset
435
436 FMPS_Rating_Algorithm_X
437 \begin_inset Quotes erd
438 \end_inset
439
440  where X names an arbitrary algorithm name.
441 \end_layout
442
443 \begin_layout Itemize
444 Ratings are a float value between 0.0 and 1.0, inclusive.
445  0.0 is the lowest possible rating; 1.0 is the highest possible rating.
446 \end_layout
447
448 \begin_layout Itemize
449 Ratings should only be rounded when necessary, in order to increase cross-player
450  compatibility.
451 \end_layout
452
453 \begin_layout Standard
454 A note on that last point: some players may only allow users to rate in
455  increments of whole numbers between 1 and 5; others 0 and 10; and so on.
456  However, players should try to ensure that the rating they display and
457  use for any purposes adheres to that saved in the tag when possible.
458  For instance, if a track has a rating of 0.9 and an application only shows
459  ratings using five star icons in full-star increments, this would be rounded
460  within the application to five stars.
461  However, the user may in fact have set the rating to 9/10 in another applicatio
462 n.
463  If the rating was being shown numerically, ideally the application would
464  only round this number when absolutely necessary and display 4.5 instead
465  of 5, which would more accurately reflect the user's set rating.
466 \end_layout
467
468 \begin_layout Subsection
469 Playcount Tags
470 \end_layout
471
472 \begin_layout Standard
473 As with ratings, there are both user and automatic playcount tags.
474  The user tag is canonical and intended to be used in the normal sense,
475  tracking how many times a song has been played (as defined below).
476  The auto/algorithmic value can be used in an application-specific way to
477  do interesting things; for instance, to cumulatively track exact percentages
478  of tracks played, in order to display to the user the number of days/hous/minut
479 es/seconds they have spent listening to a particular song.
480  
481 \end_layout
482
483 \begin_layout Standard
484 As with ratings, if both tags exist when a file is being imported or read
485  into a player's library, the user playcount takes precedence for display.
486 \end_layout
487
488 \begin_layout Standard
489 For all tag formats, the following is defined:
490 \end_layout
491
492 \begin_layout Itemize
493 A file that has no such tag is to be considered unplayed for that purpose
494  (user or algorithm).
495  Removing playcount information from a track in the media player should
496  cause the user playcount tag to be removed as well.
497  The algorithmic playcount tag does not have to be removed in this instance.
498 \end_layout
499
500 \begin_layout Itemize
501 The identifier for the (canonical) user playcount is 
502 \begin_inset Quotes eld
503 \end_inset
504
505 FMPS_Playcount
506 \begin_inset Quotes erd
507 \end_inset
508
509 .
510  This should be incremented every time a user plays the track, regardless
511  of whether they are also using user-specific playcounts as described below.
512 \end_layout
513
514 \begin_layout Itemize
515 If a player supports the notion of multiple users (perhaps from discovery
516  of the current user from the operating system) and wishes to allow the
517  users to keep separate playcounts, the identifier should be in the form
518  
519 \begin_inset Quotes eld
520 \end_inset
521
522 FMPS_Playcount_User_X
523 \begin_inset Quotes erd
524 \end_inset
525
526  where X is a user-defined value.
527  Any spaces in the username should be converted to = signs, e.g.
528  
529 \begin_inset Quotes eld
530 \end_inset
531
532 FMPS_Playcount_User_Jeff=Mitchell
533 \begin_inset Quotes erd
534 \end_inset
535
536 .
537 \end_layout
538
539 \begin_layout Itemize
540 The identifier for an algorithmic rating is 
541 \begin_inset Quotes eld
542 \end_inset
543
544 FMPS_Playcount_Algorithm_X
545 \begin_inset Quotes erd
546 \end_inset
547
548  where X names an arbitrary algorithm name.
549 \end_layout
550
551 \begin_layout Itemize
552 Playcounts are a float value with a minimum of 0.0, where 0.0 is an acceptable
553  value but indicates that a track has not been played (the same as if the
554  track had no playcount tag).
555  Playcounts (especially the user playcount) can be shown to the user as
556  integers but must always be stored as a float.
557 \end_layout
558
559 \begin_layout Itemize
560 For the user playcount, playing a track (subject to the criteria below)
561  increases the user playcount value by 1.0.
562  For the algorithmic playcount, a track's length should be considered to
563  be worth 1.0; the user skipping parts of the track may decrease the value
564  below 1.0, and the user repeating parts of the track may increase this value
565  past 1.0.
566 \end_layout
567
568 \begin_layout Itemize
569 The maximum value is 0.000001 less than the largest value able to be stored
570  in a 32-bit unsigned integer: 4,294,967,294.999999.
571  This is so that the float playcount value can be rounded to an integer
572  equivalent, if necessary.
573 \end_layout
574
575 \begin_layout Standard
576 The user playcount isn't meant to be set by the user, but rather to follow
577  these rules that define user behavior.
578  A file is to be considered 
579 \begin_inset Quotes eld
580 \end_inset
581
582 played
583 \begin_inset Quotes erd
584 \end_inset
585
586  if it meets the following criteria, inspired by Last.fm's scrobbling rules:
587 \end_layout
588
589 \begin_layout Itemize
590 If the track is less than 30 seconds long, the entire song must be played.
591 \end_layout
592
593 \begin_layout Itemize
594 If the track is more than 30 seconds long, at least fifty percent of the
595  file must be played, calculated via length of track.
596  For instance, if a track is one minute long, at least thirty seconds of
597  the track must have been played, although if the user skips backwards multiple
598  times and listens to the same ten seconds of the track three times in a
599  row, this may be considered a valid playcount.
600 \end_layout
601
602 \begin_layout Subsection
603 Performer Roles
604 \end_layout
605
606 \begin_layout Standard
607 Performer roles allow you to describe the performers in a track.
608  Current support for these roles in tag formats is sporadic or difficult
609  to parse.
610  As many of these tags as desired can be specified, to include all relevant
611  performer information.
612 \end_layout
613
614 \begin_layout Standard
615 For all tag formats, the following is defined:
616 \end_layout
617
618 \begin_layout Itemize
619 The identifier used is 
620 \begin_inset Quotes eld
621 \end_inset
622
623 FMPS_Performer:X
624 \begin_inset Quotes erd
625 \end_inset
626
627 , where X is the user-defined role (
628 \begin_inset Quotes eld
629 \end_inset
630
631 Guitar
632 \begin_inset Quotes erd
633 \end_inset
634
635
636 \begin_inset Quotes eld
637 \end_inset
638
639 Guitar (Backup)
640 \begin_inset Quotes erd
641 \end_inset
642
643
644 \begin_inset Quotes eld
645 \end_inset
646
647 Vocals
648 \begin_inset Quotes erd
649 \end_inset
650
651 ).
652 \end_layout
653
654 \begin_layout Itemize
655 The value of each identifier is the role performer's name.
656 \end_layout
657
658 \begin_layout Subsection
659 Lyrics
660 \end_layout
661
662 \begin_layout Standard
663 Embedding lyrics into a file allows users to save custom lyrics and to still
664  see the lyrics when not connected to the Internet.
665  Since different users may wish to have different sets of lyrics (for example,
666  if customizing lyrics against a music-only track) and different Internet
667  sources may have different lyrics, it is possible to store multiple lyrics
668  values by specifying a source.
669 \end_layout
670
671 \begin_layout Standard
672 For all tag formats, the following is defined:
673 \end_layout
674
675 \begin_layout Itemize
676 The identifier for the (canonical) lyrics text is 
677 \begin_inset Quotes eld
678 \end_inset
679
680 FMPS_Lyrics
681 \begin_inset Quotes erd
682 \end_inset
683
684 .
685  The data must be a UTF-8 string of arbitrary length.
686  Spaces, tabs, and newlines should be preserved when saving the string and
687  displayed properly to the user.
688 \end_layout
689
690 \begin_layout Itemize
691 Lyrics identifiers may contain information as to the source: 
692 \begin_inset Quotes eld
693 \end_inset
694
695 FMPS_Lyrics_From_X
696 \begin_inset Quotes erd
697 \end_inset
698
699  where X names either a publication/site (
700 \begin_inset Quotes eld
701 \end_inset
702
703 Lyrics_Magazine
704 \begin_inset Quotes erd
705 \end_inset
706
707 ) or a person in Firstname=Lastname format (
708 \begin_inset Quotes eld
709 \end_inset
710
711 Jeff=Mitchell
712 \begin_inset Quotes erd
713 \end_inset
714
715 ).
716 \end_layout
717
718 \begin_layout Section
719 Examples
720 \end_layout
721
722 \end_body
723 \end_document