@ircam/sc-utils
v1.8.1
Published
Set of simple generic utilities (type check, common math functions, etc.)
Downloads
219
Readme
sc-utils
Simple generic utilities (type check, common math functions, etc.)
Install
npm install --save @ircam/sc-utils
API
Table of Contents
- atodb
- counter
- dbtoa
- decibelToLinear
- decibelToPower
- delay
- exponentialScale
- ftom
- getTime
- hertzToNormalised
- idGenerator
- isBrowser
- isFunction
- isNumber
- isPlainObject
- isSequence
- isString
- isTouchDevice
- isTypedArray
- isURL
- linearScale
- linearToDecibel
- logarithmicScale
- mtof
- normalisedToHertz
- normalizedToTableScale
- powerToDecibel
- sleep
- tableToNormalizedScale
atodb
Convert a linear gain into dB
Alias: linearToDecibel
Parameters
val
number Value to convert
Examples
import { atodb } from '@ircam/sc-utils';
atodb(0);
// > 1
Returns number
counter
Create a counter function.
Parameters
from
number Start of the counter, included (optional, default0
)to
number End of the counter, included (optional, defaultNumber.MAX_SAFE_INTEGER
)step
number Increment / decrement step, if 0 returnsfrom
forever (optional, default1
)
Returns Function import { counter } from '@ircam/sc-utils'; const myCounter = counter(0.1, 0.3, 0.1); counter(); // 0.1 counter(); // 0.2 counter(); // 0.3 counter(); // 0.1 // ...
dbtoa
Convert a dB into linear gain
Alias: decibelToLinear
Parameters
val
number Value to convert
Examples
import { dbtoa } from '@ircam/sc-utils';
dbtoa(0);
// > 1
Returns number
decibelToLinear
Convert a dB into linear gain (i.e. gain)
Alias: dbtoa
Parameters
val
number Value to convert
Examples
import { decibelToLinear } from '@ircam/sc-utils';
decibelToLinear(0);
// > 1
Returns number
decibelToPower
Convert a dB into power gain
Parameters
val
number Value to convert
Examples
import { decibelToPower } from '@ircam/sc-utils';
decibelToPower(0);
// > 1
Returns number
delay
Wait for a given number of milliseconds.
See also sleep
Parameters
ms
Number Number of milliseconds to wait
Examples
import { delay } from '@ircam/sc-utils';
// wait for 1 second
await delay(1000);
Returns Promise
exponentialScale
Create an exponential scale function.
Parameters
inputStart
number Start value of input rangeinputEnd
number End value of input rangeoutputStart
number Start value of output rangeoutputEnd
number End value of output rangebase
number Base value for exponential scaling, default to2
(optional, default2
)clip
boolean Clip output to output range, default tofalse
(optional, defaultfalse
)
Examples
const { exponentialScale } = utils;
const midiToFreq = exponentialScale(69, 81, 440, 880);
midiToFreq(57);
// > 220
ftom
Convert a frequency in Hz to a MIDI note
Parameters
freq
number Frequency to convert
Examples
import { ftom } from '@ircam/sc-utils';
const freq = ftom(440);
// > 69
Returns number
getTime
Provide a unified clock in seconds accross platforms, with an origin defined by the start of the process.
Examples
import { getTime } from '@ircam/sc-utils';
setInterval(() => {
const now = getTime();
// ...
}, 1000);
hertzToNormalised
Convert a frequency in Hertz to a normalised one in [0, 1].
Normalised frequency of 1 is half the sample-rate (Nyquist frequency).
Parameters
frequencyHertz
number Frequency in Hertz to convertsampleRate
number Twice the Nyquist frequency (optional, default{}
)sampleRate.sampleRate
(optional, default2
)
Examples
import { hertzToNormalised } from '@ircam/sc-utils';
hertzToNormalised(12000, {sampleRate: 48000});
// > 0.5
Returns number
idGenerator
Create a iterator of incrementing ids
DEPRECATED Use the more generic and user friendly counter
instead.
Examples
import { idGenerator } from '@ircam/sc-utils';
const generator = idGenerator();
const id = generator.next().value
Returns Iterator
isBrowser
Check if the platform is a browser or a node process
Examples
import { isBrowser } from '@ircam/sc-utils';
isBrowser();
// > true|false
Returns boolean
isFunction
Check if the value is a function
Parameters
val
any Value to check
Examples
import { isFunction } from '@ircam/sc-utils';
isFunction(() => {});
// > true
Returns boolean
isNumber
Check if the value is a number, including Infinity. If you want to excluse Infinity, check the native Number.isFinite function
Parameters
val
any Value to check
Examples
import { isNumber } from '@ircam/sc-utils';
isNumber(42);
// > true
Returns boolean
isPlainObject
Check if the value is a Plain Old Javascript Object (POJO)
Parameters
val
any Value to check
Examples
import { isPlainObject } from '@ircam/sc-utils';
isPlainObject({ a: 1 });
// > true
Returns boolean
isSequence
Check if the value is a sequence (Array
or TypedArray
) of finite numbers
Parameters
val
any Value to check
Examples
import { isSequence } from '@ircam/sc-utils';
isSequence([1, 2, 3]);
// > true
Returns boolean
isString
Check if the value is a string
Parameters
val
any Value to check
Examples
import { isString } from '@ircam/sc-utils';
isString('test');
// > true
Returns boolean
isTouchDevice
Check if the device supports touch events
Examples
import { isTouchDevice } from '@ircam/sc-utils';
isTouchDevice();
// > true|false
Returns boolean
isTypedArray
Check if the value is a TypedArray
Parameters
val
any Value to check
Examples
import { isTypedArray } from '@ircam/sc-utils';
isTypedArray(new Float32Array([1, 2, 3]));
// > true
Returns boolean
isURL
Check if the value is a valid URL
Parameters
url
val
any Value to check
Examples
import { isURL } from '@ircam/sc-utils';
isURL('http://sub.my-site.org/abcd?test=123');
// > true
Returns boolean
linearScale
Create a linear scale function.
Parameters
inputStart
number Start value of input rangeinputEnd
number End value of input rangeoutputStart
number Start value of output rangeoutputEnd
number End value of output rangeclip
boolean Clip output to output range, default tofalse
(optional, defaultfalse
)
Examples
import { scale } from '@ircam/sc-utils';
const myScale = scale(0, 1, 50, 100);
myScale(0.5);
// > 75
Returns Function
linearToDecibel
Convert a linear gain into dB
Alias: atodb
Parameters
val
number Value to convert
Examples
import { decibelToPower } from '@ircam/sc-utils';
decibelToPower(0);
// > 1
Returns number
logarithmicScale
Create a logarithmic scale function.
Parameters
inputStart
number Start value of input rangeinputEnd
number End value of input rangeoutputStart
number Start value of output rangeoutputEnd
number End value of output rangebase
number Base value for logarithmic scaling, default to2
(optional, default2
)clip
boolean Clip output to output range, default tofalse
(optional, defaultfalse
)
Examples
const { logarithmicScale } = utils;
const freqToMidi = logarithmicScale(440, 880, 69, 81);
freqToMidi(220);
// > 57
mtof
Convert a MIDI note to frequency
Parameters
midiNote
number MIDI Note to convert
Examples
import { mtof } from '@ircam/sc-utils';
const freq = mtof(69);
// > 440
Returns number
normalisedToHertz
Convert a normalised frequency, in [0, 1], to a frequency in Hertz.
Normalised frequency of 1 is half the sample-rate (Nyquist frequency).
Parameters
frequencyNormalised
number Normalised frequency to convertsampleRate
number Twice the Nyquist frequency (optional, default{}
)sampleRate.sampleRate
(optional, default2
)
Examples
import { normalisedToHertz } from '@ircam/sc-utils';
normalisedToHertz(0.5, {sampleRate: 48000});
// > 12000
Returns number
normalizedToTableScale
Create a scale function that returns a linearly interpolated value from the given transfert table according to the given normalized position.
Parameters
Examples
import { normalizedToTableScale } from '@ircam/sc-utils'
const scale = normalizedToTableScale([1, 2, 4])
scale(0); // 1
scale(0.25); // 1.5
scale(0.5); // 2
scale(0.75); // 3
scale(1); // 4
Returns function
powerToDecibel
Convert a linear gain into dB
Parameters
val
number Value to convert
Examples
import { decibelToPower } from '@ircam/sc-utils';
decibelToPower(0);
// > 1
Returns number
sleep
Wait for a given number of seconds.
See also delay
Parameters
sec
Number Number of seconds to wait
Examples
import { sleep } from '@ircam/sc-utils';
// wait for 1 second
await sleep(1);
Returns Promise
tableToNormalizedScale
Create a scale function that returns a normalized position in the transfert table according to the given value.
Parameters
Examples
import { tableToNormalized } from '@ircam/sc-utils'
const scale = tableToNormalized([1, 2, 4])
scale(1); // 0
scale(1.5); // 0.25
scale(2); // 0.5
scale(3); // 0.75
scale(4); // 1
Returns function