diff --git a/grid/studies/max/index.md b/grid/studies/max/index.md index 995be820..07dcc745 100644 --- a/grid/studies/max/index.md +++ b/grid/studies/max/index.md @@ -5,11 +5,21 @@ redirect_from: /grid-studies-max/ --- # Grid Studies: Max +{: .no_toc } Max is a full kit of creative tools for sound, graphics, music and interactivity in a visual environment. Patching together *objects* the user can create complex interactions between software and hardware devices. The rapid and immediate nature of graphical programming lends itself well to developing for grids, making it the longtime tool of choice for monome grid-based software. This tutorial will show the basics of interfacing with the grid including how a simple, yet immediate sequencer platform can be made with a small amount of code. +
+ + sections + + {: .text-delta } +- TOC +{:toc} +
+ ## Prerequisites This lesson assumes a basic understanding of the Max patching interface. If you're absolutely new to Max it may be helpful to first go through some of the most excellent Max tutorials in-app `Help > Max Documentation`. @@ -26,7 +36,7 @@ Throughout this text, we'll use the following formatting styles: - `(message text)`: refers to a Max message object - `[objectname @args val]`: refers to a non-message Max object and the arguments needed -## 1. Connect +## 1. Connect {#connect} *See grid-studies-1-1.maxpat for this section.* @@ -42,14 +52,14 @@ Create a new object (press N) and type `bpatcher monome-device` and t Plug in your grid and it will appear in the box. If you connect more than one grid, you can choose which device to communicate with via the dropdown. -## 2. Basics +## 2. Basics {#basics} Messages are sent to `[monome-device]` through the top left inlet, and device interaction messages are transmitted through the bottom left outlet. *See grid-studies-2-1.maxpat for this section.* -### 2.1 Key input +### 2.1 Key input {#key-input} ![](images/grid-studies-2-1.png) @@ -76,7 +86,7 @@ rows -> (rows $1) To show your grid's key states, connect the output of the `route` to this `matrixctrl`. -### 2.2 LED output +### 2.2 LED output {#led-output} ![](images/grid-studies-2-2.png) @@ -104,7 +114,7 @@ To clear the entire grid, use the following message: /monome/grid/led/all 0 ``` -### 2.3 Coupled interaction +### 2.3 Coupled interaction {#coupled-interaction} To change the LEDs on our grid with each physical press, we'll connect the output of our `matrixctrl` into our `/monome/grid/led/set $1 $2 $3` message, which then feeds into `[monome-device]`'s left inlet (see the red cable in the image below). @@ -112,7 +122,7 @@ To change the LEDs on our grid with each physical press, we'll connect the outpu You now have a coupled interface, where the key state is reflected by the the LEDs. -### 2.4 Decoupled interaction +### 2.4 Decoupled interaction {#decoupled-interaction} The grid can also display information beyond the current physical interaction. Throughout this doc, we'll refer to this quality of LED independence as being *decoupled*. The most fundamental decoupled interface is an array of toggles. So, let's ignore the key up state, switching the LED state *only* on key down. @@ -134,7 +144,7 @@ By moving the key state (`z`, here as `$3`) to the front, `[route 1]` will only Connect this to the input of the `matrixctrl` and we have a toggle bank! -## 3.0 Further +## 3.0 Further {#further} Now we'll show how basic grid applications are developed by creating a step sequencer for a 128 grid. We will add features incrementally: @@ -147,7 +157,7 @@ Now we'll show how basic grid applications are developed by creating a step sequ - Adjust playback loop with two-key gesture in position row. -### 3.1 Toggles +### 3.1 Toggles {#toggles} *See grid-studies-3-1.maxpat for this step.* @@ -161,7 +171,7 @@ By switching the first and second elements and then putting them into `[route 6 Also, instead of wrapping a bunch of cords around the patch, we use `[s osc_out]` to send our `led` messages to `[r osc_out]` and into `[monome-device]`. -### 3.2 Play +### 3.2 Play {#play} *See grid-studies-3-2.maxpat for this step.* @@ -194,7 +204,7 @@ After we clear the row, we turn on the corresponding LED by passing the playhead Now when you turn on the clock, you'll see the playhead moving along the bottom row. -### 3.3 Triggers +### 3.3 Triggers {#triggers} *See grid-studies-3-3.maxpat for this step.* @@ -231,7 +241,7 @@ The "triggered" LEDs will be full brightness, drawn on top of this dim row. Lastly, there's a tiny sound engine so you can actually hear something. Turn on the DAC and turn up the gain slider. Change the note values by opening up the `trigs` subpatcher. -### 3.4 Cutting and Looping +### 3.4 Cutting and Looping {#cutting-and-looping} *See grid-studies-3-4.maxpat for this step.* @@ -272,6 +282,6 @@ See `grid-studies-3-5.maxpat` for a JavaScript implementation of this patch. *Max* was originally designed by Miller Puckette and is actively developed by [Cycling '74](http://cycling74.com). -This tutorial was created by [Brian Crabtree](https://nnnnnnnn.org) and maintained by [Dan Derks](https://dndrks.com) for [monome.org](https://monome.org). +This tutorial was created by [Brian Crabtree](https://nnnnnnnn.org) and is maintained by [Dan/i Derks](https://dndrks.com) for [monome.org](https://monome.org). Contributions welcome. Submit a pull request to [github.com/monome/docs](https://github.com/monome/docs) or e-mail `help@monome.org`. diff --git a/grid/studies/pd/index.md b/grid/studies/pd/index.md index 56a815ef..fcedbbf9 100644 --- a/grid/studies/pd/index.md +++ b/grid/studies/pd/index.md @@ -42,7 +42,7 @@ Once both are installed, navigate to `Pd > Preferences > Edit Preferences` (macO Then, place the `monome-device` folder that's included in the zip file above into your Pd externals folder. We don't need to explicitly add it to the search path. -## 1. Connect +## 1. Connect {#connect} *See grid-studies-1-1.pd for this section.* @@ -59,13 +59,13 @@ Attach your grid and you can now communicate with it through this object. Note: this object you've embedded isn't serialosc itself, which is an invisible daemon on your computer that you should have installed [via these steps](/docs/serialosc/setup). The `[monome-device]` object is an 'abstraction', which is actually the patch `monome-device.pd` *inside* of an object, to simplify communicating with serialosc from Pd. -## 2. Basics +## 2. Basics {#basics} Messages are sent to `[monome-device]` through the top left inlet, and received out the bottom left outlet. *See grid-studies-2-1.pd for this section.* -### 2.1 Key input +### 2.1 Key input {#key-input} To see what is coming from the grid, create a `[print]` and connect the left outlet of `[monome-device]` to it. Open the Pd window (Window -> Pd Window) and press some keys on the grid. OSC data will be displayed in the console. @@ -83,7 +83,7 @@ We now have a list of 3 numbers according to each key action. Use an `unpack` to ![](images/grid-studies-2-1-1.png) -### 2.2 LED output +### 2.2 LED output {#led-output} Above the `[monome-device]` create a message box (control/command + 2) and type: @@ -106,7 +106,7 @@ To clear the entire grid, use the following message: ![](images/grid-studies-2-2-1.png) -### 2.3 Coupled interaction +### 2.3 Coupled interaction {#coupled-interaction} Connect the output of @@ -118,7 +118,7 @@ You now have a coupled interface, where the key state is reflected by the the LE ![](images/grid-studies-2-3-1.png) -### 2.4 Decoupled interaction +### 2.4 Decoupled interaction {#decoupled-interaction} The most fundamental decoupled interface is an array of toggles. We can accomplish this by ignoring the key up state, switching the LED state only on key down. @@ -141,7 +141,7 @@ To complete the cycle we can then drive the corresponding LED with a message box ![](images/grid-studies-2-4-1.png) -## 3.0 Further +## 3.0 Further {#further} Now we'll show how basic grid applications are developed by creating a step sequencer, adding features incrementally: @@ -154,7 +154,7 @@ Now we'll show how basic grid applications are developed by creating a step sequ - Adjust playback loop with two-key gesture in position row. -### 3.1 Toggles +### 3.1 Toggles {#toggles} *See grid-studies-3-1.pd for this step.* @@ -199,7 +199,7 @@ This index value is then used to set two values before toggling that state. The Finally we use the index to find the current state of the table, then invert that state with '== 0'. This works because our state is always a 0 or 1. This value is then sent to update the grid LED and is stored back in the table. -### 3.2 Play +### 3.2 Play {#play} *See grid-studies-3-2.pd for this step.* @@ -223,7 +223,7 @@ After we clear the row, we turn on the corresponding LED with a normal single-LE Now when you turn on the clock, you'll see the playhead moving along the bottom row. -### 3.3 Triggers +### 3.3 Triggers {#triggers} *See grid-studies-3-3.pd for this step.* @@ -257,7 +257,7 @@ The "triggered" LEDs will be full brightness on top of this dim row. There's a tiny sound engine so you can actually hear something. Turn on the DAC and turn up the gain slider. -### 3.4 Cutting and Looping +### 3.4 Cutting and Looping {#cutting-and-looping} *See grid-studies-3-4.pd for this step.* @@ -290,6 +290,6 @@ We've created a minimal yet intuitive interface for rapidly exploring sequences. *Pure Data* was designed by Miller Puckette and is actively developed as an open source project. [puredata.info](http://puredata.info). -This tutorial was created by [Trent Gill](http://whimsicalraps.com) for [monome.org](https://monome.org), with updates in 2023 by David Niemi and [Dan Derks](https://dndrks.com). +This tutorial was created by [Trent Gill](http://whimsicalraps.com) for [monome.org](https://monome.org), with updates in 2023 by David Niemi and [Dan/i Derks](https://dndrks.com). Contributions welcome. Submit a pull request to [github.com/monome/docs](https://github.com/monome/docs) or e-mail [help@monome.org](mailto:help@monome.org). diff --git a/grid/studies/processing/index.md b/grid/studies/processing/index.md index 2f0cbea6..8d31a1be 100644 --- a/grid/studies/processing/index.md +++ b/grid/studies/processing/index.md @@ -5,9 +5,19 @@ redirect_from: /grid-studies-processing/ --- # Grid Studies: Processing +{: .no_toc } Processing is a programming language, development environment, and online community. Initially created to serve as a software sketchbook and to teach computer programming fundamentals within a visual context, Processing has evolved into a development tool for multi-media performance, including interaction with hardware devices and libraries for sound manipulation. Highly accessible and with a wealth of tutorial information, Processing is a great choice for coding with the monome grid and is fully cross-platform making it highly useful when sharing projects. +
+ + sections + + {: .text-delta } +- TOC +{:toc} +
+ ## Prerequisites If you're very new to Processing or Java, it will be very beneficial to work through the 'getting started' tutorial available directly from Processing.org: [processing.org/tutorials](https://processing.org/tutorials/gettingstarted/) @@ -36,7 +46,7 @@ For example, proper installation of `oscP5` on macOS would look like: You'll need to restart Processing if it's running while you installed these libraries. -## 1. Connect +## 1. Connect {#connect} The monome-processing library facilitates easy connection and communication with grids. Connect to a grid with the following code: @@ -59,7 +69,7 @@ m = new Monome(this, "m1000011"); The library communicates with *serialosc* to discover attached devices using OSC. For a detailed description of how the mechanism and protocol work, see [monome.org/docs/tech:osc](http://monome.org/docs/tech:osc). -## 2. Basics +## 2. Basics {#basics} In this section, we'll cover how to: @@ -67,7 +77,7 @@ In this section, we'll cover how to: - draw LEDs coupled to key presses - draw LEDs decoupled from key presses -### 2.1 Key Input +### 2.1 Key Input {#key-input} *See `grid_studies_2_1.pde` for this section.* @@ -89,7 +99,7 @@ public void key(int x, int y, int s) { We will, of course, do more interesting things with this function in the future. -### 2.2 Drawing LEDs +### 2.2 Drawing LEDs {#drawing-leds} *See `grid_studies_2_2.pde` for this section.* @@ -121,7 +131,7 @@ As seen in `grid_studies_2_2.pde` we place this code inside the `draw()` functio ![](images/grid-studies-processing-seen.png) -### 2.3 Coupled LED Interaction +### 2.3 Coupled LED Interaction {#coupled-led-interaction} *See `grid_studies_2_3.pde` for this section.* @@ -167,7 +177,7 @@ Once we've refreshed the grid, we set the `dirty` flag to `false` so we're not n The `draw()` function is called at 60 frames per second unless you specify a different rate in `setup()` such as `frameRate(10);`. -### 2.4 Decoupled LED Interaction +### 2.4 Decoupled LED Interaction {#decoupled-led-interaction} The most basic decoupled interaction is a toggle. Turn the grid into a huge bank of toggles simply by changing line 22, in the `key` function: @@ -177,7 +187,7 @@ if(s == 1) led[y][x] ^= 15; Now, only key presses (s = 1) do something, whereas releases are ignored. Each key press uses an XOR operator to toggle the LED value between 0 and 15, depending on the previous state of the LED. -## 3. Further +## 3. Further {#further} Now we'll show how basic grid applications are developed by creating a step sequencer. We will add features incrementally: @@ -190,7 +200,7 @@ Now we'll show how basic grid applications are developed by creating a step sequ - Adjust playback loop with two-key gesture in position row. -### 3.1 Toggles +### 3.1 Toggles {#toggles} *See `grid_studies_3_1.pde` for this step.* @@ -225,7 +235,7 @@ if(dirty) { That'll get us started. -### 3.2 Play +### 3.2 Play {#play} *See `grid_studies_3_2.pde` for this step.* @@ -273,7 +283,7 @@ for(int x=0;x<16;x++) { During this loop which copies steps to the grid, we check if we're updating a column that is the play position. If so, we increase the highlight value. By adding this value during the copy we'll get a nice effect of an overlaid translucent bar. -### 3.3 Triggers +### 3.3 Triggers {#triggers} *See `grid_studies_3_3.pde` for this step.* @@ -313,7 +323,7 @@ public void trigger(int i) { Some code is added throughout the file to set up drawing and gently fade everything on each redraw. -### 3.4 Cutting +### 3.4 Cutting {#cutting} *See `grid_studies_3_4.pde` for this step.* @@ -359,7 +369,7 @@ if(timer == STEP_TIME) { Now, when pressing keys on the bottom row it will cue the next position to be played. Note that we set `cutting = false` after each cycle so that each press only affects the timer once. -### 3.5 Loop +### 3.5 Loop {#loop} Lastly, we'll implement setting the loop start and end points with a two-press gesture: pressing and holding the start point, and pressing an end point while still holding the first key. We'll need to add a variable to count keys held, one to track the last key pressed, and variables to store the loop positions. @@ -423,9 +433,9 @@ if(timer == STEP_TIME) { Done! -## Closing +## Closing {#closing} -### Suggested Exercises +### Suggested Exercises {#suggested-exercises} - "Record" keypresses in the "trigger" row to the toggle matrix. - Display the loop range on the bottom row of the grid. @@ -434,7 +444,7 @@ Done! - If "alt" is held while pressing the play row, reverse the direction of play. -## Credits +## Credits {#credits} *Processing* was designed by Ben Fry and Casey Reas and is maintained by the [Processing Foundation](processing). diff --git a/grid/studies/python/index.md b/grid/studies/python/index.md index 4e543ca4..1733c1ae 100644 --- a/grid/studies/python/index.md +++ b/grid/studies/python/index.md @@ -495,6 +495,6 @@ Python was designed by Guido van Rossum and is maintained by the [Python Softwar *pymonome* was written and is maintained by [Artem Popov](https://github.com/artfwo/pymonome). -This tutorial was created by [Brian Crabtree](http://nnnnnnnn.org) and [Dan Derks](https://dndrks.com) for [monome.org](https://monome.org). +This tutorial was created by [Brian Crabtree](http://nnnnnnnn.org) and [Dan/i Derks](https://dndrks.com) for [monome.org](https://monome.org). Contributions welcome. Submit a pull request to [github.com/monome/docs](https://github.com/monome/docs) or e-mail [help@monome.org](mailto:help@monome.org). diff --git a/grid/studies/rnbo/index.md b/grid/studies/rnbo/index.md index c1e8d524..0d0c3319 100644 --- a/grid/studies/rnbo/index.md +++ b/grid/studies/rnbo/index.md @@ -4,11 +4,21 @@ nav_exclude: true --- # Grid Studies: RNBO +{: .no_toc } RNBO, by [Cycling '74](https://cycling74.com/), is a library and toolchain that uses the same visual programming patching paradigm of [Max](/docs/grid/studies/max/), but which can be compiled to run on a number of external targets. Though RNBO can export to web experiences and audio plugins, this study will focus on the Raspberry Pi target. This tutorial will show the basics of interfacing with the grid including how a simple, yet immediate sequencer platform can be made with a small amount of code. +
+ + sections + + {: .text-delta } +- TOC +{:toc} +
+ ## IMPORTANT: Prerequisites {#prerequisites} Since RNBO is an extension of Max, this study assumes familiarity with Max's patching interface and workflow nuances. We'll also assume familiarity with navigating a command line interface, as required by the RNBO Raspberry Pi export process. If you're absolutely new to RNBO it may be helpful to first go through the documents and videos at the [RNBO Hub](https://rnbo.cycling74.com/). @@ -41,7 +51,7 @@ To monitor the `[print]` messages throughout this study, SSH into your RNBO Pi a journalctl -u rnbooscquery -f ``` -## 1. Connect +## 1. Connect {#connect} To communicate with grids we trade OSC messages with serialosc. serialosc is an invisible daemon on your computer, which translates OSC messages to streams of numbers over USB. @@ -96,7 +106,7 @@ After completing the steps above, open `grid-rnbo-1.maxpat` and perform each of ![](images/rnbo-studies-1.png) -## 2. Basics +## 2. Basics {#basics} *See `grid-rnbo-2.maxpat` for this section.* @@ -104,7 +114,7 @@ RNBO's [inports and outports](https://rnbo.cycling74.com/learn/messages-and-port ![](images/rnbo-studies-2.png) -### 2.1 Key input +### 2.1 Key input {#key-input} *Open and export `grid-rnbo-2-1` to your Pi for this section.* @@ -119,7 +129,7 @@ To see what is coming from the grid, we'll print the `x`, `y` and `z` values rep Since Max and RNBO both execute in right-to-left order, we'll use `[list.rot 1]` to rotate our incoming grid messages (typically reported as `/monome/grid/key x y z`), so we have `z` state listed first. We then use `[list.slice 1]` to slice up the messages into `z` (left outlet) and `x,y` (right outlet), which then print in order of Cartesian coordinate *then* state. -### 2.2 Coupled LED output +### 2.2 Coupled LED output {#coupled-led-output} *Open and export `grid-rnbo-2-2` to your Pi for this section.* @@ -129,7 +139,7 @@ The most basic grid patch is "light up the pressed key", which we can implement To clear the entire grid when our patch is loaded, we send `[loadmess 0]` through `[outport /monome/grid/led/all]`. -### 2.3 Decoupled interaction +### 2.3 Decoupled interaction {#decoupled-interaction} *Open and export `grid-rnbo-2-3` to your Pi for this section.* @@ -164,7 +174,7 @@ if (z == 1){ // key-down only By simply connecting the outlet of our `[codebox]` to the inlet of the grid's `[outport]` (and exporting to the Pi), we now have a toggle bank! -## 3.0 Further +## 3.0 Further {#further} *See `grid-rnbo-3.maxpat` for this step.* @@ -180,7 +190,7 @@ Now we'll show how basic grid applications are developed by creating a step sequ ![](images/rnbo-studies-3.png) -### 3.1 Toggles +### 3.1 Toggles {#toggles} *Open and export `grid-rnbo-3-1` to your Pi for this section.* @@ -202,7 +212,7 @@ if (z == 1 && (y < 6)){ // key-down only, in first six rows } ``` -### 3.2 Play +### 3.2 Play {#play} *Open and export `grid-rnbo-3-2` to your Pi for this section.* @@ -232,7 +242,7 @@ We'll also add a [parameter](https://rnbo.cycling74.com/learn/using-parameters) Now when you export to the Pi target, you'll see the playhead moving along the bottom row. -### 3.3 Triggers and notes +### 3.3 Triggers and notes {#triggers-and-notes} *Open and export `grid-rnbo-3-3` to your Pi for this section.* @@ -282,7 +292,7 @@ Lastly, there's a tiny sound engine so you can actually hear something. You can ![](images/rnbo-studies-3-3-3.png) -### 3.4 Cutting and Looping +### 3.4 Cutting and Looping {#cutting-and-looping} *Open and export `grid-rnbo-3-4` to your Pi for this section.* @@ -345,11 +355,11 @@ function in2(col){ } ``` -## Closing +## Closing {#closing} We've created a minimal yet intuitive interface for rapidly exploring sequences -- we can change event triggers, loop points, and jump around the data performatively. Many more features could be added. There are numerous other ways to think about interaction between key press and light feedback in completely different contexts. -### Suggested exercises +### Suggested exercises {#suggested-exercises} - Add MIDI output - If you have access to a 256 grid, try adapting the 3.x patches to accommodate this larger size. @@ -360,10 +370,10 @@ We've created a minimal yet intuitive interface for rapidly exploring sequences - If "alt" is held while pressing a toggle, clear the entire row. - If "alt" is held while pressing the play row, reverse the direction of play. -## Credits +## Credits {#credits} *RNBO* is bundled with *Max* and is actively developed by [Cycling '74](http://cycling74.com). -This tutorial was created by [Dan Derks](https://dndrks.com) for [monome.org](https://monome.org), with generous feedback and counsel from Cycling '74 (Alex Norman, Tom Hall, and Alex Van Gils). +This tutorial was created by [Dan/i Derks](https://dndrks.com) for [monome.org](https://monome.org), with generous feedback and counsel from Cycling '74 (Alex Norman, Tom Hall, and Alex Van Gils). Contributions welcome. Submit a pull request to [github.com/monome/docs](https://github.com/monome/docs) or e-mail `help@monome.org`. \ No newline at end of file diff --git a/grid/studies/sc/index.md b/grid/studies/sc/index.md index 1c56d321..6d101c99 100644 --- a/grid/studies/sc/index.md +++ b/grid/studies/sc/index.md @@ -550,6 +550,6 @@ Done! The original `monom` SuperCollider library was written by [Raja Das and Joseph Rangel](https://github.com/Karaokaze/Monom_SCs), was maintained by [Ezra Buchla](https://github.com/catfact/monom/), and was re-built into `monomeSC` in 2023 by [Dan Derks](https://dndrks.com). -This tutorial was written by [Brian Crabtree](http://nnnnnnnn.org) and [Dan Derks](https://dndrks.com) for [monome.org](https://monome.org). Huge thanks to Raja Das for his very extensive 'Monoming with SuperCollider Tutorial'. +This tutorial was written by [Brian Crabtree](http://nnnnnnnn.org) and [Dan/i Derks](https://dndrks.com) for [monome.org](https://monome.org). Huge thanks to Raja Das for his very extensive 'Monoming with SuperCollider Tutorial'. Contributions welcome. Submit a pull request to [github.com/monome/docs](https://github.com/monome/docs) or e-mail [help@monome.org](mailto:help@monome.org). diff --git a/grid/studies/seamstress/index.md b/grid/studies/seamstress/index.md index e2a616e8..3e43d77d 100644 --- a/grid/studies/seamstress/index.md +++ b/grid/studies/seamstress/index.md @@ -3,7 +3,7 @@ layout: default nav_exclude: true --- -# grid studies: seamstress +# Grid Studies: Seamstress {: .no_toc } [seamstress](https://github.com/ryleelyman/seamstress/) is a Lua scripting environment for musical communication. It was inspired by [norns](/docs/norns) and makes use of its [scripting API](/docs/norns/reference), but it is **not** a port of the norns environment. Generally, though, seamstress is a fantastic complement to the norns scripting experience, as it has many syntactical similarities and many of the same scripting libraries. @@ -21,7 +21,7 @@ For an overview of the primary scripting differences between the two platforms, {:toc} -## prerequisites +## Prerequisites This study assumes a basic understanding of Lua. If you're absolutely new to Lua it may be helpful to first go through some of [the resources listed in our norns documentation](/docs/norns/studies/#learning-lua). @@ -37,7 +37,7 @@ Required: - Install serialosc: [/docs/serialosc/setup](/docs/serialosc/setup) - Download the code examples here: [files/grid-studies-seamstress.zip](files/grid-studies-seamstress.zip) -### running examples +### Running Examples seamstress is run from the terminal by executing the command `seamstress`. If it is not given any filename, seamstress looks for and runs a file called `script.lua` in either the current directory or in `~/seamstress/`. @@ -48,7 +48,7 @@ cd grid-studies-seamstress/files seamstress grid-studies-1 ``` -## 1. connect + basics {#connect} +## 1. Connect + Basics {#connect} *See [grid-studies-1.lua](files/grid-studies-1.lua) for this section.* @@ -79,11 +79,11 @@ This script is a very basic example of how to: As you press keys on your grid, you'll see them light up for as long as they're held. -### connection +### Connection `g = grid.connect()` creates a device table `g`, which inherits a collection of methods (demarcated with `:`) and functions designed to handle grid communication. For grid, we'll use *methods* to send commands to the grid and we use *functions* to parse what comes back. -### key input +### Key Input The `g` device table has callback *functions* for what happens when you push a key. We can assign an action to any grid key press, where `x` and `y` are the coordinates (1-indexed) and `z` is the keypress state (down: `1`, up: `0`): @@ -93,7 +93,7 @@ function g.key(x, y, z) end ``` -### LED output +### LED Output In our example script, we use two *methods* to light up the grid: @@ -102,7 +102,7 @@ In our example script, we use two *methods* to light up the grid: If we're simply interested in displaying presses, this is fine enough. But for scripts where we want to display more layers of information, this approach of directly addressing and redrawing each individual LED isn't very efficient. Let's improve upon our approach in the next section! -## 2. building a script {#scripting} +## 2. Building a Script {#scripting} When you first approach writing a grid-enabled script in seamstress, it can be helpful to start with a basic structure that has a few different components: @@ -113,7 +113,7 @@ When you first approach writing a grid-enabled script in seamstress, it can be h Moving forward, we'll refresh the grid display on a timer, which will also serve as the playhead later on. -### 2.1 basic script {#basic-script} +### 2.1 Basic Script {#basic-script} Below is a basic script that facilitates this structure: @@ -192,11 +192,11 @@ So we can write a responsive interface for our step sequencer, we establish a fe - `rows`, which we'll to set the maximum number of tracks - `grid_connected`, which we'll use to query whether there's a grid to communicate with -### schedule, process, display {#schedule-process-display} +### Schedule, Process, Display {#schedule-process-display} In our script's `init`, we schedule two functions to be executed at regular intervals. -#### clock +#### Clock The first is done with the `clock` library, which allows tempo-synced scheduling: @@ -216,7 +216,7 @@ end In `play`, we perform our actions and then sync to the clock at a quarter pulse (which is a 1/16th note in 4/4). -#### metro +#### Metro The second is done with the `metro` library, which allows scheduling with high-accuracy timers: @@ -241,7 +241,7 @@ end Since we want the grid to draw at a steady 60 frames-per-second, we opt for the higher-resolution `metro`, rather than the 'musical timing' `clock`. -### 2.2 add something to the screen {#screen} +### 2.2 Add Something to the Screen {#screen} Let's add a very small indicator to the screen which tells us whether a grid is connected or not: @@ -271,7 +271,7 @@ end So, we have our boilerplate -- let's take things further by building a bank of toggles for the sequencer. -## 3. making a step sequencer {#step} +## 3. Making a Step Sequencer {#step} To show how basic grid-enabled seamstress scripts are developed, let's create a step sequencer. We will add features incrementally: @@ -283,7 +283,7 @@ To show how basic grid-enabled seamstress scripts are developed, let's create a - Jump to playback position when key pressed in the position row. - Adjust playback loop with two-key gesture in position row. -### 3.1 toggles {#toggles} +### 3.1 Toggles {#toggles} *See [grid-studies-3-1.lua](files/grid-studies-3-1.lua) for this section.* @@ -325,7 +325,7 @@ end That'll get us started. -### 3.2 play {#play} +### 3.2 Play {#play} *See [grid-studies-3-2.lua](files/grid-studies-3-2.lua) for this section.* @@ -373,7 +373,7 @@ end While iterating over the steps in a loop, we check if we're updating a column that is the play position. If so, we increase the highlight value. By adding this value during the iteration we'll get a nice effect of an overlaid translucent bar. -### 3.3 triggers {#triggers} +### 3.3 Triggers {#triggers} *See [grid-studies-3-3.lua](files/grid-studies-3-3.lua) for this section.* @@ -600,7 +600,7 @@ end -- // NEW ``` -### 3.5 dynamic cuts {#dynamic-cuts} +### 3.5 Dynamic Cuts {#dynamic-cuts} *See [grid-studies-3-5.lua](files/grid-studies-3-5.lua) for this section.* @@ -626,7 +626,7 @@ elseif y == rows and z == 1 then Now, when pressing keys on the bottom row it will cue the next position to be played. -### 3.6 loop {#loop} +### 3.6 Loop {#loop} *See [grid-studies-3-6.lua](files/grid-studies-3-6.lua) for this section.* @@ -686,7 +686,7 @@ elseif y == rows then end ``` -## 4. transport {#transport} +## 4. Transport {#transport} *See [grid-studies-4.lua](files/grid-studies-4.lua) for this section.* @@ -695,7 +695,7 @@ As a bonus round, let's extend our script by: - adding transport controls so we can start and stop our sequencer - tying incoming transport start/stop messages to the script's sense of place and time -### adding transport actions {#transport-actions} +### Adding Transport Actions {#transport-actions} If you're used to highly-structured Digital Audio Workstations, then you might be looking for ways to create meaningful 'start' and 'stop' functionality within a seamstress script. @@ -750,7 +750,7 @@ end) -- // NEW ``` -### transport callbacks {#transport-callbacks} +### Transport Callbacks {#transport-callbacks} There are two system-level callbacks which can be assigned in your script to perform specific actions whenever the seamstress clock receives a 'start' and 'stop' message: `clock.transport.start` and `clock.transport.stop`. @@ -771,11 +771,11 @@ function clock.transport.stop() end ``` -## closing +## Closing We've created a minimal yet intuitive interface for rapidly exploring sequences. We can intuitively change event triggers, loop points, and jump around the data performatively. Many more features could be added, and there are numerous other ways to think about interaction between key press and light feedback in completely different contexts. -### suggested exercises +### Suggested Exercises - display the loop range with dim LED levels - record keypresses in the "jump" row @@ -783,10 +783,10 @@ We've created a minimal yet intuitive interface for rapidly exploring sequences. - if "alt" is held while pressing a toggle, clear the entire column - if "alt" is held while pressing the play row, reverse the direction of play -## credits +## Credits -seamstress was developed and designed by [Rylee Alanza Lyman](https://ryleealanza.org/), inspired by [*matron* from norns](https://github.com/monome/norns/tree/main/matron/src). *matron* was written by [`@catfact`](https://github.com/ryleelyman/seamstress). norns was initiated by [`@tehn`](https://github.com/tehn). +seamstress was developed and designed by [Robbie Lyman](https://github.com/robbielyman), inspired by [*matron* from norns](https://github.com/monome/norns/tree/main/matron/src). *matron* was written by [`@catfact`](https://github.com/ryleelyman/seamstress). norns was initiated by [`@tehn`](https://github.com/tehn). -This tutorial was created by [Dan Derks](https://dndrks.com) for [monome.org](https://monome.org). +This tutorial was created by [Dan/i Derks](https://dndrks.com) for [monome.org](https://monome.org). Contributions welcome. Submit a pull request to [github.com/monome/docs](https://github.com/monome/docs) or e-mail `help@monome.org`. \ No newline at end of file