sc-utils

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

Install

npm install --save @ircam/sc-utils

API

Table of Contents

• almostEqual
• almostEqualArray
• atodb
• counter
• dbtoa
• decibelToLinear
• decibelToPower
• delay
• exponentialScale
• frequencyToMidi
• ftom
• getTime
• hertzToNormalised
• idGenerator
• isBrowser
• isDefined
• isFunction
• isNumber
• isPlainObject
• isSequence
• isString
• isTouchDevice
• isTypedArray
• isURL
• linearScale
• linearToDecibel
• logarithmicScale
• midiToFrequency
• modulo
• mtof
• normalisedToHertz
• normalizedToTableScale
• powerToDecibel
• sleep
• tableToNormalizedScale

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)

Examples

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

Returns Function

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

isDefined

Check if the value is defined.

Parameters

• val any Value to check

Examples

import { isDefined } from '@ircam/sc-utils';
isDefined(42); // true
isDefined(undefined); // false
isDefined(); // false
isDefined(null); // true
isDefined(NaN); // true
isDefined(0); // true

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

modulo

• See: https://en.wikipedia.org/wiki/Modulo

Calculates the modulo operation with an optional offset.

Parameters

• value number The value to apply the modulo operation to.
• modulus number The modulus divisor.
• offset number Optional offset to apply before and after the modulo operation. (optional, default 0)

Examples

modulo(-1, 360); // returns 359
modulo(1, 360); // returns 1
modulo(-1, -360); // returns -1
modulo(1, -360); // returns -359

modulo(-1, 360, -180); // returns -1
modulo(1, 360, -180); // returns 1
modulo(-1, -360, 180); // returns -1
modulo(1, -360, 180); // returns 1

Returns number The result of the modulo operation adjusted by the offset. without offset: result in [0, modulus] for modulus > 0 result in [modulus, 0] for modulus < 0with offset: result in [offset, offset + modulus] for modulus > 0 result in [modulus + offset, offset] for modulus < 0

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.

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

• 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

License

BSD-3-Clause