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.
to install with homebrew, do
brew tap ryleelyman/seamstress
brew install seamstressif you'd like to use monome devices with seamstress, you'll need to install serialosc.
to instead build from source, you'll need the following libraries. the following incantation is for homebrew, but the list of dependencies is identical on linux.
brew install pkg-config zig asio liblo lua readline rtmidi sdl2 sdl2_image sdl2_ttfwith those installed, you can execute
zig buildto build a copy of seamstress in zig-out.
NB: this command builds seamstress in Debug mode.
you can change this
by passing -Doptimize=ReleaseFast or -Doptimize=ReleaseSafe to the build command.
NB: the created seamstress expects the directory structure
within zig-out. if you move zig-out/bin/seamstress somewhere else,
say to /usr/local/bin/seamstress
don't forget to move zig-out/share/seamstress to /usr/local/share/seamstress as well.
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.