Reference

The polec command line

Every flag the compiler takes, straight from its own help.

Anyone running the compiler.

The command line follows the same pattern for every patch: choose a source file, choose what to do with it, then supply any inputs or controls it needs. The complete help output at the end is copied from the compiler.

Read a command#

Run these examples from the repository's tools/pole directory:

./build/polec examples/sine.pole --emit=wav --out=/tmp/sine.wav --rate=48000 --frames=48000

The first argument is the source file. --emit=wav requests an offline render, --out names the output file, and the last two flags request one second of audio: 48,000 frames at 48,000 frames per second. More frames mean a longer render, not a different pitch.

Common options by purpose#

Option	Value	What it changes
`--emit=...`	`wav`, `ir`, `llvm`, `object`, `header`, `export` or `web`	The kind of output; see emit targets.
`--out=...`	File path or export stem	Where the result is written. An export stem produces several files.
`--rate=...`	Sample rate in Hz	The processing rate supplied to the patch.
`--frames=...`	Frame count	Length of an offline render; duration is frames divided by rate.
`--input=...`	Built-in signal name	Test material for a processor that needs an input.
`--input-wav=...`	WAV path	Use recorded material as the input.
`--params`	No value	List controls and exit.
`--param=name=value`	Parameter name and numeric value	Override a declared default, such as `--param=freq=440`.
`--data=name=file.wav`	External name and WAV path	Bind sample or wavetable data. Graph names include the node path.
`--play`	No value	Play live on the supported native audio platform.

A small working session#

./build/polec examples/sine.pole --params
./build/polec examples/sine.pole --emit=wav --out=/tmp/high-sine.wav --param=freq=440 --frames=48000 --rate=48000
./build/polec examples/delay.pole --emit=wav --input=impulse --out=/tmp/echo.wav --frames=96000 --rate=48000

First inspect the available controls, then change one by name. The last command feeds an impulse into a delay so its repeats are visible and audible in the two-second render. A silent input is useful for checking an effect's initial state, but it will not demonstrate what that effect does to a signal.

Complete compiler help#

usage: polec <file.pole> [--emit=ir|llvm|wav|object|header|export|web]
              [--out=<path>] [--target=<triple>] [--cpu=<model>]
              [--diagnostics=human|agent] [--rate=<hz>] [--frames=<n>]
              [--input=saw|sine|silence|impulse|notes|chords]
              [--input-wav=<path>]
              [--play] [--controls=v1,v2,...] [--data=name=file.wav]
              [--param=name=value] [--params] [--vec-report]
              [--bench-graph] [--reorder-demo]
              [--events] [--event-script]

  --play  compile, then play live through the audio device. Letter keys
          sound notes (the input endpoint carries a pitch CV in Hz);
          q quits.
  --events    play the built-in event script through the graph, on the
              TIMELINE -- each note lands on the frame it is stamped at.
  --event-script  print that script and exit, so a generated C driver
              replays exactly what the JIT played.
  --vec-report  what LLVM vectorised, and why it refused the rest.
  --approx-math  sin, exp and tanh as inline polynomials instead of
              calls to the platform's libm. Several times faster where a
              patch leans on them, a few ulp less accurate, and the same
              arithmetic on every target -- which libm never was.
  --params    list the parameters this patch declares, and exit.
  --param     set one of them; defaults apply otherwise.
  --data      fills an `external` array from a WAV -- a wavetable,
              an impulse response, a sample.
  --controls  values held on input endpoints 1..N for an offline
              render -- velocity, mod wheel, morph and so on.
  --emit=export   an object file AND its C header: --out=x writes x.o
              and x.h. Link them into a plugin and Pole is not needed
              at run time -- no LLVM, no JIT, just libm.
  --emit=web  an object file AND a JSON manifest: --out=x writes x.o
              and x.json. Targets wasm32 unless --target says
              otherwise. Link x.o with wasm-ld and the manifest tells
              a browser everything the C header would have told C.
  --target    the triple to emit an object for; defaults to this host.
  --cpu       the processor model the object is scheduled for: apple-m1 on
              arm64 macOS (the oldest such machine), generic elsewhere. An
              x86-64 plugin that may assume AVX2 says --cpu=x86-64-v3.
              e.g. x86_64-pc-windows-msvc, x86_64-unknown-linux-gnu.
  --bench-graph   for a `graph`: what a rebuild costs against editing
              one node, and what it costs to render.
  --reorder-demo  render the graph while reversing its effect chain
              once a second, so a live reorder can be listened to.