flowav-core/README.md

Core library for the FlowAV project; a livecoding audiovisual language built ontop of VideoContext and gibberish.js

# FlowAV-Core
> Core library for the FlowAV project. Use this if you'd like to include FlowAV into an existing project.

FlowAV is a live coding programming language built on top of [VideoContext](https://github.com/bbc/VideoContext) and [Gibberish](https://github.com/gibber-cc/gibberish). FlowAV gets its name from the Flow-Based Programming paradigm, and while not strictly a FBP, the syntax heavily implies a logical flow of data.

## Syntax

The best way to describe FlowAV's syntax is to breakdown a small example.

![FlowAV example](https://i.imgur.com/FB8zs8Z.jpg)

```
$ Video('01')
  : loop
  | Output()
$ Video('02')
  : scale -> 0.5
  : pos -> -0.5 0
  | Output()
$ Video('http://www.example.com/video.mp4')
  : scale -> 0.5
  : pos -> 0.5 0
  | Effect('monochrome')
    | Output()
```

The snippet of code will do the following:

- Open the video '/video/01.mp4' and display it fullsize and loop continuously.
- Open the video '/video/02.mp4'.
  - Scale the video to 50% width and height.
  - Centre the video vertically and position it in the left half of the canvas
- Open the video from the url 'http://www.example.com/video.mp4'
  - Scale the video to 50% width and height.
  - Centre the video vertically and position it in the right half of the canvas
  - Apply a monochrome filter to the video

The code is split into blocks and follows a tree-like branching structure.

### `$` and `#`
Declares the context for the following block. `$` for video and `#` for audio. Currently only the video context is functional.

### `Node('argument')`
What follows after a block declaration is a root node; these are video or image sources for the video context. The current nodes are valid root nodes:

- `Video('path/to/video')`
- `Image('path/to/image')`

The above code snippet demonstrates that FlowAV expects video files to be placed in a `/video` folder in the root directory. Doing so allows users to type the file name rather than the whole path. It also demonstrates loading a video from an external URL. While this is currently functional, it is possible this feature is dropped in the future.

Additionally, a third `Canvas()` node is planned.

### `:` and `->`

These are used to define parameters for a node, they follow the syntax `: param -> (value)` where value is optional. If left blank, the value will implicitly be `true`; useful for parameters such as `loop`.

### `|`

Connections to other nodes are notated with a pipe. An arbitrary number of connections can be made, and those connections can have parameters and connections themselves; allowing for complex effects chains.

## Getting started
If you'd just like to play around with FlowAV, check out the sister project [FlowAV-Live](https://github.com/FlowAV/FlowAV-Live) to build an environment or head [here](#) to try it in the browser.

If you'd like to contribute to FlowAV-Core or use it in an existing project follow these steps.

* Clone the repository:

  `git clone https://github.com/FlowAV/FlowAV-Core.git`

* Install dependencies:

  `npm install`

To build the project into a UMD file as `/dist/FlowAV.js` run:

  `npm run build`
  
To run a webpack dev server with hot reloading enabled run:

  `npm run dev`
  
At the moment webpack compiles all the dependencies as part of the build process. This might not be a good idea but honestly I don't have a clue...