util  Check-in [a597ad7ee7]

Added ostinata/ostinata.ct version [6c33a286d0].

            1  +# ostinata
            2  +ostinata is a simple TUI tool for composing music using csound instruments.
            3  +
            4  +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.
            5  +
            6  +## operation
            7  +when you launch ostinata, it will drop you at the command prompt. the following commands are currently understood:
            8  +
            9  +* ["pl]: enter play mode
           10  +* ["q]: quit ostinata
           11  +* [`t]: report the current clock time in seconds from the beginning of the score.
           12  +* [`t [$secs]]: set the clock to [$secs] seconds from the beginning of the score.
           13  +* [`f [$name]]: report or set the composition filename
           14  +* [`in [$instrument]]: set the channel instrument
           15  +* [`ch]: report the current channel ID
           16  +* [`ch set [$id]]: switch to a different channel, creating it if it does not exist
           17  +* [`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.
           18  +* ["ch ls]: list channels and their settings
           19  +* [`cfg [$key] [$val]]: set channel configuration. common properties include:
           20  +** ["base]: the frequency of the ntoe represented by the "a" key
           21  +** ["span]: the frequency range of the channel. the "l" note has a frequency of [= [$base] + [$span]].
           22  +** ["dwell]: how long a note will take to fade once released
           23  +* [`iso (set|add|del) [$channel-id] ...]: configures the isolation state. [`add] adds the listed channels to the isolation list; [`del] removes them.
           24  +* [`iso off]: wipe the isolation list
           25  +* [`mute \[(on|off)\]]: toggle channel mute state, or set it to a particular value
           26  +* [`amp [$val]]: displays or sets channel amplitude.
           27  +* [`perf]: play back the composition in its entirety
           28  +* [`sc]: print the score
           29  +* [`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].
           30  +* [`sc erase all]: completely wipe the current score. does not affect channel setup.
           31  +* [`st pid]: report the pid of the csound backend process
           32  +## play mode
           33  +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.
           34  +
           35  +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.
           36  +
           37  +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.
           38  +
           39  +to change the base velocity (default 1), type a numeral 1-9.
           40  +
           41  +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.
           42  +
           43  +other commands will use the top alphabetic row. it is intended to add support for
           44  +* automatic arpeggios

Modified ostinata/ostinata.janet from [567adb1f1f] to [25682f4541].

   360    360   		(defn commit-unless-shift []
   361    361   			(unless (string/check-set (event :mods) :s)
   362    362   				(commit-score)))
   363    363   		
   364    364   		(match event
   365    365   			{:how :press :key (@ (comptime ("q" 0)))}
   366    366   				(do (stop-all-notes)
   367         -					(:set-mode env :cmd)
   368         -					(commit-unless-shift))
          367  +					(when rec (commit-unless-shift))
          368  +					(:set-mode env :cmd))
   369    369   			{:how :press :key (@ (comptime ("r" 0)))}
   370    370   				(do (stop-all-notes)
   371    371   					(toggle rec)
   372    372   					(if rec (start-clock) (stop-clock))
   373    373   					(commit-unless-shift))
   374    374   			{:how :press   :key :shift-l} (+= loud 1)
   375    375   			{:how :release :key :shift-l} (-= loud 1)