Updated some text.
[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 Standard
215 The following sections describe where the information should be stored in
216  specific tag formats.
217 \end_layout
218
219 \begin_layout Subsubsection
220 MP3
221 \end_layout
222
223 \begin_layout Standard
224 MP3 values should be stored in a TXXX frame with the Description set to
225  the specified identifier and the Text set to the string representation
226  of the value.
227  The Description should be in CamelCase as specified in the following sections,
228  e.g.
229  FMPS_Rating.
230 \end_layout
231
232 \begin_layout Subsubsection
233 VorbisComments
234 \end_layout
235
236 \begin_layout Standard
237 Any file supporting VorbisComments (Vorbis, FLAC, Theora, Speex) should
238  add a comment with the Key set to the specified identifier and the Value
239  set to the string representation of the value.
240  The Key should be in all upper-case, e.g.
241  FMPS_RATING.
242 \end_layout
243
244 \begin_layout Subsubsection
245 APEv2
246 \end_layout
247
248 \begin_layout Standard
249 Any file supporting APEv2 should add a comment with the Key set to the specified
250  identifier and the Value set to the string representation of the value.
251  The Key should be in all upper-case, e.g.
252  FMPS_RATING.
253 \end_layout
254
255 \begin_layout Subsubsection
256 MP4
257 \end_layout
258
259 \begin_layout Standard
260 MP4 values should be stored at ----:com.apple.iTunes:Identifier with the value
261  a string representation of the tag's value.
262  The Identifier should be in CamelCase as specified in the following sections,
263  e.g.
264  FMPS_Rating.
265 \end_layout
266
267 \begin_layout Subsubsection
268 Windows Media
269 \end_layout
270
271 \begin_layout Standard
272 Windows Media values should be stored in the FMPS/Identifier namespace with
273  the value a string representation of the tag's value.
274  The Identifier should be in CamelCase as specified in the following sections,
275  e.g.
276  FMPS_Rating.
277 \end_layout
278
279 \begin_layout Subsection
280 Song Rating Tags
281 \end_layout
282
283 \begin_layout Standard
284 Most media players support the notion of rating content, however standards
285  for storing ratings in files do not exist.
286  Some file metadata formats completely lack rating fields; others require
287  personal information to be used as an identifier (such as a user's email
288  address) or an organizational identifier (which reduces cross-player compatibil
289 ity).
290  The goal therefore is simple: to avoid any personal identifying information
291  but avoid tying the rating to a specific player.
292 \end_layout
293
294 \begin_layout Standard
295 Three types of ratings are currently defined: user ratings, critic ratings,
296  and automatic (or algorithmic) ratings.
297 \end_layout
298
299 \begin_layout Standard
300 Although users are more naturally able to understand integer ratings, only
301  advanced users will interact with these tags directly; otherwise they will
302  be presented to the user via a conforming application.
303  Meanwhile, there are tangible benefits to storing ratings as floating-point
304  numbers, mainly due to the fact that the increased precision allows for
305  a number of interesting and useful algorithmic rating schemes to be used.
306  However, using both integer and floating-point values unnecessarily increases
307  complexity of both this spec and application code.
308  Therefore, both values are stored as floating-point numbers.
309  Conversion to and from these and an integer scale presented to the user
310  in an application is easily accomplished in the application's code if it
311  is so desired.
312 \end_layout
313
314 \begin_layout Standard
315 If a combination of rating tags exist when a file is being imported or read
316  into a player's library, the user rating is considered canonical and takes
317  precedence, meaning that if only a single value is being shown to the user
318  it should be the user-defined value.
319 \end_layout
320
321 \begin_layout Standard
322 For all tag formats, the following is defined:
323 \end_layout
324
325 \begin_layout Itemize
326 A file that has no such tag is to be considered unrated for that purpose
327  (user or algorithm).
328 \end_layout
329
330 \begin_layout Itemize
331 If a user removes ratings from a track in the media player, the user rating
332  tag should be removed as well.
333  The algorithmic rating tag does not have to be removed in this instance.
334 \end_layout
335
336 \begin_layout Itemize
337 The identifier for the (canonical) user rating is 
338 \begin_inset Quotes eld
339 \end_inset
340
341 FMPS_Rating
342 \begin_inset Quotes erd
343 \end_inset
344
345 .
346 \end_layout
347
348 \begin_layout Itemize
349 The identifier for critic ratings is 
350 \begin_inset Quotes eld
351 \end_inset
352
353 FMPS_Rating_Critic_Identifier
354 \begin_inset Quotes erd
355 \end_inset
356
357  where Identifier names either a publication/site (
358 \begin_inset Quotes eld
359 \end_inset
360
361 Rolling_Stone
362 \begin_inset Quotes erd
363 \end_inset
364
365
366 \begin_inset Quotes eld
367 \end_inset
368
369 Metacritic
370 \begin_inset Quotes erd
371 \end_inset
372
373 ) or a person in Firstname=Lastname format (
374 \begin_inset Quotes eld
375 \end_inset
376
377 Ralph=Gleason
378 \begin_inset Quotes erd
379 \end_inset
380
381 ).
382 \end_layout
383
384 \begin_layout Itemize
385 The identifier for the algorithmic rating is 
386 \begin_inset Quotes eld
387 \end_inset
388
389 FMPS_Rating_Algorithm_Identifier
390 \begin_inset Quotes erd
391 \end_inset
392
393  where Identifier names an arbitrary algorithm name.
394 \end_layout
395
396 \begin_layout Itemize
397 Ratings are a float value between 0.0 and 1.0, inclusive.
398  0.0 is the lowest possible rating; 1.0 is the highest possible rating.
399 \end_layout
400
401 \begin_layout Itemize
402 Ratings should only be rounded when necessary, in order to increase cross-player
403  compatibility.
404 \end_layout
405
406 \begin_layout Standard
407 A note on that last point: some players may only allow users to rate in
408  increments of whole numbers between 1 and 5; others 0 and 10; and so on.
409  However, players should try to ensure that the rating they display and
410  use for any purposes adheres to that saved in the tag when possible.
411  For instance, if a track has a rating of 0.9 and an application only shows
412  ratings using five star icons in full-star increments, this would be rounded
413  within the application to five stars.
414  However, the user may in fact have set the rating to 9/10 in another applicatio
415 n.
416  If the rating was being shown numerically, ideally the application would
417  only round this number when absolutely necessary and display 4.5 instead
418  of 5, which would more accurately reflect the user's set rating.
419 \end_layout
420
421 \begin_layout Subsection
422 Playcount Tags
423 \end_layout
424
425 \begin_layout Standard
426 As with ratings, there are both user and automatic playcount tags.
427  The user tag is canonical and intended to be used in the normal sense,
428  tracking how many times a song has been played (as defined below).
429  The auto/algorithmic value can be used in an application-specific way to
430  do interesting things; for instance, to cumulatively track exact percentages
431  of tracks played, in order to display to the user the number of days/hous/minut
432 es/seconds they have spent listening to a particular song.
433  
434 \end_layout
435
436 \begin_layout Standard
437 As with ratings, if both tags exist when a file is being imported or read
438  into a player's library, the user playcount takes precedence for display.
439 \end_layout
440
441 \begin_layout Standard
442 For all tag formats, the following is defined:
443 \end_layout
444
445 \begin_layout Itemize
446 A file that has no such tag is to be considered unplayed for that purpose
447  (user or algorithm).
448  Removing playcount information from a track in the media player should
449  cause the user playcount tag to be removed as well.
450  The algorithmic playcount tag does not have to be removed in this instance.
451 \end_layout
452
453 \begin_layout Itemize
454 The identifier for the (canonical) user playcount is 
455 \begin_inset Quotes eld
456 \end_inset
457
458 FMPS_Playcount
459 \begin_inset Quotes erd
460 \end_inset
461
462 .
463 \end_layout
464
465 \begin_layout Itemize
466 The identifier for an algorithmic rating is 
467 \begin_inset Quotes eld
468 \end_inset
469
470 FMPS_Playcount_Algorithm_Identifier
471 \begin_inset Quotes erd
472 \end_inset
473
474  where Identifier names an arbitrary algorithm name.
475 \end_layout
476
477 \begin_layout Itemize
478 Playcounts are a float value with a minimum of 0.0, where 0.0 is an acceptable
479  value but indicates that a track has not been played (the same as if the
480  track had no playcount tag).
481  Playcounts (especially the user playcount) can be shown the user as integers
482  but must always be stored as a float.
483 \end_layout
484
485 \begin_layout Itemize
486 For the user playcount, playing a track (subject to the criteria below)
487  increases the user playcount value by 1.0.
488  For the algorithmic playcount, a track's length should be considered to
489  be worth 1.0; the user skipping parts of the track may decrease the value
490  below 1.0, and the user repeating parts of the track may increase this value
491  past 1.0.
492 \end_layout
493
494 \begin_layout Itemize
495 The maximum value is 0.000001 less than the largest value able to be stored
496  in a 32-bit unsigned integer: 4,294,967,294.999999.
497  This is so that the float playcount value can be rounded to an integer
498  equivalent, if necessary.
499 \end_layout
500
501 \begin_layout Standard
502 The user playcount isn't meant to be set by the user, but rather to follow
503  these rules that define user behavior.
504  A file is to be considered 
505 \begin_inset Quotes eld
506 \end_inset
507
508 played
509 \begin_inset Quotes erd
510 \end_inset
511
512  if it meets the following criteria, inspired by Last.fm's scrobbling rules:
513 \end_layout
514
515 \begin_layout Itemize
516 If the track is less than 30 seconds long, the entire song must be played.
517 \end_layout
518
519 \begin_layout Itemize
520 If the track is more than 30 seconds long, at least fifty percent of the
521  file must be played, calculated via length of track.
522  For instance, if a track is one minute long, at least thirty seconds of
523  the track must have been played, although if the user skips backwards multiple
524  times and listens to the same ten seconds of the track three times in a
525  row, this may be considered a valid playcount.
526 \end_layout
527
528 \begin_layout Subsection
529 Performer Roles
530 \end_layout
531
532 \begin_layout Standard
533 Performer roles allow you to describe the performers in a track.
534  Current support for these roles in tag formats is sporadic or difficult
535  to parse.
536  As many of these tags as desired can be specified, to include all relevant
537  performer information.
538 \end_layout
539
540 \begin_layout Standard
541 For all tag formats, the following is defined:
542 \end_layout
543
544 \begin_layout Itemize
545 The identifier used is 
546 \begin_inset Quotes eld
547 \end_inset
548
549 FMPS_Performer:X
550 \begin_inset Quotes erd
551 \end_inset
552
553 , where X is the user-defined role (
554 \begin_inset Quotes eld
555 \end_inset
556
557 Guitar
558 \begin_inset Quotes erd
559 \end_inset
560
561
562 \begin_inset Quotes eld
563 \end_inset
564
565 Guitar (Backup)
566 \begin_inset Quotes erd
567 \end_inset
568
569
570 \begin_inset Quotes eld
571 \end_inset
572
573 Vocals
574 \begin_inset Quotes erd
575 \end_inset
576
577 ).
578 \end_layout
579
580 \begin_layout Itemize
581 The value of each identifier is the role performer's name.
582 \end_layout
583
584 \begin_layout Section
585 Filesystem Directives
586 \end_layout
587
588 \begin_layout Standard
589 Common functionality for many media players is the notion of a library or
590  collection as a store of media objects that can be played.
591  Generally, users specify or drag-n-drop directories or files that they
592  wish to have added to this store.
593  These subsections contain files that can be present on a user's filesystem
594  to allow for more fine-grained control over import.
595 \end_layout
596
597 \begin_layout Subsection
598 Ignore Directive
599 \end_layout
600
601 \begin_layout Standard
602 When a directory is being parsed, it should first be checked for a file
603  with the name 
604 \begin_inset Quotes eld
605 \end_inset
606
607 fmps_ignore
608 \begin_inset Quotes erd
609 \end_inset
610
611 .
612  If present, the parser should ignore that directory's files.
613 \end_layout
614
615 \end_body
616 \end_document