Properties are how we configure the behaviour of audio nodes: things like an oscillator's frequency or a filter's cutoff.
import WebAudio
import WebAudio.Property
myOsc =
WebAudio.oscillator
[ WebAudio.Property.linearRampToValueAtTime 1 <|
WebAudio.Property.frequency 880
, WebAudio.Property.type_ "sine"
]
[ WebAudio.gain
[ WebAudio.Property.gain 0.5 ]
[ WebAudio.audioDestination ]
]
This example showcases the different types of properties you can construct:
properties
like type_
. These are typical object
properties that are set on the node like any other JavaScript object, and
might be a bool
, float
, string
, etc.
audioParams
like frequency
are special,
and represent values that can be changed over time using the scheduled updates
described below. These are always Float
s!
Scheduled updates like linearRampToValueAtTime
.
These describe how a property should change over time. These scheduled updates
only work with audio params, and not normal properties.
Represents a value of some property. Our audio graphs are supposed to be declarative, so we don't want to be able to change the values of properties – you'd just return a different graph with the property you wanted changed.
This type enumerates the different types of values that might be assigned to
a property like an Elm String
or Float
, etc.
property : String -> Value -> Property
Create a custom property for a node. This is like writing node.type = 'sine'
in JavaScript:
import WebAudio.Property exposing (Property)
sine : Property
sine =
WebAudio.Property.property "type" (WebAudio.Property.string "sine")
Ideally you'll end up using one of the predifined properties like type_
instead of this function, but it's provided in case you have custom audio nodes
with properties we might not know about.
audioParam : String -> Basics.Float -> Property
Create a custom audio param for a node. This is like writing
node.frequency.value = 880
in JavaScript:
import WebAudio.Property exposing (Property)
middleA : Property
middleA =
WebAudio.Property.audioParam "frequency" 440
Ideally you'll end up using one of the predifined properties like
frequency
instead of this function, but it's provided in case you
have custom audio nodes with properties we might not know about.
setValueAtTime : Basics.Float -> Property -> Property
Schedule an update to a property to take place at some point in the future.
This is like writing node.frequency.setValueAtTime(880, context.currentTime + 1)
in JavaScript:
import WebAudio.Property exposing (Property)
setAfterOneSecond : Float -> Property
setAfterOneSecond time =
WebAudio.Property.setValueAtTime
(time + 1)
(WebAudio.Property.frequency 880)
❗️ Note that we're taking in a Float
here for the current time, and using that
to calculate the time at which we want to set the value. Because our audio graphs
are declarative we don't schedule things from now, but rather we schedule
things for fixed, known values of time.
The best way to get the current time is to use every
or at
to trigger a message carrying the context's
current time. If you want to trigger things to happen based on the time a
particular user event such as a click occured you can use
currentTime
to get the current time from the
context.
import WebAudio
import WebAudio.Context exposing (Context)
import WebAudio.Property
type Event
= NoteOn Float
| ...
audio : Context -> Event -> List WebAudio.Node
audio context event =
case event of
NoteOn time ->
[ WebAudio.oscillator
-- See the docs further down for what
-- `linearRampToValueAtTime` does!
[ WebAudio.Property.linearRampToValueAtTime
(WebAudio.Context.currentTime context + 1)
(WebAudio.Property.frequency 880)
]
[ WebAudio.gain
[ WebAudio.Property.gain 0.5 ]
[ WebAudio.audioDestination ]
]
]
_ ->
...
Be really careful when doing this, you can accidentally schedule a bunch of overlapping events if you're not paying attention!
linearRampToValueAtTime : Basics.Float -> Property -> Property
Where setValueAtTime
sets a property at a specific time,
linearRampToValueAtTime
will smoothly ramp the property from its current value
to the target value until the given time.
exponentialRampToValueAtTime : Basics.Float -> Property -> Property
Where setValueAtTime
sets a property at a specific time,
exponentialRampToValueAtTime
will ramp the property from its current value
to the target value until the given time using an exponential curve.
Often we perceive exponential curves as more natural than linear curves, so this is a good choice for things like gain or frequency.
bool : Basics.Bool -> Value
float : Basics.Float -> Value
floatList : List Basics.Float -> Value
int : Basics.Int -> Value
string : String -> Value
amp : Basics.Float -> Property
attack : Basics.Float -> Property
coneInnerAngle : Basics.Float -> Property
coneOuterAngle : Basics.Float -> Property
coneOuterGain : Basics.Float -> Property
curve : List Basics.Float -> Property
delayTime : Basics.Float -> Property
detune : Basics.Float -> Property
distanceModel : String -> Property
fftSize : Basics.Int -> Property
frequency : Basics.Float -> Property
freq : Basics.Float -> Property
gain : Basics.Float -> Property
knee : Basics.Float -> Property
loop : Basics.Bool -> Property
loopEnd : Basics.Float -> Property
loopStart : Basics.Float -> Property
maxChannelCount : Basics.Int -> Property
maxDecibels : Basics.Float -> Property
minDecibels : Basics.Float -> Property
normalize : Basics.Bool -> Property
normalise : Basics.Bool -> Property
offset : Basics.Float -> Property
orientationX : Basics.Float -> Property
orientationY : Basics.Float -> Property
orientationZ : Basics.Float -> Property
oversample : String -> Property
pan : Basics.Float -> Property
panningModel : String -> Property
playbackRate : Basics.Float -> Property
positionX : Basics.Float -> Property
positionY : Basics.Float -> Property
positionZ : Basics.Float -> Property
q : Basics.Float -> Property
ratio : Basics.Float -> Property
reduction : Basics.Float -> Property
refDistance : Basics.Float -> Property
release : Basics.Float -> Property
rolloffFactor : Basics.Float -> Property
smoothingTimeConstant : Basics.Float -> Property
threshold : Basics.Float -> Property
type_ : String -> Property
encode : Property -> Json.Encode.Value