The stream Module

A Stream object describes an audio source for decoding. The audio source can be a file or a TCP socket address (host, port). The audio source can then be decoded by passing the Stream object to client.server.Server.decodestreams.

For example, the following creates a stream from a wave file, and submits the Stream for decoding to the server:

server = Server("svserver")
stream = Stream("foo.wav")
server.decodestreams(stream)

Supported file formats wave and raw PCM. For raw audio files, parameters specifying the source’s format are required.

Stream methods do not refresh the decoding related attributes (status, start, end, stats, listeners) unless specifically noted (e.g. Stream.joinstart). To update a Stream to reflect the latest decoding state use Stream.refresh or client.server.Server.refreshstreams.

Note

When refreshing multiple streams it is much more efficient to use client.server.Server.refreshstreams than to refresh each stream seperately using Stream.refresh.

stream Methods

client.stream.createstreams(sources, **metadata)

Create and return Stream objects for each source in sources list. Any metadata fields specified will be set on all Streams created.

client.stream.createdirstreams(dirs, exts=None, filters=None, recursive=True, **metadata)

Create and return Stream objects for each audio file in the given directory (or list of directories). exts specifies the file extensions to include. When no exts are specified (the default) then all files will be included. Optional filters specify one or more regular expressions that full filenames must match to be included. If recursive is True (the default), subdirectories will be searched as well. Any metadata fields specified will be set on all Streams created.

stream Enumerations

client.stream.DecodeStatus

The Stream decoding status, one of QUEUED, ACTIVE, PAUSED, DONE, ERROR, CLOSED, or DELETED.

client.stream.Encoding

The audio source encoding, one of SPCM, UPCM, ULAW, or ALAW.

client.stream.Endian

The byte order, either LITTLE or BIG endian.

Stream Objects

class client.stream.Stream(source, **metadata)

A Stream describes an audio source for decoding.

The constructor creates a new Stream object with the given source and optional metadata. source can be a filename or socket address (‘hostname’, port), for example, Stream((“mymachine”, 4155)).

metadata is additional information to be associated with the audio source.

The following reserved metadata fields include:

samprate:sampling rate in Hz, between 8000 and 48000. Can suffix with ‘k’ for kHz. sampwidth:width of samples in bytes. sampwidth must be 1 for ULAW/ALAW sources. encoding:one of ‘SPCM’ (signed LPCM), ‘UPCM’ (unsigned LPCM), ‘ULAW’, ‘ALAW’ channels:number of audio channels (default 1) endian:byte order - ‘LITTLE’ or ‘BIG’ (default ‘LITTLE’)

For headerless sources, samprate and encoding must be specified. For headerless LPCM, sampwidth must also be specified.

start

date decode started

end

date decode ended

status

DecodeStatus for the Stream (one of QUEUED, ACTIVE, PAUSED, DONE, ERROR, CLOSED, or DELETED).

isqueued()

Return True if stream is queued for decoding.

isactive()

Return True if stream is being decoded.

ispaused()

Return True if stream decoding is paused.

isdone()

Return True if stream decoding has finished (for any reason).

iserror()

Return True if stream decoding was aborted due to an error.

isclosed()

Return True if stream decoding was manually aborted.

isdeleted()

Return True if stream was deleted.

sourcename()

Return name of source. Either base filename or <port>@<host>.

getfiletype()

Return the filetype, either ‘RAW’, ‘WAV’, or None.

fromfile()

Return True if Stream input is a file.

fromsocket()

Return True if Stream input is a socket.

fromwavfile()

Return True if Stream input is a WAV file.

fromrawfile()

Return True if Stream input is a RAW file.

size()

Return size of source in bytes if file else None.

encoding()

Return the source Encoding setting.

endian()

Return the source Endian setting.

sampwidth()

Return the source sample width in bytes.

samprate()

Return the source sample rate in Hz.

channels()

Return the number of channels in stream source.

refresh()

Refresh stream state.

joinstart()

Wait for stream decoding to start. Return True if started. Stream state is refreshed if not already started.

stats()

Return decoding stats for this stream.

sourceseconds()

Return seconds of source audio received by server or None.

listenerinfo()

Return info on who is listening to this stream.

pause()

Pause decoding stream. Return True if successful.

resume(fromtime=None)

Resume decoding stream. Return True if successful. The default is to resume from the pause. If fromtime is a datetime, resume stream from that time (up to current). If fromtime is -1, resume at current time.

close()

Stop decoding stream. Return True if successful.

delete()

Close stream and remove all decoding artifacts from server. Return True if successful.

tagsmatch(metadata)

Return True if all tags in given metadata exist and have the same values in this stream’s metadata.