update/improve README.org

README.org

@@ -4,57 +4,102 @@
 This is a Common Lisp library to interface with [[https://www.renoise.com/][Renoise]]. Currently in very early stages of development; not much functionality is written yet.
 
 * Setup
+1. Put cl-renoise in your quicklisp ~local-projects~ (it is not on Quicklisp yet).
 
-1. Enable OSC in Renoise. Edit->Preferences->OSC->Enable Server.
+2. Enable OSC in Renoise. Edit->Preferences->OSC->Enable Server. Make sure "Protocol" is set to "Udp".
 
-Make sure "Protocol" is set to "Udp".
+3. Load the library. If Renoise is running on another host or you changed the OSC port, set those variables:
+   #+BEGIN_SRC lisp
+     (ql:quickload :cl-renoise)
 
-2. Load the library. If Renoise is running on another host or you changed the OSC port, set those variables:
+     (setf renoise:*renoise-host* #(192 168 0 24)) ; If Renoise is running on 192.168.0.24. If it's running on the same computer as Lisp, you can skip this step.
 
+     (setf renoise:*renoise-port* 8000) ; Not needed if you use the default port of 8000.
+   #+END_SRC
+
+4. That's it! You can now interact with Renoise from Lisp.
+
+* Usage
+
+** Evaluate Lua in Renoise
+#+BEGIN_SRC lisp
+  (renoise:evaluate "renoise.app():show_warning((\"Hello from Lisp!\"))") ; Send Lua code to Renoise.
+
+  (renoise:warning-dialog "Hello again :^)") ; Show a warning, as above, but more conveniently.
+#+END_SRC
+
+** Edit the song
+#+BEGIN_SRC lisp
+  (renoise:edit :pattern 0 :track 1 :line 0 :column 0 :note 70) ; Set the first cell to be MIDI note 70.
+  ;; (Note that patterns, lines, and columns start from 0, while tracks start from 1.)
+#+END_SRC
+
+** Start/stop notes
 #+BEGIN_SRC lisp
-(ql:quickload :cl-renoise)
+  (renoise:note-on 48) ; Start playing the current instrument.
 
-(setf renoise:*host* #(192 168 0 24)) ; If Renoise is running on 192.168.0.24. If it's running on the same computer as Lisp, skip this step.
+  (renoise:note-off 48) ; Stop playing it.
+#+END_SRC
+
+** Start/stop the song
+#+BEGIN_SRC lisp
+  (renoise:start) ; Start playing the song.
 
-(setf renoise:*port* 8000) ; Not needed if you use the default port of 8000.
+  (renoise:stop) ; Stop playing it.
 #+END_SRC
 
-3. You can now send Lua code to Renoise to be evaluated:
+** Receive OSC messages from Renoise
+If you want to be able to receive OSC messages from Renoise, run ~initialize-osc-replier~ to set it up on the Renoise end, and start ~renoise:receiver~ in a thread on the Lisp end.
 
 #+BEGIN_SRC lisp
-(renoise:evaluate "renoise.app():show_warning((\"Hello from Lisp!\"))") ; Send Lua code to Renoise.
+  (renoise:initialize-osc-replier) ; Allow Renoise to send OSC to Lisp.
 
-(renoise:warning-dialog "Hello again :^)") ; Show a warning, as above, but more conveniently.
+  (ql:quickload :bordeaux-threads) ; Load Lisp's de facto threading library.
+
+  (bt:make-thread 'renoise:receiver :name "Renoise receiver thread") ; Make an OSC receiver thread to catch incoming messages.
 #+END_SRC
 
-4. You can also edit the song, start/stop notes, and control the transport:
+You can then use ~add-reply-handler~ and ~remove-reply-handler~ to delegate OSC messages to functions.
 
 #+BEGIN_SRC lisp
-(renoise:edit :pattern 0 :track 1 :line 0 :column 0 :note 70) ; Set the first cell to be MIDI note 70.
+  (defun handle-blah (param) ; Define a function for processing received /blah OSC messages.
+    (format t "Received /blah OSC message: ~S~%" param))
+
+  (renoise:add-reply-handler "/blah" 'handle-blah) ; Set an OSC handler for /blah messages.
 
-(renoise:note-on 48) ; Start playing the current instrument.
+  (renoise:send-reply "/blah" "Howdy!") ; Make Renoise send an OSC message to the Lisp process (which will be handled by the /blah handler).
 
-(renoise:note-off 48) ; Stop playing it.
+  (defun handle-other (&rest msg) ; Define a function for processing other received OSC messages.
+    (format t "Received OSC message: ~S~%" msg))
 
-(renoise:start) ; Start playing the song.
+  (renoise:add-reply-handler t 'handle-other) ; Add a catch-all reply handler that will be run when no other handler matches the message.
 
-(renoise:stop) ; Stop playing it.
+  (renoise:send-reply "/foobar" 99 23.0) ; Make Renoise send an OSC message to the Lisp process (which will be handled by handle-other).
 #+END_SRC
 
-5. If you want to be able to receive OSC messages from Renoise, run ~initialize-osc-replier~ to set it up, then use ~add-reply-handler~ and ~remove-reply-handler~ to delegate OSC messages to functions.
+* Related projects
 
-#+BEGIN_SRC lisp
-(renoise:initialize-osc-replier) ; Allow Renoise to send OSC to Lisp.
+** [[https://github.com/defaultxr/cl-patterns][cl-patterns]]
+cl-patterns is an algorithmic sequencing library for Common Lisp. Patterns generate sequences of numbers or values, and music is sequenced by composition of patterns.
 
-(ql:quickload :bordeaux-threads) ; Load Lisp's de facto threading library.
+A Renoise backend based on cl-renoise is being developed, which will allow you to import and export Renoise patterns.
 
-(bt:make-thread 'renoise:receive :name "Renoise receiver thread") ; Make an OSC receiver thread to catch incoming messages.
+(Unfortunately it is not possible to actually control Renoise as a synthesizer, since Renoise seems to ignore OSC time tags.)
 
-(renoise:add-reply-handler t (lambda (&rest msg) (format t "~s~%" msg))) ; Add a catch-all reply handler that will be run when no other handler matches the message.
+** [[https://codeberg.org/gsou/LCL][LCL]]
+Lua Common Lisp is an implementation of Common Lisp targeting the Lua language. The goal of this project is to provide an implementation of Common Lisp that can be used wherever an unmodified Lua VM is running.
 
-(renoise:send-reply "/foobar" 99 23.0) ; Make Renoise send an OSC message to the Lisp process.
+LCL is /not/ a Common Lisp to Lua compiler. LCL /has/ a Common Lisp to Lua compiler. LCL is an implementation of Common Lisp that happens to be running on Lua.
 
-(renoise:add-reply-handler "/blah" (lambda (param) (format t "BLAH BLAH BLAH ~s~%" param))) ; Set an OSC handler for /blah messages.
+** [[https://fennel-lang.org/][Fennel]]
+Fennel is a programming language that brings together the simplicity, speed, and reach of Lua with the flexibility of a lisp syntax and macro system.
 
-(renoise:send-reply "/blah" "Howdy!") ; Make Renoise send an OSC message to the Lisp process (which will be handled by the /blah handler).
-#+END_SRC
+Fennel is basically a lisp-like language that compiles to Lua. It is not compatible with Common Lisp, but it's certainly much nicer than writing Lua directly.
+
+** [[https://github.com/triss/sc-renoise][sc-renoise]]
+SuperCollider and Renoise extensions that allow better integration between the two tools.
+
+Maps SynthDef's to Renoise instruments such that they can be sequenced/played/recorded in the manner of any other Renoise instrument, and provides quick access to all of Renoise's OSC commands.
+
+** [[https://sccode.org/1-4SN][Supercollider to Renoise]]
+SuperCollider Renoise event type example that allows you to easily generate patterns which will be played by Renoise. Useful if you want to make patterns with VSTi.

src/cl-renoise.lisp

@@ -1,13 +1,13 @@
 ;;;; cl-renoise.lisp - basic functionality for interacting with Renoise.
-;; NOTE: Renoise 3.1.1 uses Lua 5.1.
-;; https://files.renoise.com/xrnx/documentation/Renoise.Song.API.lua.html
-;; https://github.com/renoise/xrnx
-;; https://forum.renoise.com/t/inserting-notes-into-a-pattern/49753/4
-;; https://tutorials.renoise.com/wiki/Open_Sound_Control
-;; NOTE: Renoise seems to ignore OSC timetags, thus it's not possible to schedule note on/off accurately
-;; * prior art:
-;; - https://github.com/triss/sc-renoise
-;; - http://forum.renoise.com/index.php/topic/37557-generative-music-using-supercollider-renoise/
+
+;; NOTES:
+;; - Renoise 3.1.1 uses Lua 5.1.
+;; - Renoise seems to ignore OSC timetags, thus it's not possible to schedule note on/off accurately
+;; * Renoise scripting and OSC docs:
+;; - https://files.renoise.com/xrnx/documentation/Renoise.Song.API.lua.html
+;; - https://github.com/renoise/xrnx
+;; - https://forum.renoise.com/t/inserting-notes-into-a-pattern/49753/4
+;; - https://tutorials.renoise.com/wiki/Open_Sound_Control
 ;; * https://codeberg.org/gsou/LCL - Lua Common Lisp. An implementation of Common Lisp targeting Lua.
 
 (in-package #:cl-renoise)