diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 282 |
1 files changed, 174 insertions, 108 deletions
@@ -3,152 +3,218 @@ 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 understands [Open Sound Control](http://opensoundcontrol.org/), +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: -[](https://vimeo.com/520547229) +[](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 <generic-dimmer> 18)) +(patch-fixture! washM <generic-dimmer> 19)) +(patch-fixture! washR <generic-dimmer> 20)) +(patch-fixture! footlights <generic-dimmer> 23)) +(patch-fixture! moverL <robe-dl7s-mode1> 1 #:universe 4)) +(patch-fixture! moverR <robe-dl7s-mode1> 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 (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 wrapping a lighting state inside 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 + (snap + (lighting-state + (at washL washR 30) + (at washM 40)))) + + (cue 0.8 + ;; 6-second fade to blackout + (crossfade 6 blackout)) + + (cue 1 + ;; Act 1, Scene 1 + (crossfade 3 + (lighting-state + (at front-wash 80) + (at moverL colour (cmy 25 0 0))) + (at moverL 25))) + + (cue 2 + (crossfade 3 4 ;; Separate up/down fade times + (lighting-state + (at washM 100)))) + + (cue 2.5 + (crossfade 2 + (lighting-state + (apply-state home-state) + (at moverR 100))))) ``` -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) ``` +By giving names to lighting states, cue lists can be made very concise. The +following example is from a real show: + +``` + (cue 6 (snap blue-state)) + (cue 7 (snap office-state)) + (cue 8 (snap blue-state)) + (cue 9 (snap office-state)) + (cue 10 (snap blue-state)) + (cue 11 (snap office-state)) + (cue 12 (crossfade 2 blackout)) + (cue 13 (snap office-state)) +``` -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: +Since lighting states are first-class objects, you can even do calculations +with them. In this example (from another real show), the lighting sneaks +progressively darker in a series of slow fades at dramatically appropriate +points: ``` -(patch-fixture! dimmer1 <generic-dimmer> 1)) -(patch-fixture! dimmer2 <generic-dimmer> 3)) -(patch-fixture! balcony-backlight1 <generic-dimmer> 18)) -(patch-fixture! balcony-backlight2 <generic-dimmer> 19)) -(patch-fixture! footlights <generic-dimmer> 23)) -;; Universe numbering starts at zero, matching OLA -(patch-fixture! moving-light <robe-dl7s-mode1> 1 #:universe 4)) + (cue 2 (crossfade 1 evening-state)) + (cue 3 (crossfade 15 (part-way-between evening-state night-state 0.2))) + (cue 4 (crossfade 15 (part-way-between evening-state night-state 0.4))) + (cue 5 (crossfade 15 (part-way-between evening-state night-state 0.6))) + (cue 6 (crossfade 15 (part-way-between evening-state night-state 0.8))) + (cue 7 (crossfade 15 night-state)) ``` -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. +The _structure_ of the cue list is thus separated from the _design_ of the +lighting states. The structure can often be decided and programmed weeks in +advance of the show, leaving you to concentrate on the designing the states +during the technical rehearsal. -Getting started ---------------- +Documentation index +------------------- -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 <generic-dimmer> 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. +* [Patching fixtures](docs/patching.rst) +* [Basic attribute control and building states](docs/basic-control.rst) +* [Cue lists and playbacks](docs/cue-list.rst) +* [The fixture display tool](docs/fixture-display.rst) +* [Physical controls](docs/physical-control.rst) +* [Defining a new type of fixture](docs/new-fixture.rst) -Related projects ----------------- +(Non-)warranty +-------------- -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: +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 June 2023: + + + +About the name +-------------- + +* Star-let: The little star of your show, of course. +* Let-star (let*): the sequentially evaluated form of the + [local binding syntax](https://www.scheme.com/tspl4/binding.html#./binding:h4) + in Scheme. +* [CCT Starlette](http://www.cctlighting.co.uk/125/Theatre_spotlights/Starlette_Luminaire_Range.html): + a range of theatrical lighting fixtures. -* [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 -* [QLC+](https://qlcplus.org/) the most popular open-source lighting control - program -It's also worth taking a look at the -[stage-lighting topic](https://github.com/topics/stage-lighting) on Github. +Related projects +---------------- + +In the almost absurdly specialised category of "Lisp-based stage lighting +systems", Starlet is far from being the only project: + +* [Lula](https://www.deinprogramm.de/sperber/lula/) is based on a very similar + concept, and predates Starlet by over two decades. Read + [this paper](https://doi.org/10.1145/507635.507652), which establishes a + formal basis for describing lighting states in code, and + [this thesis](https://bibliographie.uni-tuebingen.de/xmlui/bitstream/handle/10900/48174/pdf/lula-thesis.pdf?sequence=1) which goes into much more detail. +* [Afterglow](https://github.com/Deep-Symmetry/afterglow) is a live-coding + lighting controller based on Clojure. +* [Fivetwelve-CSS](https://github.com/beyondscreen/fivetwelve-css) Controls + lighting using CSS. It's not using Lisp, but it does use similar ideas about + composition. [Watch this video](https://www.youtube.com/watch?v=ani_MOZt5_c) + +You may also be interested in: + +* [Guile-OSC](https://github.com/taw10/guile-osc) - Open Sound Control library + for Guile Scheme. +* [QLC+](https://qlcplus.org/) - the most popular open-source lighting control + program +* The [stage-lighting topic](https://github.com/topics/stage-lighting) on Github. Licence |