Skip to main content
Warning: You are using the test version of PyPI. This is a pre-production deployment of Warehouse. Changes made here affect the production instance of TestPyPI (
Help us improve Python packaging - Donate today!

A _pluggable playback _queue service

Project Description

Tinnitus is a media player and playback queue.

It comes in two parts, service and remote. Once the tinnitusd service is running, the Python remote can be used to manipulate the queue and control playback. tinnitusd uses pluggable backends, which makes it easy to extend. Tinnitus is thread-safe, meaning it can be accessed by any number of remotes at once.


Please report any bugs over at <>


Prerequisites: git, pip and setuptools

Get tinnitus via git:

git clone

cd tinnitus

Optinal: Activate the virtualenv you want to install tinnitus to.

virtualenv .tinnitus

. .tinnitus/bin/activate

Install tinnitus using pip and setuptools:

pip install -e .

For a global installation (not using virtualenv), you’ll most likely have to be root.

Running the service

After installing tinnitus, you can start the service with:

tinnitusd [port]

port is an optional parameter, by default, tinnitus runs on port 18861.

If you’ve installed tinnitus to a virtualenv, make sure to activate it first.


To use the remote in your own project, install tinnitus to the same environment you’re developing your project in.

You can then use the remote with the contextmanager protocol:

from tinnitus import remote

with remote() as r:

You can also configure the remote to use a different network configuration:

import tinnitus

tinnitus.configure(host="localhost", port=1337)

Supported actions are:

r.add(resource_id, mrl, backend)

Adds an audio resource to the queue.

resource_id is an int identifying each resource unqiuely.

mrl is a str containing the resource’s location (and protocol)

backend is the name of the backend which should handle the resource


Removes an audio resource from the queue.

resource_id is an int identifying each resource unqiuely.

Removes all resources from the queue.
Returns the resource_id of the currently playing resource.
Returns the resource_id s of all queued resources as a list.
Starts playback, if the backend is paused or stopped.
Pauses playback, if the backend is playing.
Stops playback, if the backend is playing or stopped.
Skips forward to the next queued resource and starts playing.

Returns the backend’s status as either PLAYING, PAUSED or STOPPED.

The Status enum is defined in tinnitus.Status

Pluggable backends

Playback is handled by pluggable backends.

Tinnitus by default comes with a simple backend using libvlc. It is both versatile and serves as an example for the plugin structure.

Plugins are Python packages (directories containing an

In order to create a plugin called my_backend, follow these steps from the repo’s root directory:

cd plugins

mkdir my_backend


Your plugin should expose the following methods at module level (they should be located in, for it to be recognized by the service:


Called before the plugin is used for the first time.

Use this method to perform any initialisation, if needed.

callback is a method which your plugin should call once a resource has reached it’s end, save it somewhere.


Called when a resource is loaded for playback. It passes the resources to your plugin so that your plugin can perform any setup needed to play the resource with the given mrl.

mrl is the resources location (and protocol)


Called when your plugin should start playing the resource given by set_mrl.

Note: The method should be non-blocking.


Called when your plugin should pause playback of the resource.

Note: The method should be non-blocking.


Called when your plugin should stop playback of the resource.

Note: The method should be non-blocking.

Release History

Release History

This version
History Node


Download Files

Download Files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

File Name & Checksum SHA256 Checksum Help Version File Type Upload Date
tinnitus-0.1.tar.gz (6.6 kB) Copy SHA256 Checksum SHA256 Source Feb 21, 2017

Supported By

WebFaction WebFaction Technical Writing Elastic Elastic Search Pingdom Pingdom Monitoring Dyn Dyn DNS Sentry Sentry Error Logging CloudAMQP CloudAMQP RabbitMQ Heroku Heroku PaaS Kabu Creative Kabu Creative UX & Design Fastly Fastly CDN DigiCert DigiCert EV Certificate Rackspace Rackspace Cloud Servers DreamHost DreamHost Log Hosting