ref: 2ac242ffa1cbe474e7f4d020b4f3a49166ddfe46
dir: /README.md/
# ORCΛ
<img src='https://raw.githubusercontent.com/hundredrabbits/Orca/master/resources/logo.png' width="600"/>
**Each letter of the alphabet is an operation**, lowercase letters typically operate on bang(`*`), uppercase letters operate on each frame. Bangs can be generated by various operations, such as `E` colliding with a `0`, see the [bang.orca](https://github.com/hundredrabbits/Orca/blob/master/examples/bang.orca) example. Watch a music video of [ORCΛ in action](https://twitter.com/neauoire/status/1069129232708657152).
**C Port** for the [ORCΛ](https://github.com/hundredrabbits/Orca) programming environment, with a commandline interpreter.
## Prerequisites
Core library: A C99 compiler (no VLAs required), plus enough libc for `malloc`, `realloc`, `free`, `memcpy`, `memset`, and `memmove`. (Also, `#pragma once` must be supported.)
Command-line interpreter: The above, plus POSIX, and enough libc for the common string operations (`strlen`, `strcmp`, etc.)
Interactive terminal UI: The above, plus ncurses (or compatible curses library), and floating point support (for timing.) Optionally, PortMIDI can be used to enable direct MIDI output.
### Quick Start for Debian/Raspbian (Raspberry Pi)
```sh
sudo apt-get install git libncurses5-dev libncursesw5-dev libportmidi-dev
git clone https://github.com/hundredrabbits/Orca-c.git
cd Orca-c
make # Compile orca
build/orca --portmidi-list-devices # Select MIDI device
build/orca --portmidi-output-device 2 # Start livecoding
```
## Build
The build script is in `bash`. It should work with `gcc` (including the `musl-gcc` wrapper) and `clang`, and will automatically detect your compiler.
Currently known to build on macOS (`gcc`, `clang`) and Linux (`gcc`, `musl-gcc`, and `clang`, optionally with `LLD`), and Windows via cygwin or WSL (`gcc` or `clang`).
There is a fire-and-forget `make` wrapper around the build script.
PortMIDI is an optional dependency. It can be enabled by adding the option `--portmidi` when running the `tool` build script.
Mouse awareness can be disabled by adding the `--no-mouse` option.
### Make
```sh
make release # optimized build, binary placed at build/orca
make debug # debugging build, binary placed at build/debug/orca
make clean # removes build/
```
The `make` wrapper will enable `--portmidi` by default. If you run the `tool` script on its own, `--portmidi` is not enabled by default.
### Build Script
Run `./tool help` to see usage info. Examples:
```sh
./tool build -c clang-7 --portmidi orca
# Build the livecoding environment with a compiler
# named clang-7, with optimizations enabled, and
# with PortMIDI enabled for MIDI output.
# Binary placed at build/orca
./tool build -d orca
# Debug build of the livecoding environment.
# Binary placed at build/debug/orca
./tool build -d cli
# Debug build of the headless CLI interpreter.
# Binary placed at build/debug/cli
./tool clean
# Same as make clean. Removes build/
```
## Run
### Interactive terminal UI
```
Usage: orca [options] [file]
General options:
--margins <nxn> Set cosmetic margins.
Default: 2x1
--undo-limit <number> Set the maximum number of undo steps.
If you plan to work with large files,
set this to a low number.
Default: 100
--initial-size <nxn> When creating a new grid file, use these
starting dimensions.
--bpm <number> Set the tempo (beats per minute).
Default: 120
--seed <number> Set the seed for the random function.
Default: 1
-h or --help Print this message and exit.
OSC/MIDI options:
--strict-timing
Reduce the timing jitter of outgoing MIDI and OSC messages.
Uses more CPU time.
--osc-server <address>
Hostname or IP address to send OSC messages to.
Default: loopback (this machine)
--osc-port <number or service name>
UDP port (or service name) to send OSC messages to.
This option must be set for OSC output to be enabled.
Default: none
--osc-midi-bidule <path>
Set MIDI to be sent via OSC formatted for Plogue Bidule.
The path argument is the path of the Plogue OSC MIDI device.
Example: /OSC_MIDI_0/MIDI
```
Additional options are available if `orca` is built with `--portmidi`:
```
--portmidi-list-devices
List the MIDI output devices available through PortMIDI,
along with each associated device ID number, and then exit.
Do this to figure out which ID to use with
--portmidi-output-device
--portmidi-output-device <number>
Set MIDI to be sent via PortMIDI on a specified device ID.
Example: 1
```
#### Example: build and run `orca` with MIDI output
```sh
$ ./tool build --portmidi orca # compile orca using build script
$ build/orca --portmidi-list-devices # query for midi devices
ID: 3 Name: IAC Driver Bus
ID: 4 Name: USB MIDI Device
$ build/orca --portmidi-output-device 3 # run orca with midi device 3
```
#### Controls
```
┌ Controls ───────────────────────────────────────────┐
│ Ctrl+Q Quit │
│ Arrow Keys Move Cursor │
│ Ctrl+D or F1 Open Main Menu │
│ 0-9, A-Z, a-z, Insert Character │
│ !, :, =, #, * │
│ Spacebar Play/Pause │
│ Ctrl+Z or Ctrl+U Undo │
│ Ctrl+X Cut │
│ Ctrl+C Copy │
│ Ctrl+V Paste │
│ Ctrl+S Save │
│ Ctrl+F Frame Step Forward │
│ Return Append/Overwrite Mode │
│ / Key Trigger Mode │
│ ' (quote) Rectangle Selection Mode │
│ Shift+Arrow Keys Adjust Rectangle Selection │
│ Escape Return to Normal Mode or Deselect │
│ ( and ) Resize Grid (Horizontal) │
│ _ and + Resize Grid (Vertical) │
│ [ and ] Adjust Grid Rulers (Horizontal) │
│ { and } Adjust Grid Rulers (Vertical) │
│ < and > Adjust BPM │
│ ? Controls (this message) │
└─────────────────────────────────────────────────────┘
```
### CLI interpreter
The CLI (`cli` binary) reads from a file and runs the orca simulation for 1 timestep (default) or a specified number (`-t` option) and writes the resulting state of the grid to stdout.
```sh
cli [-t timesteps] infile
```
You can also make `cli` read from stdin:
```sh
echo -e "...\na34\n..." | cli /dev/stdin
```
## Extras
- Support this project through [Patreon](https://patreon.com/100).
- See the [License](LICENSE.md) file for license rights and limitations (MIT).
- Pull Requests are welcome!