Documentation Department
Installation
Coherence is still a bit cumbersome to install, as there are a lot of dependencies.
Debian and derivatives
If you are lucky, an apt-get install python-coherence is sufficient. ;-)
For Python 2.5:
apt-get install python2.5 apt-get install python-twisted-core apt-get install python-twisted-web apt-get install python-configobj
For Python 2.4:
apt-get install python2.4-elementtree python2.4-celementtree apt-get install python2.4-ctypes
Ubuntu 10.04 (Lucid)
Might already be installed by default. If not:
sudo apt-get install python-coherence
will install coherence-0.6.4 with all dependcies. (Version might change for the Lucid final)
Ubuntu 9.10 (Karmic)
Might already be installed by default. If not:
sudo apt-get install python-coherence
will install coherence-0.6.4 with all dependcies.
Ubuntu 9.04 (Jaunty)
Might already be installed by default. If not:
sudo apt-get install python-coherence
will install coherence-0.6.2 with all dependcies.
There's also porthose's PPA for Jaunty. See instructions there on how to add it to your repository list.
Ubuntu 8.10 (Intrepid)
Intrepid includes Coherence-0.5.6 in the repos. It's adviced to install the dependcies and then Coherence from svn or tarball.
aptitude install python-setuptools python-twisted python-axiom python-tagpy aptitude install gstreamer0.10-plugins-bad gstreamer0.10-plugins-ugly gstreamer0.10-plugins-bad-multiverse gstreamer0.10-plugins-ugly-multiverse python-gst0.10
Gentoo
Follow this guide for creating and using a local overlay. Use the latest ebuild attached to this #246166 bug.
'media-video' is a good place to put for now. Once you've emerged coherence, you need to add the /etc/init.d script from the bug above or use this alternative:
/etc/init.d/coherence:
#!/sbin/runscript
# Copyright 1999-2009 Gentoo Foundation
# Distributed under the terms of the GNU General Public License v2
# $Header: $
# Coherence 0.6.4 Gentoo GNU/Linux init.d script
# by Abric Luc <luc@omega-consulting.fr>
depend() {
need net
after bootmisc
}
start() {
ebegin "Starting ${SVCNAME}"
PIDFILE="${PIDFILE:-/var/run/coherence.pid}"
CONFIGFILE="${CONFIGFILE:-/etc/coherence/coherence.conf}"
if [ ! -r "${CONFIGFILE}" ]; then
eerror "Unable to read configuration file: ${CONFIGFILE}"
return 1
fi
start-stop-daemon --start --exec /usr/bin/coherence --pidfile ${PIDFILE} --background -- -c ${CONFIGFILE}
eend $?
}
stop() {
ebegin "Stopping ${SVCNAME}"
start-stop-daemon --stop --exec /usr/bin/coherence
eend $?
}
/etc/conf.d/coherence:
#!/sbin/runscript # Copyright 1999-2009 Gentoo Foundation # Distributed under the terms of the GNU General Public License v2 # $Header: $ # Coherence 0.6.4 Gentoo GNU/Linux conf.d script # by Abric Luc <luc@omega-consulting.fr> # All commented variables are the default values # Configuration file location #CONFIGFILE="/etc/coherence/coherence.conf" # PID file location #PIDFILE="/var/run/coherence.pid"
As stated in the scripts the configuration file should be /etc/coherence/coherence.conf.
Now you're up and running!
Alternative: An installation guide for Gentoo - thanks to micxer
Mandriva
Outdated?
There are packages in the official Mandriva repository called "contrib". If you don't have it, please use "http://easyurpmi.zarb.org" or "drakrpm" to add it. Since the 2008.1 release, please just do
urpmi python-coherence
The sample configuration file is located in /usr/share/doc/python-coherence/
Archlinux
Outdated!
There is a subversion package of coherence in AUR http://aur.archlinux.org/packages.php?ID=18453
yaourt -S coherence-svn
openSUSE
Please provide more info about Versions of OpenSuse, etc.
Coherence is available from the Packman repository, this can be enabled by going to YaST-> Software Repositories-> Community Repositories, or via the command line (replace $RELEASE with your version of openSUSE)
zypper ar http://ftp.skynet.be/pub/packman/suse/$RELEASE/ Packman
There are three packages available: Coherence (the main service), Coherence-server (Runlevel script enabling server implementation) and Coherence-totem-plugin (the totem plugin). Either install from YaST or
zypper in Coherence Coherence-server Coherence-totem-plugin
Or download coherence-svn.tar.gz and build / install manually.
Most of the python packages can be installed via easy_install. The only two I needed to install manually were:
openBSD
[15-Oct-10] Now available in the development branch -CURRENT (see http://www.openbsd.org/cgi-bin/cvsweb/ports/multimedia/coherence/) and will be packaged in OpenBSD 4.7.
Via the CheeseShop
Alternatively most of the Python related packages can be installed via the CheeseShop:
easy_install ConfigObj easy_install ElementTree easy_install celementtree easy_install ctypes
Nevow doesn't work yet with easy_install, it has to be installed manually.
GStreamer related packages
Plus you probably want to install the GStreamer related packages, plugins and Python bindings which will be used by the MediaRenderer backend and for transcoding. Just look up your Distros package manager for GStreamer related packages.
Other distributions and platforms
- Installation on the Maemo platform
- Installation on Windows - thanks to lightyear
- Installation on (Open)Solaris thanks to Mike Lischke
Configuration
Network
Setup a multicast route for UPnP messages. In this example with eth0 as the interface.
route add -net 239.0.0.0 netmask 255.0.0.0 eth0
Config File
Coherence looks for a configuration file named .coherence in the $HOME of the user it is running under. If $HOME can't be determined, fallback is the current directory. Alternatively with the option -c|--configfile the location of the configuration file can be passed.
An example configuration file looks like this:
logmode = warning # none, critical, error, warning, info, debug
logfile = coherence.log
#interface = eth0 # necessary for hosts with multiple physical interfaces.
#serverport = 30020 # coherence will let the OS choose the port
# if this value is not specified or set to 0
#controlpoint = yes # if set to yes, coherence will activate its
# internal ControlPoint
web-ui = no # set this to yes to enable some interactive
# Web-UI
[plugins]
[[FSStore]]
content = tests/content # append more directories separated by commas
name = Coherence Test Content
[[GStreamerPlayer]]
name = GStreamer Audio Player
[[FlickrStore]]
name = Flickr Images
proxy = yes # if set to yes coherence will fetch the images
# from Flickr for your client
refresh = 60 # check every 60 minutes with Flickr for new images in the set
This configures coherence with an overall log level 'warning', printing out only messages with that or an higher level.
The serverport tells coherence which port to listen on for control requests and event subscriptions, to serve xml files and media content, and to check every 60 minutes for new images. Be sure to allow incoming connections on this port.
Three plugins are activated, a MediaServer filesystem backend with its own configuration options, a MediaRenderer and a MediaServer with the Flickr backend.
Newer versions of Coherence use an XML configuration file. Below is a sample configuration.
<config> <!-- valid log levels: none, critical, error, warning, info, debug --> <logging level="warning"> <!-- log file configuration. If there are no active log files, Coherence will log to stdout --> <logfile active="no">coherence.log</logfile> </logging> <!-- plugin definitions. See http://coherence.beebits.net/wiki/XMLConfig for more plugin options--> <plugin active="no"> <!-- location on the filesystem of the content. append more directories separated by commas --> <content>tests/content</content> <name>Coherence Test Content</name> <backend>FSStore</backend> </plugin> <plugin active="yes"> <name>GStreamer Audio Player</name> <backend>GStreamerPlayer</backend> </plugin> <!-- Set to 'yes' to enable Coherence's internal ControlPoint --> <controlpoint>no</controlpoint> <use_dbus>yes</use_dbus> <!-- Set to 'yes' to enable some interactive Web-UI --> <web-ui>no</web-ui> <!-- Coherence will let the OS select a port at random if this value is not specified or set to 0 --> <serverport>30020</serverport> <!-- Necessary for hosts with multiple network interfaces --> <interface>eth0</interface> </config>
Startup
For a quick test just populate the tests/content/audio with some mp3 files and call
/usr/bin/coherence -c path/to/coherence.conf.example
The MediaServer with the filesystem backend should show up on your UPnP client and you should be able to browse and access these files.
If you don't want to install Coherence into the Python module space, you can try it out in development mode.
python ./setup.py develop /usr/bin/coherence -c docs/coherence.conf.example python ./setup.py develop --uninstall # in the unlikely event of a sudden loss of cabin pressure
Backends
Backends are the places, where the device implementation within Coherence is interconnected with the outside world.
A backend has to provide information for Coherence about as what it tries to operate. As an example a backend which supplies a filesystem backend should label itself as most of the time as a MediaServer.
Hacking
API documentation
trunk API generated by pydoctor
Examples
Basic examples are available on the Examples wiki page. The LOLcats backend contains many helpful and descriptive comments for authoring new device backends.
Logging
Can be configured in the configuration file
logging can now be configured via the config file or through an environment variable COHERENCE_DEBUG, which overrides the config values.
Usage is like
- COHERENCE_DEBUG=*:3 emit INFO level messages from all modules
- COHERENCE_DEBUG=*:2,ssdp:4 WARNING level messages from all modules, plus debug level for the ssdp module
