Coding in Praxis LIVE

If you can't find a built-in or existing components that does what you want, it's easy to get coding in Praxis LIVE. The code of Praxis LIVE components is based on the excellent and easy to use Processing project. Not only that, but you can rewrite components on-the-fly, while your project is running.

To get started, choose one of the base components and drag it into your graph. Alternatively, choose a built-in component or custom component that does some of what you want and start from there instead. Right-click on the component in the graph window and select Edit code to open the code in the code editor. Everytime you hit Save within the code editor your code will be recompiled and inserted into your component, even as it's running. The code editor supports code completion and will highlight errors in your code.

Note that saving code in the code editor saves the code to the component, it does not save it to disk - make sure you also save your project!

Base types

The base types for different component types are listed here. Note that most base types build on the functionality of core:custom.

Core syntax and functionality

The primary coding language used in Praxis LIVE is Java. If you've not used Processing or Java before, you should probably take some time to look through the Processing tutorials and reference - much of the information there will be useful to you.

Having said that, don't be scared to play - the built-in code editor in Praxis LIVE will highlight most errors in your code and supports intelligent code completion.

Using annotations

Unlike Processing, Praxis LIVE makes a lot of use of annotations on fields and methods. These annotations are used to integrate your code with the environment, such as providing visual ports or controls, automatically saving state, allowing variables to be controlled by MIDI / GUI, provide background loading of resources, etc.

@In(1) PImage in;

@P(1) @Port(false) PImage image;
@P(2) @Type.Number(min = 0, max = 1) scale;

@T(1) void randomize() {
  scale = random(1);
}

public void draw() {
  // do something with image and scale
}

The above code is based on one of the video base components. The above code will provide a video input port, an image property (without port) that supports background loading of an image file, a numeric scale property with visual slider, and a trigger control with visual button that calls the annotated method. Note that none of the fields are initialized by the code - all annotated fields will be automatically set by the environment.

For more information see the documentation for individual annotations.

Properties and Triggers

All base component types support the use of the @P and @T annotations to define properties and triggers (actions).

The core fields types supported by the property annotation are double, int, String, boolean and Property. All the core field types are backed by a Property object, which also supports animation - see the full Property documentation. Base types may extend the fields that can be marked with the property annotation (eg. video base types support PImage fields).

Values of property fields will normally be saved as part of the project file, unless the property is marked with @Transient or @ReadOnly. The new @Inject annotation also supports properties that are hidden and transient - useful for maintaining state or animation while coding.

The trigger annotation can be placed on a zero argument method, or on a field of type boolean or Trigger. If using a boolean field, the value will be set to true when triggered - you are responsible for resetting it.

Input and Output

All base components support the use of annotations to provide ports for control signal input and output. The auxillary annotations cause the ports to appear after property and trigger ports rather than before.

@In / @AuxIn

Use the @In or @AuxIn annotations on a method to provide a port with which to receive control values -

@In(1) void in(double input) {
  // do something with input
}

The method will be called at the correct time with the input value. Supported types are double, int, String and Argument.

Be aware that input methods will be called during the update rather than rendering part of the video processing cycle - if using in a video component, you cannot call drawing functions.

@Out / @AuxOut

Use the @Out or @AuxOut annotation on a field of type Output to provide control signal output ports on your component.

The Output object supports methods for sending double, String and Argument, as well as an empty signal.

@Out(1) Output out;

@In(1) void in(double input) {
  out.send(input);
}

Output sending should only happen during the update part of the video rendering cycle, which means that currently you should not call Output.send(..) during the draw() method of a video component.

Coming from Processing?

If you're used to working with Processing, have a read of this blog post which covers some of the differences when working with Processing code inside Praxis LIVE.