Skip to content

Update getting-started.md #10

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Update getting-started.md #10

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
93 changes: 49 additions & 44 deletions content/docs/learning/getting-started.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,28 +7,28 @@ weight: 2
---
# Getting started with hydra

This document is an introduction to making live visuals using Hydra. It covers the basics of writing code in the browser to generate and mix live video sources. No coding or video experience is necessary!
This document is an introduction to making live visuals using hydra. It covers the basics of writing code in the browser to generate and mix live video sources. No coding or video experience is necessary!

If you just want to start in 60 seconds you can also check:
If you just want to start in 60 seconds, you can also check:
* [Getting started short version](https://hackmd.io/@r08UjGF3QMCfvNmdjuY7iQ/rJCpsbNNc)

This tutorial is meant to be used from within the [hydra web editor](https://hydra.ojack.xyz/). It is also interactive -- you can directly modify the code in each code block to see how it affects the visuals.

## Get to know the browser editor
To get started, open the the [hydra web editor](https://hydra.ojack.xyz/) in a separate window. Close the top window by clicking the [x] in the top right.
To get started, open the [hydra web editor](https://hydra.ojack.xyz/) in a separate window. Close the top window by clicking the [x] on the top right corner of the page.

![](https://i.imgur.com/ZfgVjJZ.gif)

You will see some colorful visuals in the background with text on top in the top left of the screen. The text is code that generates the visuals behind it.
You will see some colorful visuals in the background with text on the top left corner of the screen. The text is code that generates the visuals behind it.

At the right up corner you will find a toolbar with these buttons:
On the top right corner, you will find a toolbar with these buttons:
![](https://i.imgur.com/iCG8Lrq.png)
1. **run all code** Runs all code on the page (same as typing *ctrl+shift+enter)
2. **upload to gallery** upload a sketch to Hydra's gallery and create a shorter URL
3. **clear all** resets the environment and clears text from the editor
4. **show random sketch**. Loads random sketch examples. Always it is a good way to learn Hydra by studying someone elses code.
5. **make random change** **dices** modify values automatically. Try it with some of the sketch examples.
6. **show info window** show overlay window with help text and links
1. **run all code**: It runs all code on the page (same as typing `ctrl+shift+enter`).
2. **upload to gallery**: It uploads a sketch to Hydra's gallery and creates a shorter URL.
3. **clear all**: It resets the environment and clears text from the editor.
4. **show random sketch**: It loads random sketch examples. It is always a good way to learn hydra by studying someone else's code.
5. **make random change**: It modifies values automatically. Try it with some of the sketch examples.
6. **show info window**: It shows an overlaid window with help text and links.


## First line of code
Expand All @@ -48,42 +48,43 @@ osc().out()

This creates a visual oscillator. Try modifying the parameters of the oscillator by putting a number inside the parentheses of `osc()`, for example ```osc(10).out()```.

Re-run the code by pressing the ***run button*** again, and seeing the visuals update. Try adding other values to control the oscillator's `frequency`, `sync`, and `color offset`.
Re-run the code by pressing the ***run button*** again, you will see the visuals updating. Try adding other values to control the oscillator's `frequency`, `sync`, and `color offset`.

```hydra
osc(5, -0.126, 0.514).out()
```


*Trick: you can also use the keyboard shortcut **‘ctrl + shift + enter’** to have the same effect as the run button.*
*Trick: you can also use the keyboard shortcut `ctrl + shift + enter` to have the same effect as the run button.*


## Adding transformations
We can add another transformation to the oscillator from above, by adding the function `rotate()` after the oscillator:

```hydra
osc(5,-0.126,0.514).rotate().out()
```

As you can see, you have first an input source `osc()` and things that come after (`rotate()` and `out()`) are connected with a dot ‘.’
In this sense, Hydra is inspired by [modular synthesis](https://en.wikipedia.org/wiki/Modular_synthesizer).
Instead of connecting cables you connect different kinds of javascript functions.
As you can see, you have first an input source `osc()`, and things that come after (`rotate()` and `out()`) are connected with a dot `.`.
In this sense, hydra is inspired by [modular synthesis](https://en.wikipedia.org/wiki/Modular_synthesizer).
Instead of connecting cables, you connect different kinds of JavaScript functions.

![](https://i.imgur.com/RBRxeiL.jpg)
###### source [Sandin Image Processor](https://en.wikipedia.org/wiki/Sandin_Image_Processor)

You can continue adding transformations to this chain of functions. For example:

```hydra
osc(5,-0.126,0.514).rotate(0, 0.2).kaleid().out()
```

Repeat:

```hydra
osc(5,-0.126,0.514).rotate(0, 0.2).kaleid().repeat().out()
```


For more available sources and transformations, see the [interactive function reference](https://hydra.ojack.xyz/api).
The logic is to start with a ***source*** (such as `osc()`, `shape()`, or `noise()`), and then add transformations to ***geometry*** and ***color*** (such as `.rotate()`, `.kaleid()`, `.pixelate()` ), and in the end always connect the chain of transformations to the output screen `.out()` .

The logic is to start with a ***source*** (such as `osc()`, `shape()`, or `noise()`), and then add transformations to ***geometry*** and ***color*** (such as `.rotate()`, `.kaleid()`, `.pixelate()` ), and always connect the chain of transformations to the output screen `.out()`.

```hydra
noise(4).color(-2, 1).colorama().out()
Expand All @@ -93,25 +94,25 @@ noise(4).color(-2, 1).colorama().out()
shape(3).repeat(3, 2).scrollX(0, 0.1).out()
```


## What is an error?
Sometimes, you will try to run a line of code, and nothing will happen. If you have an error you’ll notice text in red at the left-bottom on your screen. Something like ‘Unexpected token ‘.’ (in red) will appear. This doesn’t affect your code, but you won’t be able to continue coding until you fix the error. Usually it is a typing error or something related to the syntax.
Sometimes, you will try to run a line of code, and nothing will happen. If you have an error, you’ll notice text in red on the bottom left corner of your screen. Something like `Unexpected token` (in red) will appear. This doesn’t affect your code, but you won’t be able to continue coding until you fix the error. Usually, it is a typing error or something related to the syntax.

## What is a comment?
To create a comment in your code, i.e. a section of code that will not be executed, you can use `//` in front of that text.

```javascript
// Hello I’m a comment line. I’m a text that won’t change your code. You can write notations, your name or even a poem here.
// Hello, I’m a comment line. I’m a text that won’t change your code. You can write notations, your name, or even a poem here.
```

## Save your sketch on the internet
When you evaluate the entire code with the ***run button*** or with `shift + ctrl + enter`, hydra automatically generates a URL that contains the last changes of your sketch. You can copy and paste the URL from the URL bar to save it or share it with other people. You can also use the browser `back` and `forward` arrows to navigate to earlier versions of your sketch.


When you evaluate the entire code with the ***run button*** or with `shift + ctrl + enter`, Hydra automatically generates a URL that contains the last changes of your sketch. You can copy and paste the url from the URL bar to save it or share it with other people. You can also use the browser `back` and `forward` arrows to navigate to earlier versions of your sketch.
![](https://i.imgur.com/lV0rmoh.png)


## Using the webcam
In addition to using sources from within hydra (such as `osc()` and `shape()`), you can use hydra to process external video sources such as a webcam. To initialize the webcam, run the following code:

```javascript
s0.initCam()
```
Expand All @@ -120,7 +121,7 @@ This activates the webcam source inside a variable called `s0`, and you should s

```hydra
s0.initCam() //initialize webcam as external source 's0'
src(s0).out() // use external source 's0' inside Hydra
src(s0).out() // use external source 's0' inside hydra
```

Similar to adding transformations above, you can add transformations of color and geometry to the camera output, by adding functions to the chain:
Expand All @@ -138,19 +139,15 @@ src(s0).color(-1, 1).kaleid().out()
If you have multiple webcams, you can access separate cameras by adding a number inside `initCam`, for example `s0.initCam(1)` or `s0.initCam(2)`.




## Multiple outputs

By default, hydra contains four separate virtual outputs that can each render different visuals, and can be mixed with each other to create more complex visuals. The variables `o0`, `o1`, `o2`, and `o3` correspond to the different outputs.
By default, hydra contains four separate virtual outputs that can each render different visuals and can be mixed with each other to create more complex visuals. The variables `o0`, `o1`, `o2`, and `o3` correspond to the different outputs.

To see all four of the outputs at once, use the `render()` function. This will divide the screen into four, showing each output in a different section of the screen.

![](https://i.imgur.com/m5Q0Na6.jpg)

Using a different variable inside the `.out()` function renders the chain to a different output. For example, `.out(o1)` will render a function chain to graphics buffer `o1`.


```hydra
gradient(1).out(o0) // render a gradient to output o0
osc().out(o1) // render voronoi to output o1
Expand All @@ -160,8 +157,7 @@ noise().out(o3) // render noise to output o3
render() // show all outputs
```

By default, only output `o0` is rendered to the screen, while the `render()` command divides the screen in four. Show a specific output on the screen by adding it inside of `render()`, for example `render(o2)` to show buffer `o2`.

By default, only output `o0` is rendered to the screen, while the `render()` command divides the screen into four. Show a specific output on the screen by adding it inside of `render()`, for example `render(o2)` to show buffer `o2`.

```hydra
gradient(1).out(o0) // render a gradient to output o0
Expand All @@ -172,7 +168,6 @@ noise().out(o3) // render noise to output o3
render(o2) // show only output o2
```


*Trick: try to create different sketches and switch them in your live performance or even combine them.*


Expand Down Expand Up @@ -200,7 +195,7 @@ render() // render all four outputs at once

Try adding transformations to the above sources (such as `osc(10).rotate(0, 0.1).out(o1)`) to see how it affects the combined image. You can also specify the amount of blending by adding a separate parameter to `.blend()`, for example `.blend(o1, 0.9)`.

There are multiple [blend modes](https://en.wikipedia.org/wiki/Blend_modes) in hydra, similar to blend modes you might find in a graphics program such as photoshop or gimp. See [the function reference](https://hydra.ojack.xyz/api/) for more possibilities.
There are multiple [blend modes](https://en.wikipedia.org/wiki/Blend_modes) in hydra, similar to blend modes you might find in a graphics program such as Photoshop or gimp. See [the function reference](https://hydra.ojack.xyz/api/) for more possibilities.

```hydra
s0.initCam()
Expand All @@ -216,7 +211,7 @@ render() // render all four outputs at once


## Modulation
While ***blend*** functions combine the colors from two visual sources, ***modulate*** functions use the colors from one source to affect the ***geometry*** of the second source. This creates a sort of warping or distorting effect. An analogy in the real world would be looking through a texture glass window.
While ***blend*** functions combine the colors from two visual sources, ***modulate*** functions use the colors from one source to affect the ***geometry*** of the second source. This creates a sort of warping or distorting effect. An analogy in the real world would be looking through a textured glass window.
`modulate()` does not change color or luminosity but distorts one visual source using another visual source.

Using the same sources from above, we can use an oscillator to modulate or warp the camera image:
Expand All @@ -232,7 +227,7 @@ src(o0).modulate(o1).out(o2) // use source o1 to distort source o0, lighter area
render() // render all four outputs at once
```

You can add a second parameter to the `modulate()` function to control the amount of warping: `modulate(o1, 0.9)`. In this case, the red and green channels of the oscillator are being converted to x and y displacement of the camera image.
You can add a second parameter to the `modulate()` function to control the amount of warping: `modulate(o1, 0.9)`. In this case, the red and green channels of the oscillator are being converted to x and y displacement of the camera image.

All ***geometry*** transformations have corresponding ***modulate*** functions that allow you to use one source to warp another source. For example, `.modulateRotate()` is similar to `.rotate()`, but it allows you to apply different amounts of rotation to different parts of the visual source. See [the function reference](https://hydra.ojack.xyz/api/) for more examples.

Expand All @@ -248,7 +243,6 @@ render() // render all four outputs at once
```

## More blending and modulating

In addition to using multiple outputs to combine visuals, you can also combine multiple sources within the same function chain, without rendering them to separate outputs.

```hydra
Expand All @@ -263,35 +257,44 @@ This allows you to use many sources, blend modes, and modulation, all from withi
osc(10, 0.1, 1.2).blend(noise(3)).diff(shape(4, 0.6).rotate(0, 0.1)).out()
```

Here, we introduce the `diff()` function, another blend function that subtracts whatever is created previously in the function chain from what is inside its parenthesis. You can read more about it in [the function reference](https://hydra.ojack.xyz/api/).

*Trick: use `ctrl + shift + f` from the web editor to auto-format your code*

#### Modulating with the camera

You can also use the camera as a way to modulate other sources.

```hydra
s0.initCam() //loads a camera

shape().modulate(src(s0)).out() //shape modulated by a camera
```

Or use another source to modulate the camera source.

```hydra
s0.initCam() //loads a camera

src(s0).modulate(shape()).out() //camera modulated by a shape
```

#### Additional examples for modulating sources with blend functions




The `add()` blend function enables you to add the colors of whatever is created previously in the function chain and what is inside its parenthesis.

```hydra

noise().out(o1)
shape().out(o3)

src(o1).add(src(o3)).out(o2) //additive light. Color only gets brighter
src(o1).add(src(o3)).out(o2) //additive light. The color only gets brighter

render()
```

The `diff()` blend function subtracts whatever is created previously in the function chain from what is inside its parenthesis.

```hydra
osc(10).out(o0)

Expand All @@ -301,10 +304,12 @@ src(o0).diff(o1).out(o2) // combines different signals by color difference (colo

render()
```

The `mult()` blend function enables you to multiply the colors of whatever is created previously in the function chain and what is inside its parenthesis.

```hydra
osc().mult(src(o1)).out() // multiplies the sources together,
shape(5).out(o1)

```


Expand All @@ -314,4 +319,4 @@ We have now covered all of the basic types of functions within hydra: ***source*
#### Have fun!

---
by Flor de Fuego and Olivia Jack
by Flor de Fuego and Olivia Jack