doc/source/man/mpd-sima.1.rst

   1 ========
   2 mpd-sima
   3 ========
   4
   5 SYNOPSYS
   6 --------
   7
   8 ``mpd-sima [--daemon] [--config=conf_file] [--var-dir=var_directory] [--pid=pid_file] [--log=log_file] [--log-level=log_level] [--host=mpd_host] [--mpd_port=mpd_port]``
   9
  10 ``mpd-sima {{-h | --help} --version}``
  11
  12 ``mpd-sima [--config=conf_file] config-test``
  13
  14 ``mpd-sima [--var-dir=var_directory] create-db``
  15
  16 ``mpd-sima […] generate-config``
  17
  18 ``mpd-sima [--var-dir=var_directory] purge-history``
  19
  20 ``mpd-sima bl-view``
  21
  22 ``mpd-sima bl-add-artist [artist]``
  23
  24 ``mpd-sima bl-add-album [album]``
  25
  26 ``mpd-sima bl-add-track [track]``
  27
  28 ``mpd-sima bl-delete id``
  29
  30 ``mpd-sima random [nbtracks]``
  31
  32
  33 DESCRIPTION
  34 -----------
  35
  36 This manual page documents briefly the ``mpd-sima`` commands.
  37
  38 At start up default configuration is first overridden by user configuration in
  39 mpd_sima.cfg (see FILES_) and finally command lines options are honored. For
  40 instance you can override default MPD host (localhost) in your configuration
  41 file or with ``-S my_mpd_server.local`` option. For default configuration see
  42 CONFIGURATION_. See also environment variables special case for MPD host and
  43 port in ENVIRONMENT_.
  44
  45
  46 OPTIONS
  47 -------
  48
  49 The program follows the usual GNU command line syntax, with long options
  50 starting with two dashes ('-'). A summary of options is included below.
  51
  52 ``-h``; ``--help``
  53    Print help and exit.
  54
  55 ``--version``
  56    Print version and exit.
  57
  58 ``--daemon``
  59    Start as a daemon. Log redirected to :file:`/dev/null`, usually setting
  60    ``--log`` and ``--pid`` options in daemon mode are a good idea to
  61    monitor/stop the process.
  62
  63 ``-p pid_file``; ``--pid=pid_file``
  64    Use the specific file pid_file to store pid to.
  65
  66    Default is not to store pid info.
  67
  68 ``-l log_file``; ``--log=log_file``
  69    Use the specific file log_file to log messages to.
  70
  71    Default is to log to stdout/stderr.
  72
  73 ``-v log_level``; ``--log-level=log_level``
  74    Verbosity in [debug,info,warning,error].
  75
  76    Default is to log info messages.
  77
  78 ``-c conf_file``; ``--config=conf_file``
  79    Use the specific file conf_file to set up configuration instead of
  80    looking for the default user configuration file.
  81
  82    Default is to look for :file:`${{XDG_CONFIG_HOME}}/mpd_sima/mpd_sima.cfg`.
  83    CLI option overrides any equivalent mentioned in configuration file, ie.
  84    launching mpd-sima with ``--port`` CLI option will ignore port setting in
  85    configuration file.
  86
  87    For more details on configuration file see also `FILES <#files>`__ and `CONFIGURATION <#configuration>`__ sections.
  88
  89 ``--var-dir=var_directory``
  90    Use the specific path var_directory to look for (or create) var files
  91    (ie. database) instead of looking at the default user data
  92    location.
  93
  94    Default is to look in :file:`${{XDG_DATA_HOME}}/mpd_sima/`. Concerning
  95    :envvar:`XDG_DATA_HOME` see also `FILES section <#files>`__.
  96
  97 ``-S mpd_host``; ``--host=mpd_host``
  98    Use the specific host mpd_host as MPD server.mpd_host can be an IP or
  99    a fully qualified domain name as long as your system can resolve it.
 100    This overrides MPD_HOST environment variable.
 101    Default is *localhost*.
 102
 103    See also `ENVIRONMENT section <#environment>`__.
 104
 105 ``-P mpd_port``; ``--port=mpd_port``
 106    Use the specific port number mpd_port on MPD server. This overrides
 107    MPD_PORT environment variable.Default is *6600*.
 108
 109    See also `ENVIRONMENT section <#environment>`__
 110
 111 Command arguments
 112 -----------------
 113
 114 ``config-test``
 115    Test configuration file and exit. Uses the configuration file
 116    specified with ``--config`` or default location.
 117    Default is to use $XDG_CONFIG_HOME/mpd_sima/mpd_sima.cfg.
 118
 119    config-test tests MPD connection and Tags plugin configuration.
 120
 121 ``create-db``
 122    Create the database and exit. Uses folder specified with
 123    ``--var-dir`` or default directory.
 124
 125    Default is to use :file:`${{XDG_DATA_HOME}}/mpd_sima/` (see `CONFIGURATION
 126    section <#configuration>`__ for more).
 127
 128 ``generate-config``
 129    Generate a sample configuration file according to the current CLI
 130    options and environment variables. The configuration is written on stdout.
 131
 132 ``purge-history``
 133    Purge play history in the database and exit. Uses folder specified
 134    with ``--var-dir`` or default directory.
 135
 136    Default is to use :file:`${{XDG_DATA_HOME}}/mpd_sima/` (see `FILES section
 137    <#files>`__ for more).
 138
 139 ``bl-view``
 140    View blocklist, useful to get entry IDs to remove with delete
 141    command.
 142
 143 ``bl-add-artist artist``
 144    Add artist to the blocklist. If artist is not provided, try to get
 145    the currently playing artist.
 146
 147 ``bl-add-album album``
 148    Add album to the blocklist. If album is not provided, try to get the
 149    currently playing album.
 150
 151 ``bl-add-track track``
 152    Add track to the blocklist. If track is not provided, try to get the
 153    currently playing track.
 154
 155 ``bl-delete id``
 156    Remove blocklist entry referenced by its id. Use bloclist view
 157    command to get the id.
 158
 159 ``random [nbtracks]``
 160    Starts in random mode overriding internal plugin configuration. If
 161    `nbtracks` is provided, as many tracks will be queued (defaults to one).
 162
 163 ENVIRONMENT
 164 -----------
 165
 166 :envvar:`MPD_HOST`, :envvar:`MPD_PORT`
 167    mpd-sima will look for MPD_HOST and MPD_PORT to override built-in
 168    configuration (set to "localhost:6600").
 169
 170    mpd-sima expects MPD_HOST syntax as documented in mpc manual, cf.
 171    :manpage:`mpc(1)`. To use a password, provide a value of the form **password@host**.
 172
 173 :envvar:`HTTP_PROXY`, :envvar:`HTTPS_PROXY`
 174    mpd-sima honors HTTP_PROXY environment variables.
 175
 176
 177 CONFIGURATION
 178 -------------
 179
 180 :file:`mpd_sima.cfg`
 181    :file:`mpd_sima.cfg` is read if present. Otherwise built-in defaults are
 182    used. An example should be provided in the tarball within ``doc/examples/``.
 183    On Debian system please look in :file:`/usr/share/doc/mpd-sima`.
 184
 185 **DEFAULTS**
 186
 187    Default is to look for MPD server at localhost:6600 (or
 188    :envvar:`MPD_HOST`/:envvar:`MPD_PORT` env. var. if set).
 189
 190    The default plugins will use Last.fm to find similar tracks to queue and
 191    fallback to random if nothing if found.
 192
 193    The get the defaults as detected by mpd-sima on your system you can
 194    run mpd-sima to print the config:
 195
 196    ``mpd-sima generate-config``
 197
 198 .. only:: format_man
 199
 200    For details about mpd_sima.cfg refer to the manual :manpage:`mpd_sima.cfg(5)`
 201
 202 .. only:: format_html
 203
 204    For details about mpd_sima.cfg refer to the manual :doc:`mpd_sima.cfg.5`
 205
 206 .. include:: files.rst
 207 .. include:: seealso.rst
 208 .. include:: info.rst