Documentation Department

  1. Other distributions and platforms
  2. Via the Python Package Index
  3. Debian, Ubuntu and derivatives
  4. Mageia
  5. Mandriva
  6. Gentoo
  7. CentOS 5.5, Others(?)
  8. Archlinux
  9. openSUSE 11.2, 11.3, 11.4 and Factory
  10. openSUSE (other versions)
  11. openBSD
  12. Network
  13. Config File
    1. API documentation
    2. Examples
    3. Logging

Installation

Coherence is still a bit cumbersome to install, as there are a lot of dependencies.

Other distributions and platforms

Via the Python Package Index

For Python hackers Alternatively most of the Python related packages can be installed via the Python Package Index:

easy_install ConfigObj ElementTree celementtree ctypes

Nevow doesn't work yet with easy_install, it has to be installed manually.

Debian, Ubuntu and derivatives

Packages are available since Debian 5.0 ("lenny") and in Ubuntu universe since 8.04 (hardy). A simple

apt-get install python-coherence

is sufficient. ;-) This will install coherence-0.6.6 with all dependencies.

For Ubuntu it might even be already installed by default.

For Python 2.5:

apt-get install python-twisted-web  python-configobj

For Python 2.4:

apt-get install python2.4-elementtree python2.4-celementtree python2.4-ctypes

Mageia

Packages in the official Mageia repository. For installing the media-server use

urpmi coherence-mediaserver

The configuration file is located in /etc/coherence/.

If you only want to install the Python framework without setting up and running the media-server, use

urpmi python-coherence

Mandriva

There are packages in the official Mandriva "Contrib" repository. 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/

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

CentOS 5.5, Others(?)

This section will probably also work for any RHEL (Red Hat Enterprise Linux) or CentOS versions 5.x and 6.x, but it was only checked with CentOS 5.5.

Install the RPMForge repository via instructions at http://wiki.centos.org/AdditionalResources/Repositories/RPMForge

Then install the package:

yum install python-coherence

Archlinux

In Arch, coherence is packaged in a special kind of source repository called AUR. There are two ways to install it. The Proper Way and the Easy Way. The Proper Way involves downloading the tarball, running the makepkg command to get the source code and convert it to a package, and then running the pacman command to install the package. In this case, it is particularly hard because coherence has a ton of special prerequisites that would have to be manually downloaded and put through the same process.

Here's the Easy Way:

First, install yaourt using the following instructions: https://wiki.archlinux.org/index.php/Yaourt

The shorter, simpler way is to add the following two lines to the file "/etc/pacman.conf":

[archlinuxfr] 
Server = http://repo.archlinux.fr/$arch

And then run (as root) the command:

pacman -Sy yaourt

Then, to install coherence, run (as root) the command:

yaourt coherence

It should ask if you want the vanilla version or a version from git. It's probably better to choose the former.

Yaourt will ask a bunch of questions. If it finds a package that is unsupported by Arch, it will ask you if you want to edit the PKGBUILD. You can safely say No to these questions, but you should say Yes to any question where it asks if you wish to proceed or continue with installation.

If it presents you with a file conflict (this happened to me, but I might have answered one of those Yes/No questions incorrectly), you can force it with the following:

yaourt -f coherence

Note that forcing an installation can be dangerous.

For reference, the AUR page for coherence is here: https://aur.archlinux.org/packages.php?ID=23240

openSUSE 11.2, 11.3, 11.4 and Factory

openSUSE provides the python-coherence package in their standard "oss" repository. In 11.2 and 11.3, they are in architecture-specific directories (i586, x86_64). For 11.4 and Factory, the package was moved to the "noarch" directory. The following command will work in either case:

zypper install python-coherence

openSUSE (other versions)

Packman does not seem to contain these packages anymore. Please verify this statement and, if true, remove this subsection.

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-develop.zip 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.

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.

For example in Debian, you should install gstreamer0.10-plugins-bad gstreamer0.10-plugins-ugly python-gst0.10

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.

Note: These sample configs are depreciated albeit still work. It is prefered to use the new xml-style config. Please see XMLConfig for more information. The info on this page will soon be updated or merged.

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

Architectural Overview

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