tone 14.8.27

package/Tone/event/Pattern.ts

@@ -0,0 +1,121 @@
+import { Loop, LoopOptions } from "./Loop";
+import { PatternGenerator, PatternName } from "./PatternGenerator";
+import { ToneEventCallback } from "./ToneEvent";
+import { optionsFromArguments } from "../core/util/Defaults";
+import { Seconds } from "../core/type/Units";
+import { noOp } from "../core/util/Interface";
+
+export interface PatternOptions<ValueType> extends LoopOptions {
+	pattern: PatternName;
+	values: ValueType[];
+	callback: (time: Seconds, value?: ValueType) => void;
+}
+
+/**
+ * Pattern arpeggiates between the given notes
+ * in a number of patterns. 
+ * @example
+ * const pattern = new Tone.Pattern((time, note) => {
+ * 	// the order of the notes passed in depends on the pattern
+ * }, ["C2", "D4", "E5", "A6"], "upDown");
+ * @category Event
+ */
+export class Pattern<ValueType> extends Loop<PatternOptions<ValueType>> {
+
+	readonly name: string = "Pattern";
+
+	/**
+	 * The pattern generator function
+	 */
+	private _pattern: Iterator<ValueType>;
+
+	/**
+	 * The current value
+	 */
+	private _value?: ValueType;
+
+	/**
+	 * Hold the pattern type
+	 */
+	private _type: PatternName;
+
+	/**
+	 * Hold the values
+	 */
+	private _values: ValueType[];
+
+	/**
+	 * The callback to be invoked at a regular interval
+	 */
+	callback: (time: Seconds, value?: ValueType) => void;
+
+	/**
+	 * @param  callback The callback to invoke with the event.
+	 * @param  values The values to arpeggiate over.
+	 * @param  pattern  The name of the pattern
+	 */
+	constructor(
+		callback?: ToneEventCallback<ValueType>,
+		values?: ValueType[],
+		pattern?: PatternName,
+	);
+	constructor(options?: Partial<PatternOptions<ValueType>>);
+	constructor() {
+
+		super(optionsFromArguments(Pattern.getDefaults(), arguments, ["callback", "values", "pattern"]));
+		const options = optionsFromArguments(Pattern.getDefaults(), arguments, ["callback", "values", "pattern"]);
+
+		this.callback = options.callback;
+		this._values = options.values;
+		this._pattern = PatternGenerator(options.values, options.pattern);
+		this._type = options.pattern;
+	}
+
+	static getDefaults(): PatternOptions<any> {
+		return Object.assign(Loop.getDefaults(), {
+			pattern: "up" as "up",
+			values: [],
+			callback: noOp,
+		});
+	}
+
+	/**
+	 * Internal function called when the notes should be called
+	 */
+	protected _tick(time: Seconds): void {
+		const value = this._pattern.next() as IteratorResult<ValueType>;
+		this._value = value.value;
+		this.callback(time, this._value);
+	}
+
+	/**
+	 * The array of events.
+	 */
+	get values(): ValueType[] {
+		return this._values;
+	}
+	set values(val) {
+		this._values = val;
+		// reset the pattern
+		this.pattern = this._type;
+	}
+
+	/**
+	 * The current value of the pattern.
+	 */
+	get value(): ValueType | undefined {
+		return this._value;
+	}
+
+	/**
+	 * The pattern type. See Tone.CtrlPattern for the full list of patterns.
+	 */
+	get pattern(): PatternName {
+		return this._type;
+	}
+	set pattern(pattern) {
+		this._type = pattern;
+		this._pattern = PatternGenerator(this._values, this._type);
+	}
+}
+

package/Tone/event/PatternGenerator.test.ts

@@ -0,0 +1,95 @@
+import { expect } from "chai";
+import { PatternGenerator } from "./PatternGenerator";
+
+describe("PatternGenerator", () => {
+
+	function getArrayValues(gen: Iterator<any>, length: number): any[] {
+		const ret: any[] = [];
+		for (let i = 0; i < length; i++) {
+			ret.push(gen.next().value);
+		}
+		return ret;
+	}
+
+	context("API", () => {
+
+		it("can be constructed with an array and type", () => {
+			const pattern = PatternGenerator([0, 1, 2, 3], "down");
+			expect(getArrayValues(pattern, 10)).to.deep.equal([3, 2, 1, 0, 3, 2, 1, 0, 3, 2]);
+		});
+
+		it("can be resized smaller when the index is after the previous length", () => {
+			const values = [0, 1, 2, 3, 4];
+			const pattern = PatternGenerator(values);
+			expect(pattern.next().value).to.equal(0);
+			values.shift();
+			expect(pattern.next().value).to.equal(2);
+		});
+
+		it("throws an error with an empty array", () => {
+			expect(() => {
+				const pattern = PatternGenerator([]);
+				pattern.next();
+			}).to.throw(Error);
+		});
+	});
+
+	context("Patterns", () => {
+
+		it("does the up pattern", () => {
+			const pattern = PatternGenerator([0, 1, 2, 3], "up");
+			expect(getArrayValues(pattern, 6)).to.deep.equal([0, 1, 2, 3, 0, 1]);
+		});
+
+		it("does the down pattern", () => {
+			const pattern = PatternGenerator([0, 1, 2, 3], "down");
+			expect(getArrayValues(pattern, 6)).to.deep.equal([3, 2, 1, 0, 3, 2]);
+		});
+
+		it("does the upDown pattern", () => {
+			const pattern = PatternGenerator([0, 1, 2, 3], "upDown");
+			expect(getArrayValues(pattern, 10)).to.deep.equal([0, 1, 2, 3, 2, 1, 0, 1, 2, 3]);
+		});
+
+		it("does the downUp pattern", () => {
+			const pattern = PatternGenerator([0, 1, 2, 3], "downUp");
+			expect(getArrayValues(pattern, 10)).to.deep.equal([3, 2, 1, 0, 1, 2, 3, 2, 1, 0]);
+		});
+
+		it("does the alternateUp pattern", () => {
+			const pattern = PatternGenerator([0, 1, 2, 3, 4], "alternateUp");
+			expect(getArrayValues(pattern, 10)).to.deep.equal([0, 2, 1, 3, 2, 4, 3, 0, 2, 1]);
+		});
+
+		it("does the alternateDown pattern", () => {
+			const pattern = PatternGenerator([0, 1, 2, 3, 4], "alternateDown");
+			expect(getArrayValues(pattern, 10)).to.deep.equal([4, 2, 3, 1, 2, 0, 1, 4, 2, 3]);
+		});
+
+		it("outputs random elements from the values", () => {
+			const values = [0, 1, 2, 3, 4];
+			const pattern = PatternGenerator(values, "random");
+			for (let i = 0; i < 10; i++) {
+				expect(values.indexOf(pattern.next().value)).to.not.equal(-1);
+			}
+		});
+
+		it("does randomOnce pattern", () => {
+			const pattern = PatternGenerator([4, 5, 6, 7, 8], "randomOnce");
+			expect(getArrayValues(pattern, 10).sort()).to.deep.equal([4, 4, 5, 5, 6, 6, 7, 7, 8, 8]);
+		});
+                
+		it("randomly walks up or down 1 step without repeating", () => {
+			const values = [0, 1, 2, 3, 4];
+			const pattern = PatternGenerator(values, "randomWalk");
+			let currentIndex = values.indexOf(pattern.next().value);
+			for (let i = 0; i < 10; i++) {
+				const nextIndex = values.indexOf(pattern.next().value);
+				expect(currentIndex).to.not.equal(nextIndex);
+				// change always equals 1
+				expect(Math.abs(currentIndex - nextIndex)).to.equal(1);
+				currentIndex = nextIndex;
+			}
+		});
+	});
+});

package/Tone/event/PatternGenerator.ts

@@ -0,0 +1,176 @@
+import { assert } from "../core/util/Debug";
+import { clamp } from "../core/util/Math";
+
+/**
+ * The name of the patterns
+ */
+export type PatternName = "up" | "down" | "upDown" | "downUp" | "alternateUp" | "alternateDown" | "random" | "randomOnce" | "randomWalk";
+
+/**
+ * Start at the first value and go up to the last
+ */
+function* upPatternGen<T>(values: T[]): IterableIterator<T> {
+	let index = 0;
+	while (index < values.length) {
+		index = clampToArraySize(index, values);
+		yield values[index];
+		index++;
+	}
+}
+
+/**
+ * Start at the last value and go down to 0
+ */
+function* downPatternGen<T>(values: T[]): IterableIterator<T> {
+	let index = values.length - 1;
+	while (index >= 0) {
+		index = clampToArraySize(index, values);
+		yield values[index];
+		index--;
+	}
+}
+
+/**
+ * Infinitely yield the generator
+ */
+function* infiniteGen<T>(values: T[], gen: typeof upPatternGen): IterableIterator<T> {
+	while (true) {
+		yield* gen(values);
+	}
+}
+
+/**
+ * Make sure that the index is in the given range
+ */
+function clampToArraySize(index: number, values: any[]): number {
+	return clamp(index, 0, values.length - 1);
+}
+
+/**
+ * Alternate between two generators
+ */
+function* alternatingGenerator<T>(values: T[], directionUp: boolean): IterableIterator<T> {
+	let index = directionUp ? 0 : values.length - 1;
+	while (true) {
+		index = clampToArraySize(index, values);
+		yield values[index];
+		if (directionUp) {
+			index++;
+			if (index >= values.length - 1) {
+				directionUp = false;
+			}
+		} else {
+			index--;
+			if (index <= 0) {
+				directionUp = true;
+			}
+		}
+	}
+}
+
+/**
+ * Starting from the bottom move up 2, down 1
+ */
+function* jumpUp<T>(values: T[]): IterableIterator<T> {
+	let index = 0;
+	let stepIndex = 0;
+	while (index < values.length) {
+		index = clampToArraySize(index, values);
+		yield values[index];
+		stepIndex++;
+		index += (stepIndex % 2 ? 2 : -1);
+	}
+}
+
+/**
+ * Starting from the top move down 2, up 1
+ */
+function* jumpDown<T>(values: T[]): IterableIterator<T> {
+	let index = values.length - 1;
+	let stepIndex = 0;
+	while (index >= 0) {
+		index = clampToArraySize(index, values);
+		yield values[index];
+		stepIndex++;
+		index += (stepIndex % 2 ? -2 : 1);
+	}
+}
+
+/**
+ * Choose a random index each time
+ */
+function* randomGen<T>(values: T[]): IterableIterator<T> {
+	while (true) {
+		const randomIndex = Math.floor(Math.random() * values.length);
+		yield values[randomIndex];
+	}
+}
+
+/**
+ * Randomly go through all of the values once before choosing a new random order
+ */
+function* randomOnce<T>(values: T[]): IterableIterator<T> {
+	// create an array of indices
+	const copy: number[] = [];
+	for (let i = 0; i < values.length; i++) {
+		copy.push(i);
+	}
+	while (copy.length > 0) {
+		// random choose an index, and then remove it so it's not chosen again
+		const randVal = copy.splice(Math.floor(copy.length * Math.random()), 1);
+		const index = clampToArraySize(randVal[0], values);
+		yield values[index];
+	}
+}
+
+/**
+ * Randomly choose to walk up or down 1 index in the values array
+ */
+function* randomWalk<T>(values: T[]): IterableIterator<T> {
+	// randomly choose a starting index in the values array
+	let index = Math.floor(Math.random() * values.length);
+	while (true) {
+		if (index === 0) {
+			index++; // at bottom of array, so force upward step
+		} else if (index === values.length - 1) {
+			index--; // at top of array, so force downward step
+		} else if (Math.random() < 0.5) { // else choose random downward or upward step
+			index--;
+		} else {
+			index++;
+		}
+		yield values[index];
+	}
+}
+
+/**
+ * PatternGenerator returns a generator which will iterate over the given array
+ * of values and yield the items according to the passed in pattern
+ * @param values An array of values to iterate over
+ * @param pattern The name of the pattern use when iterating over
+ * @param index Where to start in the offset of the values array
+ */
+export function* PatternGenerator<T>(values: T[], pattern: PatternName = "up", index = 0): Iterator<T> {
+	// safeguards
+	assert(values.length > 0, "The array must have more than one value in it");
+	switch (pattern) {
+		case "up" :
+			yield* infiniteGen(values, upPatternGen);
+		case "down" :
+			yield* infiniteGen(values, downPatternGen);
+		case "upDown" :
+			yield* alternatingGenerator(values, true);
+		case "downUp" :
+			yield* alternatingGenerator(values, false);
+		case "alternateUp":
+			yield* infiniteGen(values, jumpUp);
+		case "alternateDown":
+			yield* infiniteGen(values, jumpDown);
+		case "random":
+			yield* randomGen(values);
+		case "randomOnce":
+			yield* infiniteGen(values, randomOnce);
+		case "randomWalk":
+			yield* randomWalk(values);
+	}
+}