seamstress is a Lua scripting environment for communicating with music, visuals and data.
seamstress is run from the command line.
invoke it with seamstress or seamstress <filename>
(seamstress -h lists optional command-line arguments).
on startup, seamstress will search for a user-provided script file
named <filename>.lua (defaulting to script.lua) to run.
this file may either be found in the current directory of your command-line prompt
or in ~/seamstress (that is, a folder named seamstress under your $HOME directory,
which is typically /Users/<username> on macOS and /home/<username> on Linux).
on startup, seamstress creates two OS windows
and commandeers the command-line prompt as a Lua
REPL (short for read evaluate print loop).
one of these windows is reserved for seamstress's params system,
while the other (the main window)
is available for scripts to draw to using seamstress's screen module.
to exit seamstress, close the main window or enter quit in to the REPL.
seamstress scripts are written in Lua, an embeddable, extensible scripting language. as of 1.0.0, seamstress supports Lua version 5.4.x. Lua.org has resources for programming in Lua. additionally, monome has studies for scripting in Lua for norns and seamstress to get you off the ground.
seamstress requires freetype2, harfbuzz and ncurses. on macOS do
brew install freetype2 harfbuzz ncursesalternatively to install with homebrew, do
brew tap ryleelyman/seamstress
brew install seamstresson linux, additional requirements include alsa.
each release comes with a binary for x86_64 linux and macOS,
as well as aarch64 (Apple silicon) macOS.
download the appropriate file, unzip it and
(technically optionally) add it to your PATH.
if you'd like to use monome devices with seamstress, you'll need to install serialosc.
NB: seamstress expects the file structure found inside the zipped folder
and will not work as expected if you move only the binary to a different folder.
building seamstress from source requires version 0.11.0 of zig.
the easiest way to get zig is to download a binary from here and add it to your PATH.
seamstress follows releases of zig.
to build seamstress, install the dependencies listed above (as well as pkg-config) and invoke
zig buildNB: this command builds seamstress in Debug mode.
you can change this
by passing -Doptimize=ReleaseFast or -Doptimize=ReleaseSafe to the build command.
NB: seamstress will be built as zig-out/bin/seamstress; you can add this to your PATH to have it available as seamstress.
if you previously built seamstress with sudo, you may want to run sudo zig build uninstall -p /usr/local to remove the old binary.
you may also have to delete ~/.cache/zig as well as zig-cache in the relevant directories.
the lua API is documented here.
to regenerate docs, you'll need LDoc,
which requires Penlight.
with both installed, running ldoc . in the base directory of seamstress will
regenerate documentation.
lua formatting is done with stylua,
while zig formatting is done with zig fmt.
a stylua.toml is provided, so if you feel like matching seamstress's "house lua style",
simply run stylua . in the root of the repo.
similarly, you can run zig fmt filename.zig to format filename.zig.
(this is not a requirement for contributing.)
seamstress is inspired by monome norns's matron, which was written by @catfact. norns was initiated by @tehn.