total-serialism
Advanced tools
A set of methods for the generation and transformation of number sequences useful in algorithmic composition
total-serialism is a set of methods used for procedurally generating and transforming number sequences. This library is mainly designed with algorithmic composition of music in mind, but can surely be useful for other purposes that involve generation and manipulation of arrays and numbers.
The library consists of a few subsets:
Generative : Basic methods that generate arrays of number sequences, such as methods that generate an ascending array of numbers evenly spread between a low and high value.Algorithmic : These are also generative methods, but are in general more complex algorithms, such as euclidean rhythm generation, lindenmayer string expansion, fibonacci sequence, pisano periods and more.Transform : Methods that transform the array in some fashion. Think of methods such as reversing, palindrome, duplicating, inversing, interleaving and more.Stochastic : Methods for procedurally generating number sequences based on various types of randomness, such as white noise (evenly distributed), rolling dice, flipping a coin and more.Translate : Translate between different notation systems. For example convert midi values to frequency, or note names to midi integers. Or use a relative semitone notation system and convert to midi. Map values in an Array to a specified scale, and output the relative values in the specified scale, root and octave.Utility : Methods necessary to run functions in the libraries above. But can also be of help in your own algorithmic processes.Set a global scale and map relative values to that scale to stay in tune
// Set the global scale used with toScale() and toMidi() methods
TL.setScale('minor_harmonic', 'c');
// Map relative numbers to a specified scale class (excluding root)
TL.toScale([0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11]);;
//=> [ 0, 0, 2, 3, 3, 5, 7, 7, 8, 8, 11, 11 ]
// Map relative numbers to a specified scale class (including root)
// output as midi value. Specify an octave (default = 'C3' = 4 => 48)
TL.toMidi([0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11], 4);;
//=> [ 48, 48, 50, 51, 51, 53, 55, 55, 56, 56, 59, 59 ]
Generate Lindenmayer system sequences
// Cantor set as 0's and 1's in an array ruleset
Algo.linden(1, 3, {1: [1, 0, 1], 0: [0, 0, 0]});
//=> [ 1, 0, 1, 0, 0, 0, 1, 0, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 0, 1, 0, 0, 0, 1, 0, 1 ]
Pick random values from an urn filled with a range of integers
// with default range 0 to 12 (exclusive), influenced by the random seed
Rand.urn(5);
//=> [ 3, 6, 2, 8, 7 ]
Generate Pisano periods from Fibonacci sequences
Algo.pisano(7);
//=> [ 0, 1, 1, 2, 3, 5, 1, 6, 0, 6, 6, 5, 4, 2, 6, 1 ]
Get fibonacci values as strings (to preserve the big numbers)
Algo.fibonacci(2, 100);
//=> [ '354224848179261915075', '573147844013817084101' ]
$ npm install total-serialism
The entire library
const Serialism = require('total-serialism');
Or an individual section
const Gen = require('total-serialism').Generative;
const Algo = require('total-serialism').Algorithmic;
const Mod = require('total-serialism').Transform;
const Rand = require('total-serialism').Stochastic;
const Util = require('total-serialism').Utility;
const Gen = require('total-serialism').Generative;
// generate an array of 7 ints between range 0-7
Gen.spread(7);
//=> [ 0, 1, 2, 3, 4, 5, 6 ]
// generate an array of 5 ints between range 7-19 (19 inclusive)
Gen.spreadInclusive(5, 7, 19);
//=> [ 7, 9, 11, 14, 16 ]
// generate an array of 9 floats between -1 - 1 (inclusive)
Gen.spreadInclusiveFloat(9, -1, 1);
//=> [ -1, -0.75, -0.5, -0.25, 0, 0.25, 0.5, 0.75, 1 ]
// fill an array with duplicates of a value
Gen.fill(10, 2, 15, 3, 20, 4);
//=> [ 10, 10, 15, 15, 15, 20, 20, 20, 20 ]
// generate 10 ints with 1 period of a sine function
// between a default range of 0-12
Gen.sine(10);
//=> [ 6, 9, 11, 11, 9, 6, 2, 0, 0, 2 ]
// generate 10 ints with 4 periods a sine function
Gen.sine(11, 4, 0, 7);
//=> [ 3, 6, 0, 5, 4, 0, 6, 2, 1, 6, 0 ]
// generate 7 ints of 1.5 period a cosine function
Gen.cosine(7, 1.5);
//=> [ 12, 7, 0, 2, 9, 11, 4 ]
// generate 8 floats with 1 period of a cosine function
Gen.cosineFloat(8);
//=> [ 1, 0.707, 0.000, -0.707, -1, -0.707, -0.000, 0.707 ]
const Algo = require('total-serialism').Algorithmic;
// generate a euclidean rhythm evenly spacing n-beats amongst n-steps
// inspired by Godfried Toussaints famous paper "The Euclidean
// Algorithm Generates Traditional Musical Rhythms"
Algo.euclid(16, 9, 1);
//=> [ 0, 1, 0, 1, 0, 1, 0, 1, 1, 0, 1, 0, 1, 0, 1, 1 ]
// generate a hexadecimal rhythm based on a hexadecimal string (0-f)
// inspired by Steven Yi's implementation in CSound Live Coding
Algo.hexBeat('a9d2');
//=> [ 1, 0, 1, 0, 1, 0, 0, 1, 1, 1, 0, 1, 0, 0, 1, 0 ]
The original Lindenmayer string expansion returns a string of characters based on a set of rules and an axiom specified as strings.
// Koch curve
Algo.linden('F', 2, {F: 'F+F-F-F+F'});
//=> 'F+F-F-F+F+F+F-F-F+F-F+F-F-F+F-F+F-F-F+F+F+F-F-F+F'
// Cantor set
Algo.linden('A', 3, {A: 'ABA', B: 'BBB'});
//=> 'ABABBBABABBBBBBBBBABABBBABA'
// Sierpinski Triangle
Algo.linden('F-G-G', 1, {'F': 'F−G+F+G−F', 'G' : 'GG'});
//=> 'F−G+F+G−F-GG-GG'
A more useful version that works nicely with the rest of library. By returning an array of integers it can be quickly put to use in combination with other methods and generate rhythms, melodies and more based on custom rulesets.
Algo.linden();
//=> [ 1, 0, 1, 1, 0 ] (default)
// Cantor set as 0's and 1's in an array ruleset
Algo.linden(1, 3, {1: [1, 0, 1], 0: [0, 0, 0]});
//=> [ 1, 0, 1, 0, 0, 0, 1, 0, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 0, 1, 0, 0, 0, 1, 0, 1 ]
// Set more complex rules for generating semitones for example
var complexRules = {
0: [0, 3, 7],
3: [-1, 0],
7: [12, 19, 0],
12: [12, 0, 0, 5],
5: [0, -3, 0]
}
Algo.linden(0, 2, complexRules);
//=> [ 0, 3, 7, -1, 0, 12, 19, 0, -1, 0, 3, 7, 12, 0, 0, 5, 19, 0, 3, 7 ]
Generate an array of Fibonacci numbers F[n] = F[n-1] + F[n-2]. Numbers are by default represented as Strings in order to allow for bigger numbers than 64-bit integers can represent. The calculations are done using the bignumber.js library. A second argument sets an offset to pick a certain number from the sequence.
// 10 fibonacci numbers, starting from 0, 1, 1 etc...
Algo.fibonacci(12);
//=> [ '0', '1', '1', '2', '3', '5', '8', '13', '21', '34', '55', '89' ]
// 2 fibonacci numbers, starting from the 100th value
Algo.fibonacci(2, 100);
//=> [ '354224848179261915075', '573147844013817084101' ]
Generate Pisano periods for the Fibonacci sequence. The pisano period is a result of applying a modulo operation on the Fibonacci sequence F[n] = (F[n-1] + F[n-2]) mod a. The length of the period differs per modulus value, but the sequence will always have a repetition.
// the pisano period for mod 7 has a length of 16
Algo.pisano(7);
//=> [ 0, 1, 1, 2, 3, 5, 1, 6, 0, 6, 6, 5, 4, 2, 6, 1 ]
// second argument gives a fixed length output
Algo.pisano(4, 10);
//=> [ 0, 1, 1, 2, 3, 1, 0, 1, 1, 2, 3, 1 ]
Other integer sequences based on Fibonacci are also available
Algo.pell(10);
//=> [ '0', '1', '2', '5', '12', '29', '70', '169', '408', '985' ]
Algo.threeFibonacci(10);
//=> [ '0', '1', '3', '10', '33', '109', '360', '1189', '3927', '12970' ]
Algo.lucas(10);
//=> [ '2', '1', '3', '4', '7', '11', '18', '29', '47', '76' ]
Set a custom starting pair of numbers to generate an n-bonacci sequence according to the following method: F[n] = t * F[n-1] + F[n-2]
// start with 1, 3, then multiply [n-1] by 2 before adding with [n-2]
Algo.nbonacci(10, 1, 3, 2);
//=> [ '1', '3', '7', '17', '41', '99', '239', '577', '1393', '3363' ]
// this is the same as Algo.fibonacci(10)
Algo.nbonacci(10, 0, 1, 1);
//=> [ '0', '1', '1', '2', '3', '5', '8', '13', '21', '34' ]
const Rand = require('total-serialism').Stochastic;
// set the random number generator seed
Rand.seed(19374);
// generate an array of random floats in range -1 to 1
Rand.randomFloat(3, -1, 1);
//=> [ 0.6291111850577886, 0.15153786227276944, 0.32814801081039646 ]
// generate an array of random integers in range
Rand.random(5, 0, 12);
//=> [ 3, 3, 7, 1, 0 ]
// generate an array of coin tosses
Rand.coin(10);
//=> [ 0, 1, 0, 1, 0, 1, 0, 0, 1, 0 ]
// generate an array of dice rolls
Rand.dice(4);
//=> [ 4, 4, 2, 3 ]
// shuffle the items in an array, influenced by the random seed
Rand.shuffle([0, 5, 7, 12]);
//=> [ 7, 5, 0, 12 ]
// generate a twelve-tone series, influenced by the random seed
// basically the same as: Mod.shuffle(Gen.spread(12));
Rand.twelveTone();
//=> [ 11, 0, 8, 2, 4, 9, 1, 6, 3, 5, 7, 10 ]
// generate an array with random values picked from an urn
// with default range 0 to 12 (exclusive)
Rand.urn(5);
//=> [ 3, 6, 2, 8, 7 ]
// set the range with a second argument to 0-7 (exclusive)
// when more values then range are requested the urn
// refills and reshuffles
Rand.urn(10, 7);
//=> [ 6, 4, 3, 2, 0, 5, 1, 4, 2, 1 ]
// A third argument sets a lower range replacing the default 0
Rand.urn(12, -3, 3);
//=> [ -3, 1, -1, 2, 0, -2, 2, -2, 0, -1, -3, 1 ]
// Choose random items from an array provided, uniform distribution
Rand.choose(5, [0, 1, 2, 3, 5, 8, 13]);
//=> [ 3, 0, 13, 3, 2 ]
// Array can have any datatype
Rand.choose(5, ['c', 'e', 'g']);
//=> [ 'c', 'c', 'g', 'e', 'g' ]
// Pick random items from an array similar to urn
// no repeating values untill urn is empty
Rand.pick(5, [0, 1, 2, 3, 5, 8, 13]);
//=> [ 2, 5, 8, 1, 3 ]
// Array can have any datatype
Rand.pick(5, ['c', 'e', ['g', 'd']]);
//=> [ 'e', [ 'g', 'd' ], 'c', [ 'g', 'd' ], 'e' ]
const Mod = require('total-serialism').Transform;
// duplicate an array with an offset added to every value
Mod.clone([0, 5, 7], 0, 12, -12);
//=> [ 0, 5, 7, 12, 17, 19, -12, -7, -5 ]
// combine multiple numbers/arrays into one
Mod.combine([0, 5], 12, [7, 3]);
//=> [ 0, 5, 12, 7, 3 ]
// duplicate an array certain amount of times
Mod.duplicate([0, 5, 7], 3);
//=> [ 0, 5, 7, 0, 5, 7, 0, 5, 7 ]
// add zeroes to a rhythm to make it play once over a certain amount of bars
Mod.every([1, 0, 1, 0, 1, 1, 0, 1], 2, 8));
//=> [ 1, 0, 1, 0, 1, 1, 0, 1, 0, 0, 0, 0, 0, 0, 0, 0 ]
// invert an array around a center point
Mod.invert([0, 2, 5, 10, 13], 5);
//=> [ 10, 8, 5, 0, -3 ]
// interleave multiple arrays into one
Mod.lace([0, 5, 9], [3, 3], [7, 12, 11, -1]);
//=> [ 0, 3, 7, 5, 3, 12, 9, 11, -1 ]
// merge arrays into a 2D-array
Mod.merge([0, 3, 7], [3, 12], [12, -1, 19, 5]);
//=> [ [0, 3, 12], [3, 12, -1], [7, 19], [5] ]
// generate a palindrome of an array
Mod.palindrome([0, 3, 5, 7]);
//=> [ 0, 3, 5, 7, 7, 5, 3, 0 ]
// rotate an array in positive or negative direction
Mod.rotate([0, 5, 7, 12], -1);
//=> [ 5, 7, 12, 0 ]
// reverse an array
Mod.reverse([0, 5, 7, 12]);
//=> [ 12, 7, 5, 0 ]
// spray values from one array on the non-zero places of another array
Mod.spray([12, 19, 24], [1, 0, 0, 1, 1, 0, 1, 0.3, 0]);
//=> [ 12, 0, 0, 19, 24, 0, 12, 19, 0 ]
// remove duplicates from an array, leave order of appearance intact
Mod.unique([5, 7, 5, 0, 12, 7, 5]);
//=> [ 5, 7, 0, 12 ]
const TL = require('total-serialism').Translate;
// Convert Array or Int as midi-number to midi-notenames
TL.midiToNote([60, 67, 70]);
//=> [ 'C4', 'G4', 'Bb4' ]
// alternative: TL.mton()
// Convert Array of String as midi-notenames to midi-pitch
TL.noteToMidi(['c2','d2','f#2']);
//=> [ 36, 38, 42 ]
// alternative: TL.ntom()
// Convert midi-pitches to frequency (A4 = 440 Hz)
TL.midiToFrequency([60, 67, 72]);
//=> [ 261.6255653005986, 391.99543598174927, 523.2511306011972 ]
// alternative: TL.mtof()
// Convert midi-notenames to frequency (A4 = 440 Hz)
TL.noteToFreq(['c2','d2','f#2']);
//=> [ 65.40639132514966, 73.41619197935188, 92.4986056779086 ]
// alternative: TL.ntof()
// Convert relative semitone values to midi-numbers
// specify the octave as second argument (default = 'C3' = 4 => 48)
TL.relativeToMidi([-12, 0, 7, 12], 4);
//=> [ 36, 48, 55, 60 ]
// alternative: TL.rtom()
// Convert relative semitone values to frequency (A4 = 440 Hz)
// specify the octave as second argument (default = 'C3' = 4 => 48)
TL.rtof([-12, 0, 7, 12], 4);
//=> [ 65.40639132514966,
// 130.8127826502993,
// 195.99771799087463,
// 261.6255653005986 ]
// Set the global scale used with toScale() and toMidi() methods
TL.setScale('minor_harmonic', 'a');
// Set only the root for the global scale
TL.setRoot('c');
// Return all the specified settings
TL.getSettings();
//=> { scale: 'minor_harmonic',
// root: 'Db',
// rootInt: 1,
// map: [ 0, 0, 2, 3, 3, 5, 7, 7, 8, 8, 11, 11 ],
// bpm: 110,
// measureInMs: 2181.818181818182 }
// Return all the available scale names
TL.scaleNames();
//=> [ 'chromatic', 'major', etc... ]
// Map relative numbers to a specified scale class (excluding root)
TL.toScale([0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11]);;
//=> [ 0, 0, 2, 3, 3, 5, 7, 7, 8, 8, 11, 11 ]
// Works with negative relative values
TL.toScale([8, 14, -2, 22, -7, 22, -2, 14]);
//=> [ 8, 14, -1, 23, -7, 23, -1, 14 ]
// Preserves floating point for detune/microtonality
TL.toScale([0, 4.1, 6.5, 7.1, 9.25]);
//=> [ 0, 3.1, 7.5, 7.1, 8.25 ]
// Map relative numbers to a specified scale class (including root)
// output as midi value. Specify an octave (default = 'C3' = 4 => 48)
TL.toMidi([0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11], 4);;
//=> [ 48, 48, 50, 51, 51, 53, 55, 55, 56, 56, 59, 59 ]
// Works with negative relative values
TL.toMidi([8, 14, -2, 22, -7, 22, -2, 14], 4);
//=> [ 56, 62, 47, 71, 41, 71, 47, 62 ]
// Preserves floating point for detune/microtonality
TL.toMidi([0, 4.1, 6.5, 7.1, 9.25], 'c3');
//=> [ 48, 51.1, 55.5, 55.1, 56.25 ]
This library is inspired by the composition techniques named Serialism and Total Serialism. The technique approaches the parameters that make up a piece of music as individual series of values. These parameters are (but not limited to) pitch, duration/rhythm and velocity/dynamic.
Serialism originated from the twelve-tone technique, described in 1919 by Josef Hauer in his published work "Law of the twelve tones". This technique starts out with a randomly ordered set of the twelve chromatic notes. From there on out you can apply transformations on this set, such as reverse/retrograde, inverse, transpose, and combinations between those.
For many of the functions programmed much inspiration was gained from Laurie Spiegels paper on "Manipulation of Musical Patterns" (1981) in which she suggests to "extract a basic "library" consisting of the most elemental transformations which have consistently been successfully used on musical patterns, a basic group of "tried-and-true" musical manipulations."
The euclidean rhythm generator was inspired by the famous paper by Godfried Toussaint and the hexadecimal rhythm generator was inspired by Steven Yi's implementation in the CSound livecoding environment and a workshop given by him during the ICLC 2020 in Limerick.
Inspiration for the sequencing also came from the Live Coding scene and current programming languages available such as Tidal, Extempore, SonicPi and more. In Live Coding the Serialism technique is very common when programming music. In many cases the rhythms, melodies, and other musical expressions are expressed in arrays that are iterated based on the timing of the system.
The inspiration for usage of Integer Sequences came from composers such as Iannis Xenakis, who used the fibonacci formula in his piece Nomos Alpha and referred to the technique as Fibonacci Motion. Also Xenakis referred to the usuage of set theory for composition as Symbolic Music.
Nick Collins - Algorithmic Composition Methods for Breakbeat Science
Alex McLean - Tidal Pattern Language for Live Coding of Music
Godfried Toussaint - The Euclidean Algorithm Generates Traditional Musical Rhythms
Iannis Xenakis - Formalized Music, Thought and Mathematics in Music
Thomas DeLio - Nomos Alpha: The Dialects of Structure and Materials
This library is a work in progress, and I'm always interested to receive inspiration, suggestions, enhancements, literature and more. Feel free to file an issue here and I will gladly look into it!
The MIT License
Copyright (c) 2020 Timo Hoogland
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
FAQs
A set of methods for the generation and transformation of number sequences useful in algorithmic composition
The npm package total-serialism receives a total of 177 weekly downloads. As such, total-serialism popularity was classified as not popular.
We found that total-serialism demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
PEP 770 proposes adding SBOM support to Python packages to improve transparency and catch hidden non-Python dependencies that security tools often miss.
Security News
Socket CEO Feross Aboukhadijeh discusses open source security challenges, including zero-day attacks and supply chain risks, on the Cyber Security Council podcast.
Security News
Research
Socket researchers uncover how threat actors weaponize Out-of-Band Application Security Testing (OAST) techniques across the npm, PyPI, and RubyGems ecosystems to exfiltrate sensitive data.