File	Date	Author	Commit
bin	2021-02-21	vaubeh	[a56e3a] http://mantis.vaubeh.de/view.php?id=614
htdocs	2021-02-21	vaubeh	[9916e8] http://mantis.vaubeh.de/view.php?id=553
php	2024-02-24	vaubeh	[e7c800] http://mantis.vaubeh.de/view.php?id=553
tmp	2013-02-26	vaubeh	[1ce9a4] http://mantis.vaubeh.de/view.php?id=553
.gitignore	2017-03-08	vaubeh	[6d9d27] http://mantis.vaubeh.de/view.php?id=612
2011.png	2013-02-26	vaubeh	[1ce9a4] http://mantis.vaubeh.de/view.php?id=553
LICENSE	2013-02-26	vaubeh	[1ce9a4] http://mantis.vaubeh.de/view.php?id=553
README	2024-02-24	vaubeh	[e7c800] http://mantis.vaubeh.de/view.php?id=553
conventions.txt	2013-02-26	vaubeh	[1ce9a4] http://mantis.vaubeh.de/view.php?id=553
releasenotes.txt	2024-02-24	vaubeh	[e7c800] http://mantis.vaubeh.de/view.php?id=553

Read Me

shelfelf 24.24 - README (24.02.24) - http://sourceforge.net/projects/shelfelf/
Copyright (C) 2011 - vaubeh - GNU GPL Version 2, June 1991 (see file LICENSE)


~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
scope
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

the shelfelf is a browser based remote control for your music player daemon.
the commands can be sent to itunes, mpd, squeezebox, xmms2, &c...

the shelfelf consists of:
+ mysql-database
+ web-frontend, which is working in most common browsers,
  albeit designed and optimized for tablets - like the ipad
  (microsoft internet explorer is not working at the moment)
+ a shelfelf-shelfelf-server-connection,
  - to search your friends libraries,
  - see what they are listening to,
  - chat (e.g. for sending music tipps), &c...

the shelfelf is tested on:
+ linux (debian/ubuntu)    + mpd,squeezebox,xmms2
+ linux (tiny core)        + mpd
+ linux (vortexbox,fedora) + squeezebox,xmms2
+ mac mini (snow leopard)  + itunes

the shelfelf will work best on a music-library with clean vorbis/id3-tags,
because it will group, sort, display, &c... using the tags.

the shelfelf expects the charset utf-8 everywhere:
no detection or conversion will take place.


~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
requirements
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

+ shelfelf-webservice
  + mysql 5
  + apache 2
  + php 5 or 7

+ music-player
  the recommended default on linux servers:
    + mpd
      settings in /etc/mpd.conf:
        music_directory "shelfelf music directory (SH11_MP3_BASE)"
        auto_update     "yes"
  or if you use xmms2d for playing your music:
    + xmms2d
      accept commands through a socket, by adding the tcp-ipcsocket to your
      ~/.config/xmms2/xmms2.conf:
        <section name="core">
          <property name="ipcsocket">
            unix:///tmp/xmms-ipc-xxx;tcp://localhost:5555
          </property>
        </section>  
    + xmms2
      add the tcp-ipcpath to the webserver's ~/.config/xmms2/clients/cli.conf:
        ipcpath=tcp://localhost:5555
        statusformat=${artist} - ${title}
        listformat=${title} (${minutes}:${seconds})
        autostart=true
        runnycli=true
      maybe you need a line like this in your /etc/sudoers:
        _www ALL=(ALL) NOPASSWD: /usr/bin/xmms2
      (if your webserver's xmms2 refuses to connect to your xmms2d by ipc)
  or on a mac:
    + itunes
      you need to set rpcCmdPath with sudo in your shelfelf.conf.php:
        $rpcCmdPath = 'sudo -u user '.SH11_BASE.'/bin/rpc_itunes.sh';
      and add a line like this in your /etc/sudoers ('til i know better):
        _www ALL=(ALL) NOPASSWD: /path/to/shelfelf/bin/rpc_itunes.sh
  or alternatively:
    + squeezebox
  or, if you want to use other <player>s, you have to create a:
    + /path/to/shelfelf/php/rpc_<player>.php


~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
installation
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

+ download and extract the shelfelf.tar.gz

+ run bin/install.sh (and edit your shelfelf.conf.php, if you want to)
  to upgrade an existing elf, run bin/install.sh and define your current
  shelfelf base direcory as destination (rsync will be required for that).

+ install a cron-job on the shelfelf-server:
  */10 * * * * /path/to/shelfelf/bin/elfcron.sh
  to do things in the background:
  refresh library-data, reorg the database, talk to other shelfelves, &c. ...

+ connect to your shelfelf-webserver with a browser
  on the ipad click "add to home screen" in safari, because when you launch
  it from the homescreen, it will be fullscreen ...and look quite native
  on android devices you need to add the shelfelf web site to your favourites
  and add it to the homescreen afterwards ...to get the shelfelf icon

+ edit your /path/to/shelfelf/shelfelf.conf.php if you want to,
  for a complete list of options look at /path/to/shelfelf/php/inc_config.php

optional, but recommended:
+ extract the album covers from your mp3-files
  bin/mp32jpg.sh /path/to/your/music
  extracts a _.jpg into folders, where *01*.mp3 contains an image
  (you will need eyed3, a python-id3tag-tool).


~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
thanks giving
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

as usual i did not write everything from scratch, so i want to thank:
+ linux + getid3 + xmms2swi + imageflow + gotproject + eyed3 + squeezephpapi
+ itunes + mpd + squeezebox + xmms2 + ...


~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
have fun!
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

vaubeh