Basic requirements

To run O!MPD you need to have up and running:

  • Apache or Lighttpd web server (other WWW servers should also work, but I didn’t test it)
  • PHP 5.3.0 or later with extension: GD2, ICONV, MYSQLi, JSON, MBSTRING, CTYPE and CURL
  • MySQL 4.1.0 or later
  • MPD
  • web browser with XMLHttpRequest and cookie support (any modern browser should be OK)


Download O!MPD zip file and extract its content to the web server document root directory. If you want to have ‘bleeding edge’ version, you can download it from GitHub: If you clone GitHub repo and want to keep your directory clean, copy include/ into include/ and make all of your configuration in this file.

Make sure that your web server has write access to directories:

  • /ompd/tmp/ (required for database update)
  • /ompd/stream/ (required for streaming files)
  • /ompd/cache/ (required for downloading files)

and read-only access to your media directory defined in $cfg['media_dir'] (more about this below).


All configuration is made by editing file include/ (or in include/ if you cloned GitHub repo). If you use my image, you can find this file in /var/www/html/ompd/include. The most important are 2 sections:

  • MySQL configuration – information needed to connect to MySQL server:
    • $cfg['mysqli_host'] – server IP address or name
    • $cfg['mysqli_db'] – name of O!MPD database (you can leave this untouched)
    • $cfg['mysqli_user'] and $cfg['mysql_password'] – server authentication
    • $cfg['mysqli_port'] and $cfg['mysql_socket'] – connection parameters (probably no need of change)
    • $cfg['mysqli_auto_create_db'] = true – needed to create database structure
  • Media directory – your media files location:
    • $cfg['media_dir'] – should point the same location as music_directory from MPD configuration file (mpd.conf)

Some other section:

  • Songs separators – read this
  • Tag separator – read this
  • Multiple artists – read this
  • Quick search – read this
  • Lyrics search string – read this

Rest of sections has its explanation in the configuration file.

First login and player configuration

After configuration is done, you can login to O!MPD. Enter http://www-server-IP-address/ompd (ex. in your web browser. When login for the first time, O!MPD will create database structure in MySQL. Default authentication is:

  • username: admin
  • password: admin

You can change this in Config -> Users -> Admin. Here you can also add and modify users and their privileges.

Now you can add and configure all of your MPD players. Go to Config -> Player profile and add or edit (click on pen symbol) players (IP address, port). By clicking on player’s name you set this player active. When there is more then one player defined, note symbol appears in main menu and name of active player is displayed below it. You can click on that symbol and list of all players displays – now you can click on any of them and set it active.

When it’s done you can update the database – but before you do that, read about data collection and file structure.

Data collection

In general, O!MPD takes informations about media files from tags written in them. This means that your collection must be tagged properly – minimum required tags are:


For better experience, it’s good to also have this tags:

  • YEAR

File structure

O!MPD also requires some basic order in files: each album must be placed in separated folder. Names of these folders are not important (with 2 exceptions describes later below). I have my library organized in folders like this:


My collection file structure

But you can have other file structure, for example:

  • <artist 1> – <album 1>
  • <artist 1 > – <album 2>
  • <artist 2 > – <album 1>
  • <artist 3 > – <album 1>
  • <artist 3 > – <album 2>
  • …..


  • <genre 1>
    • <artist 1>
      • <album 1>
      • <album 2>
    • <artist 2>
      • <album 1>
      • <album 2>
  • <genre 2>
    • <artist 1>
      • <album 1>
      • <album 2>
      • …..

There are two exceptions relating to the folders:

  1. If you have some tracks that doesn’t belong to any particular album and are performed by various artists, you can place them in folder defined in configuration file in section Misc artists folder. Every file from this folder will be assigned to an album with this name and file image/misc_image.jpg will be used as cover.
  2. If you have some tracks of an artist, that doesn’t belong to any particular album, you can place them in folder defined in configuration file in section Misc tracks folder. All files from this folder will be assigned to album which name consists of name of that folder and name of artist (name of artist is taken from tag ARTIST or ALBUMARTIST from first media file in folder). OK, an example: default value of  $cfg['misc_tracks_folder'] is Various Tracks of . If you create this folder and place in this some tracks of U2, O!MPD will create album called Various Tracks of U2 and will assign cover from file folder.jpg or folder.png

Database update

To update database go to Configuration -> Update. During update O!MPD looks into each folder in $cfg['media_dir'] and searches for media file (media files are defined in section Media extensions). If it finds any, it reads tags from the first file and uses it to create album entry in database. These tags are:

  • ALBUMARTIST (if not found then ARTIST) – for album artist
  • ALBUM – for album title
  • YEAR or DATE – for album issue date (only year part of date is used)
  • GENRE – for album genre

If O!MPD finds file folder.jpg or folder.png in album folder, it uses it as album cover. Name of this file can be changed in configuration file (section Image, variable $cfg['image_front']). If this file is not found, O!MPD tries to extract cover from file. If it fails, file image/no_image.png is set as album cover.

Then update process starts to index all files in folder. Tags used are:

  • ARTIST – for track artist
  • TITLE – for track title

First update will surely take long time – in my case (1400+ albums, 16000+ tracks, web server and MySQL running at QNAP NAS with 1.2GHz Marvell CPU and 256MB RAM) it takes about 1,5h. Each next update (after adding new albums to collection) takes much less time (about 7min in my system – it was in v1.0, now in v1.02 it’s about 5min).

After starting the update, the page with its progress is displayed. In that time you can normally use O!MPD – update process runs in background. You can monitor progress returning to update page.


Update progress


Update report