@huffduff/midi-writer-ts 3.2.0 → 3.2.3

package/src/midi-events/note-event.ts

@@ -0,0 +1,164 @@
+import {AbstractEvent} from '../abstract-event';
+import {MidiEvent} from './midi-event';
+import {NoteOnEvent} from './note-on-event';
+import {NoteOffEvent} from './note-off-event';
+import {Utils} from '../utils';
+
+/**
+ * Wrapper for noteOnEvent/noteOffEvent objects that builds both events.
+ * @param {object} fields - {pitch: '[C4]', duration: '4', wait: '4', velocity: 1-100}
+ * @return {NoteEvent}
+ */
+class NoteEvent implements AbstractEvent {
+	data: number[];
+	delta: number;
+	events: MidiEvent[];
+	name: string;
+	pitch: string[];
+	grace: string|string[];
+	channel: number;
+	repeat: number;
+	tick: number;
+	duration: string;
+	sequential: boolean;
+	wait: string;
+	velocity: number;
+	tickDuration: number;
+	restDuration: number;
+
+	constructor(fields) {
+		this.data = [];
+		this.name = 'NoteEvent';
+		this.pitch = Utils.toArray(fields.pitch);
+
+		this.channel = fields.channel || 1;
+		this.duration = fields.duration || '4';
+		this.grace = fields.grace;
+		this.repeat = fields.repeat || 1;
+		this.sequential = fields.sequential || false;
+		this.tick = fields.startTick || fields.tick || null;
+		this.velocity = fields.velocity || 50;
+		this.wait = fields.wait || 0;
+
+		this.tickDuration = Utils.getTickDuration(this.duration);
+		this.restDuration = Utils.getTickDuration(this.wait);
+
+		this.events 	= []; // Hold actual NoteOn/NoteOff events
+	}
+
+	/**
+	 * Builds int array for this event.
+	 * @return {NoteEvent}
+	 */
+	buildData(): NoteEvent {
+		// Reset data array
+		this.data = [];
+
+		// Apply grace note(s) and subtract ticks (currently 1 tick per grace note) from tickDuration so net value is the same
+		if (this.grace) {
+			const graceDuration = 1;
+			this.grace = Utils.toArray(this.grace);
+			this.grace.forEach(() => {
+				const noteEvent = new NoteEvent({pitch: this.grace, duration:'T' + graceDuration});
+				this.data = this.data.concat(noteEvent.data);
+			});
+		}
+
+		// fields.pitch could be an array of pitches.
+		// If so create note events for each and apply the same duration.
+
+		// By default this is a chord if it's an array of notes that requires one NoteOnEvent.
+		// If this.sequential === true then it's a sequential string of notes that requires separate NoteOnEvents.
+		if ( ! this.sequential) {
+			// Handle repeat
+			for (let j = 0; j < this.repeat; j++) {
+				// Note on
+				this.pitch.forEach((p, i) => {
+					let noteOnNew;
+
+					if (i == 0) {
+						noteOnNew = new NoteOnEvent({
+							channel: this.channel,
+							wait: this.wait,
+							delta: Utils.getTickDuration(this.wait),
+							velocity: this.velocity,
+							pitch: p,
+							tick: this.tick,
+						});
+
+					} else {
+						// Running status (can ommit the note on status)
+						//noteOn = new NoteOnEvent({data: [0, Utils.getPitch(p), Utils.convertVelocity(this.velocity)]});
+						noteOnNew = new NoteOnEvent({
+							channel: this.channel,
+							wait: 0,
+							delta: 0,
+							velocity: this.velocity,
+							pitch: p,
+							tick: this.tick,
+						});
+					}
+
+					this.events.push(noteOnNew);
+				});
+
+				// Note off
+				this.pitch.forEach((p, i) => {
+					let noteOffNew;
+
+					if (i == 0) {
+						//noteOff = new NoteOffEvent({data: Utils.numberToVariableLength(tickDuration).concat(this.getNoteOffStatus(), Utils.getPitch(p), Utils.convertVelocity(this.velocity))});
+						noteOffNew = new NoteOffEvent({
+							channel: this.channel,
+							duration: this.duration,
+							velocity: this.velocity,
+							pitch: p,
+							tick: this.tick !== null ? Utils.getTickDuration(this.duration) + this.tick : null,
+						});
+
+					} else {
+						// Running status (can omit the note off status)
+						//noteOff = new NoteOffEvent({data: [0, Utils.getPitch(p), Utils.convertVelocity(this.velocity)]});
+						noteOffNew = new NoteOffEvent({
+							channel: this.channel,
+							duration: 0,
+							velocity: this.velocity,
+							pitch: p,
+							tick: this.tick !== null ? Utils.getTickDuration(this.duration) + this.tick : null,
+						});
+					}
+
+					this.events.push(noteOffNew);
+				});
+			}
+
+		} else {
+			// Handle repeat
+			for (let j = 0; j < this.repeat; j++) {
+				this.pitch.forEach((p, i) => {
+					const noteOnNew = new NoteOnEvent({
+						channel: this.channel,
+						wait: (i > 0 ? 0 : this.wait), // wait only applies to first note in repetition
+						delta: (i > 0 ? 0 : Utils.getTickDuration(this.wait)),
+						velocity: this.velocity,
+						pitch: p,
+						tick: this.tick,
+					});
+
+					const noteOffNew = new NoteOffEvent({
+						channel: this.channel,
+						duration: this.duration,
+						velocity: this.velocity,
+						pitch: p,
+					});
+
+					this.events.push(noteOnNew, noteOffNew);
+				});
+			}
+		}
+
+		return this;
+	}
+}
+
+export {NoteEvent};

package/src/midi-events/note-off-event.ts

@@ -0,0 +1,55 @@
+import {MidiEvent} from './midi-event';
+import {Utils} from '../utils';
+
+/**
+ * Holds all data for a "note off" MIDI event
+ * @param {object} fields {data: []}
+ * @return {NoteOffEvent}
+ */
+class NoteOffEvent implements MidiEvent {
+	channel: number;
+	data: number[];
+	delta: number;
+	deltaWithPrecisionCorrection: number;
+	status: 0x80;
+	name: string;
+	velocity: number;
+	pitch: string|number;
+	duration: string|number;
+	tick: number;
+
+	constructor(fields: { channel: number; duration: string|number; velocity: number; pitch: string|number; tick?: number; data?: number[]; delta?: number }) {
+		this.name = 'NoteOffEvent';
+		this.channel = fields.channel || 1;
+		this.pitch = fields.pitch;
+		this.velocity = fields.velocity || 50;
+		this.tick = fields.tick || null;
+		this.data = fields.data;
+		this.delta = fields.delta || Utils.getTickDuration(fields.duration);
+		this.status = 0x80;
+	}
+
+	/**
+	 * Builds int array for this event.
+	 * @param {Track} track - parent track
+	 * @return {NoteOffEvent}
+	 */
+	buildData(track, precisionDelta: number, options: {middleC?: string} = {}) {
+		if (this.tick === null) {
+			this.tick = Utils.getRoundedIfClose(this.delta + track.tickPointer);
+		}
+
+		this.deltaWithPrecisionCorrection = Utils.getRoundedIfClose(this.delta - precisionDelta);
+
+		this.data = Utils.numberToVariableLength(this.deltaWithPrecisionCorrection)
+					.concat(
+							this.status | this.channel - 1,
+							Utils.getPitch(this.pitch, options.middleC),
+							Utils.convertVelocity(this.velocity)
+					);
+
+		return this;
+	}
+}
+
+export {NoteOffEvent};

package/src/midi-events/note-on-event.ts

@@ -0,0 +1,69 @@
+import { MidiEvent } from './midi-event';
+import { Utils } from '../utils';
+
+/**
+ * Holds all data for a "note on" MIDI event
+ * @param {object} fields {data: []}
+ * @return {NoteOnEvent}
+ */
+class NoteOnEvent implements MidiEvent {
+	channel: number;
+	data: number[];
+	delta: number;
+	status: 0x90;
+	name: string;
+	pitch: string | number;
+	velocity: number;
+	wait: string | number;
+	tick: number;
+	deltaWithPrecisionCorrection: number;
+
+	constructor(fields: { channel?: number; wait?: string | number; velocity?: number; pitch?: string | number; tick?: number; data?: number[]; delta?: number }) {
+		this.name = 'NoteOnEvent';
+		this.channel = fields.channel || 1;
+		this.pitch = fields.pitch;
+		this.wait = fields.wait || 0;
+		this.velocity = fields.velocity || 50;
+
+		this.tick = fields.tick || null;
+		this.delta = null;
+		this.data = fields.data;
+		this.status = 0x90;
+	}
+
+	/**
+	 * Builds int array for this event.
+	 * @param {Track} track - parent track
+	 * @return {NoteOnEvent}
+	 */
+	buildData(track, precisionDelta, options: { middleC?: string } = {}) {
+		this.data = [];
+
+		// Explicitly defined startTick event
+		if (this.tick) {
+			this.tick = Utils.getRoundedIfClose(this.tick);
+
+			// If this is the first event in the track then use event's starting tick as delta.
+			if (track.tickPointer == 0) {
+				this.delta = this.tick;
+			}
+
+		} else {
+			this.delta = Utils.getTickDuration(this.wait);
+			this.tick = Utils.getRoundedIfClose(track.tickPointer + this.delta);
+		}
+
+		this.deltaWithPrecisionCorrection = Utils.getRoundedIfClose(this.delta - precisionDelta);
+
+		this.data = Utils.numberToVariableLength(this.deltaWithPrecisionCorrection)
+			.concat(
+				this.status | this.channel - 1,
+				Utils.getPitch(this.pitch, options.middleC),
+				Utils.convertVelocity(this.velocity)
+			);
+
+		return this;
+	}
+}
+
+export { NoteOnEvent };

package/src/midi-events/pitch-bend-event.ts

@@ -0,0 +1,40 @@
+import {MidiEvent} from './midi-event';
+import {Utils} from '../utils';
+
+
+/**
+ * Holds all data for a "Pitch Bend" MIDI event
+ * [ -1.0, 0, 1.0 ] ->  [ 0, 8192, 16383]
+ * @param {object} fields { bend : float, channel : int, delta: int }
+ * @return {PitchBendEvent}
+ */
+class PitchBendEvent implements MidiEvent {
+	channel: number;
+	data: number[];
+	delta: number;
+	name: string;
+	status: 0xE0;
+
+    constructor(fields) {
+		this.channel = fields.channel || 0;
+		this.delta = fields.delta || 0x00;
+		this.name = 'PitchBendEvent';
+		this.status = 0xE0;
+ 
+		const bend14 = this.scale14bits(fields.bend);
+
+		const lsbValue = bend14 & 0x7f;          
+		const msbValue = ( bend14 >> 7 ) & 0x7f;
+		this.data = Utils.numberToVariableLength(this.delta).concat(this.status | this.channel, lsbValue, msbValue);
+    }
+
+	scale14bits(zeroOne) {
+		if ( zeroOne <= 0 ) {
+			return Math.floor( 16384 * ( zeroOne + 1 ) / 2 );
+		}
+	
+		return Math.floor( 16383 * ( zeroOne + 1 ) / 2 );
+	}
+}
+
+export {PitchBendEvent};

package/src/midi-events/program-change-event.ts

@@ -0,0 +1,28 @@
+import {MidiEvent} from './midi-event';
+import {Utils} from '../utils';
+
+/**
+ * Holds all data for a "program change" MIDI event
+ * @param {object} fields {instrument: integer, delta: integer}
+ * @return {ProgramChangeEvent}
+ */
+class ProgramChangeEvent implements MidiEvent {
+	channel: number;
+    data: number[];
+    delta: number;
+	status: 0xC0;
+    name: string;
+	instrument: number;
+
+	constructor(fields: { channel?: number; delta?: number; instrument: number; }) {
+		this.channel = fields.channel || 0;
+		this.delta = fields.delta || 0x00;
+		this.instrument = fields.instrument;
+		this.status = 0xC0;
+		this.name = 'ProgramChangeEvent';
+		// delta time defaults to 0.
+		this.data = Utils.numberToVariableLength(this.delta).concat(this.status | this.channel, this.instrument);
+	}
+}
+
+export {ProgramChangeEvent};

package/src/utils.ts

@@ -0,0 +1,263 @@
+import { Constants } from './constants';
+import { toMidi } from '@tonaljs/midi';
+
+/**
+ * Static utility functions used throughout the library.
+ */
+class Utils {
+
+	/**
+	 * Gets MidiWriterJS version number.
+	 * @return {string}
+	 */
+	static version(): string {
+		return Constants.VERSION;
+	}
+
+	/**
+	 * Convert a string to an array of bytes
+	 * @param {string} string
+	 * @return {array}
+	 */
+	static stringToBytes(string: string): number[] {
+		return string.split('').map(char => char.charCodeAt(0))
+	}
+
+	/**
+	 * Checks if argument is a valid number.
+	 * @param {*} n - Value to check
+	 * @return {boolean}
+	 */
+	// eslint-disable-next-line @typescript-eslint/no-explicit-any
+	static isNumeric(n: any): boolean {
+		return !isNaN(parseFloat(n)) && isFinite(n)
+	}
+
+	/**
+	 * Returns the correct MIDI number for the specified pitch.
+	 * Uses Tonal Midi - https://github.com/danigb/tonal/tree/master/packages/midi
+	 * @param {(string|number)} pitch - 'C#4' or midi note code
+	 * @param {string} middleC
+	 * @return {number}
+	 */
+	static getPitch(pitch: string | number, middleC: string | number = 'C4'): number {
+		return 60 - toMidi(middleC) + toMidi(pitch);
+	}
+
+	/**
+	 * Translates number of ticks to MIDI timestamp format, returning an array of
+	 * hex strings with the time values. Midi has a very particular time to express time,
+	 * take a good look at the spec before ever touching this function.
+	 * Thanks to https://github.com/sergi/jsmidi
+	 *
+	 * @param {number} ticks - Number of ticks to be translated
+	 * @return {array} - Bytes that form the MIDI time value
+	 */
+	static numberToVariableLength(ticks: number): number[] {
+		ticks = Math.round(ticks);
+		let buffer = ticks & 0x7F;
+
+		// eslint-disable-next-line no-cond-assign
+		while (ticks = ticks >> 7) {
+			buffer <<= 8;
+			buffer |= ((ticks & 0x7F) | 0x80);
+		}
+
+		const bList = [];
+		// eslint-disable-next-line no-constant-condition
+		while (true) {
+			bList.push(buffer & 0xff);
+
+			if (buffer & 0x80) buffer >>= 8
+			else { break; }
+		}
+
+		return bList;
+	}
+
+	/**
+	 * Counts number of bytes in string
+	 * @param {string} s
+	 * @return {number}
+	 */
+	static stringByteCount(s: string): number {
+		return encodeURI(s).split(/%..|./).length - 1
+	}
+
+	/**
+	 * Get an int from an array of bytes.
+	 * @param {array} bytes
+	 * @return {number}
+	 */
+	static numberFromBytes(bytes: number[]): number {
+		let hex = '';
+		let stringResult;
+
+		bytes.forEach((byte) => {
+			stringResult = byte.toString(16);
+
+			// ensure string is 2 chars
+			if (stringResult.length == 1) stringResult = "0" + stringResult
+
+			hex += stringResult;
+		});
+
+		return parseInt(hex, 16);
+	}
+
+	/**
+	 * Takes a number and splits it up into an array of bytes.  Can be padded by passing a number to bytesNeeded
+	 * @param {number} number
+	 * @param {number} bytesNeeded
+	 * @return {array} - Array of bytes
+	 */
+	static numberToBytes(number: number, bytesNeeded: number): number[] {
+		bytesNeeded = bytesNeeded || 1;
+
+		let hexString = number.toString(16);
+
+		if (hexString.length & 1) { // Make sure hex string is even number of chars
+			hexString = '0' + hexString;
+		}
+
+		// Split hex string into an array of two char elements
+		const hexArray = hexString.match(/.{2}/g);
+
+		// Now parse them out as integers
+		const intArray = hexArray.map(item => parseInt(item, 16))
+
+		// Prepend empty bytes if we don't have enough
+		if (intArray.length < bytesNeeded) {
+			while (bytesNeeded - intArray.length > 0) {
+				intArray.unshift(0);
+			}
+		}
+
+		return intArray;
+	}
+
+	/**
+	 * Converts value to array if needed.
+	 * @param {any} value
+	 * @return {array}
+	 */
+	// eslint-disable-next-line @typescript-eslint/no-explicit-any
+	static toArray(value: any): any[] {
+		if (Array.isArray(value)) return value;
+		return [value];
+	}
+
+	/**
+	 * Converts velocity to value 0-127
+	 * @param {number} velocity - Velocity value 1-100
+	 * @return {number}
+	 */
+	static convertVelocity(velocity: number): number {
+		// Max passed value limited to 100
+		velocity = velocity > 100 ? 100 : velocity;
+		return Math.round(velocity / 100 * 127);
+	}
+
+	/**
+	 * Gets the total number of ticks of a specified duration.
+	 * Note: type=='note' defaults to quarter note, type==='rest' defaults to 0
+	 * @param {(string|array)} duration
+	 * @return {number}
+	 */
+	static getTickDuration(duration: (string | string[] | number)): number {
+		if (Array.isArray(duration)) {
+			// Recursively execute this method for each item in the array and return the sum of tick durations.
+			return duration.map((value) => {
+				return Utils.getTickDuration(value);
+			}).reduce((a, b) => {
+				return a + b;
+			}, 0);
+		}
+
+		duration = duration.toString();
+
+		if (duration.toLowerCase().charAt(0) === 't') {
+			// If duration starts with 't' then the number that follows is an explicit tick count
+			const ticks = parseInt(duration.substring(1));
+
+			if (isNaN(ticks) || ticks < 0) {
+				throw new Error(duration + ' is not a valid duration.');
+			}
+
+			return ticks;
+		}
+
+		// Need to apply duration here.  Quarter note == Constants.HEADER_CHUNK_DIVISION
+		const quarterTicks = Utils.numberFromBytes(Constants.HEADER_CHUNK_DIVISION);
+		const tickDuration = quarterTicks * Utils.getDurationMultiplier(duration);
+		return Utils.getRoundedIfClose(tickDuration)
+	}
+
+	/**
+	 * Due to rounding errors in JavaScript engines,
+	 * it's safe to round when we're very close to the actual tick number
+	 *
+	 * @static
+	 * @param {number} tick
+	 * @return {number}
+	 */
+	static getRoundedIfClose(tick: number): number {
+		const roundedTick = Math.round(tick);
+		return Math.abs(roundedTick - tick) < 0.000001 ? roundedTick : tick;
+	}
+
+	/**
+	 * Due to low precision of MIDI,
+	 * we need to keep track of rounding errors in deltas.
+	 * This function will calculate the rounding error for a given duration.
+	 *
+	 * @static
+	 * @param {number} tick
+	 * @return {number}
+	 */
+	static getPrecisionLoss(tick: number): number {
+		const roundedTick = Math.round(tick);
+		return roundedTick - tick;
+	}
+
+	/**
+	 * Gets what to multiple ticks/quarter note by to get the specified duration.
+	 * Note: type=='note' defaults to quarter note, type==='rest' defaults to 0
+	 * @param {string} duration
+	 * @return {number}
+	 */
+	static getDurationMultiplier(duration: string): number {
+		// Need to apply duration here.
+		// Quarter note == Constants.HEADER_CHUNK_DIVISION ticks.
+
+		if (duration === '0') return 0;
+
+		const match = duration.match(/^(?<dotted>d+)?(?<base>\d+)(?:t(?<tuplet>\d*))?/);
+		if (match) {
+			const base = Number(match.groups.base);
+			// 1 or any power of two:
+			const isValidBase = base === 1 || ((base & (base - 1)) === 0);
+			if (isValidBase) {
+				// how much faster or slower is this note compared to a quarter?
+				const ratio = base / 4;
+				let durationInQuarters = 1 / ratio;
+				const { dotted, tuplet } = match.groups;
+				if (dotted) {
+					const thisManyDots = dotted.length;
+					const divisor = Math.pow(2, thisManyDots);
+					durationInQuarters = durationInQuarters + (durationInQuarters * ((divisor - 1) / divisor));
+				}
+				if (typeof tuplet === 'string') {
+					const fitInto = durationInQuarters * 2;
+					// default to triplet:
+					const thisManyNotes = Number(tuplet || '3');
+					durationInQuarters = fitInto / thisManyNotes;
+				}
+				return durationInQuarters
+			}
+		}
+		throw new Error(duration + ' is not a valid duration.');
+	}
+}
+
+export { Utils };