What is Shiva?
The Mozilla Hacks blog kindly published a nice article that explains the ideas that inspire this software: Shiva: More than a RESTful API to your music collectionPrerequisites
You are going to need:- ffmpeg
- libxml C headers
- python headers
- sqlite (optional)
This makes the whole indexing slower because issues a request on a per-album and per-artist basis, but does a lot of work automatically for you.
By default Shiva uses a SQLite database, but this can be overriden.
To install all the dependencies on Debian (and derivatives):
sudo apt-get install libxml2-dev libxslt-dev ffmpeg python-dev sqliteIf at some point of the installation process you get the error:
/usr/bin/ld: cannot find -lzYou also need the package lib32z1-dev
On Mac OS X with homebrew you can get the libxml headers with:
brew install libxml2 libxsltOn Mac OS X sqlite should come pre-installed. If it's not:
brew install sqlite
Installation
- Get the source:
$ git clone https://github.com/tooxie/shiva-server.git
$ cd shiva-server
- Create and activate your virtalenv (highly recommended):
$ virtualenv .virtualenv
$ source .virtualenv/bin/activate
- Install:
$ python setup.py develop
- Rename shiva/config/local.py.example to local.py:
$ cp shiva/config/local.py.example shiva/config/local.py
- Edit it and configure the directories to scan for music.
- See Scanning directories for more info.
- Run the indexer:
$ shiva-indexer
- Run the file server:
$ shiva-fileserver
- Run the server in a different console:
$ shiva-server
- Point your browser to a Resource, like: http://127.0.0.1:9002/artists (See Resources)
Installation using pip
You can install Shiva through pip, running the following command:$ pip install shiva
Note: This will install the latest release, which may contain bugs and lack some features. It is highly recommended that you install the latest development version, following the manual installation guide above.
Configuring
Shiva looks for config files in the following places:- config/local.py relative to the directory where Shiva is installed.
- If an environment variable $SHIVA_CONFIG is set, then is assumed to be pointing to a config file.
- $XDG_CONFIG_HOME/shiva/config.py which defauls to $HOME/.config/shiva/config.py.
DEBUG
It's possible to load settings specific for debugging. If you have the following in any of your config files:DEBUG = True
- config/debug.py relative to the directory where Shiva is installed.
- $XDG_CONFIG_HOME/shiva/debug.py which defauls to $HOME/.config/shiva/debug.py.
Indexing
The indexer receives the following command line arguments.- --lastfm
- --hash
- --nometadata
- --reindex
- --write-every=<num>
When --hash is present, Shiva will hash every file using the md5 algorithm, in order to find duplicates, which will be ignored. Note that this will decrease indexing speed notably.
The --nometadata option saves dummy tracks with only path information, ignoring the file's metadata. This means that albums and artists will not be saved, but indexing will be as fast as it gets.
If both the --nometadata and --lastfm flags are set, --nometadata will take precedence and --lastfm will be ignored.
With --reindex the whole database will be dropped and recreated. Be careful, all existing information will be deleted. If you just want to update your music collection, run the indexer again without the --reindex option.
The indexer is optimized for performance; hard drive hits, like file reading or DB queries, are done as few as possible. As a consequence, memory usage is quite heavy. Keep that in mind when indexing large collections.
To keep memory usage down, you can use the --write-every parameter. It receives a number and will write down to disk and clear cache after that many tracks indexed. If you pass 1, it will completely ignore cache and just write every track to disk. This has the lowest possible memory usage, but as a downside, indexing will be much slower.
It's up to you to find a good balance between the size of your music collection and the available RAM that you have.
Restricting extensions
If you want to limit the extensions of the files to index, just add the following config to your local.py file:ALLOWED_FILE_EXTENSIONS = ('mp3', 'ogg')
Scanning directories
To tell Shiva which directories to scan for music, you will have to configure your shiva/config/local.py file. There you will find a MEDIA_DIRS option where you need to supply MediaDir objects.This object allows for media configuration. By instantiating a MediaDir class you can tell Shiva where to look for the media files and how to serve those files. It's possible to configure the system to look for files on a directory and serve those files through a different server.
MediaDir(root='/srv/http', dirs=('/music', '/songs'),
url='http://localhost:8080/')
If just a dir is provided you will also need to run the file server, as mentioned in the installation guide. This is a simple file server, for testing purposes only. Do NOT use in a live environment.
MediaDir('/home/fatmike/music')
