Class reference

Python bindings for libsox

This are the python bindings for the library libsox, which is an audio manipulation library used by sox.

Quickstart

The most important classes are CSoxStream, CEffectsChain and CEffect. Using these classes all internal effects provided by libsox can be applied to audio files.

Using CNullFile, the effects requiring dummy input (such as synth) can also be used.

Please check out the examples provided with the source, they will set you up fast and easy.

Example

import pysox

def mktestfile():
    #open the nullfile to provide signal parameters: 48000kHz, 32bit on 2 channels
    #the nullfile produces an infinite amount of silence. So only to be used with
    # trim effect or synth, which has a length parameter
    nullfile = pysox.CNullFile()
    signal = nullfile.get_signal()
    #open an output file using the nullfiles signal parameters
    out = pysox.CSoxStream('test.wav', 'w', signal)

    #create the effect chain with input and output streams
    chain = pysox.CEffectsChain(nullfile, out)
    #add the synth effect to the chain, we use 3 seconds of sine sweep
    effect = pysox.CEffect("synth",[b'3', b'sine', b'300-3000'])
    chain.add_effect(effect)

    #process the effects chain, this applies all effecte on the input, producing the output
    chain.flow_effects()

    #cleanup
    out.close()
    #libsox internal cleanup takes place if we delete our chain or the script exits. So we are lazy here.

mktestfile()

class pysox.CEncodingInfo

Representation of struct sox_encodinginfo_t

Constructor to create an encodinginfo

class pysox.CEncodingInfo(CSoxEncoding.SIGN2, 32)

The optional positional arguments encoding, bits_per_sample can be given, in order to generate a static encodinginfo suitable to provide configuration data for streams.

CEncodingInfo.get_encodinginfo

get_encodinginfo()

Return a dictionary describing the encoding of the stream.

CEncodingInfo.set_param

set_param( [encoding=ecode] [, bits_per_sample=bps] )

Alter the given parameters of this encodinginfo.

ecode is the numeric encoding, see sox.h, enum sox_encoding_t for encodings. CEncodingInfo defines symbols for encoding as class attributes:

CSoxEncoding.UNKNOWN = 0 #,
CSoxEncoding.SIGN2 = 1   #, /* signed linear 2's comp: Mac */
CSoxEncoding.UNSIGNED = 2 #, /* unsigned linear: Sound Blaster */
CSoxEncoding.FLOAT = 3    #, /* floating point (binary format) */
CSoxEncoding.FLOAT_TEXT = 4 #, /* floating point (text format) */
CSoxEncoding.FLAC = 5     #, /* FLAC compression */
CSoxEncoding.HCOM = 6     #, /*  */
CSoxEncoding.WAVPACK = 7  #, /*  */
CSoxEncoding.WAVPACKF = 8 #, /*  */
CSoxEncoding.ULAW = 9     #, /* u-law signed logs: US telephony, SPARC */
CSoxEncoding.ALAW = 10     #, /* A-law signed logs: non-US telephony, Psion */
CSoxEncoding.G721 = 11     #, /* G.721 4-bit ADPCM */
CSoxEncoding.G723 = 12     #, /* G.723 3 or 5 bit ADPCM */
CSoxEncoding.CL_ADPCM = 13 #, /* Creative Labs 8 --> 2,3,4 bit Compressed PCM */
CSoxEncoding.CL_ADPCM16 = 14#, /* Creative Labs 16 --> 4 bit Compressed PCM */
CSoxEncoding.MS_ADPCM = 15 #, /* Microsoft Compressed PCM */
CSoxEncoding.IMA_ADPCM = 16#, /* IMA Compressed PCM */
CSoxEncoding.OKI_ADPCM = 17#, /* Dialogic/OKI Compressed PCM */
CSoxEncoding.DPCM = 18     #, /*  */
CSoxEncoding.DWVW = 19     #, /*  */
CSoxEncoding.DWVWN = 20    #, /*  */
CSoxEncoding.GSM = 21      #, /* GSM 6.10 33byte frame lossy compression */
CSoxEncoding.MP3 = 22      #, /* MP3 compression */
CSoxEncoding.VORBIS = 23   #, /* Vorbis compression */
CSoxEncoding.AMR_WB = 24   #, /* AMR-WB compression */
CSoxEncoding.AMR_NB = 25   #, /* AMR-NB compression */
CSoxEncoding.CVSD = 26     #, /*  */
CSoxEncoding.LPC10 = 27    #, /*  */

bps is the sample rate in bits per sample

class pysox.CSoxStream

Representation of struct sox_format_t

This class also has the capability of opening audio files for reading and writing and to retrieve their stream parameters such as encodinginfo and signalinfo.

Create a sox stream (sox_format_t)

class pysox.CSoxStream(path)

class pysox.CSoxStream(path, 'w', CSignalInfo signalInfo)

class pysox.CSoxStream(path, 'w', CSignalInfo signalInfo [, CEncodingInfo encodingInfo] [, fileType])

Constructor

Kwargs:

param String path:  The filename to read or write param String mode:  optional file mode ‘r’ or ‘w’, defaults to ‘r’ param CSignalInfo signalInfo:  required only for write mode to define the signal characteristics using the CSignalInfo class. param CEncodingInfo encodingInfo:  optional output encoding for write mode using the CEncodingInfo class. param String fileType:  optional, e.g. “wav” raises IOError:if the file cannot be opened raises TypeError:  if write mode is requested and the signalInfo is not given

CSoxStream.close

Close the stream

CSoxStream.get_encoding

retrieve the CEncodingInfo object representation of this streams encoding

Changes to the encoding’s parameters will change the stream’s encoding, too

CSoxStream.get_signal

retrieve the CSignalInfo object representation of this streams signal

Changes to the signal’s parameter will change the stream’s parameters, too

CSoxStream.open_read

open_read(path [, CSignalInfo signalInfo=None] [, CEncodingInfo encodingInfo=None] [, fileType=None])

open an audio file for reading

Raises:

IOError if file not existent

CSoxStream.open_write

open_write(path, CSignalInfo signalInfo [, CEncodingInfo encodingInfo=None] [, fileType=None])

Open this stream for writing

Args:

path

signalInfo

Kwargs:

encodingInfo

fileType

Raises:

TypeError if signalInfo is missing

IOError if the file cannot be opened

class pysox.CSignalInfo

Representation of struct sox_signalinfo_t

create a signalinfo descriptor

class pysox.CSignalInfo([rate, channels, precision] [,length])

If the parameters are given, the signalinfo is a static structure usable to provide signal data for streams.

CSignalInfo.get_signalinfo

Retrieve the details of the signal

Returns:

dict containing rate, channels, precision and length

CSignalInfo.set_param

alter the parameters of this signalinfo. Either of the kwargs can be given to set appropriate aspect.

Kwargs: rate: int

channels: int

precision: int

length: int

class pysox.SoxSampleBuffer

Python representation of a sox buffer memory area

Supports the PEP-3118 buffer interface and can be used within a memoryview object.

Additionally, __getitem__ and __setitem__ and the iterator interface are supported in order to access the buffer data using index operations

Kwargs:

data: default None, initialize the buffer with a bytarray, bytes or an array of integers. The data is being copied.

Raises:

TypeError if data is not bytes or an array

Raises:

TypeError if data is not bytes or an array

frombytes

replace our buffer with the contents of the bytearray

Args:

ba: bytearray

Raises:

BufferError if being held by a view

fromlist

replace our buffer with the contents of the array of integers

Args:

ba: array of integers e.g. [1,2,3,4]

Raises:

BufferError if being held by a view

get_buffer_size

return the size of this buffer in bytes. len(obj) defaults to this unless set_datalen has been called. In that case, len(obj) returns the number of valid bytes, whereas this function still returns the size of our buffer

recieved_flags

release_ok

set_datalen

set_readonly

tobytearray

return a bytearray object of the buffer.

The bytearray is a copy. Modifications will not reflect into the sox buffer

tolist

Return a list of this buffers items.

The list is a copy, changes will not reflect into the sox buffer

writebytes

fill our buffer with the contents of the bytearray

Args:

ba: bytearray

writelist

fill our buffer with the contents of the array of integers

Args:

ba: array of integers e.g. [1,2,3,4]

Raises:

IndexError if too much data is given

class pysox.CEffectsChain

The effectschain is the primary instrument of processing audio data. CEffectsChain is basically a wrapper around sox_effects_chain_t and provides methods to add effects, to start the processing (flow) and to set parameters on input and output.

Create an effect chain

Kwargs:

istream: CSoxStream input stream object

ostream: CSoxStream output stream object

add_effect

Add an effect to the chain

Args:

effect: CEffect object

flow_effects

Flow samples through the effects processing chain until EOF is reached.

Kwargs:

optimize_trim: boolean, default True

Raises:

PysoxError if configuration of chain is inconsistent

or chain is not valid anymore

class pysox.CPysoxPipeStream

Input stream analog to CSoxStream, but reading from a python:processes Pipe

Kwargs:

path: multiprocessing.Pipe socket endpoint

close

Close the stream

open_read

open_write

start_read

class pysox.CEffect

CEffect(“trim”, [ b‘2’, b‘4’])

Basic sox effect wraps all builtin effects. It is also used to derive custom effects by inheriting and overloading the create method.

Kwargs:

name: string of the effects name

arguments: array of effect arguments containing byte strings

Create a sox internal effect

optional parameters to initialize the effect: @param <string> name of the effect @param <[]> array of effect arguments @see create

get_in_encoding

retrieve the CEncodingInfo object representation of this streams in_encoding

get_in_signal

retrieve the CSignalInfo object representation of this streams in_signal

get_name

Retrieve the effect’s name

Returns:

string

get_out_encoding

retrieve the CEncodingInfo object representation of this streams in_encoding

get_out_signal

retrieve the CSignalInfo object representation of this streams out_signal

set_out_signal

class pysox.SocketOutput

SocketOutput(“output”,[connection])

Output the chain data to a multiprocess socket. Used as output effect at the end of a chain.

Args:

connection: multiprocessing Pipe of a process child

Example:

parent_conn, child_conn = Pipe()
output = SocketOutput("output", [child_conn])
chain = pysox.CEffectsChain()
chain.add_effect(output)
...

class pysox.CCustomEffect

Example custom effect usable as audio data input into a chain. CCustomEffect must be overloaded and the method callback is then used to provide audio input data.

Create a sox internal effect

optional parameters to initialize the effect: @param <string> name of the effect @param <[]> array of effect arguments @see create

drain

virtual function, must be overloaded

Args:

SoxSampleBuffer buffer_object: accessor to raw sox buffer using Buffer interface or container interface

Returns:

number of samples processed or 0 if end of file

flow

virtual function, must be overloaded

Args:

SoxSampleBuffer buffer_object: accessor to raw sox buffer using Buffer interface or container interface

Returns:

number of samples in obuf for next effect or 0 if this is the last effect (output)

Raises:

Exception if some error occured in order to stop processing

kill

Called when chain shuts down, after stop

Used to do final cleanups

start

Called when chain starts flowing

Used to do last setups

stop

Called when chain shuts down

Returns:

number of clipped samples

class pysox.PowerMixFiles

PowerMixFiles(“input”, [“test1.wav”, “test2.wav”])

Input effect provider for CEffectChain in order to mix multiple input files. This effect replaces the sox internal input effect.

Volumes are mixed down by 1/sqrt(n) where n is the number of inputs.

Clipping might occur here, but in most cases distortions are not susceptible.

class pysox.ConcatenateFiles

ConcatenateFiles(“input”, [“test1.wav”, “test2.wav”])

Input effect provider for CEffectChain in order to concatenate multiple input files. This effect replaces the sox internal input effect.

All audio data must be the same format (bitrate, channels, precision) The output’s length is the total length of all combined signals.

class pysox.MixFiles

MixFiles(“input”, [“test1.wav”, “test2.wav”])

Input effect provider for CEffectChain in order to mix multiple input files. This effect replaces the sox internal input effect.

Volumes are mixed down by 1/n where n is the number of inputs.

Clipping probably will not occur with this method, but the signal appears to be less loud than the originals.

The input files signals must be equal, meaning bitrate and channels must be equal. The signal’s length can be different, the output will get the length of the longest signal.

class pysox.CNullFile

nullstream = CNullFile()

The null input file, which produces an infinite amount of silence

Kwargs:

path: string

mode: string

signalInfo: CSignalInfo

if provided, these signal parameters are used. Otherwise the signal will be 48000 rate, 2 channels, 32 bits

encodingInfo: CEncodingInfo

if provided, use that encodingInfo, otherwise we’ll have 32bit signed integer PCM

fileType: string

Create the null input file, which produces silence of infinite length.

class pysox.CSoxApp(*files, **kwargs)

from pysox import CSoxApp
sapp = CSoxApp(input1, input2, output, nullparams=(44100,2,32) )
sapp.flow([ ('trim', [b'0',b'2']), ] )

or:

sapp = CSoxApp(input1, input2, input3, nullparams=(44100,2,32), effectparams=[('trim', [b'0',b'2']), ], output='output0' )
sapp.flow()

Args:

inputfile [, ...] outputfile

Kwargs:

effectparams: list(effectparam)

efectparam=( name, [arguments] )

nullparams: set(rate,channels,precision)

output: string

if given, all positional arguments are inputs, and this kwarg is the output. If output is pysox-chain, the audio will be piped to it’s input chain

If any inputfile is the string ‘null’, then CNullFile is used to generate silence with the nullparams as signal parameters.

flow(effectparams=None)

flow the chain created in setup

Kwargs:

effectparams=list(effectparam)