Block based synthesis and music library
Project description
Klang
Block based synthesis and music library for Python. Klang is German for sound.
Getting Started
Prerequisites
We use Python bindings for PortAudio and RtMidi. On Mac they can be installed via Homebrew.
Installing
Klang can be installed via PyPi / pip or directly via setup.py. Note that there is a C extension which needs to be compiled (klang/audio/_envelope.c
). C extensions can be compiled in place with:
python3 setup.py build_ext --inplace
For developing you can link your working copy with
python3 setup.py develop
Running the tests
Tests can be run via with
python3 setup.py test
Safety First
As always when programming with sound: Unplug your headphones or be very sure of what you are doing! Also with low headphone volume bugs in the code can result in very unpleasant loud noises which could probably impair your hearing. Be careful!
Klang Primer
Klang provides various audio related blocks. Every block can have multiple in- and outputs and by connecting them with each other we can define our network. Once we are finished with patching we can run our network with by calling run_klang(*blocks)
. This function only needs some blocks which belong to the network. It will then automatically discovers the other blocks of the network and deduce an appropriate block execution order.
In the following script we create a 440 Hz sine oscillator which output gets send to the sound card.
from klang.audio import Oscillator, Dac
from klang.klang import run_klang
# Init blocks
osc = Oscillator(frequency=440.)
dac = Dac(nChannels=1)
# Define network
osc.output.connect(dac.input)
# Run it
run_klang(dac)
Audio can be written to disk as a WAV file with the filepath
argument.
run_klang(*blocks, filepath='some/filepath.wav')`
Connections
There are two different connection types in Klang:
- Value (
Input
andOutput
classes) - Message (
MessageInput
andMessageOutput
classes)
Value based connections can hold any kind of Python object as value. Message connections have an internal queue.
The former is mostly used to propagate audio samples and modulation signals through the network (Numpy arrays as values). The latter is used for discrete messages like note messages.
There are also corresponding Relay connections (Relay
and MessageRelay
classes). These are used to build composite blocks (blocks which contain there own network of child blocks). Relays can be used to interface between the inside and outside of an composite block.
Defining The Network
The connect
method can be used to connect inputs and outputs with each other. Note that it is always possible to connect one output to multiple inputs but not the other way round. As a shorthand there are two overloaded operators:
- Pipe operator
|
: Connect multiple blocks in series. - Mix operator
+
: Mix multiple value outputs together.
# Pipe operator
a | b | c
# Is equivalanet to:
# >>> a.output.connect(b.input)
# ... b.output.connect(c.input)
# Mix operator
mixer = a + b + c
# Is equivalanet to:
# >>> mixer = Mixer(nInputs=0)
# ... mixer.add_new_channel()
# ... a.output.connect(mixer.inputs[-1])
# ... mixer.add_new_channel()
# ... b.output.connect(mixer.inputs[-1])
# ... mixer.add_new_channel()
# ... c.output.connect(mixer.inputs[-1])
Examples
See the examples/
directory with a couple example script which illustrate the core functionality of Klang. Currently there are:
hello_world.py
: 440 Hz sine wave generatorarpeggiator_demo.py
: Two synthesizer patch with an arpeggiator and some sound effectsaudio_file_demo.py
: Looped audio file playback (gong.wav
sample) with audio effectsmicro_rhythm_demo.py
: Kick and Hi-Hat pattern where the latter is phrased with a micro rhythmsequencer_demo.py
: Techno patch with sequencersynthesizer_demo.py
: This has to be started as root. Computer keyboard playable monophonic synthesizertempo_aware_effects.py
: Modulated noise with time synced effects
Coding Style
PEP8 / Google flavored. With the one exception for variable and argument names (camelCase
). Function and in methods are snake_case()
.
Author
- Alexander Theler - GitHub
Acknowledgments
Thanks for the support and inputs!
- Nico Neureiter GitHub
- Andreas Steiner Smoke And Mirrors
- Lawrence Markwalder GitHub
Project details
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for klang-0.1.3-cp37-cp37m-macosx_10_13_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | a7e0150b01e9269cc3577e56abd41c8a04fcd1423d5a255d2046c2264e91a4de |
|
MD5 | d2181f70a6a2b7ab7b40635226c9097b |
|
BLAKE2b-256 | 60174f18b7e5bbcb530e0493de666e5ce9395063133b0e6fea5a1d07469206ea |