Martin McBride, 2021-09-10
Tags python open source github pysound
Categories pysound pysound reference

Pysound reference

Pysound is a simple sound synthesis library written in Python.

Pysound is open-source, and the code is available on github. You can also download it from PyPi, see the version information.

This section is a reference guide for Pysound, defining all the components in the library. For a beginner's guide to using Pysound, see the tutorial.

Pysound modules

Pysound is divided into several modules:

  • buffer - functions for creating and manipulating buffers and buffer parameters.
  • const - some useful constants.
  • oscillators - creating basic tones.
  • soundfile - reading and writing sounds to file.
  • envelopes - creating time varying signals.
  • mixers - mixing sounds in various ways.
  • sequencers - combining a set of sounds as a sequence.
  • effects - special effects that can be applied to sounds.
  • graph - plots sound functions.

Overview of operations

One of the main aims of Pysound is to keep the sound generation code as simple as possible, so that it is easy to build your own sound processing functions to use within the framework for creating experimental sounds.

Uses include:

  • Sound design.
  • Instrument design.
  • Creating complex solos, controlling many parameters of the sound with custom functions.

With that aim in mind. Pysound makes a few compromises:

  • It is mono only, it does not create or process stereo sound. This is because handling stereo would complicate the processing function for little benefit. Stereo is almost always applied during mixing. If you really want to do clever things with multiple channels, it is possible to create two or more separate mono sounds.
  • The sound is stored entirely in memory, and fully processed by each component before it is passed on to the next. This again makes the code a lot simpler. It is aimed at a typical situation where sounds are fairly short. On most computers you will be able to handle sounds that are a few minutes long without problems.
  • As a consequence of the previous limitation, Pysound isn't suitable for live coding. It just isn't what it is designed for.

Design overview

Pysound uses NumPy arrays to store sound data during processing. Sound is stored as a 1 dimensional float array.

A BufferParams object stores the length and sample rate of the buffer. It is passed separately.

An advantage of using NumPy arrays to represent sounds is that we can apply NumPy vectorised operators. For example if a and b are two sound objects, we can create a new object that is the sum of the two sounds simply using a + b. This will create a new NumPy array that is the element-wise sum of the two sounds.

Most sound processing components are simple functions that create a NumPy array as output.

In most cases, the input to a sound component can either be a numerical value, or a sound buffer. So for example:

  • If we pass the value 400 is as the frequency parameter of a sine wave generator, it will create a tone with a fixed frequency.
  • If instead we pass in a Numpy array, the frequency of the sine wave can be made to vary over time.

This is the basic mechanism for linking different components to create complex sounds.

Join me on substack to keep up to date with this blog