From a0dc6d0c58b78b280d86b391a5f5f3e880bd7401 Mon Sep 17 00:00:00 2001 From: Thomas White Date: Sun, 13 Feb 2022 21:00:02 +0100 Subject: Update docs --- README.md | 224 +++++++++++++++++++++++++++++++++----------------------------- 1 file changed, 121 insertions(+), 103 deletions(-) (limited to 'README.md') diff --git a/README.md b/README.md index a81b2f1..351cd8d 100644 --- a/README.md +++ b/README.md @@ -3,147 +3,165 @@ Starlet: Stage lighting control in Lisp Starlet is an experimental Lisp-based domain-specific language (DSL) for theatrical lighting control. It's based on -[Guile](https://www.gnu.org/software/guile/) and sends its DMX output via -[OLA](https://openlighting.org) to almost any type of lighting control -interface - DMX, sACN, Art-Net etc. Starlet also undertands MIDI, enabling you -to control lights and cues with physical faders, knobs and buttons. +[Guile](https://www.gnu.org/software/guile/) and uses the +[Open Lighting Architecture](https://openlighting.org) to connect with almost +any type of lighting control interface - USB DMX dongles, sACN, Art-Net etc. +Starlet also undertands MIDI, enabling you to control lights and cues with +physical faders, knobs and buttons. + +Rather than adding "scripting" as an afterthought, Starlet puts the full power +of the programming language in the spotlight, allowing you to *program* your +lights. + +Starlet is explicitly designed for *theatrical* lighting control, with cue +lists, playbacks and multi-part cues being the centre of attention. Automatic +pre-setting of attributes ("auto move while dark") is the default. + + +Video demonstration +------------------- Click for a video demonstration: -[![Video demonstration](screenshot.png)](https://vimeo.com/520547229) +[![Video demonstration](docs/screenshot.png)](https://vimeo.com/520547229) -With Starlet, a cue list looks like this: + +Getting started +--------------- + +Read [INSTALL.md](INSTALL.md) for basic setup instructions. + + +Quick tour +---------- + +Lighting fixtures are referred to by names, rather than numbers: ``` -(define my-cue-list - (cue-list - - (cue 1 - (lighting-state (at dim1 '100)) - (at mh1 'pan 25)) - #:fade-up 3 - #:fade-down 5) - - (cue 2 - (lighting-state (at dim1 '50) - (at dim2 '100) - (at mh1 'pan 50)) - #:fade-up 3 - #:fade-down 1 - #:down-delay 3) - - (cue 3 - (lighting-state #f) ; blackout - #:fade-down 2 -``` +;; Patch some fixtures +(patch-fixture! washL 18)) +(patch-fixture! washM 19)) +(patch-fixture! washR 20)) +(patch-fixture! footlights 23)) +(patch-fixture! moverL 1 #:universe 4)) +(patch-fixture! moverR 101 #:universe 4)) -Creating a playback object and running a cue list looks like this: +;; Turn the footlights on at full intensity +(at footlights 100) +;; Turn on both moving lights and set colour +(at moverL moverR 60) +(at moverL moverR 'colour (make-colour-rgb 45 10 0)) ``` -(define pb (make-playback #:cue-list my-cue-list)) -(cut-to-cue-number! pb 1) -(go! pb) -(go! pb) -(go! pb) ; and so on +The fixture names are normal Scheme variables. You can do usual things such +as creating lists: + +``` +(define front-wash (list washL washM washR)) +(at front-wash 100) ``` -Lighting states can be prepared separately and assigned to variables: +A lighting state is a collection of attribute values, and can be associated +with a variable name: ``` -(define spooky-dungeon +(define home-state (lighting-state - (at dimmer1 20) - (at dimmer2 20) - (at moving-light 70) - (at moving-light 'red 100) - (at moving-light 'green 10) - (at moving-light 'blue 12))) + (at footlights 100) + (at front-wash 100) + (at moverL moverR 100) + (at moverL moverR 'tilt 45) + (at moverL 'pan -15) + (at moverR 'pan 15))) ``` -You can use pre-prepared states in cues, even if some minor modifications are -needed. This makes it really easy to understand the contents of a cue without -having to interpret a screenful of numbers: +A cue is formed by associating a lighting state with a *transition effect*, +such as a crossfade or snap (zero-time crossfade). A cue list is simply a list +of cues: ``` -(cue 57 - (lighting-state (apply-state spooky-dungeon) - (at follow-spot 100)) - #:fade-up 3 - #:fade-down 3) +(cue-list + + (cue 0.5 + ;; Tab warmers + (lighting-state + (at washL washR 30) + (at washM 40)) + (snap)) + + (cue 0.8 + ;; Blackout + (lighting-state) + (crossfade 6)) ;; 6 second fade + + (cue 1 + ;; Act 1, Scene 1 + (lighting-state + (at front-wash 80) + (at moverL 'colour (make-colour-cmy 2700/127 0 0))) + (at moverL 25) + (crossfade 3)) + + (cue 2 + (lighting-state + (at washM 100)) + (crossfade 3 4)) ;; Separate up/down fade times + + (cue 2.5 + (lighting-state + (apply-state home-state) + (at moverR 100) + (crossfade 2))) + + .... ``` -Multi-part cues are supported. Simply specify the fade parameters and which -fixtures should be in the part: +To 'execute' a cue list, load it into a *playback* object: ``` -(cue 64 - (lighting-state (apply-state indoor-act1-general) - #:fade-up 3 - #:fade-down 3 - - (cue-part (dim3 - dim4 - dim8 - (list moving-light 'pan 'tilt)) - #:down-time 2 - #:down-delay 1)) +(define pb (make-playback #:cue-list my-cue-list)) + +(cut-to-cue-number! pb 1) +(go! pb) ``` -Everything from a simple dimmers to wacky multi-parameter fixtures are -supported. New fixture classes can be defined using some simple Scheme code. -Patching fixtures looks like this: +Documentation index +------------------- -``` -(patch-fixture! dimmer1 1)) -(patch-fixture! dimmer2 3)) -(patch-fixture! balcony-backlight1 18)) -(patch-fixture! balcony-backlight2 19)) -(patch-fixture! footlights 23)) -;; Universe numbering starts at zero, matching OLA -(patch-fixture! moving-light 1 #:universe 4)) -``` +* [Patching fixtures](docs/patching.rst) +* [The fixture display tool](docs/fixture-display.rst) +* More to come: + - Basic control of attributes, building states + - Cue lists + - Defining a new fixture type + - Using physical controls via MIDI -Note that the names of the fixtures are just normal Scheme variables. They can -be anything you like, and you're encouraged to make the names more descriptive -than logical channel numbers, where appropriate. +(Non-)warranty +-------------- -Getting started ---------------- +Starlet is an experiment in progress, and there are no guarantees of any kind +of stability (non-crashiness, consistency of language etc). Don't rely on +syntax and interfaces staying the same, i.e. don't "git pull" right before a +show! Nevertheless, Starlet is reliable enough for adventurous types to +consider using it for real shows. Here it is running a show in front of a live +(paying!) audience in February 2022: -1. Install and set up [OLA](https://openlighting.org) for your lighting - environment. -2. Install [Guile](https://www.gnu.org/software/guile/), if it's not already - there. Version 3 is required. -3. Install Starlet: - `meson build`, `ninja -C build` and `sudo ninja -C build install` -4. Start olad if it's not already running: `olad -l 3` (in a separate - terminal). -5. Run `guile`. -6. Once in the Guile REPL, import some Starlet modules: - `(use-modules (starlet scanout) (starlet state) (starlet fixture-library - generic dimmer))` -7. Patch a fixture: - `(patch-fixture! mydimmer 1 #:universe 2)` - Replace 1 and 2 with the DMX address and universe (respectively) of a real - dimmer. -8. Turn the dimmer on with `(at mydimmer 100)` -9. Look in the _examples_ and _docs_ folders for more advanced ideas. +![Starlet in use](docs/show.jpg) Related projects ---------------- -There are many stage lighting software projects, but most of them seem to -concentrate on "disco style" effects and chases whereas Starlet is aimed more -towards theatre shows. Here are some that I found especially interesting: - +Here are some related projects that I found especially interesting. +Amazingly, Starlet is not the only project to be found in the almost absurdly +specialised category of "Lisp-based stage lighting systems"! -* [Fivetwelve-CSS](https://github.com/beyondscreen/fivetwelve-css) DMX lighting - control using CSS. [Watch this video](https://www.youtube.com/watch?v=ani_MOZt5_c) * [Afterglow](https://github.com/Deep-Symmetry/afterglow) Clojure live coding environment using OLA +* [Fivetwelve-CSS](https://github.com/beyondscreen/fivetwelve-css) DMX lighting + control using CSS. [Watch this video](https://www.youtube.com/watch?v=ani_MOZt5_c) * [QLC+](https://qlcplus.org/) the most popular open-source lighting control program -- cgit v1.2.3