tinnitus 0.1

A pluggable playback queue service

Info:

See <https://github.com/strangedev/tinnitus>.

Author:

Noah Hummel <[e-mail]>

Date:

2017-02-21

Revision:

1

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.

Note

Please report any bugs over at <https://github.com/strangedev/tinnitus/issues>

Setup

Prerequisites: git, pip and setuptools

Get tinnitus via git:

git clone https://github.com/strangedev/tinnitus.git

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.

Remote

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:
    print(r.status())

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
r.remove(resource_id)	Removes an audio resource from the queue. resource_id is an int identifying each resource unqiuely.
r.clear()	Removes all resources from the queue.
r.current()	Returns the resource_id of the currently playing resource.
r.queue()	Returns the resource_id s of all queued resources as a list.
r.play()	Starts playback, if the backend is paused or stopped.
r.pause()	Pauses playback, if the backend is playing.
r.stop()	Stops playback, if the backend is playing or stopped.
r.play_next()	Skips forward to the next queued resource and starts playing.
r.status()	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 __init__.py).

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

cd plugins

mkdir my_backend

touch __init__.py

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

init(callback)	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.
set_mrl(mrl)	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)
play()	Called when your plugin should start playing the resource given by set_mrl. Note: The method should be non-blocking.
pause()	Called when your plugin should pause playback of the resource. Note: The method should be non-blocking.
stop()	Called when your plugin should stop playback of the resource. Note: The method should be non-blocking.