Faust Libraries

This repository contains the source code and the documentation of the DSP libraries of the Faust Programming Language.

Here is the online documentation of the Faust libraries (which also serves as a proper README for this repository).

Prerequisites

• you must have awk and mkdocs installed.
• you must have the Faust source code installed. You can get it from github.

WARNING: adding new files

Be sure to add new files in the doc/docs, and not in the docs which is the folder generated by the build process.

Building the documentation

The build process is based on make located in the doc folder. Building the documentation site is based on mkdocs. To install the required components type:

To generate all these files type:

$ make install

Testing and generating

You can test the web site using the mkdoc embedded web server. This server also scan any change in the source directory and refresh the pages dynamically which is really convenient for the development process. To launch the server type:

$ make serve

When ready, you can generate the documentation web site. Type:

$ make build

The web site will be available from the site folder at the root of the faustlibraries folder

More details on the build process:

$ make help

Faust Library JSON Exports

This repository can also generate machine-readable JSON exports of the Faust library documentation directly from the .lib sources.

The generator is:

scripts/build_faust_doc_index.py

It parses documentation blocks from the library sources, starting from stdfaust.lib, follows library("...") and import("...") directives, and extracts for each documented symbol:

• summary
• usage
• params
• notes
• io with inSignals / outSignals when derivable
• testCode
• references
• source

Two JSON layouts are supported:

• monolithic: one full JSON file containing all libraries and symbols
• split: one compact global index plus one detailed JSON file per module

Default Make targets:

make doc-index
make doc-index-split

Default output locations:

• make doc-index writes tests/faust-doc-index.json
• make doc-index-split writes:
  • tests/faust-doc-index.json
  • tests/faust-doc/index.json
  • tests/faust-doc/modules/*.json

You can override the output paths:

make doc-index DOC_INDEX_OUTPUT=/tmp/faust-doc-index.json
make doc-index-split DOC_INDEX_OUTPUT=/tmp/faust-doc-index.json DOC_INDEX_SPLIT_DIR=/tmp/faust-doc

You can also run the generator directly:

python3 scripts/build_faust_doc_index.py --repo-root . --output tests/faust-doc-index.json --pretty
python3 scripts/build_faust_doc_index.py --repo-root . --output tests/faust-doc-index.json --split-output-dir tests/faust-doc --pretty

The split layout is recommended for LLM or retrieval-based use because it avoids loading the whole documentation into context for every request.

Local Documentation Query API

The repository also ships with a local query tool that reproduces the Faust library documentation operations used in faustforge:

scripts/faust_doc_api.py

Supported operations:

• search_faust_lib
• get_faust_symbol
• list_faust_module
• get_faust_examples
• explain_faust_symbol_for_goal

The tool can read either:

• the monolithic export tests/faust-doc-index.json
• the split export tests/faust-doc/index.json

If --index is omitted, it tries these defaults in that order:

1. tests/faust-doc/index.json
2. tests/faust-doc-index.json

Examples:

python3 scripts/faust_doc_api.py --pretty search_faust_lib reverb --limit 5
python3 scripts/faust_doc_api.py --pretty search_faust_lib filter --module filters --limit 10

python3 scripts/faust_doc_api.py --pretty get_faust_symbol de.delay
python3 scripts/faust_doc_api.py --pretty list_faust_module delays --limit 20
python3 scripts/faust_doc_api.py --pretty get_faust_examples delay
python3 scripts/faust_doc_api.py --pretty explain_faust_symbol_for_goal re.springreverb "build a metallic spring reverb"

To force a specific index location:

python3 scripts/faust_doc_api.py --index tests/faust-doc-index.json --pretty get_faust_symbol aa.Rsqrt
python3 scripts/faust_doc_api.py --index tests/faust-doc --pretty list_faust_module filters --limit 10

Operation semantics mirror faustforge:

• search_faust_lib(query, limit?, module?) searches symbols by name, qualified name, summary, and source file without loading full docs into context
• get_faust_symbol(symbol) returns the full symbol entry plus close alternatives
• list_faust_module(module, limit?) lists symbols from one library module such as delays or filters
• get_faust_examples(symbolOrModule, limit?) returns the #### Test snippets for a symbol or module
• explain_faust_symbol_for_goal(symbol, goal) builds an action-oriented explanation for a concrete DSP objective

The make clean target removes the generated JSON artifacts by default:

• tests/faust-doc-index.json
• tests/faust-doc/

Publishing

Publishing is handled by GitHub Actions. Pushing to the main branch will build and deploy the site.

LLMs

The site exposes an llms.txt file generated from doc/docs/llms.txt and published at https://faustlibraries.grame.fr/llms.txt.

WARNING!!

• never delete the doc/docs/CNAME file (which is mandatory for the final generated site to work)