summaryrefslogtreecommitdiffstats
path: root/manual/appendix/file_formats.tex
blob: 4d64cf6bc6ffad210146e57cb0e486f247db1006 (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
% $Id$ %
\chapter{File formats}
\section{\label{ref:Supportedfileformats}Supported file formats}
\begin{rbtabular}{\textwidth}{cl>{\raggedright}p{7em}X}%
{\textbf{Icon} & \textbf{File Type} & \textbf{Extension} 
  & \textbf{Action when selected}}{}{}
\includegraphics[width=0.37cm]{appendix/images/icon-directory.png} 
  & Directory & \emph{none} & Enter the directory \tabularnewline
  \includegraphics[width=0.37cm]{appendix/images/icon-audio-file.png} 
  & Audio file & \emph{various}\newline%
  (see \ref{ref:Supportedaudioformats})%
  % do NOT use \reference{} here as that will break the table.
  & Start playing the file and show the WPS\tabularnewline
  & Bookmark & \fname{.bmark} & Display all bookmarks for an audio file\tabularnewline
  & Game of Life & \fname{.cells} & Show the configuration with the
     ``Rocklife'' plugin\tabularnewline
\includegraphics[width=0.37cm]{appendix/images/icon-config.png} 
  & Configuration File & \fname{.cfg} & Load the settings file\tabularnewline
\includegraphics[width=0.37cm]{appendix/images/icon-chip8.png} 
  & Chip8 game & \fname{.ch8} & Play the Chip8 game \tabularnewline
\opt{lcd_color}{
  & Colours & \fname{.colours} & Open the colours file for editing.
    See \reference{ref:ChangingFiletypeColours}.\tabularnewline
}
\includegraphics[width=0.37cm]{appendix/images/icon-cuesheet.png} 
  & Cuesheet & \fname{.cue} & View the cuesheet file \tabularnewline
\opt{radio}{
  & FM Presets & \fname{.fmr} & Load the FM Presets (previous are discarded)\tabularnewline
}
\includegraphics[width=0.37cm]{appendix/images/icon-font.png} 
  & Font & \fname{.fnt} & Change the user interface font to this one\tabularnewline
\opt{gigabeat}{
  \includegraphics[width=0.37cm]{appendix/images/icon-rolo.png} 
  & Rockbox firmware & \fname{.gigabeat} & Load the new firmware with ROLO \tabularnewline
}
\opt{iaudio}{
  \includegraphics[width=0.37cm]{appendix/images/icon-rolo.png} 
  & Rockbox firmware & \fname{.iaudio} & Load the new firmware with ROLO \tabularnewline
}
\opt{ipod}{
  \includegraphics[width=0.37cm]{appendix/images/icon-rolo.png} 
  & Rockbox firmware & \fname{.ipod} & Load the new firmware with ROLO \tabularnewline
}
\opt{iriverh100,iriverh300}{
  \includegraphics[width=0.37cm]{appendix/images/icon-rolo.png} 
  & Rockbox firmware & \fname{.iriver} & Load the new firmware with ROLO \tabularnewline
}
\includegraphics[width=0.37cm]{appendix/images/icon-image-file.png} 
  & Image & \fname{.jpg} & View the JPEG image \tabularnewline
  & Link & \fname{.link} & Display list of target files and directories;
    selecting one jumps to the target. See \reference{ref:Shortcutsplugin}.\tabularnewline
\includegraphics[width=0.37cm]{appendix/images/icon-lang.png} 
  & Language File & \fname{.lng} & Load the language file \tabularnewline
\includegraphics[width=0.37cm]{appendix/images/icon-playlist.png}
  & Playlist & \fname{.m3u}, \fname{.m3u8} & Load the playlist and start playing 
    the first file \tabularnewline
\opt{iriverh10,iriverh10_5gb,sansa,mrobe100,vibe500,samsungyh}{
  \includegraphics[width=0.37cm]{appendix/images/icon-rolo.png} 
  & Rockbox firmware & \fname{.mi4} & Load the new firmware with ROLO \tabularnewline
}
 \includegraphics[width=0.37cm]{appendix/images/icon-movie-file.png}
 & Video & \fname{.mpg}, \fname{.mpeg}, \fname{.mpv}, \fname{.m2v} & Play the MPEG1/2 video \tabularnewline
\includegraphics[width=0.37cm]{appendix/images/icon-rock.png} 
  & Plugin & \fname{.rock} & Start the plugin\tabularnewline
\opt{sansaAMS}{
  \includegraphics[width=0.37cm]{appendix/images/icon-rolo.png} 
  & Rockbox firmware & \fname{.sansa} & Load the new firmware with ROLO \tabularnewline
}
\includegraphics[width=0.37cm]{appendix/images/icon-text.png} 
  & Text File & \fname{.txt} & Display the text file using the text viewer plugin\tabularnewline
  & Voice file & \fname{.voice} & Allow Rockbox to speak menus\tabularnewline
\includegraphics[width=0.37cm]{appendix/images/icon-wps.png} 
  & While Playing Screen & \fname{.wps} & Load the new WPS display configuration\tabularnewline
\end{rbtabular}

  \chapter{Audio and metadata formats}
  \section{\label{ref:Supportedaudioformats}Supported audio formats}
  \subsection{Lossy Codecs}
  \begin{rbtabular}{\textwidth}{l>{\raggedright}p{6em}X}%
  {\textbf{Format} & \textbf{Extension} & \textbf{Notes}}{}{}
    ATSC A/52 (AC3)
        & \fname{.a52}, \fname{.ac3}, \fname{.rm}, \fname{.ra}, \fname{.rmvb}
        & Supports downmixing for playback of 5.1 streams in stereo\\
    ADX
        & \fname{.adx} 
        & Encrypted ADX is not supported.\\
    Advanced Audio Coding
        & \fname{.m4a}, \fname{.m4b}, \fname{.mp4}, \fname{.rm}, \fname{.ra}, \fname{.rmvb}
        \nopt{clipv1,c200v2}{
            & Supports AAC-LC, -HEv1, and -HEv2 profiles\\}
        \opt{clipv1,c200v2}{ % low memory targets (CODEC_SIZE <= 512 KB)
            & Supports AAC-LC profile\\}
    MPEG audio
        & \fname{.mpa}, \fname{.mp1}, \fname{.mp2}, \fname{.mp3} 
        & MPEG 1/2/2.5 Layer 1/2/3\\
    Musepack
        & \fname{.mpc} 
        & Supports SV7 and SV8 in mono/stereo \\
    OGG/Vorbis
        & \fname{.ogg}, \fname{.oga} 
        & Playback of some old ``floor 0'' files may fail on low memory targets.
          Files with album art larger than available RAM will be skipped. 
          Chained Ogg files are not supported.\\
    Sony Audio
        & \fname{.oma}, \fname{.aa3}, \fname{.rm}, \fname{.ra}, \fname{.rmvb}
        & Supports ATRAC3\\
    RealAudio
        & \fname{.rm}, \fname{.ra}, \fname{.rmvb}
        & Supports RealAudio G2 (Cook)\\
    Speex
        & \fname{.spx} 
        & \\
    Dialogic telephony type
        & \fname{.vox} 
        & \\
    Windows Media Audio Standard
        & \fname{.wma}, \fname{.wmv}, \fname{.asf} 
        & \\
    Windows Media Audio Professional
        & \fname{.wma}, \fname{.wmv}, \fname{.asf} 
        & \\
  \end{rbtabular}
  
  \note{AAC-HE profiles might not play in realtime on all devices due to CPU 
  performance requirements.}

  \subsection{Lossless Codecs}
  \begin{rbtabular}{\textwidth}{lp{6em}X}%
  {\textbf{Format} & \textbf{Extension} & \textbf{Notes}}{}{}
    Audio Interchange File Format
        & \fname{.aif}, \fname{.aiff} 
        & Linear PCM 8/16/24/32 bit, IEEE float 32/64 bit, ITU-T G.711 a-law/$\mu$-law,
          QuickTime IMA ADPCM\\
    Monkey's Audio
        & \fname{.ape}, \fname{.mac} 
        & 
        \opt{gigabeatf,iriverh100,iriverh300,iaudiox5,iaudiom5,iaudiom3,ipodnano2g,clipv1}{
            -c1000 to -c3000 files decode fast enough to be useful.}
        \opt{gigabeats}{}
        \opt{ipod,iriverh10,iriverh10_5gb,mrobe100,sansa,vibe500,samsungyh}{
            \nopt{ipodnano2g}{Only -c1000 files decode fast enough to be useful.}}
            \\
    Sun Audio
        & \fname{.au}, \fname{.snd} 
        & Linear PCM 8/16/24/32 bit, IEEE float 32/64 bit, ITU-T G.711 a-law/$\mu$-law\\
    Free Lossless Audio
        & \fname{.flac} 
        & Supports multichannel playback including downmixing to stereo.\\
    Apple Lossless
        & \fname{.m4a}, \fname{.mp4} 
        & \\
    Shorten
        & \fname{.shn} 
        & Seeking not supported.\\
    True Audio
        & \fname{.tta} 
        & \\
    Wave64
        & \fname{.w64} 
        & Supports same formats as Waveform audio format.\\
    Waveform audio format
        & \fname{.wav} 
        & Linear PCM 8/16/24/32 bit, IEEE float 32/64 bit, ITU-T G.711 a-law/$\mu$-law,
          Microsoft ADPCM, Intel DVI ADPCM (IMA ADPCM) 2/3/4/5 bit, Dialogic OKI ADPCM,
          YAMAHA ADPCM, Adobe SWF ADPCM\\
    Wavpack
        & \fname{.wv} 
        & \\
  \end{rbtabular}
  
  \note{Free Lossless Audio multichannel tracks may not play in realtime on all devices due to CPU 
  performance requirements.}

  \subsection{Other Codecs}
  \begin{rbtabular}{\textwidth}{l>{\raggedright}p{6em}X}%
  {\textbf{Format} & \textbf{Extension} & \textbf{Notes}}{}{}
    Atari Sound Format
        & \fname{.cmc}, \fname{.cm3}, \fname{.cmr}, \fname{.cms}, \fname{.dmc}, 
          \fname{.dlt}, \fname{.mpt}, \fname{.mpd} 
        & \\
    Synthetic music Mobile Application Format
        & \fname{.mmf} 
        & PCM/ADPCM only \\
    Game Boy Sound Format
        & \fname{.gbs}
        & Progress bar and seek use subtracks instead of seconds.\\
    AY Sound Chip Music
        & \fname{.ay}
        & Progress bar and seek use subtracks instead of seconds for
          multitrack files.\\
    Hudson Entertainment System Sound Format
        & \fname{.hes}
        & Progress bar and seek use subtracks instead of seconds.\\
    \nopt{clipv1,c200v2}{
    MSX Konami Sound System
        & \fname{.kss}
        & Progress bar and seek use subtracks instead of seconds.\\}
    SMS/GG/CV Sound Format
        & \fname{.sgc}
        & Supports Sega Master System and Game Gear Sound Format. 
          Progress bar and seek use subtracks instead of seconds.\\
    Video Game Music Format
        & \fname{.vgm}
        & \\
    Gzipped Video Game Music Format
        & \fname{.vgz}
        & \\
    MOD
        & \fname{.mod} 
        & \\
    NES Sound Format
        & \fname{.nsf}, \fname{.nsfe} 
        & Progress bar and seek use subtracks instead of seconds.\\
    Atari SAP
        & \fname{.sap} 
        & \\
    Sound Interface Device
        & \fname{.sid} 
        & Progress bar and seek use subtracks instead of seconds.\\
    SPC700
        & \fname{.spc} 
        & \\
  \end{rbtabular}
  
  \note{NSF and VGM might not play in realtime on all devices due to CPU 
  performance requirements.}
  
  \subsection{Codec featureset}
  \begin{rbtabular}{.95\textwidth}{lXXX}%
  {\textbf{Format} & \textbf{Seek} & \textbf{Resume} & \textbf{Gapless}}{}{}
    ATSC A/52 (AC3)                             & x & x &   \\
    ADX                                         & x &   &   \\
    Advanced Audio Coding                       & x & x & x \\
    MPEG audio                                  & x & x & x \\
    Musepack                                    & x & x & x \\
    OGG/Vorbis                                  & x & x & x \\
    Sony Audio                                  & x & x &   \\
    RealAudio                                   & x & x &   \\
    Dialogic telephony type                     & x & x &   \\
    Windows Media Audio Standard                & x & x &   \\
    Windows Media Audio Professional            & x & x &   \\
    Audio Interchange File Format               & x & x & x \\
    Monkey's Audio                              & x & x & x \\
    Sun Audio                                   & x & x & x \\
    Free Lossless Audio                         & x & x & x \\
    Apple Lossless                              & x & x & x \\
    Shorten                                     &   &   & x \\
    True Audio                                  & x & x & x \\
    Wave64                                      & x & x & x \\
    Waveform audio format                       & x & x & x \\
    Wavpack                                     & x & x & x \\
    Atari Sound Format                          & x &   &   \\
    Synthetic music Mobile Application Format   & x & x &   \\
    Game Boy Sound Format                       & x &   &   \\
    AY Sound Chip Music                         & x &   &   \\
    Hudson Entertainment System Sound Format    & x &   &   \\
    MSX Konami Sound System                     & x &   &   \\
    SMS/GG/CV Sound Format                      & x &   &   \\
    Video Game Music Format                     & x & x &   \\
    Gzipped Video Game Music Format             & x & x &   \\
    MOD                                         & x &   &   \\
    NES Sound Format                            & x &   &   \\
    Atari SAP                                   & x &   &   \\
    Sound Interface Device                      & x &   &   \\
    SPC700                                      & x &   &   \\
  \end{rbtabular}
  
  \note{The seek implementations of NES Sound Format, Sound Interface Device,
  Game Boy Sound Format, AY Sound Chip Music, Hudson Entertainment System Sound,
  Format, MSX Konami Sound System and SMS/GG/CV Sound Format use subtracks
  instead of seconds, whereas each subtrack equals a second.}
  
  \section{\label{ref:SupportedMetadata}Supported metadata tags}
    Rockbox supports different metadata formats. In general those tag formats
    are ID3 (v1.0, v1.1, v2.2, v2.3 and v2.4), APE (v1 and v2), Vorbis, MP4 and 
    ASF. Few codecs use codec specific tags, several codecs do not use any tags 
    yet. The following table gives an overview about what tag types rockbox 
    supports for which audio file extension.
    
    \note{There is always only \emph{one} tag type supported for each file
    extension.}
    
    \begin{rbtabular}{\textwidth}{lX}%
    {\textbf{Tag type} & \textbf{File extension}}{}{}
      ID3               & \fname{.mp1}, \fname{.mpa}, \fname{.mp2}, \fname{.mp3},
                          \fname{.rm}, \fname{.ra}, \fname{.rmvb}, \fname{.tta} \\
      APE               & \fname{.mpc}, \fname{.ape}, \fname{.mac}, \fname{.wv} \\
      Vorbis            & \fname{.ogg}, \fname{.oga}, \fname{.spx}, \fname{.flac} \\
      MP4               & \fname{.m4a}, \fname{.m4b}, \fname{.mp4} \\
      ASF               & \fname{.wma}, \fname{.wmv}, \fname{.asf} \\
      Codec specific    & \fname{.mmf}, \fname{.mod}, \fname{.nsf}, \fname{.nsfe},
                          \fname{.sap}, \fname{.sid}, \fname{.spc}, \fname{.gbs},
                          \fname{.ay}, \fname{.kss}, \fname{.sgc}, \fname{.vgm} \\
      None              & \fname{.a52}, \fname{.ac3}, \fname{.adx}, \fname{.oma},
                          \fname{.aa3}, \fname{.aif}, \fname{.aiff}, \fname{.au},
                          \fname{.snd}, \fname{.shn}, \fname{.vox}, \fname{.w64},
                          \fname{.wav}, \fname{.cmc}, \fname{.cm3}, \fname{.cmr},
                          \fname{.cms}, \fname{.dmc}, \fname{.dlt}, \fname{.mpt},
                          \fname{.mpd}, \fname{.hes}, \fname{.vgz} \\
    \end{rbtabular}
    
    \subsection{Featureset for generic metadata tags}
    \label{ref:featureset_for_generic_metadata_tags}
    \begin{rbtabular}{0.90\textwidth}{lXXXXX}%
    {\textbf{Feature} & \textbf{ID3} & \textbf{APE} & \textbf{Vorbis} & 
     \textbf{MP4} & \textbf{ASF}}{}{}
     Embedded albumart \fname{.bmp}     &   & x &   &   &   \\
     Embedded albumart \fname{.jpg}     & x & x &   & x & x \\
     Embedded albumart \fname{.png}     &   & x &   &   &   \\
     Embedded cuesheet                  & x & x & x &   &   \\
     Replaygain information             & x & x & x & x & x \\
     Title (string)                     & x & x & x & x & x \\
     Artist (string)                    & x & x & x & x & x \\
     Album (string)                     & x & x & x & x & x \\
     Genre (string)                     & x & x & x & x & x \\
     Disc (string or number)            & x & x & x & x &   \\
     Track (string or number)           & x & x & x & x & x \\
     Year (string or number)            & x & x & x & x & x \\
     Composer (string)                  &   & x & x & x & x \\
     Comment (string)                   & x & x & x & x & x \\
     Albumartist (string)               & x & x & x & x & x \\
     Grouping (string)                  &   & x & x & x &   \\
    \end{rbtabular}
    
    \note{Embedded album art for ASF is limited to pictures of maximum 64 KB size.}
    
    \subsection{Featureset for codec specific metadata}
    \begin{rbtabular}{\textwidth}{lX}%
    {\textbf{Feature} & \textbf{Codec specific metadata (file extension)}}{}{}
     Embedded \fname{.bmp}  & None \\
     Embedded \fname{.jpg}  & None \\
     Embedded \fname{.png}  & None \\
     Replaygain             & \fname{.mpc}\\
     Title                  & \fname{.tta}, \fname{.spc}, \fname{.mmf}, \fname{.sid}, 
                              \fname{.rm}, \fname{.ra}, \fname{.rmvb}, \fname{.nsf}, 
                              \fname{.nsfe}, \fname{.mod}, \fname{.sap}, \fname{.gbs},
                              \fname{.ay}, \fname{.sgc}, \fname{.vgm} \\
     Artist                 & \fname{.tta}, \fname{.spc}, \fname{.mmf}, \fname{.sid}, 
                              \fname{.rm}, \fname{.ra}, \fname{.rmvb}, \fname{.nsf}, 
                              \fname{.nsfe}, \fname{.sap}, \fname{.gbs}, \fname{.ay},
                              \fname{.sgc}, \fname{.vgm} \\
     Album                  & \fname{.spc}, \fname{.sid}, \fname{.nsf}, \fname{.nsfe},
                              \fname{.gbs}, \fname{.ay}, \fname{.sgc}, \fname{.vgm} \\
     Genre                  & \fname{.tta}, \fname{.spc}, \fname{.sap} \\
     Disc                   & \fname{.tta} \\
     Track                  & \fname{.tta} \\
     Year                   & \fname{.spc}, \fname{.sid}, \fname{.sap} \\
     Composer               & \fname{.mmf} \\
     Comment                & \fname{.spc}, \fname{.rm}, \fname{.ra}, \fname{.rmvb},
                              \fname{.vgm} \\
     Albumartist            & None \\
     Grouping               & None \\
    \end{rbtabular}
    
    \subsection{Limitations of metadata handling}
    \begin{enumerate}
        \item Multiple tags (e.g. for Genre) are not supported. The first tag 
              item of a set of multiple tags is used.
        \item Only one tag type is supported for each audio format.
    \nopt{clipv1,c200v2}{
        \item Overall there are 900 bytes available to load metadata strings.
        \item The maximum size of each metadata item (e.g. Artists) is limited 
              to 240 bytes.
    }
    \opt{clipv1,c200v2}{
        \item Overall there are 300 bytes available to load metadata strings.
        \item The maximum size of each metadata item (e.g. Artists) is limited 
              to 90 bytes.
    }
    \end{enumerate}