KAudio Python Library

From vjmedia
Revision as of 04:27, 5 May 2015 by Kdmccormick (talk | contribs) (Demo Video)

KAudio is an experimental proof-of-concept audio processing library for Python. It allows users to generate audio signals, load audio from files, apply various effects to the audio, and then play it back. It is not currently a finished product, and it is not intended to be used in a production environment.

Installation

Requirements:

  • Python 2.7.x
  • NumPy 1.8.2 or greater
  • PyAudio 0.2.8 or greater

Setup:

  • Download the latest version of kaudio.py from the GitHub page.
  • Place it in the same folder as the module from which you wish to use KAudio

Use

import kaudio
kaudio.init()
 
// your code here
 
kaudio.terminate()

Documentation

The two fundamental data types in KAudio are Signals and Effects. Signals represent a stream of audio data, either from a file or generated programmatically. Effects represent machines that take in signals and maniupulate them. Examples include Amplifiers, Compressers, and Faders.

Signal Constructors

SignalFromAudioFile(fpath, loop=False)
    fpath (str)  : file path to a 2-channel, uncompressed PCM .WAV file
    loop  (bool) : loaded audio is looped if True, else is played just once
Wave(wave_type, freq, amplitude, loop=True)
    wave_type (int)   : shape of wave. See WaveType constants
    freq      (float) : frequency of wave in hertz
    amplitude (int16) : maximum amplitude of wave on a scale of 0 to 2^15 - 1
    loop      (bool)  : if True plays indefinitely, else plays exactly one period
CompositeSignal(*signals)
    signals (Signal[]) : argument list of signals to be averaged together to form a new signal

Signal Methods

play()
    starts playing the signal to default audio output
pause()
    stops playing the signal, but preserves its state
rewind()
    resets the signal to its original state
is_playing()
    returns whether or not the signal is currently being played
add_effect(e)
    e (Effect) : the effect to be applied to this signal
remove_effect(e)
    e (Effect) : the effect to be removed from this signal

Effect Constructors

Amplifier(gain)
    gain (float) : factor by which the signal's amplitude will be scaled
Fader(left_gain, right_gain)
    left_gain  (float) : factor by which the amplitude of the signal's left channel will be scaled
    right_gain (float) : factor by which the amplitude of the signal's right channel will be scaled
ComplexFader(l_to_l, l_to_r, r_to_l, r_to_r)
    Similar to fader, but allows redirection of one channel's data to another
    l_to_l (float) : factor by which signal's left channel will be scaled and outputted to the new signal's left channel
    l_to_r (float) : factor by which signal's left channel will be scaled and outputted to the new signal's right channel
    r_to_l (float) : factor by which signal's right channel will be scaled and outputted to the new signal's left channel
    r_to_r (float) : factor by which signal's right channel will be scaled and outputted to the new signal's right channel
Overdriver(gain, cutoff)
    Distorts the given signal
    gain   (float) : factor by which the signal's amplitude will be scaled
    cutoff (int16) : absolute value at which the amplitude of the wave will be clipped off
Oscillator(freq, gain)
    Amplifies and attenuates the given signal in a periodic fashion
    freq      (int)   : frequency of the oscillation in Hertz
    amplitude (float) : maximum gain/attenuation factor throughout cycle
Compressor(low_thresh, low_factor, high_thresh, high_factor)
    low_thresh  (int16) : maximum amplitude threshold for upward scaling
    low_factor  (float) : factor by which samples below low_thresh are scaled upwards
    high_thresh (int16) : minimum amplitude threshold for downward scaling
    high_factor (float) : factor by which samples below high_thresh are scaled downwards

Effect Methods

Effects do not have any methods that are intended for outside modules to use. However, you may safely modify the values you passed in as constructor parameters (Fader.left_gain, Oscillator.freq, etc.), and the changes will take place in real time.

Other

 init()
     Initializes PyAudio library; must be called before using KAudio
 terminate()
     Terminates PyAudio library; should be called when finished using KAudio
 set_chunk_size(val)
     val (int) : the number of frames to be written to the output stream at a time
 WaveTypes constants for passing into Wave constructor:
     WaveType.SINE
     WaveType.SQAURE
     WaveType.TRIANGLE
     WaveType.SAWTOOTH

Demo Video

The media player is loading...