From 78ae60302301ae56a446b25a7db1617ecf32c7d5 Mon Sep 17 00:00:00 2001 From: unspeaker Date: Mon, 30 Dec 2024 22:14:39 +0100 Subject: [PATCH] update README --- README.md | 182 +++++++++++++----------------------------------------- 1 file changed, 42 insertions(+), 140 deletions(-) diff --git a/README.md b/README.md index af9208ba..ef493af3 100644 --- a/README.md +++ b/README.md @@ -1,87 +1,43 @@ # tek [![Please don't upload to GitHub](https://nogithub.codeberg.page/badge.svg)](https://nogithub.codeberg.page) -a music making program for your terminal +a music making program for [24-bit unicode terminals](https://sw.kovidgoyal.net/kitty/). + +written in [rust](https://www.rust-lang.org/) +with [ratatui](https://ratatui.rs/) on [crossterm](https://docs.rs/crossterm/latest/crossterm/) +for [jack](https://jackaudio.org/) and [pipewire](https://www.pipewire.org/). + +**tek** is available as [source](https://codeberg.org/unspeaker/tek#building-from-source), +[statically linked binaries](https://codeberg.org/unspeaker/tek/releases), and on the +[aur](https://codeberg.org/unspeaker/tek#arch-linux). ![Screenshot](https://codeberg.org/unspeaker/tek/attachments/549efab7-f46b-438b-9508-cd499d044b41) -## what it does +this codebase produces the following binaries: -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). +* **`tek_sequencer`** is a single-track, multi-pattern MIDI sequencer with properly tempo-synced pattern switch +* **`tek_groovebox`** connects the sequencer to a sampler, so that you can sample while you sequence +* **`tek_arranger`** is a multi-track sequencer based on a familiar clip launching UI +* **`tek_transport`** is a JACK transport controller +* **`tek_sampler`** is a MIDI-controlled sampler +* **`tek_plugin`** is an audio plugin host. +* **`tek_channel`** is a standalone channel strip +* **`tek_mixer`** is an audio mixer. -> [!NOTE] -> -> 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... and refactoring... and refactoring... you know -> how it is. +some of these are currently work in progress. -## project status - -for roadmap, see https://codeberg.org/unspeaker/tek/milestones - -> [!NOTE] -> -> As of 2024-12-25, the release window has been open since 2024-12-10. -> [6 alpha/beta versions have been published on the Releases page](https://codeberg.org/unspeaker/tek/releases). - -> [!NOTE] -> -> I still want to tag the first working prototypes (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! - -[^0]: (Especially if you know how to host LV2 plugin UIs in `winit`; -or how to relink abandoned Win32 VST2s into LV2 or CLAP monoliths 😁) - -## 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)) 😏) +the project roadmap is at https://codeberg.org/unspeaker/tek/milestones ## getting started -### requirements - -* Linux -* JACK or Pipewire -* a terminal supporting 24-bit colors (I use `kitty`) - -### recommended - -* MIDI controller -* Samples -* LV2 plugins +* **requirements:** linux; jack or pipewire; 24-bit terminal (i use `kitty`) +* **recommended:** midi controller; samples in wav format; lv2 plugins. ### installation #### arch linux -[tek](https://codeberg.org/unspeaker/tek) is available as a package in the AUR. You can install it using an AUR helper (e.g. `paru`): +[tek](https://codeberg.org/unspeaker/tek) is available as a package in the AUR. +you can install it using an AUR helper (e.g. `paru`): ```sh paru -S tek @@ -89,92 +45,38 @@ paru -S tek ### downloads -See the [releases page](https://codeberg.org/unspeaker/tek/releases). +see the [releases page](https://codeberg.org/unspeaker/tek/releases). ### 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.: +you'll need a Rust toolchain and various system libraries. + +you can obtain the former using `rustup` and the latter using `nix-shell`. +there's a `shell.nix` provided with the project. + +from there, use the commands in the `Justfile`, e.g.: ```sh just arranger ``` -## contents +## design goals -This crate provides several musical utilities. +### lightweight -### `tek_sequencer` +* pop-up scratchpad for musical ideas +* low resource consumption, can stay open in background +* advanced toolset allows quickly expanding on compositions -A single-track, multi-pattern MIDI sequencer with properly tempo-synced pattern switch. +### flexible -### `tek_groovebox` +* inspired by trackers and hardware sequencers +* able to record while playing! -A single-track, multi-pattern MIDI sequencer, attached to a sampler or plugin -(see `tek_plugin`). +### programmable -### `tek_arranger` - -A multi-track, multi-pattern MIDI sequencer translating the familiar clip launching workflow -into the TUI medium. - -### `tek_transport` - -Standalone JACK transport controller. - -* Todo: bpm: shift +/- 0.001 -* Todo: quant/sync: shift = next/prev value of same type (normal, triplet, dotted) - * Or: use shift to switch between inc/dec top/bottom value? -* Todo: focus play button -* Todo: focus time position -* Todo: edit numeric values -* Todo: jump to time/bbt markers -* Todo: count xruns - -## `tek_sampler` - -TODO: Standalone MIDI-controlled sampler. - -## `tek_mixer` - -TODO: Mixer. - -- Meters: propagate clipping: - - If one stage clips, all stages after it are marked red - - If one track clips, all tracks that feed from it are marked red? - -## `tek_track` - -TODO: Channel strip. - -## `tek_plugin` - -TODO: Plugin host. - -## 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. +* human-readable project format +* command architecture allows for scripting and remapping ---