Menu
▾
▴
[beepmp-cvs] bmpx/docs Makefile.am,NONE,1.1 config-file-format.html,NONE,1.1 media-library-format.html,NONE,1.1
|
From: Milosz D. <mde...@us...> - 2005-09-10 05:21:25
|
Update of /cvsroot/beepmp/bmpx/docs In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv26410/docs Added Files: Makefile.am config-file-format.html media-library-format.html Log Message: New directories docs/ and dbus-examples/ --- NEW FILE: config-file-format.html --- <html> <head> <title>BMP XML Configuration File Format Documentation</title> <style type="text/css"/> tt { color: #101090; padding: 4px;} body { text-align: justify; margin-right: 2em; font-size: 10pt;} li { margin-bottom: 1em; } #example { margin-left: 6em; background-color: #e0e0e0; padding: 2em; border: 1px solid black;} .underline { text-decoration: none; font-weight: bold; color: #4040f0;} .domain { margin-left: 6em; } .key-name { font-family: monospace; color: blue; } .typename { color: green; font-weight: bold;} </style> </head> <body> <h1>BMP XML Configuration File</h1> <div id="header"> <p>BMP now uses an XML format to store it's session-persistent configuration settings. This document describes the format and explains the possible/settable values.</p> </div> <div> The configuration file is <span class="underline">domain/key based</span>. This means there are 'domains' which are contained inside the element <tt><domain/></tt> of which you can think as of 'sets', e.g. one 'set' (for example) for the playlist window, one set for the main window, one set with global settings, etc. Each <tt><domain/></tt> element holds an <tt>id</tt> attribute which specifies the <span class="underline">unique domain identifer</span>. <p>Each of the domains contains any number of keys, which are held inside a <tt><key/></tt> element, which has an <tt>id</tt> attribute that specifies the key id. <span class="underline">The key id has to be unique per-domain, but not inter-domain unique.</span> A key also has a <tt>type</tt> attribute which specifies it's value type. The type can be one of <tt>string</tt>, <tt>integer</tt> or <tt>boolean</tt>. For booleans, a value of either 'TRUE' or '1' means true, any other value means false. Unlike the <tt><domain/></tt> element, the <tt><key/></tt> element also holds a text node child which is the <span class="underline">key value</span>. <p> To illustrate everything better, here is a complete exemplary configuration file: <p> <div id="example"> <tt> <?xml version="1.0"?><br/> <bmp version="0.7"><br/><br/> <domain id="bmp"><br/> <key id="playlists-path" type="string">/home/user/.bmp/playlists</key><br/> <key id="skin" type="string">/home/user/share/bmpx/skins/default</key><br/> <key id="titlestring-format" type="string">%p: %t</key><br/> <key id="volume" type="integer">0</key><br/> </domain><br/><br/> <domain id="playlist-window"><br/> <key id="vsep-width" type="integer">250</key><br/> <key id="font" type="string">Bitstream Vera Sans 9</key><br/> <key id="pos_x" type="integer">251</key><br/> <key id="pos_y" type="integer">148</key><br/> <key id="width" type="integer">550</key><br/> <key id="height" type="integer">464</key><br/> <key id="visible" type="boolean">TRUE</key><br/> <key id="current-playlist" type="string">Bossa_Nova_2001</key><br/> </domain><br/><br/> <domain id="main-window"><br/> <key id="pos_x" type="integer">801</key><br/> <key id="pos_y" type="integer">148</key><br/> </domain><br/><br/> </bmp> </tt> </div> <p> First of all, we have the root node, <tt><bmp></tt>, which also holds the version information of the bmp version that saved this configuration file (note that 0.7 currently refers to the BMPx codebase version, not the mainline BMP which is at 0.9.7.1 in CVS). This root node contains the domains with their keys. <p> This example configuration file shows also all domains/keys currently respected by BMP (BMPx). Following a listing of all domains and keys with explanations. <p> <div> <div class="domain"> <h3>Domain: 'bmp'</h3> <ul> <li><span class="key-name"><span class="typename">string:</span> playlists-path</span><br/> Specifies the path where BMP is saving the playlists at exit. This can be any local path (not URI, currently), e..g $HOME/Desktop/Playlists (although you presently can't use $HOME in the specification, you have to use a fully qualified path). At the moment this cannot be changed trough the GUI so make sure you also actually move your playlists when you change the path. </li> <li><span class="key-name"><span class="typename">string:</span> skin</span><br/> Specifies the fully qualified local path to the currently used skin file or directory (not URI).<br/>Changeable from the GUI (Preferences section 'Appearance') (Actually you choose the skin trough a list, but what gets stored is the respective's skin file path.) </li> <li><span class="key-name"><span class="typename">string:</span> titlestring-format</span><br/> The titlestring format which specifies how metadata is displayed in the track list.<br/>Changeable from the GUI (Preferences section 'Playlist'). </li> <li><span class="key-name"><span class="typename">integer:</span> volume</span><br/> The saved volume at exit. Integer value, range 0-100. </li> <li><span class="key-name"><span class="typename">string:</span> file-chooser-path</span><br/> The path at which the file selector was the last time it was opened. </li> </ul> </div> <div class="domain"> <h3>Domain: 'playlist-window'</h3> <ul> <li><span class="key-name"><span class="typename">integer:</span> vsep-width</span><br/> Specifies the width of the right-side of the playlist pane. Do not change this value manually, the results could be unexpected. </li> <li><span class="key-name"><span class="typename">string:</span> font</span><br/> Specifies the font used in the playlist window.<br/>Changeable from the GUI (Preferences section 'Appearance'). </li> <li><span class="key-name"><span class="typename">integer:</span> pos_x</span><br/> Saved x-position of the playlist window.<br/>Don't change it manually unless needed (error condition or other). </li> <li><span class="key-name"><span class="typename">integer:</span> pos_y</span><br/> Saved y-position of the playlist window.<br/>Don't change it manually unless needed (error condition or other). </li> <li><span class="key-name"><span class="typename">integer:</span> width</span><br/> Saved width of the playlist window.<br/>Don't change it manually unless needed (error condition or other). </li> <li><span class="key-name"><span class="typename">integer:</span> height</span><br/> Saved height of the playlist window.<br/>Don't change it manually unless needed (error condition or other). </li> <li><span class="key-name"><span class="typename">boolean:</span> visible</span><br/> Indicates whether the playlist window should be initially shown after startup. </li> <li><span class="key-name"><span class="typename">string:</span> current-playlist</span><br/> The currently selected playlist name as file basename without extension. </li> </ul> </div> <div class="domain"> <h3>Domain: 'main-window'</h3> <ul> <li><span class="key-name"><span class="typename">integer:</span> pos_x</span><br/> Saved x-position of the main window.<br/>Don't change it manually unless needed (error condition or other). </li> <li><span class="key-name"><span class="typename">integer:</span> pos_y</span><br/> Saved y-position of the main window.<br/>Don't change it manually unless needed (error condition or other). </li> </ul> </div> </div> </body> </html> --- NEW FILE: Makefile.am --- EXTRA_DIST= HTML_FILES= \ config-file-format.html \ media-library-format.html all-local: $(HTML_FILES) EXTRA_DIST += $(HTML_FILES) --- NEW FILE: media-library-format.html --- <html> <head> <title>BMP Media Cache Format Documentation</title> <style type="text/css"/> .underline { text-decoration: none; font-weight: bold; color: #4040f0;} .domain { margin-left: 6em; } .key-name { font-family: monospace; color: blue; } .typename { color: green; font-weight: bold;} .info { color: #425ad5; } #packets { margin-top: 2em; } body { font-size: 10pt; } p { margin-left: 3em; margin-right: 2em;} ul { margin-left: 3em; } li { margin-top: 1.5em; margin-right: 2em; } tt { color: red; } </style> </head> <body> <h1>BMP Media Cache Format Documentation</h1> <p>The media library used by BMP is a binary metadata cache, binary here means it's not a human readable format like XML or CSV or plain text; this choice was made mostly because of speed concerns. <h2>File Format</h2> <p> <ul> <li>The beginning of the file must contain the string <tt>'MC'</tt> (in uppercase ASCII, non-null terminated) followed by the <tt>uint16_t</tt> value <tt>'666'</tt>; in other words the first 4 bytes of a BMP media cache file are <tt>0x4D 0x43 0x9A 0x02</tt>. This is the 'file magic' for BMP media cache files, and only those containing this file magic at the start of the file are recognized as BMP media cache files by BMP.</li> </ul> </p> <p>Following can be any of the following packets. Each packet type is identified by a <tt>uint8_t</tt> value, following the individual packet data as described below.</p> <div id="packets"> <h2>Packet Types</h2> <ul> <li><tt>0x01</tt><br/> Library Name<br/><br/> This packet holds the individual libary's name. This packet is <b><i>optional</i></b>.<br/> The next value is a <tt>uint8_t</tt> size of the following, <b><i>non-null terminated</i></b> string which is the library name. It should be obvious but just to make it totally clear, using a <tt>uint8_t</tt> size for the string length <b><i>limits the name to a maximal length of 255 characters</i></b>. </li> <li><tt>0x02</tt><br/> Media File<br/><br/> This packet type holds the information about a particular file. It is divided into sub-packets which are identified by a <tt>uint8_t</tt> value. They are described in the following list:<br/><br/> <ul> <li><tt>0x01</tt><br/> Database File ID<br/><br/> Following is a <tt>uint16_t</tt> value with the database's unique file id (UFID) for this file. It must not change for every individual file between reads and (re)-writes of the cache file. </li> <li><tt>0x02</tt><br/> File URI<br/><br/> Following is a <tt>uint16_t</tt> value with the length of the file's URI string, and directly after that the string itself. Currently only 'file://' URIs are supported. </li> <li><tt>0x03</tt><br/> Metadata Value<br/><br/> Following is a <tt>uint8_t</tt> identifier which specifies which particular metadatum is following. The enumeration is this (it is identical to the enumeration in <tt>src/bmp_metadata.h</tt>):<br/> <p> <tt>0x00</tt> TITLE</li><br/> <tt>0x01</tt> TIME</li><br/> <tt>0x02</tt> TRACK</li><br/> <tt>0x03</tt> RATING</li><br/> <tt>0x04</tt> ARTIST</li><br/> <tt>0x05</tt> ALBUM</li><br/> <tt>0x06</tt> DATE</li><br/> <tt>0x07</tt> GENRE</li><br/> <tt>0x08</tt> COMMENT</li><br/> <tt>0x09</tt> BITRATE</li><br/> </p> Currently all values are being saved as strings. Hence the next following field is a <tt>uint16_t</tt> value holding the length of the actual contents of the individual metadatum, after that the (non-null terminated) string holding the data itself.<br/><br/> Even though the point of the media cache is to cache metadata, holding metadata is optional for a file record in the BMP media cache file; it is possible for a file record to not hold any Metadata Value packet at all. Possible reasons are for example that the file simply doesn't hold any metadata; it is up to the application to make something out of that, e.g. use the filename for display instead of metadata. </li> <li><tt>0x04</tt><br/> End of Media File<br/><br/> No data follows, it signalises the end of the Media File packet. </li> </ul> <li><tt>0x03</tt><br/> EMC (End of Media Cache)<br/><br/> This packet signalizes the end of the cache file. No other data follows, it is a signal to the application to stop reading the metadata cache.</li> </ul> </div> </body> </html> |