+++ /dev/null
-<?xml version='1.0' encoding='UTF-8'?>
-<!--
-
-`xsltproc -''-nonet \
- -''-param man.charmap.use.subset "0" \
- -''-param make.year.ranges "1" \
- -''-param make.single.year.ranges "1" \
- /usr/share/xml/docbook/stylesheet/nwalsh/manpages/docbook.xsl \
- manpage.xml'
-
-A manual page <package>.<section> will be generated. You may view the
-manual page with: nroff -man <package>.<section> | less'. A typical entry
-in a Makefile or Makefile.am is:
-
-DB2MAN = /usr/share/sgml/docbook/stylesheet/xsl/nwalsh/manpages/docbook.xsl
-XP = xsltproc -''-nonet -''-param man.charmap.use.subset "0"
-
-manpage.1: manpage.xml
- $(XP) $(DB2MAN) $<
-
-The xsltproc binary is found in the xsltproc package. The XSL files are in
-docbook-xsl. A description of the parameters you can use can be found in the
-docbook-xsl-doc-* packages. Please remember that if you create the nroff
-version in one of the debian/rules file targets (such as build), you will need
-to include xsltproc and docbook-xsl in your Build-Depends control field.
-Alternatively use the xmlto command/package. That will also automatically
-pull in xsltproc and docbook-xsl.
-
-Notes for using docbook2x: docbook2x-man does not automatically create the
-AUTHOR(S) and COPYRIGHT sections. In this case, please add them manually as
-<refsect1> ... </refsect1>.
-
-To disable the automatic creation of the AUTHOR(S) and COPYRIGHT sections
-read /usr/share/doc/docbook-xsl/doc/manpages/authors.html. This file can be
-found in the docbook-xsl-doc-html package.
-
-Validation can be done using: `xmllint -''-noout -''-valid manpage.xml`
-
-General documentation about man-pages and man-page-formatting:
-man(1), man(7), http://www.tldp.org/HOWTO/Man-Page/
-
--->
-<!DOCTYPE refentry [
-
- <!ENTITY dhsection "5">
- <!ENTITY dhpackage "mpd-sima">
- <!ENTITY dhutils "mpd_sima.cfg">
-
-]>
-
-<refentry xmlns="http://docbook.org/ns/docbook"
- xmlns:xi="http://www.w3.org/2001/XInclude" version="5.0">
- <xi:include href="info.xml" />
- <refmeta>
- <refentrytitle>&dhutils;</refentrytitle>
- <manvolnum>&dhsection;</manvolnum>
- </refmeta>
- <refnamediv>
- <refname>&dhutils;</refname>
- <refpurpose>&dhpackage; will try to maintain some titles ahead in the queue
- following different policies. This manual document the
- configuration file for &dhpackage;.</refpurpose>
- </refnamediv>
- <refsect1 id="description">
- <title>DESCRIPTION</title>
- <para>This manual page documents briefly <command>&dhpackage;</command>
- configuration options available in user configuration file
- (see <xref linkend="files"/>).</para>
- </refsect1>
- <refsect1 id="examples">
- <title>EXAMPLES</title>
- <!--
- <refsect2 id="track">
- <title>Default queue mode, similar artist.</title>
- <para></para>
- <para></para>
- </refsect2> -->
- <refsect2 id="tags">
- <title>File tags queue mode (offline mode).</title>
- <para>Here is an example of autoqueue using file tags only.</para>
- <programlisting><xi:include href="tags.cfg" parse="text" />
- </programlisting>
- </refsect2>
- <refsect2 id="album">
- <title>Album queue mode using last.fm recommendations (online mode).</title>
- <para>Here is an example of album queue configuration using online recommendations system.</para>
- <programlisting><xi:include href="album.cfg" parse="text" />
- </programlisting>
- </refsect2>
- </refsect1>
-
- <refsect1 id="options">
- <title>Configuration file</title>
- <para>The configuration file consists of sections, led by a
- <command>[section]</command> header and followed by <option>name: value</option>
- entries, with continuations in the style of RFC 822 (see section
- 3.1.1, “LONG HEADER FIELDS”); <option>name=value</option> is also accepted. Lines
- beginning with <parameter>'#'</parameter> or <parameter>';'</parameter>
- are ignored and may be used to provide comments (<emphasis>Nota
- Bene:</emphasis> inline comment are possible using <parameter>'#'</parameter>).</para>
- <title>OPTIONS</title>
- <para>The default values are used in the options lists below.</para>
- <refsect2 id="MPD">
- <title>MPD section</title>
- <para>This section is meant to configure MPD access, MPD host
- address / port and password if necessary.</para>
- <variablelist>
- <!-- Use the variablelist.term.separator and the
- variablelist.term.break.after parameters to
- control the term elements. -->
- <varlistentry> <!-- MPD -->
- <term><option>[MPD]</option></term>
- <listitem></listitem>
- </varlistentry>
- <varlistentry> <!-- MPD.host -->
- <term><option>host=</option><replaceable>localhost</replaceable></term>
- <listitem>
- <para>Set MPD host. Use IP or FQDN.</para>
- </listitem>
- </varlistentry>
- <varlistentry> <!-- MPD.port -->
- <term><option>port=</option><replaceable>6600</replaceable></term>
- <listitem>
- <para>Set host port to access MPD to.</para>
- </listitem>
- </varlistentry>
- <varlistentry> <!-- MPD.password -->
- <term><option>password=</option><replaceable>s3cr3t</replaceable></term>
- <listitem>
- <para>Set MPD password to use. Do not use this option
- if you don't have enabled password protected access
- on your MPD server.</para>
- </listitem>
- </varlistentry>
- </variablelist>
- </refsect2>
- <refsect2 id="log">
- <title>log section</title>
- <para>Configure logging.</para>
- <variablelist>
- <varlistentry> <!-- LOG -->
- <term><option>[log]</option></term>
- <listitem><para></para></listitem>
- </varlistentry>
- <varlistentry> <!-- log.logfile -->
- <term><option>logfile=</option></term>
- <listitem>
- <para>File to log to, usually in dæmon mode.<sbr />Default
- (empty or unset) is to log to stdin/stdout.</para>
- </listitem>
- </varlistentry>
- <varlistentry> <!-- log.verbosity -->
- <term><option>verbosity=</option><replaceable>info</replaceable></term>
- <listitem>
- <para>Logging verbosity among
- <replaceable>debug</replaceable>,
- <replaceable>info</replaceable>,
- <replaceable>warning</replaceable>,
- <replaceable>error</replaceable>.</para>
- </listitem>
- </varlistentry>
- </variablelist>
- </refsect2>
- <refsect2 id="daemon">
- <title>Process daemonization</title>
- <para>Configure process daemon.</para>
- <variablelist>
- <varlistentry> <!-- DAEMON -->
- <term><option>[daemon]</option></term>
- <listitem><para></para></listitem>
- </varlistentry>
- <varlistentry> <!-- daemon.daemon -->
- <term><option>daemon=false</option></term>
- <listitem>
- <para>whether to daemonize process or not.</para>
- </listitem>
- </varlistentry>
- <varlistentry> <!-- daemon.pidfile -->
- <term><option>pidfile=</option></term>
- <listitem>
- <para>Where to store process ID.</para>
- </listitem>
- </varlistentry>
- </variablelist>
- </refsect2>
- <refsect2 id="sima">
- <title>sima section</title>
- <para>Core &dhutils; configuration.</para>
- <variablelist>
- <varlistentry> <!-- SIMA -->
- <term><option>[sima]</option></term>
- <listitem><para></para></listitem>
- </varlistentry>
- <variablelist>
- <varlistentry> <!-- sima.contrib -->
- <term><option>contrib=</option><replaceable></replaceable></term>
- <listitem>
- <para></para>
- </listitem>
- </varlistentry>
- <varlistentry> <!-- sima.internal -->
- <term><option>internal=</option><replaceable>Lastfm, Random, Crop</replaceable></term>
- <listitem>
- <para>&dhpackage;'s plugin management for internal source plugin
- and contrib (ie. external plugins).<sbr /> Plugins list is a
- comma separated string list.<sbr /> Optional plugin's
- configuration lays in its own section.<sbr />For instance a
- "AwesomePlugin" declared here gets its configuration from the
- corresponding section "[awesomeplugin]".
- </para>
- <para>The default list of plugins to load at startup: <option>Lastfm</option>,<option>Random</option>,<option>Crop</option>.<sbr />
- <option>Crop</option> is an utility plugin, it does not queue any tracks (cf. below).<sbr />
- <option>Random</option> will queue a track at random if other plugins did not return any tracks.<sbr />
- </para>
- <para>You can add, combine here as many plugins you want.<sbr />
- The priority may be used to order them.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry> <!-- sima.history_duration -->
- <term><option>history_duration=</option><replaceable>8</replaceable></term>
- <listitem>
- <para>How far to look back in history to avoid to play
- twice the same track/title (duration in
- hours).<sbr />
- The <option>history_duration</option> is also used to give priority to not recently played artists.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry> <!-- sima.queue_length -->
- <term><option>queue_length=</option><replaceable>2</replaceable></term>
- <listitem>
- <para>Threshold value triggering queue process.</para>
- </listitem>
- </varlistentry>
- <varlistentry> <!-- sima.musicbrainzid -->
- <term><option>musicbrainzid=</option><replaceable>true</replaceable></term>
- <listitem>
- <para>Use MusicBrainzIdentifier to search music (mainly
- for artists).
- Default is True, switch to False if you don't have
- MusicBrainzIdentifier set for at least 80% of you
- music library.<sbr /> Consider using these metadata as it
- enhances a lot artist/album/tracks identification.
- Use Picard to tag your file: <ulink url="https://picard.musicbrainz.org/"/>.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry> <!-- sima.repeat_disable_queue -->
- <term><option>repeat_disable_queue=</option><replaceable>true</replaceable></term>
- <listitem>
- <para>Prevent disabling queuing in repeat play mode.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry> <!-- sima.single_disable_queue -->
- <term><option>single_disable_queue=</option><replaceable>true</replaceable></term>
- <listitem>
- <para>Prevent disabling queuing in single play mode.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- </variablelist>
- </refsect2>
- <refsect2 id="crop">
- <title>Crop section</title>
- <para>crop plugin's configuration:</para>
- <varlistentry> <!-- crop -->
- <term><option>[crop]</option></term>
- </varlistentry>
- <varlistentry> <!-- crop.consume -->
- <term><option>consume=</option><replaceable>10</replaceable></term>
- <listitem>
- <para>How many played tracks to keep in the queue.
- Allows you to maintain a fixed length queue.
- Set to some negative integer to keep all played tracks.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry> <!-- crop.priority -->
- <term><option>priority=</option><replaceable>10</replaceable></term>
- <listitem>
- <para>
- Plugin priority
- </para>
- </listitem>
- </varlistentry>
- </refsect2>
- <refsect2 id="random">
- <title>Random section</title>
- <para>When no similar tracks are found, falling back to random queuing.</para>
- <para>Random plugin's configuration:</para>
- <varlistentry> <!-- random -->
- <term><option>[random]</option></term>
- </varlistentry>
- <varlistentry> <!-- random.track_to_add -->
- <term><option>track_to_add=</option><replaceable>1</replaceable></term>
- <listitem>
- <para>How many track(s) to add.</para>
- </listitem>
- </varlistentry>
- <varlistentry> <!-- random.flavour -->
- <term><option>flavour=</option><replaceable>sensible</replaceable></term>
- <listitem>
- <para>Different mode, aka random flavour,
- are available:
- <replaceable>pure</replaceable>,
- <replaceable>sensible</replaceable>,
- <itemizedlist mark='bullet'>
- <listitem>
- <para><replaceable>pure</replaceable>, pure random choice, even among recently played track.
- </para>
- </listitem>
- <listitem >
- <para><replaceable>sensible</replaceable>, use play history to filter chosen tracks.
- </para>
- </listitem>
- </itemizedlist>
- </para>
- </listitem>
- </varlistentry>
- <varlistentry> <!-- random.priority -->
- <term><option>priority=</option><replaceable>50</replaceable></term>
- <listitem>
- <para>
- Plugin priority
- </para>
- </listitem>
- </varlistentry>
- </refsect2>
- <refsect2 id="lastfm">
- <title>LastFm section</title>
- <para>LastFM plugin's configuration.</para>
- <variablelist>
- <varlistentry> <!-- lastfm -->
- <term><option>[lastfm]</option></term>
- </varlistentry>
- <varlistentry> <!-- lastfm.queue_mode -->
- <term><option>queue_mode=</option><replaceable>track</replaceable></term>
- <listitem>
- <para>Queue mode to use among
- <replaceable>track</replaceable>,
- <replaceable>top</replaceable> and
- <replaceable>album</replaceable> (see <xref linkend="queue_mode"/> for info about queue modes).</para>
- </listitem>
- </varlistentry>
- <varlistentry> <!-- lastfm.max_art -->
- <term><option>max_art=</option><replaceable>10</replaceable></term>
- <listitem>
- <para>Maximum number of similar artist to retrieve from local
- media library.<sbr />When set to something superior
- to zero, it tries to get as much similar artists
- from media library.</para>
- </listitem>
- </varlistentry>
- <varlistentry> <!-- lastfm.depth -->
- <term><option>depth=</option><replaceable>1</replaceable></term>
- <listitem>
- <para>How many artists to base on similar artists
- search.<sbr /> The first is the last played artist
- and so on back in the history. Highter depth
- generates wider suggestions, it might help to
- reduce looping over same artists.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry> <!-- lastfm.single_album -->
- <term><option>single_album=</option><replaceable>false</replaceable></term>
- <listitem>
- <para>Prevent from queueing a track from the same album
- (it often happens with OST).<sbr />
- Only relevant in "track" queue mode.</para>
- </listitem>
- </varlistentry>
- <varlistentry> <!-- lastfm.track_to_add -->
- <term><option>track_to_add=</option><replaceable>1</replaceable></term>
- <listitem>
- <para>How many track(s) to add. Only relevant in
- <option>top</option> and <option>track</option>
- queue modes. This is actually an upper limit,
- min(<option>max_art</option>,
- <option>track_to_add</option>) will be used.</para>
- </listitem>
- </varlistentry>
- <varlistentry> <!-- lastfm.album_to_add -->
- <term><option>album_to_add=</option><replaceable>1</replaceable></term>
- <listitem>
- <para>How many album(s) to add. Only relevant in
- <option>album</option> queue modes.</para>
- </listitem>
- </varlistentry>
- <varlistentry> <!-- lastfm.track_to_add_from_album -->
- <term><option>track_to_add_from_album=</option><replaceable>0</replaceable></term>
- <listitem>
- <para>How many track(s) to add from each selected albums. Only relevant in
- <option>album</option> queue modes. When set to 0 or lower the whole album is queued.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry> <!-- lastfm.cache -->
- <term><option>cache=</option><replaceable>True</replaceable></term>
- <listitem>
- <para>Whether or not to use on-disk persistent http
- cache.<sbr />When set to "true", sima will use a
- persistent cache for its http client. The cache is
- written along with the dbfile in:<sbr />
- <filename>$XDG_DATA_HOME/mpd_sima/http/WEB_SERVICE</filename>.<sbr/>
- If set to "false", caching is still done but in memory.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry> <!-- lastfm.priority -->
- <term><option>priority=</option><replaceable>100</replaceable></term>
- <listitem>
- <para>
- Plugin priority
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- </refsect2>
- <refsect2 id="genre">
- <title>Genre section</title>
- <para>Genre plugin's configuration.</para>
- <para>This plugin permits offline autoqueuing based on files genre tag only.</para>
- <para>It will try to queue tracks with similar genres (track's genre being read from tags).</para>
- <varlistentry> <!-- genre -->
- <term><option>[genre]</option></term>
- </varlistentry>
- <varlistentry> <!-- tags.queue_mode -->
- <term><option>queue_mode=</option><replaceable>track</replaceable></term>
- <listitem>
- <para>Queue mode to use among
- <replaceable>track</replaceable>,
- <replaceable>album</replaceable> (see <xref linkend="queue_mode"/> for info about queue modes).</para>
- </listitem>
- </varlistentry>
- <varlistentry> <!-- genre.single_album -->
- <term><option>single_album=</option><replaceable>false</replaceable></term>
- <listitem>
- <para>Prevent from queueing a track from the same album
- (it often happens with OST).<sbr />
- Only relevant in "track" queue mode.</para>
- </listitem>
- </varlistentry>
- <varlistentry> <!-- genre.priority -->
- <term><option>priority=</option><replaceable>80</replaceable></term>
- <listitem>
- <para>
- Plugin priority
- </para>
- </listitem>
- </varlistentry>
- <varlistentry> <!-- genre.track_to_add -->
- <term><option>track_to_add=</option><replaceable>1</replaceable></term>
- <listitem>
- <para>How many track(s) to add.</para>
- </listitem>
- </varlistentry>
- <varlistentry> <!-- genre.album_to_add -->
- <term><option>album_to_add=</option><replaceable>1</replaceable></term>
- <listitem>
- <para>How many album(s) to add. Only relevant in
- <option>album</option> queue mode.</para>
- </listitem>
- </varlistentry>
- </refsect2>
- <refsect2 id="tags">
- <title>Tags section</title>
- <para>Tags plugin's configuration. There is no default configuration for this plugin,
- it does not work out of the box.</para>
- <para>This plugin permits offline autoqueuing based on files tags only. Supported tags are
- <option>'comment'</option>, <option>'date'</option>, <option>'genre'</option>,
- <option>'label'</option> and <option>'originaldate'</option>.</para>
- <para>In addition to supported tags above you can use an MPD filter. Please refer to
- MPD protocol documentation for more.</para>
- <para>All tag entries in this section are ANDed as a single MPD filter to look for titles
- in the library. Moreover, for each tags, comma separated values are also ORed.<sbr />
- For instance setting "<option>genre=rock</option>" and
- "<option>date=1982,1983,1984,1985,1986,1987,1988,1989</option>"
- will end up looking for track tagged with genre <option>rock</option>
- and date within 1982 through 1989.<sbr />
- Using an MPD filter to replace <option>date</option> you can achieve
- the same with the following setting: "<option>genre=rock</option>" and
- "<option>filter=(date =~ '198[2-9]+')</option>" (provided your MPD server
- was compiled with libpcre).
- </para>
- <varlistentry> <!-- tags -->
- <term><option>[tags]</option></term>
- </varlistentry>
- <varlistentry> <!-- tags.queue_mode -->
- <term><option>queue_mode=</option><replaceable>track</replaceable></term>
- <listitem>
- <para>Queue mode to use among
- <replaceable>track</replaceable>,
- <replaceable>album</replaceable> (see <xref linkend="queue_mode"/> for info about queue modes).</para>
- </listitem>
- </varlistentry>
- <varlistentry> <!-- tags.single_album -->
- <term><option>single_album=</option><replaceable>false</replaceable></term>
- <listitem>
- <para>Prevent from queueing a track from the same album
- (it often happens with OST).<sbr />
- Only relevant in "track" queue mode.</para>
- </listitem>
- </varlistentry>
- <varlistentry> <!-- tags.filter -->
- <term><option>filter=</option></term>
- <listitem>
- <para>You can use here any valid MPD filter as defined in MPD protocol documentation.</para>
- </listitem>
- </varlistentry>
- <varlistentry> <!-- tags.comment -->
- <term><option>comment=</option></term>
- </varlistentry>
- <varlistentry> <!-- tags.date -->
- <term><option>date=</option></term>
- </varlistentry>
- <varlistentry> <!-- tags.genre -->
- <term><option>genre=</option></term>
- </varlistentry>
- <varlistentry> <!-- tags.label -->
- <term><option>label=</option></term>
- </varlistentry>
- <varlistentry> <!-- tags.originaldate -->
- <term><option>originaldate=</option></term>
- </varlistentry>
- <varlistentry> <!-- tags.priority -->
- <term><option>priority=</option><replaceable>80</replaceable></term>
- <listitem>
- <para>
- Plugin priority
- </para>
- </listitem>
- </varlistentry>
- <varlistentry> <!-- tags.track_to_add -->
- <term><option>track_to_add=</option><replaceable>1</replaceable></term>
- <listitem>
- <para>How many track(s) to add.</para>
- </listitem>
- </varlistentry>
- <varlistentry> <!-- tags.album_to_add -->
- <term><option>album_to_add=</option><replaceable>1</replaceable></term>
- <listitem>
- <para>How many album(s) to add. Only relevant in
- <option>album</option> queue mode.</para>
- </listitem>
- </varlistentry>
- </refsect2>
- </refsect1>
- <refsect1 id="queue_mode">
- <title>QUEUE MODES</title>
- <para>Different queue modes are available with some plugins (check for
- <option>queue_mode</option> presence in plugin config).
- </para>
- <para>&dhpackage; tries preferably to chose among unplayed artists or
- at least not recently played artist.</para>
- <variablelist>
- <varlistentry>
- <term><option>track</option></term>
- <listitem>
- <para>Queue a similar track chosen at random from a similar artist.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><option>top</option></term>
- <listitem>
- <para>Queue a track from a similar artist, chosen among
- "top tracks" according to last.fm data mining.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><option>album</option></term>
- <listitem>
- <para>Queue a whole album chosen at random from a similar artist.</para>
- <para><emphasis>Nota Bene:</emphasis><sbr /> Due to the
- track point of view of database build upon tracks tags
- an album lookup for a specific artist will return
- albums as soon as this artist appears in a single track
- of the album.<sbr />
- For instance looking for album from "The Velvet
- Underground" will fetch "Last Days" and "Juno" OSTs
- because the band appears on the soundtrack of these two
- movies.<sbr />
- A solution is for you to set AlbumArtists tag to
- something different than the actual artist of the
- track. For compilations, OSTs etc. a strong convention
- is to use "Various Artists" for this tag.</para>
- <para>&dhpackage; is currently looking for AlbumArtists tags
- and avoid album where this tag is set with "Various
- Artists". If a single track within an album is found
- with AlbumArtists:"Various Artists" the complete album
- is skipped and won't be queued.</para>
- </listitem>
- </varlistentry>
- </variablelist>
- </refsect1>
- <xi:include href="files.xml" />
- <xi:include href="feedback.xml" />
- <xi:include href="seealso.xml" />
-</refentry>
-<!-- vim: tabstop=4 softtabstop=4 shiftwidth=4 :
--->
home / dev / repositories / mpd-sima.git / blobdiff