@ircam/sc-utils NPM

sc-utils

Simple generic utilities (type check, common math functions, etc.)

Install

npm install --save @ircam/sc-utils

API

almostEqual

Checks if two numeric values are approximately equal within a given tolerance.

Parameters

value number The first value to compare.
reference number The second value to compare.
tolerance number The tolerance within which the values are considered equal. Note: tolerance must take into account the sum of all relative and absolute errors. (optional, default Number.EPSILON)

Examples

import { almostEqual } from '@ircam/sc-utils';
almostEqual(0.1 + 0.2, 0.3); // true
almostEqual(0.1 + 0.2, 1e-18); // false
almostEqual(0.1, 0.11, 0.02); // true

Returns boolean Returns true if the values are approximately equal, otherwise false.

almostEqualArray

See: almostEqual

Checks if two arrays of numeric values are approximately equal element-wise within a given tolerance.

Parameters

value Array<number> The first array to compare.
reference Array<number> The second array to compare.
tolerance number The tolerance within which the values are considered equal. Note: tolerance must take into account the sum of all relative and absolute errors. (optional, default Number.EPSILON)

Examples

import { almostEqualArray } from '@ircam/sc-utils';
almostEqualArray([0.1, 0.1 + 0.2], [0.1, 0.3]); // true

Returns boolean Returns true if the arrays have got the same size, and if every value of the same index are approximately equal. Otherwise false.

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, default 0)
to number End of the counter, included (optional, default Number.MAX_SAFE_INTEGER)
step number Increment / decrement step, if 0 returns from forever (optional, default 1)

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.

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 range
inputEnd number End value of input range
outputStart number Start value of output range
outputEnd number End value of output range
base number Base value for exponential scaling, default to 2 (optional, default 2)
clip boolean Clip output to output range, default to false (optional, default false)

Examples

const { exponentialScale } = utils;
const midiToFreq = exponentialScale(69, 81, 440, 880);
midiToFreq(57);
// > 220

frequencyToMidi

Convert a frequency in Hz to a MIDI note

Parameters

freq number Frequency to convert

Examples

import { frequencyToMidi } from '@ircam/sc-utils';
const freq = frequencyToMidi(440);
// > 69

Returns number

ftom

Convert a frequency in Hz to a MIDI note

Alias: frequencyToMidi

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);

Returns number

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 convert
sampleRate number Twice the Nyquist frequency (optional, default {})
- sampleRate.sampleRate (optional, default 2)

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 range
inputEnd number End value of input range
outputStart number Start value of output range
outputEnd number End value of output range
clip boolean Clip output to output range, default to false (optional, default false)

Examples

import { linearScale } from '@ircam/sc-utils';
const myScale = linearScale(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 range
inputEnd number End value of input range
outputStart number Start value of output range
outputEnd number End value of output range
base number Base value for logarithmic scaling, default to 2 (optional, default 2)
clip boolean Clip output to output range, default to false (optional, default false)

Examples

const { logarithmicScale } = utils;
const freqToMidi = logarithmicScale(440, 880, 69, 81);
freqToMidi(220);
// > 57

midiToFrequency

Convert a MIDI note to frequency

Parameters

midiNote number MIDI Note to convert

Examples

import { midiToFrequency } from '@ircam/sc-utils';
const freq = midiToFrequency(69);
// > 440

Returns number

mtof

Convert a MIDI note to frequency

Alias: midiToFrequency

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 convert
sampleRate number Twice the Nyquist frequency (optional, default {})
- sampleRate.sampleRate (optional, default 2)

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

transfertTable Array<number> Sequence of finite numbers to use as lookup table

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.

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

transfertTable Array<number> Sequence of finite numbers to use as lookup table

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