tek/README.md

# tek

a music making program for your terminal

## project status

> [!WARNING]
>
> As of 2024-10-25, I'm on track to releasing `tek 0.2.0` sometime in December 2024.
> I plan to tag the working prototype (as seen in the demos published in the
> [tek channel at basspistol's peertube](https://v.basspistol.org/c/tek/videos) as `0.1.0`—
> once I've identified the appropriate commit!
>
> I've been dreaming of this project for a decade, and finally had the experience and peace of mind
> to start building it in late May 2024.  I quickly reached the limit of how much of the UI I can
> write imperatively, so I started refactoring it in a more declarative style. The new interface
> logic is holding out pretty well, though it's not presently without its warts.
>
> Your moral support means a lot to me. Feel free to [contact me on Mastodon](https://mastodon.social/@unspeaker)!
> (Especially if you know how to host LV2 plugin UIs in `winit`; or how to relink abandoned Win32
> VST2s into LV2 or CLAP monoliths 😁)
>
> Love,
>
> (a rogue knowledge worker in a cyberpunk dystopia)

## what it does

Tek is a [MIDI](https://en.wikipedia.org/wiki/MIDI) sequencer, sampler, and plugin host
for the Linux terminal. It's written in [Rust](https://www.rust-lang.org/), and targets
[JACK](https://jackaudio.org/) (or [Pipewire](https://www.pipewire.org/)'s JACK implementation).

## design goals

### lightweight

My goal is to have a pop-up scratchpad for musical ideas that doesn't get in the way
of building upon them. Kind of like [Ableton](https://www.ableton.com/) — but for free systems,
and without all the bloat!

### flexible

Besides Ableton, I'm also inspired by the workflow of trackers and various old-school hardware
sequencers (of which I've broken several). I've found that every existing music-making tool
takes me about 80% of the way to the music I want to make. And so, after a decade of fucking
around, I've decided it's finally time to make good on my old dream to build the instrument
that will take me 100% there.

### programmable

A secondary goal is to make my music making environment extensible, programmable, and
interoperable; the intended project format is an
[S-expression](https://en.wikipedia.org/wiki/S-expression)-based notation
([EDN](https://en.wikipedia.org/wiki/Clojure#Extensible_Data_Notation),
[Steel](https://github.com/mattwparas/steel), or similar... though I've also been
looking for an excuse to embed a
[Forth](https://en.wikipedia.org/wiki/Forth_(programming_language)) 😏)

## getting started

### requirements

* Linux
* JACK or Pipewire
* a terminal (I use `kitty`)

### recommended

* MIDI controller
* Samples
* LV2 plugins

### downloads

> [!WARNING]
>
> Binaries are currently unavailable. Right now your only option is to build from source.
> In the future I plan to integrate Codeberg Actions.

### building from source

You need a Rust toolchain and various system libraries. You can obtain the former
using `rustup` and the latter using `nix-shell`. From there, use the commands in the
`Justfile`, e.g.:

```sh
just arranger
```

## usage

> [!WARNING]
>
> The following applies to `tek 0.1.0`. I will update it as part of the `0.2.0` release.

### Overview

Tek is inspired by "clip launching" workflows as exemplified by Ableton Live, Bitwig Studio,
Ardour, and probably others. The main view consists of three sections:

* The **arranger view** corresponds to Ableton's Session and Arrangement views.
  It allows you to put together a musical composition as a sequence of **phrases**,
  playing simultaneously across multiple **tracks**.
* The **sequencer view** allows you to edit phrases, which consist of MIDI events.
* The **chain view** allows you to add **devices** to each track. Devices determine
  how a given phrase will sound. Currently, there are two devices implemented:
  **sampler** and **plugin**.

> [!NOTE]
> Use `Tab` to switch focus between views. Use `Enter` to exclusively focus the highlighted view,
> and `Esc` to unfocus it. When a view is focused, use the `Arrow Keys` and `Enter` to navigate.
> Use `;` (semicolon) to open the command palette, which will list the remaining keybindings.

## todo

* framework:
  * command system:
    * [ ] customize key map
    * [ ] midi map
    * [ ] scriptable
    * [ ] command panel
    * [ ] search panel
  * rendering:
    * [ ] LineBuffer for scroll?
    * [ ] Buffered rendering with e.g. needs_update (only needed if the release build becomes slow)
      * [x] Buffered sequencer
      * [ ] Buffered chain view
* transport/arranger/sequencer:
  * [x] Fix next/prev clip
  * [ ] Move clip/track/scene
  * [ ] Set track gain
  * [ ] Play from one clip, record into another
  * [ ] Offbeat of next clip starts during end of first
  * [ ] Pattern chain
  * [ ] Actually sync
  * transport:
    * [x] Focus transport to set BPM/sync/quant with `.,`
    * [ ] Double/halve BPM with `xX`
  * save and load:
    * [ ] human readable format
    * [ ] preserve formatting
* synth/sampler/fx chain:
  * sampler:
    * [x] Sample browser
    * [ ] Resample
    * [ ] Repitch
    * [ ] Sample editor
    * [ ] Envelope
    * [ ] Stretch sample to BPM
    * [ ] Set BPM from sample
    * [ ] Map MIDI note to sample
    * [ ] Multisample
  * Chain:
    * [ ] Add device
    * [ ] View and connect device ports in chain view
    * [ ] Open LV2 GUI
    * [ ] Pin favorite FX parameters with `*`
    * [ ] Parallel monitoring chain
    * [ ] Support CLAP plugins
    * [ ] Support VST2
    * [ ] Support VST3