README.md
1Radiance
2========
3
4Radiance is video art software for VJs. It supports beat detection, animated GIFs, YouTube video, OpenGL shader effects. It is designed for live performance and runs on Linux and MacOS.
5
6[](https://travis-ci.org/zbanks/radiance)
7
8Artwork
9-------
10
11
12
13[Sample Artwork 1](https://i.imgur.com/R4tsFfG.gifv)
14
15[Sample Artwork 2](https://i.imgur.com/B0QMoXT.gifv)
16
17[Sample Artwork 3](https://i.imgur.com/4FON4vY.gifv)
18
19[Screencapture from this artwork](https://i.imgur.com/Vb1yPZl.gifv)
20
21[Example effects](https://radiance.video/library/)
22
23Download
24--------
25
26You can download Radiance for Linux or MacOS from the [releases](https://github.com/zbanks/radiance/releases) page.
27
28Build
29-----
30
31### Dependencies
32
33- `Qt 5.9` or higher
34- `PortAudio`
35- `FFTW3`
36- `libsamplerate`
37
38### Optional Dependencies
39- `libmpv`
40- `rtmidi`
41
42Install dependencies on Ubuntu:
43
44 $ sudo apt-add-repository ppa:beineri/opt-qt591-trusty
45 $ sudo apt-get update
46 $ sudo apt-get install qt59base qt59multimedia qt59quickcontrols qt59imageformats qt59quickcontrols2 qt59script libfftw3-dev libsamplerate0-dev libasound2-dev libmpv-dev libdrm-dev libgl1-mesa-dev
47 $ git clone https://github.com/EddieRingle/portaudio # build & install
48 $ git clone https://github.com/thestk/rtmidi # build & install
49
50Note: you may need to install portaudio & rtmidi from git as above
51
52### Building Radiance
53
54 git clone https://github.com/zbanks/radiance
55 git submodule update --init
56 cd radiance
57 mkdir build
58 cd build
59 cmake .. # -DCMAKE_PREFIX_PATH=/opt/qt59/ -DCMAKE_BUILD_TYPE=Debug
60 make
61 ./radiance # Qt UI
62 ./radiance_cli # Command line GIF generator
63
64If you `git pull` changes, make sure you also do `git submodule update` to pull in changes to `BTrack/`.
65
66### youtube-dl
67
68Radiance uses `libmpv` to load videos, which can optionally use `youtube-dl` to stream videos from YouTube and many other sites. Since `youtube-dl` updates frequently, we have avoided bundling it with Radiance. Instead, on Linux:
69
70 sudo pip install youtube-dl
71
72or on Mac:
73
74 brew install youtube-dl
75
76You can then load YouTube videos into Radiance using the youtube node in the library.
77
78Mouse Control
79-------------
80
81- `Double click` (in the library) - add tile
82- `Click` (on a tile) - select tile
83- `Ctrl`-`click` (on a tile) - select multiple
84- `Shift`-`click` (on a tile) - select contiguous
85- `Click and drag` (on a tile) - re-order selected tiles
86- `Scroll wheel` - change intensity of selected tiles
87- `Ctrl`-`scroll wheel` - zoom
88
89Keyboard Control
90----------------
91
92- `:` - Search library
93- `Ctrl`-`+` - Zoom in
94- `Ctrl`-`-` - Zoom out
95- `Ctrl`-`0` - Reset zoom
96- `` ` ``, `0-9` - Set selected slider. `` ` `` = 0%; `1` = 10%; `5` = 50%; `0` = 100%
97- `j` - Decrement selected slider by 10%
98- `k` - Increment selected slider by 10%
99- `Delete` - Remove a tile
100- `Ctrl` + `` ` ``, `1-9` - Assign slider to MIDI knob
101- `r` - Reload tile
102- `Esc` - Close output window
103
104Shader Effects
105--------------
106
107Radiance generates video from a set of connected "VideoNodes." Most commonly, these nodes are based on OpenGL fragment shaders, but can also be static images, GIFs, or videos. Each node takes one or more inputs and produces exactly one output.
108
109Each OpenGL fragment shader node is described by a single `.glsl` file in [`resources/library/effects`](https://github.com/zbanks/radiance/tree/master/resources/library/effects).
110
111For the most part, these files are plain GLSL describing the fragment shader. This is similar to setups on shadertoy.com or glslsandbox.com . Each shader defines a function `void main(void)` which sets a pixel color `vec4 fragColor` for a given coordinate `vec2 uv`. `fragColor` is an RGBA color with pre-multiplied alpha: so white with 40% opacity is encoded as `vec4(0.4, 0.4, 0.4, 0.4)`. The coodinate `uv` has `x` and `y` values in the range `[0.0, 1.0]` with `vec2(0., 0.)` corresponding to the lower-left corner.
112
113The shader also has access to its input(s) as textures through the `iInput` (or `iInputs[]`) uniforms.
114
115In addition, each shader has access to additional uniforms which are documented in [`resources/effects/*.glsl`](https://github.com/zbanks/radiance/tree/master/resources/library/effects). The most important is `iIntensity`, which is a value in the range `[0.0, 1.0]` which is mapped to a slider in the UI that the user controls. There is a limitation of having *exactly one* input slider per effect: this is intentional to reduce the cognitive overhead on the end user. Other variables include information about the current audio or time.
116
117### Invariants
118
119Each shader must follow these properties:
120
121* The `fragColor` set by each shader must be a valid, pre-multiplied alpha, RGBA tuple. Each component of the `vec4` must be in the range `[0.0, 1.0]`, and the RGB components must be less than or equal to the A component. (See `afixhighlight` for a shader that will highlight errors here in pink)
122* Identity: the shader must pass through its first input completely unchanged when `iIntensity == 0.` This means that inserting a new shader should not affect the output until its intensity is increased.
123
124
125### Multi-buffer Shader Effects
126
127Some effects cannot be accomplished with a single fragment shader pass. An effect can consist of a series of shaders, separated by `#buffershader`. Each shader renders to a texture in `iChannels[]` (e.g. the first renders to `iChannels[0]`). The shaders are rendered in backwards-order, so the last shader in the file is rendered first. Only the output of the first shader in the file is displayed -- the other buffers persist between frames but are not exposed to other nodes.
128
129An example that uses this feature is [`foh.glsl`](https://github.com/zbanks/radiance/blob/master/resources/library/effects/foh.glsl). This implements an (exponential) "first-order hold" - it samples the input texture on a multiple of the beat and stores it in `iChannel[1]`.
130
131
132
133Copyright & License
134-------------------
135
136Released under the MIT/X11 License. Copyright 2016 Zach Banks and Eric Van Albert.
137
138
){kind=link}
){kind=link}