Skip to content

Standard Library

Jump to bottom
github-actions[bot] edited this page May 2, 2026 · 1 revision

Standard Library

Flow's standard library provides all built-in functions. Most programs need use "@std" at minimum.

Why use "@std" Matters

Without use "@std", you only have raw language syntax (variables, operators, proc, note streams, context blocks). Essential functions like print, str, concat, add, sub, list, map, filter, and all collection operations require the standard library.

use "@std"
(print "now print works")

Modules

Module Import Provides
@std use "@std" Core + collections + bars (also auto-imports @collections and @bars)
@collections use "@collections" List operations (head, tail, map, filter, etc.)
@audio use "@audio" Audio creation, effects, playback, synthesis, MIDI/WAV I/O
@notation use "@notation" Musical notation (note durations, rests, time signatures)
@bars use "@bars" Bar/note operations
@composition use "@composition" Timeline, voice, track, polyrhythm, variation

@std automatically imports @collections and @bars, so you rarely need to import them separately.

Core Functions

I/O

Function Signature Description
print (String) -> Void Print string with newline

String Operations

Function Signature Description
str (T) -> String Convert any value to string
len (String) -> Int String length
concat (String, String) -> String Concatenate strings

str has overloads for Int, Float, Double, String, Bool, Note, Bar, Semitone, Cent, Millisecond, Second, Decibel, Array, Sequence, Chord, Section, Song.

Arithmetic

Function Signature Description
add (Int, Int) -> Int (plus Float / Double overloads) Addition
sub (Int, Int) -> Int Subtraction
mul (Int, Int) -> Int Multiplication
div (Int, Int) -> Int Integer division (and Float/Double overloads)
abs (Int) -> Int / (Double) -> Double Absolute value
min (Int, Int) -> Int / (Double, Double) -> Double Minimum
max (Int, Int) -> Int / (Double, Double) -> Double Maximum

Binary operators +, -, *, / also work for arithmetic expressions.

Math

Function Signature Description
sin (Double) -> Double Sine
cos (Double) -> Double Cosine
tan (Double) -> Double Tangent
sqrt (Double) -> Double Square root
floor (Double) -> Int Round down
ceil (Double) -> Int Round up
round (Double) -> Int Round to nearest
pow (Double, Double) -> Double Exponentiation
log (Double) -> Double Natural log
pi () -> Double π
tau () -> Double 2π

Comparison

Function Signature Description
equals (T, T) -> Bool Loose equality (with type coercion)
sequals (T, T) -> Bool Strict equality (types must match)
lt (T, T) -> Bool Less than
gt (T, T) -> Bool Greater than
lte (T, T) -> Bool Less than or equal
gte (T, T) -> Bool Greater than or equal

Logical

Function Signature Description
and (Bool, Bool) -> Bool Eager AND
and (Lazy<Bool>, Lazy<Bool>) -> Bool Short-circuit AND
or (Bool, Bool) -> Bool Eager OR
or (Lazy<Bool>, Lazy<Bool>) -> Bool Short-circuit OR
not (Bool) -> Bool Logical NOT
if (Bool, Lazy<T>, Lazy<T>) -> T Conditional (lazy branches)

Type Conversion

Function Signature Description
intToDouble (Int) -> Double Int → Double
doubleToInt (Double) -> Int Double → Int (truncates)
stringToInt (String) -> Int Parse Int (returns Void on failure)
stringToDouble (String) -> Double Parse Double (returns Void on failure)

Lazy and Control

Function Signature Description
eval (Lazy<T>) -> T Force evaluation of a lazy value
setMaxIterations (Int) -> Void Cap loop iterations (safety limit)

Random

Function Signature Description
? () -> Float Random float [0, 1)
?? () -> Float Seeded random float [0, 1)
??set (Int) -> Void Set the seeded RNG state
??reset () -> Void Reset the seeded RNG

Collection Functions

Function Signature Description
list (...T) -> T[] Create array from varargs
length / len (T[]) -> Int Array length
head (T[]) -> T First element
tail (T[]) -> T[] All except first
last (T[]) -> T Last element
init (T[]) -> T[] All except last
empty (T[]) -> Bool Is empty?
reverse (T[]) -> T[] Reverse order
take (T[], Int) -> T[] First N elements
drop (T[], Int) -> T[] Drop first N
append (T[], T) -> T[] Add to end
prepend (T, T[]) -> T[] Add to start
concat (T[], T[]) -> T[] Concatenate arrays
contains (T[], T) -> Bool Contains element?
map (T[], T => U) -> U[] Transform elements
filter (T[], T => Bool) -> T[] Filter by predicate
reduce (T[], U, (U, T) => U) -> U Fold with accumulator
each (T[], T => Void) -> Void Apply for side effects
range (Int, Int) -> Int[] Integer range [lo, hi)
zip (T[], U[]) -> [T, U][] Pair elements

See Collections for details.

Audio Functions

Buffer Operations

Function Signature Description
createBuffer (Int, Int, Int) -> Buffer Create buffer (frames, channels, sample rate)
getFrames / getChannels / getSampleRate (Buffer) -> Int Buffer metadata
getSample (Buffer, Int, Int) -> Float Get sample (frame, channel)
setSample (Buffer, Int, Int, Double) -> Void Set sample
fillBuffer (Buffer, Double) -> Void Fill with constant
copyBuffer (Buffer) -> Buffer Deep copy
sliceBuffer (Buffer, Int, Int) -> Buffer Extract slice
appendBuffers (Buffer, Buffer) -> Buffer Concatenate end-to-end
scaleBuffer (Buffer, Double) -> Buffer Multiply all samples by gain
mix (Buffer, Buffer) -> Buffer Mix at unity gain
mixBuffers (Buffer, Buffer, Double, Double) -> Buffer Mix with per-source gains
fadeIn (Buffer, Double) -> Buffer Linear fade-in (seconds)
fadeOut (Buffer, Double) -> Buffer Linear fade-out (seconds)

Signal Generation

Function Signature Description
createOscillatorState (Double, Int) -> OscillatorState Oscillator state
resetPhase (OscillatorState) -> Void Reset phase
generateSine / generateSaw / generateSquare / generateTriangle (Buffer, OscillatorState, Double) -> Void Fill buffer with waveform
createSineTone / createSawTone / createSquareTone / createTriangleTone (Double, Double, Double) -> Buffer Ready-to-use tone (duration, frequency, amplitude)
oscillator (String, Array) / (String, Function) / (String, Function, Int) Register a custom wavetable oscillator

Envelopes

Function Signature Description
createAR (Double, Double, Int) -> Envelope Attack-Release envelope
createADSR (Double, Double, Double, Double, Int) -> Envelope ADSR envelope
applyEnvelope (Buffer, Envelope) -> Buffer Apply envelope shape

Effects

Function Signature Description
reverb (Buffer, Double) -> Buffer / (Buffer, Double, Double, Double) -> Buffer Reverb
lowpass / highpass (Buffer, Double) -> Buffer Filters (cutoff Hz)
bandpass (Buffer, Double, Double) -> Buffer Band-pass filter
compress (Buffer, Double, Double) -> Buffer / (Buffer, Double, Double, Double, Double) -> Buffer Compressor
sidechain (Buffer, Buffer, Double, Double) -> Buffer / (… , Double, Double) Sidechain compressor
delay (Buffer, Double, Double, Double) -> Buffer Feedback delay
gain (Buffer, Double) -> Buffer Gain (dB)
pan (Buffer, Double) -> Buffer Stereo pan (-1 .. +1)

Playback

Function Signature Description
play (Buffer) -> Void / (Sequence) -> Void Play (blocking)
stream (Buffer) -> Void / (Sequence) -> Void Play asynchronously
loop (Buffer) -> Void / (Buffer, Int) -> Void Loop indefinitely / N times
preview (Buffer) -> Void Low-quality preview
stop () -> Void Stop playback
audioDevices () -> String[] List devices
setAudioDevice (String) -> Bool Set output device
isAudioAvailable () -> Bool Check backend

WAV / MIDI I/O

Function Signature Description
exportWav (Buffer, String) -> Void / (Buffer, String, Int) -> Void Export WAV (optional bit depth)
writeWav (String, Buffer) -> Void / (String, Buffer, Int) -> Void Path-first WAV export
loadWav (String) -> Buffer Load WAV file
writeMidi (String, Song) -> Void Export Song to Standard MIDI File

Timeline and Voice

Function Signature Description
setBPM (Double) -> Void Set global BPM
getBPM () -> Double Get current BPM
beatsToFrames (Double, Int) -> Int Beats → frames
framesToBeats (Int, Int) -> Double Frames → beats
createVoice (Buffer, Double) -> Voice Voice at beat offset
setVoiceGain / setVoicePan / setVoiceOffset (Voice, Double) -> Void Voice parameters
createTrack (Int, Int) -> Track Empty track
addVoice (Track, Voice) -> Void Add voice
setTrackGain / setTrackPan / setTrackOffset (Track, Double) -> Void Track parameters
renderTrack (Track, Double) -> Buffer Render track over N beats
setMaxVoices (Int) -> Void Set polyphonic voice pool size

Vocalization

Function Signature Description
sing (String, Note, Double) -> Buffer Formant-synthesized vowel / syllable
tts (String) -> Buffer External TTS → buffer
setTtsCommand (String) -> Void Configure TTS command template

Visualization

Function Signature Description
visualize (Sequence) -> Void ASCII piano-roll
visualize (Buffer) -> Void ASCII waveform

Harmony Functions

Function Signature Description
chordNotes (Chord) -> String[] Notes in chord
chordRoot (Chord) -> String Root note
chordQuality (Chord) -> String Quality string
arpeggio (Chord, String) -> Sequence Arpeggiate ("up", "down", "updown")
scaleNotes (String) -> String[] Scale note names
resolveNumeral (String, String) -> Chord Roman numeral → chord
getSections (Song) -> String[] Section names
sectionSequences (Section) -> String[] Sequence names within a section

Transform Functions

Function Signature Description
transpose (Sequence, Semitone) -> Sequence / (Sequence, Cent) -> Sequence Shift pitch
invert (Sequence) -> Sequence Mirror intervals
retrograde (Sequence) -> Sequence Reverse note order
augment (Sequence) -> Sequence Double durations
diminish (Sequence) -> Sequence Halve durations
up / down (Sequence, Int) -> Sequence Octave shift
repeat (Sequence, Int) -> Sequence / (Sequence, Int, Semitone) -> Sequence Repeat (optionally with transposition)
concat (Sequence, Sequence) -> Sequence Join sequences
crescendo (Sequence, Double, Double) -> Sequence Rising velocity
decrescendo (Sequence, Double, Double) -> Sequence Falling velocity
swell (Sequence, Double, Double) -> Sequence Rise-then-fall
ritardando / accelerando (Sequence, Double) -> Sequence Slow-/speed-up feel
fermata (Sequence, Int) -> Sequence Hold note at index
humanize (Sequence, Double) -> Sequence Random velocity variation
trill (Sequence, Semitone) -> Sequence Rapid alternation
tremolo (Sequence, Int) -> Sequence Rapid repetition

Composition Functions

Function Signature Description
euclidean (Int, Int, Note) -> Sequence Euclidean rhythm (hits, steps, pitch)
vary (Sequence, Double) + typed / seeded / diatonic overloads Stochastic mutation
polyrhythm (Sequence, Sequence) -> Buffer / (…, Int) -> Buffer Overlay sequences with different time signatures
tempoRamp (Sequence, Double, Double) -> Buffer / (…, String) -> Buffer Render with interpolated tempo
renderSong (Song, String) -> Buffer / (Song, Function) -> Buffer Render song with synth name or lambda instrument
renderSequenceToVoices (Sequence, String, Int, Double) -> Voice[] Render sequence to voices
renderBarToVoices (Bar, String, Int, Double) -> Voice[] Render bar to voices
renderBarAtBeat (Bar, Double, String, Int, Double) -> Voice[] Render bar at beat offset
renderBarAtTime (Bar, Double, String, Int, Double) -> Voice[] Render bar at time offset

Musical Notation Functions

Function Signature Description
createMusicalNote (Note, NoteValue) -> MusicalNote Note with duration
createRest (NoteValue) -> MusicalNote Rest with duration
createTimeSignature (Int, Int) -> TimeSignature Time signature
createMusicalBar (MusicalNote[], TimeSignature) -> Bar Bar from notes
createEmptyMusicalBar (TimeSignature) -> Bar Empty bar
createSequence () -> Sequence Empty sequence
addBarToSequence (Sequence, Bar) -> Sequence Add bar to sequence
noteToFrequency (Note) -> Double Note → Hz (A4 = 440)
noteValueToBeats (NoteValue, Int) -> Double Duration → beats
validateBarDuration (Bar, TimeSignature) -> Bool Check bar fits time signature
getRemainingBeats (Bar) -> Double Remaining capacity
wouldFit (Bar, MusicalNote) -> Bool Would note fit?

Bar Functions

Function Signature Description
createBar () -> Bar Empty bar
createBarWithNote (Note) -> Bar Bar with one note
createBarFromNotes (Note[]) -> Bar Bar from array
addNoteToBar (Bar, Note) -> Void Append note
tryAddNoteToBar (Bar, MusicalNote) -> Bool Try append
getNoteFromBar (Bar, Int) -> Note Note at index
barLength (Bar) -> Int Note count
setTimeSignature (Bar, Int, Int) -> Void Set time signature
getTimeSignature (Bar) -> String Get time signature string

Song Functions

Function Signature Description
createSong (String) -> Song Empty song
addBarToSong (Song, String) -> Void / (Song, String, Int) -> Void / (Song, Sequence) -> Void Add section reference or ad-hoc sequence

See Also

Clone this wiki locally