diff --git a/js/js-export/API/PitchBlocksAPI.js b/js/js-export/API/PitchBlocksAPI.js index f5ea886fef..93112bc2b8 100644 --- a/js/js-export/API/PitchBlocksAPI.js +++ b/js/js-export/API/PitchBlocksAPI.js @@ -27,16 +27,33 @@ * @classdesc methods are imported by a importMethod function call from MusicBlocks class. */ class PitchBlocksAPI { + /** + * Plays a note with specified pitch and octave. + * @param {string} note - The note name to play (e.g., 'C', 'D', etc.) + * @param {number} octave - The octave number for the note + * @returns {Promise} Command execution promise + */ playPitch(note, octave) { const args = JSInterface.validateArgs("playPitch", [note, octave]); return this.runCommand("playPitch", [args[0], args[1], 0, this.turIndex, MusicBlocks.BLK]); } + /** + * Steps the pitch up or down by a specified value. + * @param {number} value - The number of steps to move (positive for up, negative for down) + * @returns {Promise} Command execution promise + */ stepPitch(value) { const args = JSInterface.validateArgs("stepPitch", [value]); return this.runCommand("stepPitch", [args[0], this.turIndex]); } + /** + * Plays the nth pitch in the current modal scale. + * @param {number} number - The scale degree to play + * @param {number} octave - The octave number + * @returns {Promise} Command execution promise + */ playNthModalPitch(number, octave) { const args = JSInterface.validateArgs("playNthModalPitch", [number, octave]); return this.runCommand("playNthModalPitch", [ @@ -47,16 +64,32 @@ class PitchBlocksAPI { ]); } + /** + * Plays a pitch specified by its number value. + * @param {number} number - The pitch number to play + * @returns {Promise} Command execution promise + */ playPitchNumber(number) { const args = JSInterface.validateArgs("playPitchNumber", [number]); return this.runCommand("playPitchNumber", [args[0], this.turIndex, MusicBlocks.BLK]); } + /** + * Plays a note at a specified frequency in Hertz. + * @param {number} value - The frequency in Hertz + * @returns {Promise} Command execution promise + */ playHertz(value) { const args = JSInterface.validateArgs("playHertz", [value]); return this.runCommand("playHertz", [args[0], this.turIndex]); } + /** + * Sets an accidental (sharp, flat, etc.) for subsequent notes. + * @param {string} accidental - The accidental to apply + * @param {Function} flow - Flow function to execute after setting accidental + * @returns {string} ENDFLOWCOMMAND + */ async setAccidental(accidental, flow) { const args = JSInterface.validateArgs("setAccidental", [accidental, flow]); await this.runCommand("setAccidental", [args[0], this.turIndex, MusicBlocks.BLK]); @@ -64,6 +97,12 @@ class PitchBlocksAPI { return this.ENDFLOWCOMMAND; } + /** + * Transposes subsequent notes by a scalar value. + * @param {number} value - The number of scale degrees to transpose + * @param {Function} flow - Flow function to execute after transposition + * @returns {string} ENDFLOWCOMMAND + */ async setScalarTranspose(value, flow) { const args = JSInterface.validateArgs("setScalarTranspose", [value, flow]); await this.runCommand("setScalarTranspose", [args[0], this.turIndex]); @@ -71,6 +110,12 @@ class PitchBlocksAPI { return this.ENDFLOWCOMMAND; } + /** + * Transposes subsequent notes by a specified number of semitones. + * @param {number} value - The number of semitones to transpose + * @param {Function} flow - Flow function to execute after transposition + * @returns {string} ENDFLOWCOMMAND + */ async setSemitoneTranspose(value, flow) { const args = JSInterface.validateArgs("setSemitoneTranspose", [value, flow]); await this.runCommand("setSemitoneTranspose", [args[0], this.turIndex]); @@ -78,11 +123,24 @@ class PitchBlocksAPI { return this.ENDFLOWCOMMAND; } + /** + * Sets the register (octave range) for subsequent notes. + * @param {number} value - The register value to set + * @returns {Promise} Command execution promise + */ setRegister(value) { const args = JSInterface.validateArgs("setRegister", [value]); return this.runCommand("setRegister", [args[0], this.turIndex]); } + /** + * Inverts the current pitch sequence based on specified parameters. + * @param {string} name - The name of the inversion + * @param {number} octave - The octave for the inversion + * @param {string} mode - The mode for the inversion + * @param {Function} flow - Flow function to execute after inversion + * @returns {string} ENDFLOWCOMMAND + */ async invert(name, octave, mode, flow) { const args = JSInterface.validateArgs("invert", [name, octave, mode, flow]); await this.runCommand("invert", [args[0], args[1], args[2], this.turIndex]); @@ -90,23 +148,34 @@ class PitchBlocksAPI { return this.ENDFLOWCOMMAND; } + /** + * Sets the pitch number offset for subsequent notes. + * @param {number} pitch - The pitch offset value + * @param {number} octave - The octave offset value + * @returns {Promise} Command execution promise + */ setPitchNumberOffset(pitch, octave) { const args = JSInterface.validateArgs("setPitchNumberOffset", [pitch, octave]); return this.runCommand("setPitchNumberOffset", [args[0], args[1], this.turIndex]); } + /** + * Converts a number to its corresponding pitch name. + * @param {number} number - The number to convert + * @returns {string} The pitch name + */ numToPitch(number) { const args = JSInterface.validateArgs("numToPitch", [number]); return Singer.PitchActions.numToPitch(args[0], "pitch", this.turIndex); } + /** + * Converts a number to its corresponding octave. + * @param {number} number - The number to convert + * @returns {number} The octave number + */ numToOctave(number) { const args = JSInterface.validateArgs("numToOctave", [number]); return Singer.PitchActions.numToPitch(args[0], "octave", this.turIndex); } - - // getPitchInfo(type) { - // let args = JSInterface.validateArgs("getPitchInfo", [type]); - // return Singer.PitchActions.getPitchInfo(args[0], this.turIndex); - // } } diff --git a/js/js-export/API/RhythmBlocksAPI.js b/js/js-export/API/RhythmBlocksAPI.js index 7f7cbcff07..1993eccb6e 100644 --- a/js/js-export/API/RhythmBlocksAPI.js +++ b/js/js-export/API/RhythmBlocksAPI.js @@ -27,6 +27,12 @@ * @classdesc methods are imported by a importMethod function call from MusicBlocks class. */ class RhythmBlocksAPI { + /** + * Plays a note with the specified value. + * @param {number} value - The value/duration of the note to play + * @param {Function} flow - Flow function to execute after playing the note + * @returns {string} ENDFLOWCOMMAND + */ async playNote(value, flow) { const args = JSInterface.validateArgs("playNote", [value, flow]); await this.runCommand("playNote", [args[0], "newnote", this.turIndex, MusicBlocks.BLK]); @@ -34,6 +40,12 @@ class RhythmBlocksAPI { return this.ENDFLOWCOMMAND; } + /** + * Plays a note with a specified duration in milliseconds. + * @param {number} value - The duration in milliseconds + * @param {Function} flow - Flow function to execute after playing the note + * @returns {string} ENDFLOWCOMMAND + */ async playNoteMillis(value, flow) { const args = JSInterface.validateArgs("playNoteMillis", [value, flow]); await this.runCommand("playNote", [args[0], "osctime", this.turIndex, MusicBlocks.BLK]); @@ -41,10 +53,20 @@ class RhythmBlocksAPI { return this.ENDFLOWCOMMAND; } + /** + * Plays a rest (silence) for the current turtle. + * @returns {Promise} Command execution promise + */ playRest() { return this.runCommand("playRest", [this.turIndex]); } + /** + * Adds a rhythmic dot to extend the duration of a note. + * @param {number} value - The dot value to apply + * @param {Function} flow - Flow function to execute after applying the dot + * @returns {string} ENDFLOWCOMMAND + */ async dot(value, flow) { const args = JSInterface.validateArgs("dot", [value, flow]); await this.runCommand("doRhythmicDot", [args[0], this.turIndex]); @@ -52,6 +74,11 @@ class RhythmBlocksAPI { return this.ENDFLOWCOMMAND; } + /** + * Ties two notes together. + * @param {Function} flow - Flow function to execute after applying the tie + * @returns {string} ENDFLOWCOMMAND + */ async tie(flow) { const args = JSInterface.validateArgs("tie", [flow]); await this.runCommand("doTie", [this.turIndex]); @@ -59,6 +86,12 @@ class RhythmBlocksAPI { return this.ENDFLOWCOMMAND; } + /** + * Multiplies the duration of a note by a specified factor. + * @param {number} factor - The multiplication factor to apply + * @param {Function} flow - Flow function to execute after multiplication + * @returns {string} ENDFLOWCOMMAND + */ async multiplyNoteValue(factor, flow) { const args = JSInterface.validateArgs("multiplyNoteValue", [factor, flow]); await this.runCommand("multiplyNoteValue", [args[0], this.turIndex]); @@ -66,6 +99,13 @@ class RhythmBlocksAPI { return this.ENDFLOWCOMMAND; } + /** + * Applies a swing rhythm effect to notes. + * @param {number} swingValue - The amount of swing to apply + * @param {number} noteValue - The note value to apply swing to + * @param {Function} flow - Flow function to execute after applying swing + * @returns {string} ENDFLOWCOMMAND + */ async swing(swingValue, noteValue, flow) { const args = JSInterface.validateArgs("multiplyNoteValue", [swingValue, noteValue, flow]); await this.runCommand("addSwing", [args[0], args[1], this.turIndex]); diff --git a/js/js-export/API/ToneBlocksAPI.js b/js/js-export/API/ToneBlocksAPI.js index fe3b270ea2..43b70417f0 100644 --- a/js/js-export/API/ToneBlocksAPI.js +++ b/js/js-export/API/ToneBlocksAPI.js @@ -27,6 +27,12 @@ * @classdesc methods are imported by a importMethod function call from MusicBlocks class. */ class ToneBlocksAPI { + /** + * Sets the instrument/timbre for the current turtle. + * @param {string} instrument - The name of the instrument to set + * @param {Function} flow - Flow function to execute after setting the instrument + * @returns {string} ENDFLOWCOMMAND + */ async setInstrument(instrument, flow) { const args = JSInterface.validateArgs("setInstrument", [instrument, flow]); await this.runCommand("setTimbre", [args[0], this.turIndex]); @@ -34,6 +40,13 @@ class ToneBlocksAPI { return this.ENDFLOWCOMMAND; } + /** + * Applies a vibrato effect to the current turtle's sound. + * @param {number} intensity - The intensity of the vibrato effect + * @param {number} rate - The rate of the vibrato oscillation + * @param {Function} flow - Flow function to execute after applying vibrato + * @returns {string} ENDFLOWCOMMAND + */ async doVibrato(intensity, rate, flow) { const args = JSInterface.validateArgs("doVibrato", [intensity, rate, flow]); await this.runCommand("doVibrato", [args[0], args[1], this.turIndex]); @@ -41,6 +54,14 @@ class ToneBlocksAPI { return this.ENDFLOWCOMMAND; } + /** + * Applies a chorus effect to the current turtle's sound. + * @param {number} chorusRate - The rate of the chorus effect + * @param {number} delayTime - The delay time for the chorus + * @param {number} chorusDepth - The depth of the chorus effect + * @param {Function} flow - Flow function to execute after applying chorus + * @returns {string} ENDFLOWCOMMAND + */ async doChorus(chorusRate, delayTime, chorusDepth, flow) { const args = JSInterface.validateArgs("doChorus", [ chorusRate, @@ -53,6 +74,14 @@ class ToneBlocksAPI { return this.ENDFLOWCOMMAND; } + /** + * Applies a phaser effect to the current turtle's sound. + * @param {number} rate - The rate of the phaser effect + * @param {number} octaves - Number of octaves the effect should span + * @param {number} baseFrequency - The base frequency for the phaser + * @param {Function} flow - Flow function to execute after applying phaser + * @returns {string} ENDFLOWCOMMAND + */ async doPhaser(rate, octaves, baseFrequency, flow) { const args = JSInterface.validateArgs("doPhaser", [rate, octaves, baseFrequency, flow]); await this.runCommand("doPhaser", [args[0], args[1], args[2], this.turIndex]); @@ -60,6 +89,13 @@ class ToneBlocksAPI { return this.ENDFLOWCOMMAND; } + /** + * Applies a tremolo effect to the current turtle's sound. + * @param {number} frequency - The frequency of the tremolo effect + * @param {number} depth - The depth of the tremolo effect + * @param {Function} flow - Flow function to execute after applying tremolo + * @returns {string} ENDFLOWCOMMAND + */ async doTremolo(frequency, depth, flow) { const args = JSInterface.validateArgs("doTremolo", [frequency, depth, flow]); await this.runCommand("doTremolo", [args[0], args[1], this.turIndex]); @@ -67,6 +103,12 @@ class ToneBlocksAPI { return this.ENDFLOWCOMMAND; } + /** + * Applies a distortion effect to the current turtle's sound. + * @param {number} distortion - The amount of distortion to apply (0-1) + * @param {Function} flow - Flow function to execute after applying distortion + * @returns {string} ENDFLOWCOMMAND + */ async doDistortion(distortion, flow) { const args = JSInterface.validateArgs("doDistortion", [distortion, flow]); await this.runCommand("doDistortion", [args[0], this.turIndex]); @@ -74,6 +116,12 @@ class ToneBlocksAPI { return this.ENDFLOWCOMMAND; } + /** + * Applies a harmonic effect to the current turtle's sound. + * @param {number} harmonic - The harmonic number to apply + * @param {Function} flow - Flow function to execute after applying harmonic + * @returns {string} ENDFLOWCOMMAND + */ async doHarmonic(harmonic, flow) { const args = JSInterface.validateArgs("doHarmonic", [harmonic, flow]); await this.runCommand("doHarmonic", [args[0], this.turIndex, MusicBlocks.BLK]);