Tutorial

brianchirls edited this page Mar 29, 2012 · 8 revisions

Seriously.js Tutorial

Loading Seriously.js scripts

The first step to use Seriously.js is to load up the necessary scripts. You'll need both the Seriously.js core code as well as any effects you'll need. Don't forget to adjust the paths to the script files, depending on where you put them relative to the html file.

<!DOCTYPE html>
<html>
<head><title>Seriously.js Tutorial</title></head>
<body>
	<!-- page content goes here -->
	<script src="seriously.js"></script>
	<script src="effects/seriously.vignette.js"></script>
	<script src="effects/seriously.hue-saturation.js"></script>
	<script src="effects/seriously.split.js"></script>
	<script>
	//main code goes here
	</script>
</body>
</html>

You can load your scripts inside the head element, but it's often a good idea to load them at the end of the page so the browser can render some of your content before waiting for the scripts to load. It makes the page feel faster to the user.

Seriously.js is smart enough that you don't need to load seriously.js before loading the script code, but you are responsible for making sure that all these scripts are loaded before any of your custom code creates any Seriously objects.

When you finally deploy your work, you may want to put all these scripts in a single file and minify it so that it loads up really fast. If you're going to use video, you'll already have plenty of data to load, and every millisecond counts on the web.

Source media and target canvas

Now you're going to need some video or images for Seriously.js to process. In this example, we'll use an <img> element, though you can just as easily use a <video> or a <canvas>. And we'll add an id attribute to make it easier to reference our image.

<img src="images/colorbars.png" id="colorbars"/>

We also need a <canvas> element on which to draw the results. Again, we'll set an id attribute, and we also need to add height and width.

<canvas id="canvas" width="640" height="480"></canvas>

You'll usually want to hide your inputs using CSS, usually by setting display: none. Or you can create the element in Javascript code and just avoid attaching it to the DOM. But for now, we'll leave it visible so you can see what's going on behind the scenes.

Connecting it all up

Now it's time to write the Javascript code that will create and render our composition. The simplest composition we can create is to connect a source directly to a target.

// declare our variables
var seriously, // the main object that holds the entire composition
	colorbars, // a wrapper object for our source image
	target; // a wrapper object for our target canvas

seriously = new Seriously();

// Create a source object by passing a CSS query string.
colorbars = seriously.source('#colorbars');

// now do the same for the target canvas
target = seriously.target('#canvas');

Now that we have all our objects created, let's connect them and start rendering.

// connect any node as the source of the target. we only have one.
target.source = colorbars;

seriously.go();

When we first create the composition network and connect everything, Seriously doesn't start rendering. By calling seriously.go(), we tell Seriously to keep rendering everything in our network whenever any videos are playing or effect parameters change.

You should now see two copies of the color bars. The second copy is our output canvas. Seriously.js will scale the output to whatever dimensions you give it. So try changing the height and width of the canvas and see what happens.

Apply your first effect

So far, our example is looking pretty boring, so let's add some effects. We'll start with a vignette effect. We've already loaded up the script for the vignette plugin, so now all we need is a simple script to create the effect node and connect it to our composition in the right place.

Creating effect nodes is similar to creating source and target nodes, but even easier, since all we need is the name of the effect we want.

var vignette = seriously.effect('vignette');

Now we need to connect everything in the right order. A Seriously composition is a network of sources, targets and effects. All of them are nodes, and images pass from one node to the next, with each effect node modifying the image and passing it along until it reaches a target node, which displays the result. Effect nodes have one or more image sources and output a single image. Source nodes have no inputs, and target nodes have no output.

In our example, we want to pass our image from the source node to the vignette node, and from the vignette node to the target. So the whole script should look like this:

// declare our variables
var seriously, // the main object that holds the entire composition
	colorbars, // a wrapper object for our source image
	vignette, // a vignette effect
	target; // a wrapper object for our target canvas

seriously = new Seriously();
colorbars = seriously.source('#colorbars');
target = seriously.target('#canvas');
vignette = seriously.effect('vignette');

// connect all our nodes in the right order
vignette.source = colorbars;
target.source = vignette;
seriously.go();

Reload the page, and you should see the color bars with the vignetting, a darkening around the edges.

A Shortcut

To make life easier for everyone, Seriously goes out of its way to validate any parameter inputs it receives. Seriously.js knows that vignette.source needs to be an image output, either from a source node or an effect node. So if we give it another kind of input that points to an image (or video or canvas) element, it will go ahead and create the source node for us.

We can skip creating the colorbars node and just write the following:

vignette.source = '#colorbars';	

There are some advanced features we can use by accessing the actual source node access. So if we need that later on, we can always retreive it by accessing vignette.source, which will now point to the actual source object.

Adjusting effect parameters

While every effect comes set up ready to display, most of them will need some adjustment. So most effects have one or more parameters that can be modified to tweak the results, just as the effects in Final Cut Pro or After Effects do. Later on, we'll explore how to animate these values.

Each plugin should (eventually) have documentation about the parameters you can adjust. The vignette effect has only one parameter, amount, which is by default set to 1.

To set a parameter, simply set the property on the effect object. Experiment with setting vignette.amount to different values and see what happens.

vignette.amount = 10;
//or...
vignette.amount = 0.1;

Seriously allows some effect parameters to have limits on their values, such as a maximum or a minimum. In this case, vignette.amount has a minimum value of 0. If the value is set outside the defined range, it will automatically be capped. Try it:

vignette.amount = -42;
console.log(vignette.amount); // should be 0

Similarly, if you set the value to the wrong type (in this case, a number), it will revert back to the default.

vignette.amount = 10; // everything is okay
console.log(vignette.amount); // 10

vignette.amount = 'not a number';
console.log(vignette.amount); // should be 1

Going interactive

Another neat trick Seriously pulls is that it makes it easy to set an effect parameter to watch an HTML form element. Whether or not you want to give users direct control over a parameter in your final composition, this is a useful way to experiment with how effects will look.

Let's create a range input element in our web page, which looks like a slider. Even though vignette.amount doesn't have an upper limit, the range input requires a maximum, so we'll set one that's big enough. These elements also have a step value, which defaults to 1, so we'll set that to something very small to make it slide smoothly. You may wish to also add a label that indicates what the slider slides.

<input type="range" id="vignette-range" min="0" max="20" step="0.0001" value="1"/>

Unfortunately, Firefox does not yet support range inputs. But we can fix this easily with html5slider, which will make them for you. Just get this script from the GitHub repo (it's also packaged with Seriously.js), place it on your web server, and add it to the web page like this:

<script src="html5slider.js"></script>

Now we just have to set vignette.amount to the input element, and we're good to go.

vignette.amount = '#vignette-range';

You can also set it by pointing directly to the DOM object.

vignette.amount = document.getElementById('vignette-range'); //same thing

Now reload the page and see what happens when you adjust the slider.