splat

Fragment objects

class splat.Fragment(channels, rate, duration)

A fragment of sound data.

Create an empty sound fragment with the given number of channels, sample rate in Hertz and initial duration in seconds. If no duration is specified, the fragment will be empty. All the samples are initialised to 0 (silence).

All Splat sound data is contained in Fragment objects. They are accessible as a mutable sequence of tuples of floating point values to represent the samples of the audio channels. The length of each sample tuple is equal to the number of channels of the fragment, the maximum being fixed to 16.

n2s(n)

Convert a sample index number n into a time in seconds.

classmethod open(file_name, mode='r')

Open a file to create a sound fragment

Open a sound file specified by file_name and imports its contents into a new Fragment instance, which is then returned.

resize(duration)

Resize the fragment to the specified duration in seconds.

s2n(s)

Convert a time in seconds s to a sample index number.

save_to_file(file_name, sample_width=2, start=0, end=None)

Save the contents of the audio fragment to an audio file.

A file is created with the provided name file_name, and the contents of the audio fragment are written to it. The sample_width argument contains the resolution in bytes for each channels, which by default is 2 (16 bits).

Note: Only WAV files are currently supported.

It’s also possible to only save a part of the fragment using the start and end arguments with times in seconds.

Generator objects

class splat.Generator(frag, filters=None)

Generator to manage sound sources

This class needs to be sub-classed to implement splat.Generator.run() with a concreate sound source. It creates a splat.Fragment instance to store the generated and mixed sounds.

The frag argument must be a splat.Fragment instance.

A chain of filters can also be initialised here with a list of filter functions and internally create a splat.FilterChain() object. This can be altered later via splat.Generator.filters.

_run(source, start, end, *args, **kw)

Main method, designed to be invoked by sub-classes via splat.Generator.run()

The source argument is a sound source function (Sound sources), to which the *args and **kw arguments are passed on. The sound is supposed to start and end at the times specified by the start and end arguments.

channels

Number of channels

filters

The splat.FilterChain being used.

frag

splat.Fragment instance with the generated sounds

levels

Sound levels as a tuple in dB

run(start, end, *args, **kw)

Main abstract method to be implemented by sub-classes

This method is the main entry point to run the generator and actually produce some sound data. It will typically call splat.Generator._run() with a sound source and specific arguments.

sample_rate

Sample rate in Hz

time_stretch

Time stretch factor

All start and end times are multiplied by this value when calling splat.Generator.run().

class splat.SineGenerator(frag, filters=None)

Sine wave generator.

This is the simplest generator, based on the splat.sources.sine() source to generate pure sine waves.

The frag argument must be a splat.Fragment instance.

A chain of filters can also be initialised here with a list of filter functions and internally create a splat.FilterChain() object. This can be altered later via splat.Generator.filters.

class splat.OvertonesGenerator(*args, **kw)

Overtones generator.

Overtones are defined by an overtones dictionary. This uses the splat.sources.overtones() source.

Note: The time to generate the signal increases with the number of overtones n.

ot_decexp(k=1.0, n=24)

Set harmonic overtones levels following a decreasing exponential.

For a given ratio k and a harmonic i from 1 to a total number of harmonics n, the amplitude of each overtone is set following this function:

As a result, the fundamental frequency (overtone 1.0) always has an amplitude of 1.0 (0 dB).

A higher k value means the function will decrease faster causing less high-frequency harmonics.

Sound sources

splat.sources.sine(*args, **kwargs)

splat.sources.overtones(*args, **kwargs)

Filter functions and FilterChain objects

A filter function takes a splat.Fragment and a tuple of arguments with its specific parameters. It is expected to run on the entirety of the fragment. Filter functions can be combined into a series via the splat.FilterChain class.

class splat.FilterChain(filters=None, *args, **kw)

Chain of filters to process existing data

This class is used by the splat.Generator classes to define a chain of filter functions that are run on each newly created splat.Fragment instance from a sound source (Sound sources).

This class implements the collections.Sequence interface to hold a chain of filter functions. The initial filter functions are provided via the filters list. The idea is to be able to go through them in a specific order over a same audio fragment so the output of one filter is the input of the next.

append(filter_func, args=())

Add a filter function to the chain.

The filter function filter_func is added to the end of the chain, and the provided args tuple is associated with it to provide specific parameters when invoking it by splat.FilterChain.run`().

run(frag)

Run all the filter functions on a sound fragment.

All the filter functions in the chain are run with their associated arguments on the splat.Fragment argument frag.

splat.filters.linear_fade(frag, duration=0.01)

Apply a linear fade-in and fade-out on the fragment.

For the given duration in seconds, apply a gain that varies linearly from 0.0 to 1.0 and then from 1.0 to 0.0 respectively at the beginning and end of the fragment. This duration is adjusted evenly if the fragment is too short.

splat.filters.dec_envelope(*args, **kwargs)

splat.filters.reverse(*args, **kwargs)

splat.filters.reverb(*args, **kwargs)

General purpose functions

splat.lin2dB(*args, **kwargs)

splat.dB2lin(*args, **kwargs)