Third draft
[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 Date
49 November 13th, 2009
50 \end_layout
51
52 \begin_layout Author
53 Copyright 2009 by 
54 \begin_inset Flex Element:Firstname
55 status collapsed
56
57 \begin_layout Plain Layout
58 Jeff
59 \end_layout
60
61 \end_inset
62
63  
64 \begin_inset Flex Element:Surname
65 status collapsed
66
67 \begin_layout Plain Layout
68 Mitchell
69 \end_layout
70
71 \end_inset
72
73
74 \end_layout
75
76 \begin_layout Author
77 To be released under an appropriate license when one is selected
78 \end_layout
79
80 \begin_layout Abstract
81 This specification describes various metadata and behavioral items intended
82  to reduce complexity and enhance functionality for users of free music
83  and media players.
84  It does this by proposing standards for common functionality needs where
85  none currently exist, and doing so in a way that is easily adoptable cross-play
86 er and cross-format, when applicable.
87 \end_layout
88
89 \begin_layout Section
90 Metadata Tags
91 \end_layout
92
93 \begin_layout Standard
94 The metadata tag formats evolved from Quod Libet's VorbisComments suggestions
95  at 
96 \begin_inset Flex URL
97 status collapsed
98
99 \begin_layout Plain Layout
100
101 http://code.google.com/p/quodlibet/wiki/Specs_VorbisComments
102 \end_layout
103
104 \end_inset
105
106 , however this attempts to not only address ambiguities and incompatibilities
107  with the specification at that URL, but also to define how this functionality
108  should be applied cross-format.
109  It is intended that as usable ways of inserting the metadata described
110  become available for formats not currently specified, that this document
111  will be updated to meet those needs.
112 \end_layout
113
114 \begin_layout Standard
115 All newly-specified tags carry an identifier 
116 \begin_inset Quotes eld
117 \end_inset
118
119 FMPS_
120 \begin_inset Quotes erd
121 \end_inset
122
123  to tie the tags to this specification.
124  The reason is simple.
125  Since the official metadata specifications either fail to define or define
126  unusable tags, these value are only official to the extent that this specificat
127 ion is adopted.
128  Without an identifier to give context to the meanings and limitations of
129  the values, there is a real possibility that a noncompliant media player
130  will use the same tag names in an incompatible fashion, whether intentionally
131  or not, and there is no way to determine whether a seemingly compatible
132  use of the tags by a noncompliant player actually results in user-intended
133  behavior.
134  As these identifiers are read and modified only by players and advanced
135  users, it is not expected to be a hindrance to adoption or to cause undue
136  burden on either.
137 \end_layout
138
139 \begin_layout Subsection
140 Common Data and Tag Information
141 \end_layout
142
143 \begin_layout Standard
144 This section provides 
145 \begin_inset Quotes eld
146 \end_inset
147
148 up-front
149 \begin_inset Quotes erd
150 \end_inset
151
152  information that is pertinent to all tags described below, such as what
153  encoding to use and which tags to use in various formats.
154 \end_layout
155
156 \begin_layout Standard
157 For all tag formats, the following is defined:
158 \end_layout
159
160 \begin_layout Itemize
161 All identifers and values are strings in UTF-8 encoding.
162 \end_layout
163
164 \begin_layout Itemize
165 A period/full stop is used to separate the digits in a float value from
166  the fractional part of the float.
167  All float values must include a period/full stop (1 is not acceptable;
168  1.0 is correct).
169 \end_layout
170
171 \begin_layout Itemize
172 Float values should be limited to six decimal places.
173 \end_layout
174
175 \begin_layout Itemize
176 Any spaces in identifiers should be represented using underscores ( _ )
177  instead, although this can be converted to spaces for display to the user.
178 \end_layout
179
180 \begin_layout Standard
181 The following sections describe where the information should be stored in
182  specific tag formats.
183 \end_layout
184
185 \begin_layout Subsubsection
186 MP3
187 \end_layout
188
189 \begin_layout Standard
190 MP3 values should be stored in a TXXX frame with the Description set to
191  the specified identifier and the Text set to the string representation
192  of the value.
193  The Description should be in CamelCase as specified in the following sections,
194  e.g.
195  FMPS_Rating.
196 \end_layout
197
198 \begin_layout Subsubsection
199 VorbisComments
200 \end_layout
201
202 \begin_layout Standard
203 Any file supporting VorbisComments (Vorbis, FLAC, Theora, Speex) should
204  add a comment with the Key set to the specified identifier and the Value
205  set to the string representation of the value.
206  The Key should be in all upper-case, e.g.
207  FMPS_RATING.
208 \end_layout
209
210 \begin_layout Subsubsection
211 APEv2
212 \end_layout
213
214 \begin_layout Standard
215 Any file supporting APEv2 should add a comment with the Key set to the specified
216  identifier and the Value set to the string representation of the value.
217  The Key should be in all upper-case, e.g.
218  FMPS_RATING.
219 \end_layout
220
221 \begin_layout Subsubsection
222 MP4
223 \end_layout
224
225 \begin_layout Standard
226 MP4 values should be stored at ----:com.apple.iTunes:Identifier with the value
227  a string representation of the tag's value.
228  The Identifier should be in CamelCase as specified in the following sections,
229  e.g.
230  FMPS_Rating.
231 \end_layout
232
233 \begin_layout Subsubsection
234 Windows Media
235 \end_layout
236
237 \begin_layout Standard
238 Windows Media values should be stored in the FMPS/Identifier namespace with
239  the value a string representation of the tag's value.
240  The Identifier should be in CamelCase as specified in the following sections,
241  e.g.
242  FMPS_Rating.
243 \end_layout
244
245 \begin_layout Subsection
246 Song Rating Tags
247 \end_layout
248
249 \begin_layout Standard
250 Most media players support the notion of rating content, however standards
251  for storing ratings in files do not exist.
252  Some file metadata formats completely lack rating fields; others require
253  personal information to be used as an identifier (such as a user's email
254  address) or an organizational identifier (which reduces cross-player compatibil
255 ity).
256  The goal therefore is simple: to avoid any personal identifying information
257  but avoid tying the rating to a specific player.
258 \end_layout
259
260 \begin_layout Standard
261 Three types of ratings are currently defined: user ratings, critic ratings,
262  and automatic (or algorithmic) ratings.
263 \end_layout
264
265 \begin_layout Standard
266 Although users are more naturally able to understand integer ratings, only
267  advanced users will interact with these tags directly; otherwise they will
268  be presented to the user via a conforming application.
269  Meanwhile, there are tangible benefits to storing ratings as floating-point
270  numbers, mainly due to the fact that the increased precision allows for
271  a number of interesting and useful algorithmic rating schemes to be used.
272  However, using both integer and floating-point values unnecessarily increases
273  complexity of both this spec and application code.
274  Therefore, both values are stored as floating-point numbers.
275  Conversion to and from these and an integer scale presented to the user
276  in an application is easily accomplished in the application's code if it
277  is so desired.
278 \end_layout
279
280 \begin_layout Standard
281 If a combination of rating tags exist when a file is being imported or read
282  into a player's library, the user rating is considered canonical and takes
283  precedence, meaning that if only a single value is being shown to the user
284  it should be the user-defined value.
285 \end_layout
286
287 \begin_layout Standard
288 For all tag formats, the following is defined:
289 \end_layout
290
291 \begin_layout Itemize
292 A file that has no such tag is to be considered unrated for that purpose
293  (user or algorithm).
294 \end_layout
295
296 \begin_layout Itemize
297 If a user removes ratings from a track in the media player, the user rating
298  tag should be removed as well.
299  The algorithmic rating tag does not have to be removed in this instance.
300 \end_layout
301
302 \begin_layout Itemize
303 The identifier for the (canonical) user rating is 
304 \begin_inset Quotes eld
305 \end_inset
306
307 FMPS_Rating
308 \begin_inset Quotes erd
309 \end_inset
310
311 .
312 \end_layout
313
314 \begin_layout Itemize
315 The identifier for critic ratings is 
316 \begin_inset Quotes eld
317 \end_inset
318
319 FMPS_Rating_Critic_Identifier
320 \begin_inset Quotes erd
321 \end_inset
322
323  where Identifier names either a publication/site (
324 \begin_inset Quotes eld
325 \end_inset
326
327 Rolling_Stone
328 \begin_inset Quotes erd
329 \end_inset
330
331
332 \begin_inset Quotes eld
333 \end_inset
334
335 Metacritic
336 \begin_inset Quotes erd
337 \end_inset
338
339 ) or a person in Firstname=Lastname format (
340 \begin_inset Quotes eld
341 \end_inset
342
343 Ralph=Gleason
344 \begin_inset Quotes erd
345 \end_inset
346
347 ).
348 \end_layout
349
350 \begin_layout Itemize
351 The identifier for the algorithmic rating is 
352 \begin_inset Quotes eld
353 \end_inset
354
355 FMPS_Rating_Algorithm_Identifier
356 \begin_inset Quotes erd
357 \end_inset
358
359  where Identifier names an arbitrary algorithm name.
360 \end_layout
361
362 \begin_layout Itemize
363 Ratings are a float value between 0.0 and 1.0, inclusive.
364  0.0 is the lowest possible rating; 1.0 is the highest possible rating.
365 \end_layout
366
367 \begin_layout Itemize
368 Ratings should only be rounded when necessary, in order to increase cross-player
369  compatibility.
370 \end_layout
371
372 \begin_layout Standard
373 A note on that last point: some players may only allow users to rate in
374  increments of whole numbers between 1 and 5; others 0 and 10; and so on.
375  However, players should try to ensure that the rating they display and
376  use for any purposes adheres to that saved in the tag when possible.
377  For instance, if a track has a rating of 0.9 and an application only shows
378  ratings using five star icons in full-star increments, this would be rounded
379  within the application to five stars.
380  However, the user may in fact have set the rating to 9/10 in another applicatio
381 n.
382  If the rating was being shown numerically, ideally the application would
383  only round this number when absolutely necessary and display 4.5 instead
384  of 5, which would more accurately reflect the user's set rating.
385 \end_layout
386
387 \begin_layout Subsection
388 Playcount Tags
389 \end_layout
390
391 \begin_layout Standard
392 As with ratings, there are both user and automatic playcount tags.
393  The user tag is canonical and intended to be used in the normal sense,
394  tracking how many times a song has been played (as defined below).
395  The auto/algorithmic value can be used in an application-specific way to
396  do interesting things; for instance, to cumulatively track exact percentages
397  of tracks played, in order to display to the user the number of days/hous/minut
398 es/seconds they have spent listening to a particular song.
399  
400 \end_layout
401
402 \begin_layout Standard
403 As with ratings, if both tags exist when a file is being imported or read
404  into a player's library, the user playcount takes precedence for display.
405 \end_layout
406
407 \begin_layout Standard
408 For all tag formats, the following is defined:
409 \end_layout
410
411 \begin_layout Itemize
412 A file that has no such tag is to be considered unplayed for that purpose
413  (user or algorithm).
414  Removing playcount information from a track in the media player should
415  cause the user playcount tag to be removed as well.
416  The algorithmic playcount tag does not have to be removed in this instance.
417 \end_layout
418
419 \begin_layout Itemize
420 The identifier for the (canonical) user playcount is 
421 \begin_inset Quotes eld
422 \end_inset
423
424 FMPS_Playcount
425 \begin_inset Quotes erd
426 \end_inset
427
428 .
429 \end_layout
430
431 \begin_layout Itemize
432 The identifier for an algorithmic rating is 
433 \begin_inset Quotes eld
434 \end_inset
435
436 FMPS_Playcount_Algorithm_Identifier
437 \begin_inset Quotes erd
438 \end_inset
439
440  where Identifier names an arbitrary algorithm name.
441 \end_layout
442
443 \begin_layout Itemize
444 Playcounts are a float value with a minimum of 0.0, where 0.0 is an acceptable
445  value but indicates that a track has not been played (the same as if the
446  track had no playcount tag).
447  Playcounts (especially the user playcount) can be shown the user as integers
448  but must always be stored as a float.
449 \end_layout
450
451 \begin_layout Itemize
452 For the user playcount, playing a track (subject to the criteria below)
453  increases the user playcount value by 1.0.
454  For the algorithmic playcount, a track's length should be considered to
455  be worth 1.0; the user skipping parts of the track may decrease the value
456  below 1.0, and the user repeating parts of the track may increase this value
457  past 1.0.
458 \end_layout
459
460 \begin_layout Itemize
461 The maximum value is 0.000001 less than the largest value able to be stored
462  in a 32-bit unsigned integer: 4,294,967,294.999999.
463  This is so that the float playcount value can be rounded to an integer
464  equivalent, if necessary.
465 \end_layout
466
467 \begin_layout Standard
468 The user playcount isn't meant to be set by the user, but rather to follow
469  these rules that define user behavior.
470  A file is to be considered 
471 \begin_inset Quotes eld
472 \end_inset
473
474 played
475 \begin_inset Quotes erd
476 \end_inset
477
478  if it meets the following criteria, inspired by Last.fm's scrobbling rules:
479 \end_layout
480
481 \begin_layout Itemize
482 If the track is less than 30 seconds long, the entire song must be played.
483 \end_layout
484
485 \begin_layout Itemize
486 If the track is more than 30 seconds long, at least fifty percent of the
487  file must be played, calculated via length of track.
488  For instance, if a track is one minute long, at least thirty seconds of
489  the track must have been played, although if the user skips backwards multiple
490  times and listens to the same ten seconds of the track three times in a
491  row, this may be considered a valid playcount.
492 \end_layout
493
494 \begin_layout Subsection
495 Performer Roles
496 \end_layout
497
498 \begin_layout Standard
499 Performer roles allow you to describe the performers in a track.
500  Current support for these roles in tag formats is sporadic or difficult
501  to parse.
502  As many of these tags as desired can be specified, to include all relevant
503  performer information.
504 \end_layout
505
506 \begin_layout Standard
507 For all tag formats, the following is defined:
508 \end_layout
509
510 \begin_layout Itemize
511 The identifier used is 
512 \begin_inset Quotes eld
513 \end_inset
514
515 FMPS_Performer:X
516 \begin_inset Quotes erd
517 \end_inset
518
519 , where X is the user-defined role (
520 \begin_inset Quotes eld
521 \end_inset
522
523 Guitar
524 \begin_inset Quotes erd
525 \end_inset
526
527
528 \begin_inset Quotes eld
529 \end_inset
530
531 Guitar (Backup)
532 \begin_inset Quotes erd
533 \end_inset
534
535
536 \begin_inset Quotes eld
537 \end_inset
538
539 Vocals
540 \begin_inset Quotes erd
541 \end_inset
542
543 ).
544 \end_layout
545
546 \begin_layout Itemize
547 The value of each identifier is the role performer's name.
548 \end_layout
549
550 \begin_layout Section
551 Filesystem Directives
552 \end_layout
553
554 \begin_layout Standard
555 Common functionality for many media players is the notion of a library or
556  collection as a store of media objects that can be played.
557  Generally, users specify or drag-n-drop directories or files that they
558  wish to have added to this store.
559  These subsections contain files that can be present on a user's filesystem
560  to allow for more fine-grained control over import.
561 \end_layout
562
563 \begin_layout Subsection
564 Ignore Directive
565 \end_layout
566
567 \begin_layout Standard
568 When a directory is being parsed, it should first be checked for a file
569  with the name 
570 \begin_inset Quotes eld
571 \end_inset
572
573 fmps_ignore
574 \begin_inset Quotes erd
575 \end_inset
576
577 .
578  If present, the parser should ignore that directory's files.
579 \end_layout
580
581 \end_body
582 \end_document