{"id":15070044,"url":"https://github.com/atheler/klang","last_synced_at":"2025-04-10T17:10:55.115Z","repository":{"id":62574349,"uuid":"265188974","full_name":"atheler/klang","owner":"atheler","description":"Block based synthesis and music library for Python","archived":false,"fork":false,"pushed_at":"2020-10-16T09:44:39.000Z","size":16928,"stargazers_count":21,"open_issues_count":1,"forks_count":1,"subscribers_count":2,"default_branch":"master","last_synced_at":"2024-04-26T18:04:23.023Z","etag":null,"topics":["adsr","dag","envelope","frequency-modulation","micro-rhythm","midi","music","music-composition","music-generation","music-library","music-theory","oscillator","python","python3","rhythm","synth","synthesizer","temperament","tuning","waveform"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/atheler.png","metadata":{"files":{"readme":"README.rst","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-05-19T08:24:54.000Z","updated_at":"2023-04-18T08:58:15.000Z","dependencies_parsed_at":"2022-11-03T20:42:37.732Z","dependency_job_id":null,"html_url":"https://github.com/atheler/klang","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/atheler%2Fklang","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/atheler%2Fklang/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/atheler%2Fklang/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/atheler%2Fklang/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/atheler","download_url":"https://codeload.github.com/atheler/klang/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248261343,"owners_count":21074221,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["adsr","dag","envelope","frequency-modulation","micro-rhythm","midi","music","music-composition","music-generation","music-library","music-theory","oscillator","python","python3","rhythm","synth","synthesizer","temperament","tuning","waveform"],"created_at":"2024-09-25T01:46:43.826Z","updated_at":"2025-04-10T17:10:55.093Z","avatar_url":"https://github.com/atheler.png","language":"Python","funding_links":[],"categories":["Music"],"sub_categories":["Programming"],"readme":"Klang\n=====\n\nBlock based synthesis and music library for Python. *Klang* is German for sound.\n\nGetting Started\n---------------\n\nPrerequisites\n^^^^^^^^^^^^^\n\nWe use Python bindings for `PortAudio \u003chttp://www.portaudio.com\u003e`_ and `RtMidi\n\u003chttps://www.music.mcgill.ca/~gary/rtmidi/\u003e`_. On Mac they can be installed via\n`Homebrew \u003chttps://brew.sh\u003e`_.\n\nInstalling\n^^^^^^^^^^\n\nKlang can be installed via PyPi / pip or directly via setup.py. Note that there\nare some audio C extensions. Python fallbacks exists.\n\n.. code-block:: bash\n\n    python3 setup.py build_ext --inplace\n\nFor developing you can link your working copy with\n\n.. code-block:: bash\n\n    python3 setup.py develop\n\nRunning the tests\n-----------------\n\nTests can be run via with\n\n.. code-block:: bash\n\n    python3 setup.py test\n\nSafety First\n------------\n\nAs always when programming with sound: Unplug your headphones or be very sure of\nwhat you are doing! Also with low headphone volume bugs in the code can result\nin very unpleasant loud noises which could probably impair your hearing. Be\ncareful!\n\nKlang Primer\n------------\n\nKlang provides various audio related blocks. Every block can have multiple in-\nand outputs and by connecting them with each other we can define our network.\nOnce we are finished with patching we can run our network with by calling\n`run_klang(*blocks)`. This function only needs some blocks which belong to the\nnetwork. It will then automatically discovers the other blocks of the network\nand deduce an appropriate block execution order.\n\nIn the following script we create a 440 Hz sine oscillator which output gets\nsend to the sound card.\n\n.. code-block:: python\n\n    from klang.audio import Oscillator, Dac\n    from klang.klang import run_klang\n\n    # Init blocks\n    osc = Oscillator(frequency=440.)\n    dac = Dac(nChannels=1)\n\n    # Define network\n    osc.output.connect(dac.input)\n\n    # Run it\n    run_klang(dac)\n\nAudio can be written to disk as a WAV file with the `filepath` argument.\n\n.. code-block:: python\n\n    run_klang(*blocks, filepath='some/filepath.wav')\n\nConnections\n^^^^^^^^^^^\n\nThere are two different types of connections in Klang:\n\nValue\n  These connection can hold any kind of Python object which will be propagated\n  through the network and updated during each cycle. Most commonly these are\n  numpy arrays holding audio or modulation signals (``Input`` and ``Output``\n  classes).\n\nMessage\n  Discrete messages. Each message input has its own internal message queue. Most\n  commonly ``Note`` messages (``MessageInput`` and ``MessageOutput`` classes).\n\nThere are also corresponding *Relay* connections (``Relay`` and ``MessageRelay``\nclasses). These are used to build composite blocks (blocks which contain there\nown network of child blocks). Relays can be used to interface between the inside\nand outside of an composite block.\n\nDefining The Network\n^^^^^^^^^^^^^^^^^^^^\n\nThe ``connect`` method can be used to connect inputs and outputs with each other.\nNote that it is always possible to connect one output to multiple inputs but not\nthe other way round. As a shorthand there are two overloaded operators:\n\n- Pipe operator ``|``: Connect multiple blocks in series.\n- Mix operator ``+``: Mix multiple value outputs together.\n\n.. code-block:: python\n\n    # Pipe operator\n    a | b | c\n\n    # Is equivalanet to:\n    # \u003e\u003e\u003e a.output.connect(b.input)\n    # ... b.output.connect(c.input)\n\n.. code-block:: python\n\n    # Mix operator\n    mixer = a + b + c\n\n    # Is equivalanet to:\n    # \u003e\u003e\u003e mixer = Mixer(nInputs=0)\n    # ... mixer.add_new_channel()\n    # ... a.output.connect(mixer.inputs[-1])\n    # ... mixer.add_new_channel()\n    # ... b.output.connect(mixer.inputs[-1])\n    # ... mixer.add_new_channel()\n    # ... c.output.connect(mixer.inputs[-1])\n\nExamples\n--------\n\nSee the ``examples`` directory with a couple example script which illustrate the\ncore functionality of Klang. Currently there are:\n\n- `hello_world.py \u003chttps://github.com/atheler/klang/blob/master/examples/hello_world.py\u003e`_: 440 Hz sine wave generator\n- `aeolian_arp.py \u003chttps://github.com/atheler/klang/blob/master/examples/aeolian_arp.py\u003e`_: More fun with random ever changing arpeggios.\n- `arpeggiator_demo.py \u003chttps://github.com/atheler/klang/blob/master/examples/arpeggiator_demo.py\u003e`_: Two synthesizer patch with an arpeggiator and some sound effects\n- `audio_file_demo.py \u003chttps://github.com/atheler/klang/blob/master/examples/audio_file_demo.py\u003e`_: Looped audio file playback (`gong.wav` sample) with audio effects\n- `haunting_envelopes.py \u003chttps://github.com/atheler/klang/blob/master/examples/haunting_envelopes.py\u003e`_: Multiple oscillators controlled by looping envelopes\n- `micro_rhythm_demo.py \u003chttps://github.com/atheler/klang/blob/master/examples/micro_rhythm_demo.py\u003e`_: Kick and Hi-Hat pattern where the latter is phrased with a micro rhythm\n- `reverberation_demo.py \u003chttps://github.com/atheler/klang/blob/master/examples/reverberation_demo.py\u003e`_: Ambient loop showcasing the reverb effect.\n- `sequencer_demo.py \u003chttps://github.com/atheler/klang/blob/master/examples/sequencer_demo.py\u003e`_: Techno patch with sequencer\n- `synthesizer_demo.py \u003chttps://github.com/atheler/klang/blob/master/examples/synthesizer_demo.py\u003e`_: This has to be started as root. Computer keyboard playable monophonic synthesizer\n- `tempo_aware_effects.py \u003chttps://github.com/atheler/klang/blob/master/examples/tempo_aware_effects.py\u003e`_: Modulated noise with time synced effects\n\nCoding Style\n------------\n\nPEP8 / Google flavored. With the one exception for variable and argument names\n(`camelCase`). Function and in methods are `snake_case()`.\n\nAuthor\n------\n\n* **Alexander Theler** (`GitHub \u003chttps://github.com/atheler\u003e`_)\n\nAcknowledgments\n---------------\n\nThanks for the support and inputs!\n\n- `Nico Neureiter \u003chttps://github.com/NicoNeureiter\u003e`_\n- `Andreas Steiner \u003chttp://smokeandmirrors.ch\u003e`_\n- `Lawrence Markwalder \u003chttps://github.com/lmarkwalder\u003e`_\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fatheler%2Fklang","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fatheler%2Fklang","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fatheler%2Fklang/lists"}