Skip to content
Back to top

# Python module base class

All the Python DSP modules are based on a common base class. In order to keep the documentation short, all Python classes in the previous sections only had the `process` method described, and control methods where necessary. This section provides the user with a more in-depth information of the Python API, which may be useful when adding custom DSP modules.

Some classes overload the base class APIs where they require different input data types or dimensions. However, they will all have the attributes and methods described below.

The process methods can be split into 2 groups:

1. `process` is a 64b floating point implementation

2. `process_xcore` is a 32b fixed-point implementation, with the aim of being bit exact with the C/assembly implementation.

The `process_xcore` methods can be used to simulate the xcore implementation precision and the noise floor. The Python `process_xcore` implementations have very similar accuracy to the xcore C `adsp_*` implementations (subject to the module and implementation). Python simulation methods tend to be slower as Python has a limited support for the fixed point processing. Bit exactness is not always possible for modules that use 32b float operations, as the rounding of these can differ between C libraries.

There are 3 layers of `process` functions:

1. `process` operates for a single sample on a single channel

2. `process_channels` operates on all channels for a single sample

3. `process_frame` operates on all samples and channels for a single frame.

A DSP module may overload one or all of these, depending if it operates sample-wise, channel-wise or frame-wise. It is expected that `process_frame` will be called by higher level DSP Stages.

class audio_dsp.dsp.generic.dsp_block(fs, n_chans, Q_sig=27)

  Generic DSP block, all blocks should inherit from this class and implement it’s methods.

  By using the metaclass NumpyDocstringInheritanceInitMeta, parameter and attribute documentation can be inherited by the child classes.

  Parameters:
    fs int

      Sampling frequency in Hz.

    n_chans int

      Number of channels the block runs on.

    Q_sig: int, optional

      Q format of the signal, number of bits after the decimal point. Defaults to Q4.27.

  Attributes:
    fs int

      Sampling frequency in Hz.

    n_chans int

      Number of channels the block runs on.

    Q_sig: int

      Q format of the signal, number of bits after the decimal point.

  freq_response(nfft=32768)

    Calculate the frequency response of the module for a nominal input.

    The generic module has a flat frequency response.

    Parameters:
      nfft int, optional

        The number of points to use for the FFT, by default 512

    Returns:
      tuple

        A tuple containing the frequency values and the corresponding complex response.

  process(sample: float, channel=0)

    Take one new sample and give it back. Do no processing for the generic block.

    Parameters:
      sample float

        The input sample to be processed.

      channel int, optional

        The channel index to process the sample on. Default is 0.

    Returns:
      float

        The processed sample.

  process_channels(sample_list: list[float]) → list[float]

    Process the sample in each audio channel using floating point maths.

    The generic implementation calls self.process for each channel.

    Parameters:
      sample_list list[float]

        The input samples to be processed. Each sample represents a different channel

    Returns:
      list[float]

        The processed samples for each channel.

  process_channels_xcore(sample_list: list[float]) → list[float]

    Process the sample in each audio channel using fixed point maths.

    The generic implementation calls self.process_xcore for each channel.

    Parameters:
      sample_list list[float]

        The input samples to be processed. Each sample represents a different channel

    Returns:
      list[float]

        The processed samples for each channel.

  process_frame(frame: list)

    Take a list frames of samples and return the processed frames.

    A frame is defined as a list of 1-D numpy arrays, where the number of arrays is equal to the number of channels, and the length of the arrays is equal to the frame size.

    For the generic implementation, just call process for each sample for each channel.

    Parameters:
      frame list

        List of frames, where each frame is a 1-D numpy array.

    Returns:
      list

        List of processed frames, with the same structure as the input frame.

  process_frame_xcore(frame: list)

    Take a list frames of samples and return the processed frames, using an xcore-like implementation.

    A frame is defined as a list of 1-D numpy arrays, where the number of arrays is equal to the number of channels, and the length of the arrays is equal to the frame size.

    For the generic implementation, just call process for each sample for each channel.

    Parameters:
      frame list

        List of frames, where each frame is a 1-D numpy array.

    Returns:
      list

        List of processed frames, with the same structure as the input frame.

  process_xcore(sample: float, channel=0)

    Take one new sample and return 1 processed sample.

    For the generic implementation, scale and quantize the input, call the xcore-like implementation, then scale back to 1.0 = 0 dB.

    Parameters:
      sample float

        The input sample to be processed.

      channel int, optional

        The channel index to process the sample on. Default is 0.

    Returns:
      float

        The processed output sample.