Pattern library for algorithmic music composition and performance in Common Lisp

cl-patterns

#+TITLE: cl-patterns

A library for writing patterns to generate or process (a)musical sequences of mathematically (un)related (non-)compound values in Lisp.

Put more simply, cl-patterns is a system for making music and noise via Lisp code.

It is heavily inspired by [[https://supercollider.github.io/][SuperCollider]]'s [[http://doc.sccode.org/Tutorials/A-Practical-Guide/PG_01_Introduction.html][patterns system]], with aims to implement much of it, but in a more robust, expressive, consistent, reflective, and lispy way:

- robust: prefer coercing values into something "correct" rather than failing or giving an error. if you're "in the zone" and writing music, you probably want your compositional tools to "do what you mean" and allow you to take as many sensible shortcuts as possible, rather than forcing you to waste time manually declaring and setting up everything.
- expressive: make writing music as easy and "natural" as possible, so that patterns can be built in real-time, in performance settings, without having to think so hard about how to bend the library to your will. I feel this is a weakness of SuperCollider.
- consistent: edge cases minimized, arguments for the various functions in an intuitive order, thus resulting in less cognitive load for the user.
- reflective: store more data about the stream state and more metadata about the patterns. make it easier for a pattern to access the values of another pattern, for patterns to affect other patterns, etc.
- lispy: prefer lisp idioms rather than direct translations of the SuperCollider way of doing things (while still keeping things relatively similar so it's not a huge adjustment for SC users to make).

In addition to emulating most of SuperCollider's patterns system, another goal is to further extend it with more tools and more ways to write patterns/sequences. The most obvious example being a "drum sequence" notation like ~k - - - k - - - k - - - k - - -~ for a four-to-the-floor beat. The idea is that Lisp's macros should make it possible to more expressively write music with code.

* Intro

Make sure you have [[https://www.quicklisp.org/beta/][Quicklisp]] installed and working with your Lisp implementation, then load cl-patterns:

#+BEGIN_SRC lisp
  (ql:quickload 'cl-patterns)
  (use-package 'cl-patterns)
#+END_SRC

Create a pattern like so:

#+BEGIN_SRC lisp
  (defparameter *pat* (pbind :foo (pseq '(1 2 3))
                             :bar (prand '(9 8 7) 5)))
#+END_SRC

Since patterns are basically "templates", you need to turn them into ~pstream~ objects in order to actually get output from them:

#+BEGIN_SRC lisp
  (defparameter *pstream* (as-pstream *pat*))
#+END_SRC

Then, you can get results from the pstream one at a time with ~next~, or many at a time with ~next-n~ or ~next-upto-n~:

#+BEGIN_SRC lisp
  (next-n *pstream* 3)
  ;; => ((EVENT :FOO 1 :BAR 8) (EVENT :FOO 2 :BAR 9) (EVENT :FOO 3 :BAR 8))
#+END_SRC

To actually hear sound output, you'll need to start an audio server. Right now, SuperCollider is the main audio server that cl-patterns is tested against, but there is also preliminary support for [[http://incudine.sourceforge.net/][Incudine]] as well as MIDI output through ALSA.

To use the SuperCollider backend, simply load the ~cl-patterns/supercollider~ system with quicklisp. This will automatically take care of loading the required [[https://github.com/byulparan/cl-collider][cl-collider]] library for you:

#+BEGIN_SRC lisp
  (ql:quickload :cl-patterns/supercollider)
#+END_SRC

From here, you can take a look at the code in the [[file:doc/supercollider-example.lisp][supercollider-example.lisp]] file for a short example of how to define your own synths and play them with patterns. You may also be interested in [[https://defaultxr.github.io/cl-collider-tutorial/][my cl-collider tutorial]] for a more in-depth introduction to cl-collider.

For more information on how to use cl-patterns, refer to [[file:doc/tutorial.org][tutorial.org]] for an introduction.

You can get a list of all defined patterns using ~(all-patterns)~. Every pattern should have usage information and examples in its docstring, which of course can be accessed using the standand ~describe~ or ~documentation~ functions.

* Features

This library isn't just a copy of SuperCollider's patterns - I wanted to improve upon them as well. For a list of notable features in cl-patterns, see [[file:doc/features.org][features.org]].

If you're familiar with SuperCollider, you may also want to look at [[file:doc/sc-differences.org][sc-differences.org]] for a listing of differences between this library and SC's patterns, or [[file:doc/sc.org][sc.org]] for a listing of patterns in SuperCollider and their equivalent (and implementation status) in cl-patterns.

** Emacs "Helper Functions"

Included in [[file:res/emacs/][res/emacs/]] are a few small libraries that make it more convenient to work with cl-patterns and the synthesis engines it supports from inside Emacs. Their functionality includes:

- commands for playing/stopping the pattern, buffer, proxy, or other object under point
- command to stop all playing patterns, nodes, etc.
- command to open the SuperCollider documentation for a specified class (with completion)
- [[file:res/emacs/cl-patterns-skeletons.el][skeletons]] for commonly-used patterns/functions
- and a few other utility functions.

Here's the recommended setup to load these libraries automatically via your Emacs init file:

#+begin_src emacs-lisp
  (defun cl-patterns-helpers-load ()
    (interactive)
    (sly-eval-async '(cl:let ((system (asdf:find-system "cl-patterns" nil)))
                             (cl:when system (cl:namestring (asdf:system-source-directory system))))
      (lambda (path)
        (load (concat path "res/emacs/cl-patterns-helpers") nil nil nil t)
        (load (concat path "res/emacs/cl-patterns-skeletons") nil nil nil t)))
    (define-key sly-mode-map (kbd "C-c p") 'cl-patterns-play-or-end-context-or-select-pdef)
    (define-key sly-mode-map (kbd "C-c P") 'cl-patterns-play-or-stop-context-or-select-pdef)
    (define-key sly-mode-map (kbd "C-c s") 'cl-patterns-stop-all)
    (define-key sly-doc-map (kbd "s") 'cl-patterns-supercollider-documentation))

  (add-hook 'sly-connected-hook 'cl-patterns-helpers-load)
#+end_src

The above should also work with slime; just replace all instances of "sly" with "slime".

* Status

Right now, the library may be described as being in a "late alpha" stage, as fewer and fewer major changes are still being made. Most of the included patterns and exported functionality now have relatively stable APIs as well as tests to guard against regressions. There may still be the occasional change of functionality in the library, though most user-facing changes will be gracefully deprecated and documented in commit messages, so check those if you have any issues after updating.

Despite that, lots of functionality is already written and the library should be stable enough for normal usage in most cases.

Many [[file:t/][tests]] have already been written to help guard against regressions.

Much documentation is still being written, but there is already a good amount of information in the [[file:doc/][doc]] directory, and in the docstrings for the patterns, functions, etc.

See [[file:doc/TODO.org][TODO.org]] and [[file:doc/roadmap.org][roadmap.org]] for a listing of tasks that need to be completed and ideas for future features. The code itself is also littered with comments marked "FIX" noting various known issues and possible changes and optimizations that could be made.

** Backends

The SuperCollider backend is the primary backend that cl-patterns is tested against so it should generally work the best and should be usable for most purposes.

The Incudine backend should work for most purposes, though currently multichannel expansion does not work.

The ALSA MIDI backend has some functionality complete and should be usable for basic tasks, but is still very much a work in progress.

* Tour

- [[file:README.org][README.org]] - this file. self-expanatory, I'd hope.
- [[file:LICENSE][LICENSE]] - the MIT license.
- [[file:cl-patterns.asd][cl-patterns.asd]] - cl-patterns systems definition file.

** doc

- [[file:doc/backends.org][backends.org]] - information about cl-patterns backends, including how to write your own.
- [[file:doc/cookbook.org][cookbook.org]] - a cookbook of ideas and inspiration for your cl-patterns hacking.
- [[file:doc/features.org][features.org]] - listing of notable features of cl-patterns.
- [[file:doc/isobar.org][isobar.org]] - list of patterns in [[https://github.com/ideoforms/isobar][isobar]] and their equivalents in cl-patterns.
- [[file:doc/other-libraries.org][other-libraries.org]] - listing of other libraries that have similar goals or may be useful in conjunction with cl-patterns.
- [[file:doc/patterns.org][patterns.org]] - organized index of the pattern classes included in cl-patterns.
- [[file:doc/roadmap.org][roadmap.org]] - general overview of major goals for the future development of cl-patterns.
- [[file:doc/sc.org][sc.org]] - a list of pattern classes and special keys in SuperCollider and their cl-patterns implementation status.
- [[file:doc/sc-differences.org][sc-differences.org]] - listing of things that differ between cl-patterns and SuperCollider.
- [[file:doc/special-keys.org][special-keys.org]] - description of keys that have special effects when used in an event or pbind.
- [[file:doc/supercollider-example.lisp][supercollider-example.lisp]] - short example of how to use cl-patterns with cl-collider.
- [[file:doc/TODO.org][TODO.org]] - a list of things and ideas that have not yet been implemented into cl-patterns, but may be in the future.
- [[file:doc/tutorial.org][tutorial.org]] - explanation of the basic concepts of cl-patterns, meant for people who have never used SuperCollider's patterns.
- [[file:doc/writing-your-own.org][writing-your-own.org]] - information about how to write your own pattern classes.

** res

*** emacs

- [[file:res/emacs/cl-patterns-helpers.el][cl-patterns-helpers.el]] - Helper functions to make cl-patterns more convenient to use from Emacs (see [[Emacs "Helper Functions"][above]]).
- [[file:res/emacs/cl-patterns-skeletons.el][cl-patterns-skeletons.el]] - Emacs skeletons (templates) for quickly inserting commonly-used lisp forms.

** src

- [[file:src/package.lisp][package.lisp]] - the package definition file.
- [[file:src/utility.lisp][utility.lisp]] - general utility functions and special variable definitions.
- [[file:src/conversions.lisp][conversions.lisp]] - functions to convert between units (i.e. midinote to frequency, decibels to amplitude, etc.).
- [[file:src/scales.lisp][scales.lisp]] - musical pitch (scales/tuning) data and structs.
- [[file:src/event.lisp][event.lisp]] - code to represent and deal with events. includes the ~event~ class, information about special keys (i.e. ~freq~, ~amp~...), etc.
- [[file:src/eseq.lisp][eseq.lisp]] - event sequence class and functionality.
- [[file:src/backend.lisp][backend.lisp]] - code to handle "backends"; i.e. how cl-patterns will actually "play" events.
- [[file:src/render.lisp][render.lisp]] - generic functionality for rendering patterns.
- [[file:src/clock.lisp][clock.lisp]] - the scheduling functionality to make sure that each event is played at the proper time.

*** patterns

- [[file:src/patterns/patterns.lisp][patterns.lisp]] - general pattern macros and functionality + the standard set of patterns; includes the ~pattern~ superclass, ~pbind~, ~pseq~, ~pk~, etc.
- [[file:src/patterns/pdef.lisp][pdef.lisp]] - ~pdef~ and associated functionality to define and reference "named patterns".
- [[file:src/patterns/pmeta.lisp][pmeta.lisp]] - ~pmeta~; meta-pattern for embedding and controlling other patterns.
- [[file:src/patterns/bjorklund.lisp][bjorklund.lisp]] - Euclidean pattern functionality such as ~pbjorklund~, etc.
- [[file:src/patterns/cycles.lisp][cycles.lisp]] - TidalCycles-inspired patterns and notation, i.e. ~pcycles~, etc.
- [[file:src/patterns/track.lisp][track.lisp]] - tracker-inspired patterns and notation, i.e. ~ptrack~ and associated functions, macros, reader macros, etc.
- [[file:src/patterns/sc-compatibility.lisp][sc-compatibility.lisp]] - patterns intended to be fully compatible with SuperCollider's patterns system.
- [[file:src/patterns/export.lisp][export.lisp]] - export all defined patterns in the ~*patterns*~ list.

*** backends

- [[file:src/backends/supercollider.lisp][supercollider.lisp]] - code to interface cl-patterns with [[https://supercollider.github.io/][SuperCollider]] via the [[https://github.com/byulparan/cl-collider][cl-collider]] library.
- [[file:src/backends/incudine.lisp][incudine.lisp]] - code to interface cl-patterns with [[https://github.com/titola/incudine][Incudine]].
- [[file:src/backends/debug.lisp][debug.lisp]] - basic debug backend. responds to all events, printing and storing them without any audio output.
- [[file:src/backends/alsa-midi.lisp][alsa-midi.lisp]] - code to interface cl-patterns with [[https://github.com/defaultxr/cl-alsaseq][cl-alsaseq]].

*** formats

- [[file:src/formats/midifile.lisp][midifile.lisp]] - functionality to interact with MIDI files (load the ~cl-patterns/midifile~ system to use this).
- [[file:src/formats/supercollider-score.lisp][supercollider-score.lisp]] - functionality to interact with [[http://doc.sccode.org/Classes/Score.html][SuperCollider Score]] files.

*** extensions

- [[file:src/extensions/generic-cl.lisp][generic-cl.lisp]] - additional methods for [[https://github.com/alex-gutev/generic-cl][generic-cl]]. enable by loading the ~cl-patterns/generic-cl~ subsystem.
- [[file:src/extensions/sequence.lisp][sequence.lisp]] - additional methods for implementations that support [[http://www.sbcl.org/manual/#Extensible-Sequences][extensible sequences]].
- [[file:src/extensions/swank.lisp][swank.lisp]] - creature comforts for slime/swank users.
- [[file:src/extensions/slynk.lisp][slynk.lisp]] - creature comforts for sly/slynk users.

** t

contains the files for the [[https://github.com/sionescu/fiveam][FiveAM]]-based test suite for the library.

* Community

If you need support or just want to chat, the official cl-patterns chatroom is on Matrix at [[https://matrix.to/#/#cl-patterns:struct.ws][#cl-patterns:struct.ws]], and bridged to IRC at [[https://web.libera.chat/#cl-patterns][#cl-patterns on irc.libera.chat]].

Any bugs, feature requests, suggestions, etc should be submitted to the GitHub [[https://github.com/defaultxr/cl-patterns/issues][issue tracker]]. Please feel free to submit issues even if they might already be known as it helps to figure out which parts of the library to prioritize development on. It's also nice to know that people are using the library. :)


alexandria

bordeaux-threads

closer-mop

dissect

local-time

mutility

mutility/loopy

named-readtables

cl-alsaseq

cl-patterns/alsa-midi

cl-patterns/debug

incudine

cl-patterns/incudine

midi

cl-patterns/midifile

cl-patterns with additional syntax sugar exports. Deprecated system; use the mutility library or manually import functions instead.

cl-patterns

Upstream URL

Author

License

cl-patterns

Version:

License:

Authors:

Dependencies:

cl-patterns/alsa-midi

Version:

License:

Authors:

Dependencies:

cl-patterns/debug

Version:

License:

Authors:

Dependencies:

cl-patterns/incudine

Version:

License:

Authors:

Dependencies:

cl-patterns/midifile

Version:

License:

Authors:

Dependencies:

cl-patterns/sugar

Version:

License:

Authors:

Dependencies:

cl-patterns/supercollider

Version:

License:

Authors:

Dependencies:

cl-patterns/tests

License:

Authors:

Dependencies:

Dependencies (11)

Dependents (2)