@grame/libfaust

The Faust compiler provided with high-level services that transform DSP code into Faust Audio nodes.

Usage no npm install needed!

<script type="module">
  import grameLibfaust from 'https://cdn.skypack.dev/@grame/libfaust';
</script>

README

Faust Web Audio Library

The Faust Web Audio library provides a high level Javascript API over the Faust compiler. The interface is designed to be used with TypeScript, but describes and documents the API for pure Javascript as well. This document provides an overview of the differents levels of the API. Examples of use are also provided in the exemplesfolder.

Table of Content

Organisation of the API

The API is organised from low to high level as illustrated by the figure below.

Overview

Faust Compiler WebAssembly module

The first level is the Faust compiler compiled as a wasm library named libfaust-wasm. It consists in 3 different files:

  • libfaust-wasm.wasm : the Faust compiler provided as a WebAssembly module
  • libfaust-wasm.js : a javascript loader of the WebAssembly module
  • libfaust-wasm.data : a virtual file system containing the Faust libraries.

You must include libfaust-wasm.js in your html page. The loader will take care of providing an instance of the Faust WebAssembly module and of the associated virtual file system (libfaust-wasm.data). Note that depending on the relative location of libfaust-wasm.js, the loader may fail to find libfaust-wasm.data; in this case, the simple solution consists in copying libfaust-wasm.data aside the refering web page.

Faust Compiler Javascript Interface

The Faust Compiler Javascript interface is described in FaustCompiler.d.ts.
It provides classic Faust compilation services, which output is a raw WebAssembly module with an associated JSON description of the module.

Faust Wasm Instance

This level takes a WebAssembly module produced by the Faust compiler or a precompiled module loaded from a file, and builds an instance of this module with the proper Wasm memory layout, ready to run, but not yet connected to any audio node. It is described in FaustGenerator.d.ts.

Faust Audio Nodes Instances and Offline Processor

This level takes a Faust Wasm instance to build an audio node. AudioWorklet and ScriptProcessor nodes are supported.

Note that ScriptProcessor is marked as deprecated but it's the only audio architecture available on Safari. Both monophonic (generators, effects...) or polyphonic (instruments) nodes can be created.

By default, and to save CPU, created audio nodes are not processing audio buffers. They have to be explicitely started with the start method (and possibly stopped if needed using the stopmethod).

Warning: AudioWorklet is a recent technology and may not be supported by all the browsers. Check the compatibility chart.

An offline processor to render a DSP in a non real-time context and get the computed frames is available. It is described in FaustWebAudio.d.ts. It will automatically use the start and stop methods internally to activate actual rendering in its plot method.

High-level API

A high-level API is available to compile a DSP program and create the audio node, either monophonic or polyphonic. It is described in index.d.ts. More generally, the Faustxxx.d.tsfiles describe interfaces and index.d.ts describes functions and includes the interface files.

How to use with typescript

Simply include the following to get access to types and functions:

///<reference types="@grame/libfaust"/>

Dynamic and Static Instances

The Faust Wasm and Audio Node levels make it possible to generate instances from Faust dsp code as well as from pre-compiled WebAssembly modules. In the latter case, it is not necessary to include the libfaust-wasm.js library, FaustLibrary.js is sufficient to provide the required services. This allows to generate lighter and faster-loading HTML pages.

Note: to create a polyphonic instance from a pre-compiled WebAssembly module, an additional mixer32.wasm file (or mixer64.wasm when compiled in -double ) is required and must be present at the same level as the referring HTML page. This module is part of the dist folder.

Misc. services

  • FaustUtilities.d.ts: provides facilities to browse Faust generated SVG diagrams
  • FaustWAP.d.ts: provides Web Audio Plugins API support.

Important note

Html pages embedding the Faust compiler must be served using https, unless using http://localhost.