audio Package

audio Package

class, metadata=None)[source]

Bases: object

A class that should be returned from the function passed to Manager for file discovery.

This is to make switching functions easier since the Manager doesn’t need to know what format the function returns but only know that it returns a FileInformation instance instead.


Bases: dict

class, processors=None, options=None, handlers=None)[source]

Bases: object

A class that manages the audio pipeline. Each component gets a reference to the processor before it.


This is a very cruel pipeline and has specifics to our needs and is in no way a generic implementation.

Nor does it have proper definitions of what should go out or into a processor.

The Manager expects that all registered processors have at least the following characteristics:

start(): Called when Manager.start() is called. This should
initialize required components. The Manager expects that a call to close and start is close to equal of recreating the whole instance.
close(): Called when Manager.close() is called. This should
close down the processor cleanly and if potential long running cleanups are to be done should use the garbage sub package shipped with the audio package.
__init__(): Called when the Manager instance is created.

This should not start any state dependant parts, these should be done in the start method instead.

Gets passed one positional argument that is the previous processor in the chain. Or if the first processor read below.

Gets passed extra keyword arguments if specified in the class attribute options. Read more about this attribute below.

The current version expects the first specified processor to take a function as source argument. That can be called for the filepath of an audiofile. This first processor is responsible for opening it.


This means the processor doesn’t actually need to decode the file but that it is just expected to accept the function as source. What it does with the function is not important to the Manager.

The current version expects the last specified processor to have several methods available to be used by the Manager. These are:

status(): A method that is called when status() is called.
This should return something of significants to the user.
metadata(): A method that accepts a single unicode argument.
This is called whenever new metadata is found at the start of the processor chain.

Calls the close method on all registered processor instances.


Exceptions are propagated.

Returns unicode:
 A full file path to an audio file.

The value returned from Manager.source() is expected to be an FileInformation object. But there is one exception to this rule.

When Manager.source() returns a different type it will be used as the positional arguments to the FileInformation constructor by using the FileInformation(*returntype) syntax.

processors = [<class ''>, <class ''>, <class ''>]

A list of processors that are instanced in order and are passed their previous friend as first argument.


Calls the start method on all registered processor instances.

This method does nothing if a previous call to start() was successful but close() was not called in between the two calls.


Exceptions are propagated.


Calls the status method on the last processor in the chain.

If no method was found returns False instead.[source]'/media/F/Music', files=None)[source]

encoder Module

A very simple encoder module.

The encoders currently supported are listed below:

  • LAME MP3 encoder

Other formats would require a rework of this module to be more generic.

class, options, handlers)[source]

Bases: object

An Encoder class that handles the encoder subprocess underneath.

Right now this class only supports encoding by using a LAME mp3 encoder binary. Other formats are not supported.


This calls the EncoderInstance.close() method on the EncoderInstance.

options = [(u'lame_settings', [u'--cbr', u'-b', u'192', u'--resample', u'44.1'])]

This method is called by the EncoderInstance class when it gets closed or an error occurs in the instance. This should handle the case gracefully and even restart the instance if the close was unintentional by the user.

The method registers the EncoderInstance instance for garbage collection by the garbage module.


This method rather then restart, destroys and then recreates the underlying EncoderInstance instance.

settings = None

The settings for encoding to pass to lame as a list.


This clears our alive flag and starts a new EncoderInstance instance by calling start_instance().


This method is responsible for creating and starting the EncoderInstance class instances.

This creates a new EncoderInstance instance and calls the EncoderInstance.start() method on it.

After the call to ‘start’ returns the new instance is assigned to instance.


Bases: object

Class that represents a subprocessed encoder.

This is a non-generic class as of now and could be made generic and supporting different kind of format encoders. As of yet this only supports the LAME binary encoder.


This class is used internally and should never be instantiated directly by the user.

read(size=4096, timeout=10.0)[source]


A garbage object to be registered for EncoderInstance class instances.

collect()[source] = u'lame'

The path to the LAME binary. This can be just ‘lame’ on bash environments.

files Module

Module that handles file access and decoding to PCM.

It uses python-audiotools for the majority of the work done.


Bases: exceptions.Exception

Exception raised when an error occurs in this module.


Bases: object

A Simple wrapper around the audiotools library.

This opens the filename given wraps the file in a PCMConverter that turns it into PCM of format 44.1kHz, Stereo, 24-bit depth.


Registers self for garbage collection. This method does not close anything and only registers itself for colleciton.

progress(current, total)[source]

Dummy progress function

read(size=4096, timeout=0.0)[source]

Returns at most a string of size size.

The timeout argument is unused. But kept in for compatibility with other read methods in the audio module.

class, options, handlers)[source]

Bases: object

The FileSource class expects a function as source.

This function should return an absolute path to a supported audio file as an unicode or bytes object.

No options are supported for this class.

No handlers are supported for this class.


Calls the source function and returns the result if not None.


Sets the initial source from the source function.

read(size=4096, timeout=10.0)[source]

Starts the source



Garbage class of the AudioFile class


Tries to close the AudioFile resources when called.

icecast Module

A module that adds some extra useful wrapping around the libshout library.

class, options, handlers)[source]

Bases: object

The Icecast class expects a source that returns encoded MP3 audio data. Use of other formats as of now is not supported.

The source requires the following attributes:

A method that returns encoded MP3 audio data.

param size:An int signifying the amount of bytes to read.
returns:bytes containing the requested MP3 audio data.

We accept a single option that is a full fletched configuration for the underlying libshout library.

  • icecast_config:

    A dict containing the configuration for libshout. For the exact contents of the dictionary see IcecastConfig.

The following handler hooks are supported by Icecast.

  • icecast_start(icecast):

    Called when the Icecast.start() is called.

    param icecast:Icecast instance.
  • icecast_close(icecast):

    Called when the Icecast.close() is called.

    param icecast:Icecast instance.
  • icecast_connect(icecast, options):

    Called when Icecast.connect() is called.

    param icecast:Icecast instance.
    param options:IcecastConfig instance used.
  • icecast_metadata(icecast, metadata):

    Called when metadata is send to the server.

    param icecast:Icecast instance.
    param metadata:unicode instance containing the metadata send.

Closes the libshout object and tries to join the thread if we are not calling this from our own thread.


Connect the libshout object to the configured server.


Returns True if the libshout object is currently connected to an icecast server.

connecting_timeout = 5.0

The time to wait when we lose connection by cause of external behaviour.

options = [(u'icecast_config', {})]
read(size, timeout=None)[source]

Internal method

Tries to recreate the libshout object.


Internal method

Creates a libshout object and puts the configuration to use.


Starts the thread that reads from source and feeds it to icecast.


Tries to change the source without disconnect from icecast.


Bases: dict

Simple dict subclass that knows how to apply the keys to a libshout object.

The following dictionary items are supported:

  • host:

    The hostname of the icecast server to connect to. (defaults to localhost)

  • port:

    The port the icecast server is running on. (defaults to 8000)

  • user:

    The icecast user.

  • password:

    The password for the icecast server.

  • mount:

    The mountpoint to connect to.

  • format:

    The format we are going to stream in.

    Can be one of the following:
    • 0 = OGG encoded data.
    • 1 = MP3 encoded data.
  • protocol:

    The protocol to use to connect to the icecast server.

    Can be one of the following:
    • 0 = HTTP protocol
    • 1 = XAUDIOCAST protocol
    • 2 = ICY protocol

    If you are unsure of which one to use, you are most likely after the HTTP protocol.

  • name:

    An optional name to show on the icecast page.

  • url:

    An optional URL to be placed on the icecast page.

  • genre:

    An optional genre to be shown on the icecast page.

  • agent:

    The useragent to connect with. (defaults to libshout/version)

  • description:

    An optional small description to show on the icecast page.

  • charset:

    An optional charset to use for sending metadata. (defaults to UTF-8)

  • public:

    An optional boolean specifying if this stream is to be marked as public in icecast. (This affects indexing on external sites.)

  • dumpfile:

    A file to dump the streamed data to.

  • audio_info:

    Can be ignored, see libshout docs for info.

  • metadata:

    Can be ignored, see libshout docs for info.


Setup ‘shout’ configuration by setting attributes on the object.

‘shout’ is a pylibshout.Shout object.


Bases: exceptions.Exception

Project Versions

Table Of Contents

Previous topic

streamer Package

Next topic

garbage Package

This Page