mirror of https://gitea.heck.live/heck/Orca-Workshop.git synced 2024-11-21 15:29:14 +01:00

Course material for Heck's Orca-Workshop [mirror - weil hat spaß gemacht]

Find a file

heck 384b74c661 README - inline ALL tutorial sources		2023-04-08 19:59:52 +02:00
demos	Add demos	2023-04-08 02:01:04 +02:00
tutorials	Add: "Tutorial 2a: CakeTracker"	2023-04-08 18:44:39 +02:00
LICENSE	Initial commit	2023-04-05 17:21:57 +00:00
README.md	README - inline ALL tutorial sources	2023-04-08 19:59:52 +02:00

README.md

Orca-Workshop

Orca is an esoteric programming language and live editor designed to quickly create procedural sequencers.
Orca is one of the inventions of Devine Lu Linvega of the small artist collective 'Hundred Rabbits'.

In this workshop we will:

Look at a few orca demos to get an impression
Get an orca setup running on your machine
Get a very quick language overview
Play through some tutorials together
Get hooked and get lost in the rabbithole of orca

Please find a collection of orca resources at the end of this document.

Installation

Orca

There are many implementations of Orca.
The ones that work well for this workshop are:

Easy setup: electron/js
Advanced setup: ANSI-C implementation

Easy setup

The quickest way to get started on any platform is to just use the 'fancy' electron framework version. I recommend doing that for the workshop, to avoid the "install-party" effect. Download and run the binary release. The source link is just for your reference.

Binary release: https://hundredrabbits.itch.io/orca
Source/Docs: https://github.com/hundredrabbits/Orca

Advanced Setup

My favourite setup though, is running the ANSI-C version in Cool-Retro-Term.
Orca AND Cool-Retro-Term are available in many package managers, have a look in yours. Maybe you are lucky...
Of course you can run this version of orca in any terminal.

Source/Docs: https://github.com/hundredrabbits/Orca-c

Pilot

Orca cant make any sounds on its own, it can only generate MIDI, OSC or UDP output.
Pilot is a 'companion' program (from hundredrabbits as well) that is a fun little synthesizer and is very easy to use with orca over UDP.
Download and run the binary release. The source link is just for your reference.

Binary release: https://hundredrabbits.itch.io/pilot
Source/Docs: https://github.com/hundredrabbits/Pilot

Language Quick Overview

Esoteric Programming Language
'Frame-Oriented' (execution model)
26 operators A-Z
1 datatype - Base36
Uppercase operators execute on every frame
Lowercase operators execute on a 'Bang'
Data is just Base36 numbers '0-9' and 'a-z'
I/O: no I just O. MIDI/OSC/UDP

Tutorial Main Function

This is the Tutorial main function. Return here after every tutorial to decide what you wanna do next.
Definitely, do the Tutorial 1: First Bleeps, first.

If you are reading this you must be have completed Tutorial 1: First Bleeps. Congratulations! You did so, right?

Your next options are:
1.) You feel like the lazy beaver and just want to improve your bleepyness the easy way, and quickly sound like you know what your doing?
Tutorial 2a: CakeTracker is for you

2.) You feel more like the clever rabbit, you need the deep dive, and in the end you want to know more about orca than your fellow workshop-mates that just bleep-away with their 2 operators?
Tutorial 2b: ScopeHero is for you.

Tutorial 1: First Bleeps

In this tutorial we will only learn 2 of the 26 operators, and we will already be making polymetric noise.
Isn't that great?

Have a look into the directory tutorials/1_first_bleeps/.
There is an orca program for each chapter.

1. Bangs

The 'bang' is the trigger that activates lower-case operators.
There is technically only one operator that directly generates a bang. Its the operator D.

D - Delay, bang periodically (count / frame-modulo)

.................................................................
..######.....#....#.....#..#####...####..........................
..#.....#...#.#...##....#.##....#.#.....#........................
..#.....#..#...#..#.#...#.#.......##.............................
..######..##....#.#..#..#.#..####..#####.........................
..#.....#.#######.#...#.#.#.....#.......##.......................
..#.....#.#.....#.#....##.#.....#.#.....##.......................
..######..#.....#.#.....#..#####...#####.........................
.................................................................
.................................................................
...#.uppercase...#...#.lowercase......#..........................
...#.executes....#...#.needs.a.bang...#..........................
...#.evey.frame..#...#.to.execute.....#..........................
.................................................................
.............................D....#.D.bangs.periodically.#.......
..................................#.*.is.a.bang.#................
.........I.........i.........i...................................
.........i...................0...................................
.................................................................

2. First Bleeps

Operators you learn in this chapter:

; - Send UDP packet (- / data)

for synthesizing the actual waves we are using 'Pilot', a soft-synth which we control with UDP packets. So, the commands we send using the UDP output operator are actually Pilot commands, not orca.

Pilot commands are 3-5 'bytes' long, where the first 3 are required.
The format is: CH OCT NOTE [VOL] [DECAY]

Where:

CH - Channels 1-f exist, they all sound different (and they are monophonic)
OCT - Around 8 octaves should definitely exist
NOTE - Note names where Upper-case are white keys and Lower-case are Black-keys
VOL - The Volume 0-z (even though the doc says 0-f, but hey we love clipping dont we?)
DECAY - The 'length' of the note, 0-f (?)

Example:
;13C - Pilot plays note 'C' of octave 3 (default volume and length)

.................................................................................................
.................................................................................................
..#######.###.######...#####..#######.......######..#.......#######.#######.######...#####.......
..#........#..#.....#.#.....#....#..........#.....#.#.......#.......#.......#.....#.#.....#......
..#........#..#.....#.#..........#..........#.....#.#.......#.......#.......#.....#.#............
..#####....#..######...#####.....#..........######..#.......#####...#####...######...#####.......
..#........#..#...#.........#....#..........#.....#.#.......#.......#.......#.............##.....
..#........#..#....#..#.....#....#..........#.....#.#.......#.......#.......#.......#.....##.....
..#.......###.#.....#..#####.....#..........######..#######.#######.#######.#........######......
.................................................................................................
.................................................................................................
............................................D2...................................................
......#.;.operator.send.UDP.#..........#....*;15C................................................
......#.to.pilot............#....................................................................
.................................................................................................
.................................................................................................
............................................D3...................................................
.......................................#.....;24E................................................
.................................................................................................
.................................................................................................
.................................................................................................
............................................D5...................................................
.......................................#.....;54G................................................
.................................................................................................
.................................................................................................
.................................................................................................
............................................D7...................................................
.......................................#.....;33G................................................
.................................................................................................
.................................................................................................

Congrats

Congratulations you have witnessed the easiest programming language to make a sound. 2 operators are all you need. Now return to the Tutorial main function to plan your next adventure.

Tutorial 2a: CakeTracker

In this tutorial we will learn how, using only 4 more operators, we can melodize beethoven out of the water like a piece of cake.

Have a look into the directory tutorials/2a_caketracker/.
There is an orca program for each chapter.

1. Counter

In this chapter you learn 1 of 2 operators that can count.

C - Count (rate / modulo)

.........................................................
.........................................................
....####...####..#....#.#....#.#####.######.#####........
...#....#.#....#.#....#..#...#...#...#......#....#.......
...#......#....#.#....#.#.#..#...#...#####..#....#.......
...#......#....#.#....#.#..#.#...#...##.....#####........
...#....#.#....#.#....#.#...##...#...#......#...##.......
....####...####...####..#....#...#...######.#....##......
.........................................................
.........................................................
...#.outputs.framenr.divided.by.rate.modulo.range.#......
.........................................................
.........................................................
...................#.rate.#.#.range.#....................
.........................................................
..........................1C8............................
...........................6.............................
.........................................................
.........................................................
...............#.These.are.the.default.#.................
.........................................................
.........................................................
...........................C.............................
...........................6.............................
.........................................................
.........................................................
.........................................................
...........#.increment.every.8.frame.up.to.3.#...........
.........................................................
..........................8C4............................
...........................2.............................
.........................................................
.........................................................

2. Track

The track lets us store a list and access its elements.

T - Track (index, length / list)

You guessed it, using a counter you can now iterate the elements of a list

.........................................................
.........................................................
.........................................................
.........#######..#####.....#.....#####..#....#..........
............#....##....#...#.#...#.....#.#...#...........
............#....#.....#..#...#..#.......#..#............
............#....######..#.....#.#.......####............
............#....#...#...#######.#.......#..##...........
............#....#....#..#.....#.#.....#.#...##..........
............#....#.....#.#.....#..#####..#....###........
.........................................................
..........#.Track.output.one.element.of.a.list.#.........
.........................................................
.............#.4.elements.#.#.the.list.is.abcd.#.........
.........................................................
........#.outputs.the.#..04Tabcd.........................
........#...element...#....a.............................
........#.....nr.0....#..................................
.........................................................
.........................................................
.........................................................
........#.attach.a.counter.to.the.index.operand.#........
.........................................................
........................4C4..............................
.........................24Tabcd.........................
...........................c.......#.YAY.#...............
.........................................................
.........................................................
.........................................................
.........................................................
.........................................................
.........#.use.the.track.output.as.the.notenr.#..........
.........................................................
........................4C8..............................
....................#..D168TceghcEgh.....................
........................;14g.............................
.........................................................

3. Variables

In this chapter you learn all the operators related to variables:

V - Variable, r/w single (Write: name / val | Read: - / name)
K - Kontakt, read multiple (Read: count / names)

.................................................................
..#....#...##...#####..#...##...#####..#......######..####.......
..#....#..#..#..#....#.#..#..#..#....#.#......#......#...........
..#....#.#....#.#....#.#.#....#.#####..#......#####...####.......
..#....#.######.#####..#.######.#....#.#......#...........##.....
...#..#..#....#.#...#..#.#....#.#....#.#......#......#....##.....
....##...#....#.#....#.#.#....#.#####..######.######..####.......
.................................................................
.................................................................
..................#.Write.a.variable.#...........................
.................................................................
............................2C.........R8........................
................aV2........bV1.......cV7.........................
.................................................................
.................................................................
.................................................................
..................#.Read.a.variable.#............................
.................................................................
.................Va.........Vb........Vc.........................
.................2..........1.........7..........................
.................................................................
.................................................................
.................................................................
..................#.Read.mutliple.vars.#.........................
.................................................................
.................................................................
..........................3Kabc......#.reads.a.b.and.c.#.........
............................217..................................
.................................................................
.................................................................

4. CakeTracker

Putting it all together Using the values of our list (in track) as note-numbers, we are now the new-age melody heroes.
Enjoy the eternal bleeps of the spotless beethoven.

.........................................................................................
.......#####.......................#######...............................................
......#.....#...##...#....#.######....#....#####....##....####..#....#.######..####......
......#........#..#..#...#..#.........#....#....#..#..#..#....#.#...#..#......#....#.....
......#.......#....#.####...#####.....#....#....#.#....#.#......####...####...#....#.....
......#.......######.#..#...#.........#....#####..######.#......#..#...##.....#####......
......#.....#.#....#.#...#..#.........#....#...#..#....#.#....#.#...#..##.....#...#......
.......#####..#....#.#....#.######....#....#....#.#....#..####..#....#.######.#....#.....
.........................................................................................
...........#.combining.the.result.of.first.bleeps.with.the.track.and.variable.#..........
.........................................................................................
.........................................................................................
.........................................................................................
..........................................C..............................................
..........................................18Tfheiokl.....................................
..........................................aVh............................................
.........................................................................................
.........................................................................................
.........................................................................................
..........................................D2..Va.........................................
...........................................;14h..........................................
.........................................................................................
.........................................................................................
.........................................................................................
..........................................D3..Va.........................................
..........................................*;23h..........................................
.........................................................................................
.........................................................................................
.........................................................................................
..........................................D1..Va.........................................
..........................................*;52hf2........................................
.........................................................................................
.........................................................................................
.........................................................................................
..........................................D7..Va.........................................
...........................................;33h3z........................................
.........................................................................................
.........................................................................................
..................#.results.in.eternal.bleeps.of.the.spotless.beethoven.#................
.........................................................................................
.........................................................................................

Congrats

Congratulations beethoven went home crying. Now return to the Tutorial main function to plan your next adventure.

Tutorial 2b: Scopehero

This is a very empowering tutorial with its 13 operators covered.

Have a look into the directory tutorials/2b_scopehero/.
There is an orca program for each chapter.

1. Arithmetic

In this chapter you learn (almost) all the operators to generate and manipulate numbers:

C - Count (rate / modulo)
I - Increment (increment / max)
R - Random (min / max)
A - Add (operand / operand)
B - Subtract (operand / operand)
M - Multiply (operand / operand)

.........................................................................................
.........................................................................................
.........................................................................................
............##...#####..#.#####.#....#.#....#.######.#....#.#####.#..#####...............
...........#..#..#....#.#...#...#....#.##..##.#......##...#...#...#.#....#...............
..........##...#.#....#.#...#...######.#.##.#.#####..#.#..#...#...#.#....................
..........######.#####..#...#...#....#.#....#.#......#..#.#...#...#.#....................
..........#....#.#...#..#...#...#....#.#....#.#......#...##...#...#.#....#...............
..........#....#.#....#.#...#...#....#.#....#.######.#....#...#...#..####................
.........................................................................................
.........................................................................................
....#.increment.#....#.count.#..#.random.#...#.add.#...#.subtract.#..#.multiply.#........
.........................................................................................
.........................................................................................
..........I..............C...........R.........2A3.........2B3...........2M3.............
..........g..............1...........s..........5...........1.............6..............
.........................................................................................
.........................................................................................

2. Variables

In this chapter you learn all the operators related to variables:

V - Variable, r/w single (Write: name / val | Read: - / name)
K - Kontakt, read multiple (Read: count / names)

.................................................................
..#....#...##...#####..#...##...#####..#......######..####.......
..#....#..#..#..#....#.#..#..#..#....#.#......#......#...........
..#....#.#....#.#....#.#.#....#.#####..#......#####...####.......
..#....#.######.#####..#.######.#....#.#......#...........##.....
...#..#..#....#.#...#..#.#....#.#....#.#......#......#....##.....
....##...#....#.#....#.#.#....#.#####..######.######..####.......
.................................................................
.................................................................
..................#.Write.a.variable.#...........................
.................................................................
............................2C.........R8........................
................aV2........bV1.......cV7.........................
.................................................................
.................................................................
.................................................................
..................#.Read.a.variable.#............................
.................................................................
.................Va.........Vb........Vc.........................
.................2..........1.........7..........................
.................................................................
.................................................................
.................................................................
..................#.Read.mutliple.vars.#.........................
.................................................................
.................................................................
..........................3Kabc......#.reads.a.b.and.c.#.........
............................217..................................
.................................................................
.................................................................

3. Writer

There are a number of operators to write data into the grid. In this chapter we only look at one:

X - Write (x, y / data )

.................................................
.................................................
...#.....#.######..###.#######.#######.#######...
...#..#..#.#.....#..#.....#....#.......#.....#...
...#..#..#.#.....#..#.....#....#.......#.....#...
...#..#..#.######...#.....#....#####...######....
...#..#..#.#...#....#.....#....#.......#...#.....
...#..#..#.#....#...#.....#....#.......#....#....
....##.##..#.....#.###....#....######..#.....#...
.................................................
.................................................
.................................................
.................................................
....#.X.writes.the.right.operand.to.x.and.y.#....
.................................................
....#.xy.................#.......................
....#....data.but.only.1.#.......................
.................................................
.................................................
.................................................
......11X0.......................................
.................................................
.........0.......................................
.................................................
.................................................
.################################################
.................................................
..........................D1.....................
..........................*......................
..........................iz..#.just.increment.#.
..........#.var.a.#.....aVs...#.to.z.#...........
.................................................
.................................................
.......Cz.Va.....................................
.......n.Xs......................................
.........56789abcdefghijklmnopqrstuvwxy01234.....
.................................................

4. Flying Operators

In this chapter you learn about all the flying operators \o/ \o/ \o/:

E - East
W - West
N - North
S - South

.........................................................................................................................
.........................................................................................................................
...######.#......#...#.#.#....#..####....#######.######..#######.######.....#....#######.#######.######...#####..........
...#......#.......#.#..#.##...#.#....#...#.....#.#.....#.#.......#.....#...#.#......#....#.....#.#.....#.#.....#.........
...#####..#........#...#.#.#..#.#........#.....#.#.....#.#.......#.....#..#...#.....#....#.....#.#.....#.#...............
...#......#........#...#.#..#.#.#..###...#.....#.######..#####...######..#.....#....#....#.....#.######...#####..........
...#......#........#...#.#...##.#....#...#.....#.#.......#.......#...#...#######....#....#.....#.#...#.........#.........
...#......#####....#...#.#....#..####....#.....#.#.......#.......#....#..#.....#....#....#.....#.#....#..#.....#.........
.........................................#######.#.......#######.#.....#.#.....#....#....#######.#.....#..#####..........
.........................................................................................................................
.....................................#.There.are.4.flying.operators.#....................................................
.........................................................................................................................
.........................................................................................................................
..............................................#.type.them.in.the.box.#...................................................
..............................................000000000000000000000000...................................................
..............................................0......................0...................................................
..............................................0......................0...................................................
.................................#.E.east..#..0......................0...................................................
.................................#.W.west..#..0......................0...................................................
.................................#.N.nord..#..0......................0...................................................
.................................#.S.south.#..0......................0...................................................
..............................................0......................0...................................................
..............................................0......................0...................................................
..............................................0......................0...................................................
..............................................000000000000000000000000...................................................
.........................................................................................................................
.........................................................................................................................
..###############################################################################################################........
.........................................................................................................................
..#.now.try.the.writer.with.the.E.operator.#.............................................................................
.........................................................................................................................
.........................................................................................................................
.........................................................................................................................
...11XE..................................................................................................................
.........................................................................................................................
......E..................................................................................................................
.........................................................................................................................
.........................................................................................................................
.........................................................................................................................
.........................................................................................................................
.........................................................................................................................
.........................................................................................................................
.........................................................................................................................
.........................................................................................................................
..###############################################################################################################........
.........................................................................................................................
..#.visualize.a.counter.by.using.it.on.the.y.param.of.the.writer.#.......................................................
.........................................................................................................................
.........................................................................................................................
#.C8.....................................................................................................................
..4XE....................................................................................................................
.........................................................................................................................
.........................................................................................................................
.........................................................................................................................
.........................................................................................................................
...E.....................................................................................................................
.........................................................................................................................
.........................................................................................................................
.........................................................................................................................
.........................................................................................................................
.........................................................................................................................
.........................................................................................................................
.........................................................................................................................
.........................................................................................................................
.........................................................................................................................

5. Scope

Putting it all together

Yay, by now we have already learned 15 operators, more than half of them all.
Now we can combine them to create a 'scope' to visualize and debug any variable values.

.................................................
.................................................
.....#####...#####..#######.######..#######......
....#.....#.#.....#.#.....#.#.....#.##...........
....#.......#.......#.....#.#.....#.##...........
.....#####..#.......#.....#.######..####.........
.........##.#.......#.....#.#.......##...........
....#....##.#.....#.#.....#.#.......##...........
.....#####...#####..#######.#.......########.....
.................................................
....#.use.the.writer.to.visualize.and.debug.#....
.................................................
.................................................
.................................................
..........................D1.....................
..........................*......................
.........................1iz.....................
..........#.var.a.#.....aVf......................
.................................................
.................................................
.................................................
.......Cz.Va.....................................
.......w.Xf......................................
..Va.....ijklmnopqrstuvwxy0123456789abcdefgh.....
..fXE............................................
.##.........................................##...
.##.........................................##...
.##.........................................##...
.##.........................................##...
.##.........................................##...
.##.........................................##...
.##.........................................##...
.##.........................................##...
.##.........................................##...
.##.........................................##...
.##.........................................##...
.##.........................................##...
.##.........................................##...
.##.........................................##...
.##.........................................##...
.##.........................................##...
.##.........................................##...
.##.........................................##...
.##.........................................##...
.##.........................................##...
.##.........................................##...
.##.........................................##...
.##.........................................##...
.##.........................................##...
.##.........................................##...
.##.........................................##...
.##.........................................##...
.##.........................................##...
.##.........................................##...
.##.........................................##...
.##.........................................##...
.##.........................................##...
.##.........................................##...
.##.........................................##...
.##.........................................##...
.................................................

6. ScopeHero

Putting it even togetherererer

What is even more fun than 1 scope, is 3 scopes.
Let generate 2 'signals', add them together to create a third signal, and use our scope technique to visualize whats going on.

................................#####...#####..#######.######..#######.#.....#.#######.######..#######...................................
...............................#.....#.#.....#.#.....#.#.....#.#.......#.....#.#.......#.....#.#.....#...................................
...............................#.......#.......#.....#.#.....#.#.......#.....#.#.......#.....#.#.....#...................................
................................#####..#.......#.....#.######..#####...#######.####....######..#.....#...................................
....................................##.#.......#.....#.#.......#.......#.....#.#.......#...#...#.....#...................................
...............................#....##.#.....#.#.....#.#.......#.......#.....#.#.......#....#..#.....#...................................
................................#####...#####..#######.#.......#######.#.....#.######..#.....#.#######...................................
.........................................................................................................................................
...................................................D1...........................D1.......................................................
...................................................*............................*........................................................
..................................................1iz.......#.increment.#.......i8.......................................................
.................................................hB4.........#.bounce.#.........4B4......................................................
...................................#.var.a.#....aVd............................bV0....#.var.b.#..........................................
.........................................................................................................................................
.........................................................................................................................................
...........................................................#.add.a.and.b.#...............................................................
.........................................................................................................................................
................................................................Va..Vb...................................................................
................................................................dYdA0....................................................................
.................................................................cVd.....................................................................
...............................................................#.var.c#..................................................................
.......Cz.Va.........................................Cz.Vb.........................................Cz.Vc.................................
.......m.Xd..........................................m.X0..........................................m.Xd..................................
..Va.....0123456789abcdefghhgfedcba987654321....Vb.....23432101234321012343210210123432101....Vc.....24666668aceeeeegikljhfdecaaaaa86422.
..dXE...........................................0XE...........................................dXE........................................
.##.........................................##.##.........................................##.##.........................................#
.##.........................................##.##.........................................##.##.........................................#
.##.........................................##.##.........................................##.##.........................................#
.##.........................................##.##.........................................##.##.........................................#
.##.........................................##.##.........................................##.##.........................................#
.##.........................................##.##.........................................##.##.........................................#
.##.........................................##.##.........................................##.##.........................................#
.##.........................................##.##.........................................##.##.........................................#
.##.........................................##.##.........................................##.##.........................................#
.##.........................................##.##.........................................##.##.........................................#
.##.........................................##.##.........................................##.##.........................................#
.##.........................................##.##.........................................##.##.........................................#
.##.........................................##.##.........................................##.##.........................................#
.##.........................................##.##.........................................##.##.........................................#
.##.........................................##.##.........................................##.##.........................................#
.##.........................................##.##.........................................##.##.........................................#
.##.........................................##.##.........................................##.##.........................................#
.##.........................................##.##.........................................##.##.........................................#
.##.........................................##.##.........................................##.##.........................................#
.##.........................................##.##.........................................##.##.........................................#
.##.........................................##.##.........................................##.##.........................................#
.##.........................................##.##.........................................##.##.........................................#
.##.........................................##.##.........................................##.##.........................................#
.##.........................................##.##.........................................##.##.........................................#
.##.........................................##.##.........................................##.##.........................................#
.##.........................................##.##.........................................##.##.........................................#
.##.........................................##.##.........................................##.##.........................................#
.##.........................................##.##.........................................##.##.........................................#
.##.........................................##.##.........................................##.##.........................................#
.##.........................................##.##.........................................##.##.........................................#
.##.........................................##.##.........................................##.##.........................................#
.##.........................................##.##.........................................##.##.........................................#
.##.........................................##.##.........................................##.##.........................................#
.##.........................................##.##.........................................##.##.........................................#
.##.........................................##.##.........................................##.##.........................................#
.........................................................................................................................................
.........................................................................................................................................

Congrats

Congratulations!!! You are hardcore! your mum must be so proud of you! All that bloody brain acrobatics without even one bleep, a real martyr. Now return to the Tutorial main function to plan your next adventure.

README.md

Orca-Workshop

Installation

Orca

Easy setup

Advanced Setup

Pilot

Language Quick Overview

Tutorial Main Function

Tutorial 1: First Bleeps

1. Bangs

2. First Bleeps

Congrats

Tutorial 2a: CakeTracker

1. Counter

2. Track

3. Variables

4. CakeTracker

Congrats

Tutorial 2b: Scopehero

1. Arithmetic

2. Variables

3. Writer

4. Flying Operators

5. Scope

6. ScopeHero

Congrats

Resources

Orca

General

ANSI-C version

JS/Electron version

Pilot