hvcc

The heavy hvcc compiler for Pure Data patches. Updated to python3 and additional generators

View the Project on GitHub

The Heavy Audio Programming Language Specification

Graph

The graph object is the top-level object which can be loaded from file. It is a dictionary with four keys.

imports

An optional list of paths defines where abstractions can be found. By default, the following paths are implicitly searched in order before any of the listed paths.

  1. Low-level Heavy objects
  2. Heavy standard library
  3. Local path
  4. Imported paths

Note that if an abstraction with the same name is found in more than one path, the first one found is used.

Paths may be relative or absolute. If they are relative, they are relative to the location of the graph which is being defined.

{
  "imports": [
    "path/to/dir",
    "path/to/other/dir"
  ]
}

args

This key defines the parameters which a graph or object can take. Each element in the args list is a dictionary containing a set of keys describing that argument.

In this example, the graph has one parameter, fc. It is a float, and is not required to be supplied when the graph is instantiated. This parameter defaults to a value of 0.0. If a parameter is required, the default value may be set as null.

{
  "args": [
    {
      "name": "fc",
      "type": "float",
      "description": "The cutoff frequency (Hz).",
      "default": 0.0,
      "required": false
    }
  ]
}

objects

The objects key declares a dictionary of objects in this graph. Each key is a unique identifier for the object. See below for a definition of object dictionaries.

{
  "objects": {
    "add_0": {
      "type": "add",
      "args": {
        "k": 5
      },
      "properties": {
        "x": 100,
        "y": 200
      }
    }
  }
}

connections

A list of connection objects between the objects in the graph. Each connection is defined by its type, as well as a from starting point and a to termination point composed of an an object id and a let index.

A connection type can be any one of:

  1. -->: a control connection
  2. -~>: a connection that can be either control or signal, the exact type of which must be resolved at compiletime.
  3. ~f>: a float signal connection
  4. ~i>: an int signal connection
{
  "connections": [
    {
      "type": "-->",
      "to": {
        "id": "add_0",
        "inlet": 0
      },
      "from": {
        "id": "loadbang_0",
        "outlet": 0
      }
    }
  ]
}

Object

An object dictionary defines which object is required, as well as arguments, properties, or annotations defining its behaviour. The standard keys include:

{
  "add_0": {
    "type": "add",
    "args": {
      "k": 5
    },
    "properties": {
      "x": 100,
      "y": 200
    }
  }
}

type

This key defines which object or abstractions the object refers to. If the object type are resolved according to the Heavy path importation priority list as described above.

args

Object arguments are described, and are object-specific. If a graph argument should be passed to an object in the graph, the argument an be referred to by appending a $ to the from of the argument name.

{
  "add_0": {
    "args": {
      "k": "$fc"
    }
  }
}

This argument value will be resolved at compile time, with a defined default value being used if none is available.

properties (optional)

An optional properties key may be supplied to give user-defined to UI-related information. This might include the x, y position of an object in a patch. The parameters dictionary is not used in the compilation process.

annotations (optional)

Some objects may be annotated in order to provide additional hints to the compiler, or to modify standard behaviour. Three annotations are available, scope, static, and const.

{
  "annotations": {
    "scope": "public",
    "static": true,
    "const": true
  }
}

Considerations

Combinations of scope and static may have slightly different meanings typically found in other languages.

Objects and Scoping

There is a specific set of objects to which scoping rules apply. These are: