util  Check-in [a597ad7ee7]

# ostinata
ostinata is a simple TUI tool for composing music using csound instruments.

note that in order to be usable, ostinata needs a terminal that supports the kitty keyboard protocol, since there is no other way to get key release events.

## operation
when you launch ostinata, it will drop you at the command prompt. the following commands are currently understood:

* ["pl]: enter play mode
* ["q]: quit ostinata
* [`t]: report the current clock time in seconds from the beginning of the score.
* [`t [$secs]]: set the clock to [$secs] seconds from the beginning of the score.
* [`f [$name]]: report or set the composition filename
* [`in [$instrument]]: set the channel instrument
* [`ch]: report the current channel ID
* [`ch set [$id]]: switch to a different channel, creating it if it does not exist
* [`ch mv [$from] (to|clobber|merge) [$to]]: moves a channel from one ID to another. [`clobber] will simply overwrite any existing channel with the ID [$to]. [`merge] merges the two channels.
* ["ch ls]: list channels and their settings
* [`cfg [$key] [$val]]: set channel configuration. common properties include:
** ["base]: the frequency of the ntoe represented by the "a" key
** ["span]: the frequency range of the channel. the "l" note has a frequency of [= [$base] + [$span]].
** ["dwell]: how long a note will take to fade once released
* [`iso (set|add|del) [$channel-id] ...]: configures the isolation state. [`add] adds the listed channels to the isolation list; [`del] removes them.
* [`iso off]: wipe the isolation list
* [`mute \[(on|off)\]]: toggle channel mute state, or set it to a particular value
* [`amp [$val]]: displays or sets channel amplitude.
* [`perf]: play back the composition in its entirety
* [`sc]: print the score
* [`sc comp [$file]]: print the score as a csound score file. if [$file] is specified, the composition will be written to disk at path [$file].
* [`sc erase all]: completely wipe the current score. does not affect channel setup.
* [`st pid]: report the pid of the csound backend process
## play mode
in play mode, you can use the bottom two alphabetic rows of the keyboard to play notes with your chosen instrument ("a" ~ "l", "z" ~ ","). the bottom row corresponds to half-notes; i.e., "z" plays a note halfway between "a" and "s". to increase velocity for a single note by one step, hold left shift. to decrease velocity by half a step, hold right shift. these can be combined.

to toggle recording mode, press "r". when in recording mode, all (un-muted) tracks will be played back in realtime. any notes played while recording mode is active will, naturally, be added to the score.

to reset the clock to the current starting time, press tab. the starting time is the value of the clock at the point play mode was entered, which makes it easier to add notes iteratively. using the "t" command at the command prompt to set other clock values.

to change the base velocity (default 1), type a numeral 1-9.

if you exit recording mode while holding shift (that is, typing an uppercase "R" or "Q"), the notes added in the current session will not be committed to the score. if you make a mistake mid-record, "R<tab>" will cancel the record session and reset the clock to the start time.

other commands will use the top alphabetic row. it is intended to add support for
* automatic arpeggios

		(defn commit-unless-shift []
			(unless (string/check-set (event :mods) :s)
				(commit-score)))
		
		(match event
			{:how :press :key (@ (comptime ("q" 0)))}
				(do (stop-all-notes)

					(:set-mode env :cmd)
					(commit-unless-shift))
			{:how :press :key (@ (comptime ("r" 0)))}
				(do (stop-all-notes)
					(toggle rec)
					(if rec (start-clock) (stop-clock))
					(commit-unless-shift))
			{:how :press   :key :shift-l} (+= loud 1)
			{:how :release :key :shift-l} (-= loud 1)

		(defn commit-unless-shift []
			(unless (string/check-set (event :mods) :s)
				(commit-score)))
		
		(match event
			{:how :press :key (@ (comptime ("q" 0)))}
				(do (stop-all-notes)
					(when rec (commit-unless-shift))
					(:set-mode env :cmd))

			{:how :press :key (@ (comptime ("r" 0)))}
				(do (stop-all-notes)
					(toggle rec)
					(if rec (start-clock) (stop-clock))
					(commit-unless-shift))
			{:how :press   :key :shift-l} (+= loud 1)
			{:how :release :key :shift-l} (-= loud 1)