Configuration

A configuration can be given as argument to the application or via a system property config.file. Please see the Spec for the config file format.

It is recommended to copy the reference.conf file (which is shown below) and comment everything and then uncomment and change things you want to be different.

The packaged application already contains this file. All settings not specified in the configuration file falls back to the appropriate setting in reference.conf.

Reference.conf

mpc4s {
  http {
    # The application name, used in loggin and information responses
    app-name = "mpc4s-http"

    # The base url; used to create links
    baseurl = "http://localhost:9600"

    # Host and port to bind the http service to
    bind {
      host = "127.0.0.1"
      port = 9600
    }

    ## The music directory; it should be the same as configured with
    ## mpd. For multiple mpd connections, this acts as a default and
    ## is used if no specific music directory is specified for some
    ## mpd connection.
    ##
    ## This is a required setting.
    #music-directory = "/var/lib/mpd/music"

    # The connection to MPD. Multiple mpd connections can be
    # specified. If they don't share the same music directory, you
    # need to configure it per mpd connection.
    #
    # There *must* be at least one config with id "default". Other ids
    # should be short names without weird chars or spaces, because
    # they will be part of the endpoint url.
    mpd.configs {
      default = {
        host = "127.0.0.1"
        port = 6600
        password = ""

        # The `max_connections` setting from your mpd server. The http
        # server should not exceed this limit.
        max-connections = 5

        # Timeout for mpd commands
        timeout = 5 seconds

        # A human readable title, like “Living Room”.
        title = "Default"

        ## A music directory for this specific mpd. If left out, the
        ## global configured music directory is used.
        #music-directory = ""
      }
    }

    # Configures how a file per album (booklet or cover) is searched.
    album-file {
      disc-directories = [ "cd", "disc", "CD", "Cd", "Disc", "DISC" ]
      disc-separators = [ "", ".", "-", "_", " " ]
      disc-numbers = [
        "01", "02", "03", "04", "05", "06", "07", "08", "09",
        "1", "2", "3", "4", "5", "6", "7", "8", "9", "10", "11", "12", "13", "14", "15",
        "I", "II", "III", "IV", "V", "VI", "VII", "VIII", "IX", "X"
      ]

      # Paths to files are cached in memory to avoid requests to
      # mpd. This specifies the maximum cache size. A value <= 0
      # disables the cache.
      cache-size = 3000
    }

    # Possible file names for covers.
    cover {
      basenames = [ "cover", "artwork", "Cover", "Artwork" ]
      extensions = [ "jpg", "jpeg", "png", "gif" ]
    }

    # Posslible filenames for booklets.
    booklet {
      basenames = [ "booklet", "artwork" ]
      extensions = [ "pdf" ]
    }

    # Covers can be resized before transmitting.
    #
    # It usually doesn't make much sense to transmit high quality
    # cover art to your small-screen android device. So they can be
    # resized to save bandwidth and make rendering the library page
    # faster.
    cover-thumbnails {
      # Whether to enable this feature.
      enable = true

      # The reason for resizing is to save bandwidth. If the file is
      # small enough the cost of resizing is not necessary.
      min-file-size = "70K"

      # Too large files may result in out-of-memory errors. For
      # resizing the files must be read completely in memory. Files
      # greater that this size are skipped.
      max-file-size = "70M"

      # The directory that is used to save resized images. The
      # directory must exist and the process must be able to write
      # into it. There should be enough space to hold all thumbnails
      # of all your cover art (around 5M for 100 files at
      # 500x500px). Note that this directory is not cleaned up
      # automatically.
      directory = "thumbnails"

      # Since processing images requires some resources (memory+cpu)
      # it might be necessary to restrict the number of parallel
      # invocations. Note, that this only applies to the first time a
      # thumbnail is requested. Subsequent requests simply return the
      # peviously generated file.
      max-parallel = 5
    }

    # Allows to specifiy a directory that the http server can serve
    # files from. Everything below that directory is served!
    custom-content {
      enabled = false
      directory = "some-directory"
    }
  }
}

Noteworthy settings

There is a required setting (the app won’t start without):

  • mpc4s.http.music-directory: The music directory used by MPD. This is used to serve cover files from.

Other important ones include:

  • mpc4s.http.baseurl: The base url to the application. This is used to construct urls.
  • mpc4s.http.bind.{host|port}: The host and port to bind the http server to.
  • mpc4s.http.mpd.default.{host|port}: Connection info to MPD.
  • mpc4s.http.mpd.default.max-connections: The maximum allowed connections to MPD. This must be lower than the corresponding value in mpd.conf.

Regarding max-connections setting: MPD has the same setting that specifies how many concurrent connections are allowed. This value should always be lower than the one in your MPD config file! It can be quite low. But: When the covers are initially loaded, one mpd request is issued for each cover. So there are many multiple concurrent requests. A high max-connections value here will speed up loading covers initially. However, after first load, the paths to the cover files are cached (the images are also cached in the browser) and subsequent requests won’t ask mpd again.