orca-rs/README.md

orca-rs

A Rust port of Orca-c, the livecoding environment for procedural sequencing.

Install

On Arch Linux:

yay -S orca-rs

Build

cargo build --release

Requires ALSA headers on Linux (alsa-lib) for MIDI support.

Run

orca-rs [options] [file.orca]

With no file, edits save to untitled.orca. A named file that doesn't exist yet is created on first save.

Option	Effect
--bpm <n>	Tempo (default 120; one tick = one 16th note)
--seed <n>	Random seed for the R operator
--udp-port <n> / --udp-host <h>	Send ; strings over UDP (host defaults to 127.0.0.1)
--osc-port <n> / --osc-host <h>	Send = messages over OSC
--no-midi	Disable MIDI output (on by default)
--midi-name <s>	Connect to an existing MIDI port whose name contains <s>
--list-midi	List MIDI output ports and exit

MIDI is on by default: orca-rs creates a virtual ALSA sequencer port named orca-rs, which PipeWire exposes through its Midi-Bridge — connect it to a synth with qpwgraph/Helvum, or find it under wpctl status.

There is also a headless runner, equivalent to orca-c's cli:

orca-cli -t 60 file.orca   # simulate 60 ticks, print the grid

Keys

Key	Action
Arrow keys	Move cursor (Alt+arrows: leap by 8)
Shift+arrows	Grow/shrink selection
Ctrl+arrows	Resize grid
0-9 a-z A-Z ! : ; = # * . ?	Place glyph (fills selection)
Backspace / Delete	Erase selection
Space	Play / pause
Ctrl+F	Step one frame (while paused)
Ctrl+R	Reset frame counter
< / >	BPM −1 / +1
( / )	BPM −10 / +10
Ctrl+Z or Ctrl+U	Undo
Ctrl+X / Ctrl+C / Ctrl+V	Cut / copy / paste selection
Ctrl+S	Save
Esc	Collapse selection
Ctrl+Q	Quit

Layout

• src/sim/ — the VM: all operators, ported from orca-c's sim.c
• src/tui.rs — terminal UI (crossterm), counterpart of tui_main.c
• src/io.rs — UDP / OSC / MIDI event output
• src/bin/orca-cli.rs — headless runner, counterpart of cli_main.c

Releasing

Releases are cut with cargo-release (cargo release patch|minor), which bumps Cargo.toml and aur/PKGBUILD and pushes a v* tag. The Gitea Actions workflow then builds x86_64 and aarch64 tarballs, attaches them to the Gitea release, and pushes the updated PKGBUILD to the AUR. Required repo secrets: GITEA_TOKEN, AUR_SSH_KEY.