Plays an effect recipe (.sfx.json) with variation, and renders it offline the same way. More...
| Import Statement: | import Clayground.Sound |
A recipe is a stack of layers - each one voice with a source (oscillator, noise - white, pink or brown, drawn every sample or clocked by the layer's pitch - or a WAV sample), an envelope, a pitch curve, a filter curve, an oscillator's two-operator FM with an index envelope or its ring modulation, an LFO - sine, square, sample-and-hold or smooth random, seeded by the play - on the pitch, the volume or the filter cutoff, a tanh drive and a bit and rate crush, a start offset, a gain and a pan, in Hz, ms, semitones and dB; each envelope segment and the pitch sweep linear or, up to exponential, a straight line in dB; a layer with a burst plays as many short seeded grains, maxVoices bounding how many ring at once - plus a variation spec: a random range per layer field, a seed and a round-robin pool size. The plugin README documents the format; the parser rejects an unknown field by its name and path. A recipe can also be compiled from a design file - a template, its macro values and overrides (.sfx.design.json) - by the engine library; the player reads only the compiled recipe (README, "Design files").
SfxPlayer {
id: detent
source: "sfx/wheel-detent.sfx.json"
}
// in a handler:
var seed = detent.play()
var samples = detent.renderOffline(seed) // what that play() sounded like
Every play() draws the next variation; a seed always draws the same values. play() and renderOffline() schedule the same notes through one code path, so a pre-rendered file of a seed and the live sound of it are the same samples. Watches the recipe file and hot-reloads it; a broken save keeps the last good recipe.
Path to a .sfx.json recipe. Sample files in it are relative to it.
True once the recipe parsed and its samples loaded.
Last parse or load error, empty when OK. Starts with the path of the failing field, e.g. layers[1].envelope: unknown field 'decya'.
The recipe's name.
The number of layers in the recipe.
The recipe's variation.pool: play() cycles through this many variations; 0 makes every play a new one.
The seed of the last play() or playSeed(), -1 before the first.
Volume of every layer, 0..1, default 1.
-1 (left) .. +1 (right), added to each layer's own pan. Default 0.
The bus the layers mix into: "sfx" (default), "music" or "voice".
When true, play() repeats the variation it drew pass after pass until stop(), for an ambience bed. A pass starts one period after the one before: the time until the last layer ends, less that layer's release, so the release crossfades into the next pass and there is no gap. Read by play() and renderOffline(); a loop that already plays goes on until stop(). Default false.
Plays the next variation and returns its seed, or -1 when nothing is loaded. velocity (0..1, default 1) scales every layer. detune (semitones, default 0) transposes every layer, oscillator and sample: the play sounds as the recipe would with every layer's detune raised by it, so one recipe plays a scale.
Plays the variation of seed, at velocity and transposed by detune semitones as in play(). Returns false when nothing is loaded.
Ends every voice this player started: a ringing layer runs its own release from now and is freed, a layer whose offset has not come yet does not start, and a loop plays no further pass. The player stays loaded; the next play() sounds as before.
The seed the index-th play() since the recipe loaded uses.
What playSeed() of seed at velocity and detune (semitones, default 0) sends into its bus, as mono samples (the (L + R) / 2 downmix, clamped to -1..1) at 44.1 kHz, from the first layer's start to the last layer's end - with loop, passes periods (default 1) of the loop - at the player's volume and pan. Renders on an engine of its own and does not touch the live sound. The bus volume, echo and reverb are not part of it.
Emitted after the recipe file changed on disk and was loaded again.
Emitted when the recipe or one of its samples fails to load. On a hot reload the previous recipe keeps playing.
See also SynthInstrument, SampleInstrument, and SongPlayer.