REF / Music API / Envelope

Ascene . Anode . Agraph . Aengine
Songbook . Song
WSLoader . Sound Loaders
Random . Rhythm . TimeKeeper
MIDI . OSC . HID . Piano
Plot . Envelope . Util
Music Theory with Tonal

---

home . Topics . Interface . Reference . Examples

right-click to navigate to page sections

---

The purpose of class Envelope is to programmatically evaluate an LFO envelope function y = f(x), as used by Envelope Editor, Hz.LFO, Hz.Filter.

Our implementation also includes support for Deep Envelopes where y = f(x, z). This representation is used by Hz.Spectre as time-varying spectral weights.

Envelope API

// To use the API, construct and initialize an instance of the class like so:
let myenv = new Envelope();
myenv.InitJSON(somejson);

// Next, invoke one of the evaluation method. Rinse and repeat.
let val = myenv.EvaluateOne(.5);

Here are the available methods.

Method	Description
Init(obj)	Initialize from an object representation as produced by JSON.parse
InitJSON(str)	Parses the contents of a .knt or .vitallfo file
EvaluateOne(t)	Returns a value between 0 and 1 representing the envelope function at t (0-1)
Render(npts, ?z)	Returns an array of npts values representing the entire envelope. For deep-envelopes the optional z-value can be used to interpolate between existing planes.
ActivatePlane(z)	If your knt file has deepdata, this is used to establish the current evaluation plane.

kntfiles

The .knt file format is a single JSON object with these fields:

Field	Description
name	string: describes the shape of the envelope
smooth	boolean: global smoothing
data	an array of triples representing t, y and power. Thus the number of knots is the length of this array divided by 3. t and y are (0-1) and power is (-5-5)
settings	an optional object containing preview/sonification parameters

A Deep-Envelope is distinguished from a simple envelope by the replacement of the data field with deepdata. Now deepdata is an array of [z, obj] where each obj includes name, smooth and data.

Example Simple Envelope

{
  "name":"Weird Step",
  "smooth":false,
  "data":[
     0,1,-3.401787519454956,
     0.10631868243217468,0.017857134342193604,4.633926868438721,
     0.3212454915046692,0.13214224576950073,-2.4107143878936768,
     0.8373624086380005,1,0,
     1,1,0
  ]
}

Example Deep Envelope

{
  "deepdata": [
    [
      0, {
        "name": "first",
        "data": [
          0,
          0.22205781050901263,
          -2.5799999999999987,
          0.3091237542343533,
          0.9331673705267847,
          0,
          0.5734536082474228,
          0.4070904645476766,
          0,
          0.6409451692363833,
          0.7298288508557457,
          0,
          0.7048969072164949,
          0.41075794621026795,
          0.24,
          0.7615979381443299,
          0.9669926650366751,
          1.76,
          0.8170103092783505,
          0.41442542787285996,
          0,
          0.8878865979381441,
          0.964547677261614,
          -4.84,
          1,
          0.4034229828850868,
          0
        ],
        "smooth": true,
        "context": null
      }
    ],
    [
      0.5, {
        "name": "mid",
        "data": [
          0,
          0,
          3.1,
          0.5,
          1,
          0,
          1,
          0,
          0
        ],
        "smooth": false
      }
    ],
    [
      0.8, {
        "name": "first",
        "data": [
          0,
          0.22205781050901263,
          -4.379999999999999,
          0.3452901195146426,
          0.9804400977995122,
          0,
          0.5734536082474228,
          0.4070904645476766,
          0,
          0.6409451692363833,
          0.7298288508557457,
          0,
          0.7048969072164949,
          0.41075794621026795,
          0.24,
          0.7615979381443299,
          0.9669926650366751,
          1.76,
          0.8170103092783505,
          0.41442542787285996,
          0,
          0.8878865979381441,
          0.964547677261614,
          -4.84,
          1,
          0.4034229828850868,
          0
        ],
        "smooth": true,
      }
    ],
    [
      1, {
        "name": "end",
        "data": [
          0,
          0,
          0,
          0.5090415913200723,
          0.8909090909090907,
          4.94,
          1,
          0,
          0
        ],
        "smooth": true
      }
    ]
  ],
  "settings": {
    "gain": 0.8,
    "speed": 1,
    "freqMin": 100,
    "freqMax": 400,
    "gridStyle": "Log",
    "gridX": 8,
    "gridY": 10,
    "gridLogMin": "80",
    "gridLogMax": "14000"
  }
}