Constructor
new Scratch3MusicBlocks(runtime)
Parameters:
| Name | Type | Description |
|---|---|---|
runtime |
Runtime | the runtime instantiating this block package. |
Members
(static) BEAT_RANGE :Object
The minimum and maximum beat values, for clamping the duration of play note, play drum and rest. 100 beats at the default tempo of 60bpm is 100 seconds.
Type:
- Object
(static) CONCURRENCY_LIMIT :number
The maximum number of sounds to allow to play simultaneously.
Type:
- number
(static) DEFAULT_MUSIC_STATE :MusicState
The default music-related state, to be used when a target has no existing music state.
Type:
- MusicState
(static) MIDI_NOTE_RANGE :Object
The minimum and maximum MIDI note numbers, for clamping the input to play note.
Type:
- Object
(static) STATE_KEY :string
The key to load & store a target's music-related state.
Type:
- string
(static) TEMPO_RANGE :Object
The minimum and maximum tempo values, in bpm.
Type:
- Object
(private) _bufferSources :Array
An array of audio bufferSourceNodes. Each time you play an instrument or drum sound, a bufferSourceNode is created. We keep references to them to make sure their onended events can fire.
Type:
- Array
(private) _concurrencyCounter :number
The number of drum and instrument sounds currently being played simultaneously.
Type:
- number
(private) _drumPlayers :Array
An array of sound players, one for each drum sound.
Type:
- Array
(private) _instrumentPlayerArrays :Array.<Array>
An array of arrays of sound players. Each instrument has one or more audio players.
Type:
- Array.<Array>
(private) _instrumentPlayerNoteArrays :Array.<Array>
An array of arrays of sound players. Each instrument mya have an audio player for each playable note.
Type:
- Array.<Array>
DRUM_INFO :Array.<object>
An array of info about each drum.
Type:
- Array.<object>
INSTRUMENT_INFO :Array.<object>
An array of info about each instrument.
Type:
- Array.<object>
MIDI_DRUMS :Array.<Array>
An array that is a mapping from MIDI drum numbers in range (35..81) to Scratch drum numbers. It's in the format [drumNum, pitch, decay]. The pitch and decay properties are not currently being used.
Type:
- Array.<Array>
MIDI_INSTRUMENTS :Array.<number>
An array that is a mapping from MIDI instrument numbers to Scratch instrument numbers.
Type:
- Array.<number>
runtime :Runtime
The runtime instantiating this block package.
Type:
Methods
(private) _beatsToSec(beats) → {number}
Convert a number of beats to a number of seconds, using the current tempo.
Parameters:
| Name | Type | Description |
|---|---|---|
beats |
number | number of beats to convert to secs. |
Returns:
seconds - number of seconds beats will last.
- Type
- number
(private) _buildMenu(info) → {array}
Create data for a menu in scratch-blocks format, consisting of an array of objects with text and value properties. The text is a translated string, and the value is one-indexed.
Parameters:
| Name | Type | Description |
|---|---|---|
info |
Array.<object> | An array of info objects each having a name property. |
Returns:
- An array of objects with text and value properties.
- Type
- array
(private) _checkStackTimer(util)
Check the stack timer, and if its time is not up yet, yield the thread.
Parameters:
| Name | Type | Description |
|---|---|---|
util |
object | utility object provided by the runtime. |
(private) _clampBeats(beats) → {number}
Clamp a duration in beats to the allowed min and max duration.
Parameters:
| Name | Type | Description |
|---|---|---|
beats |
number | a duration in beats. |
Returns:
- the clamped duration.
- Type
- number
_decodeSound(soundBuffer) → {Promise}
Decode a sound and return a promise with the audio buffer.
Parameters:
| Name | Type | Description |
|---|---|---|
soundBuffer |
ArrayBuffer | a buffer containing the encoded audio. |
Returns:
- a promise which will resolve once the sound has decoded.
- Type
- Promise
(private) _getMusicState(target) → {MusicState}
Parameters:
| Name | Type | Description |
|---|---|---|
target |
Target | collect music state for this target. |
Returns:
the mutable music state associated with that target. This will be created if necessary.
- Type
- MusicState
_loadAllSounds()
Decode the full set of drum and instrument sounds, and store the audio buffers in arrays.
(private) _onTargetCreated(newTarget, sourceTargetopt)
When a music-playing Target is cloned, clone the music state.
Parameters:
| Name | Type | Attributes | Description |
|---|---|---|---|
newTarget |
Target | the newly created target. |
|
sourceTarget |
Target |
<optional> |
the target used as a source for the new clone, if any. |
Listens to Events:
_playDrumForBeats(drumNum, beats, util)
Internal code to play a drum sound for some number of beats.
Parameters:
| Name | Type | Description |
|---|---|---|
drumNum |
number | the drum number. |
beats |
beats | the duration in beats to pause after playing the sound. |
util |
object | utility object provided by the runtime. |
(private) _playDrumNum(util, drumNum)
Play a drum sound using its 0-indexed number.
Parameters:
| Name | Type | Description |
|---|---|---|
util |
object | utility object provided by the runtime. |
drumNum |
number | the number of the drum to play. |
(private) _playNote(util, note, durationSec)
Play a note using the current instrument for a duration in seconds. This function actually plays the sound, and handles the timing of the sound, including the "release" portion of the sound, which continues briefly after the block execution has finished.
Parameters:
| Name | Type | Description |
|---|---|---|
util |
object | utility object provided by the runtime. |
note |
number | the pitch of the note to play, interpreted as a MIDI note number. |
durationSec |
number | the duration in seconds to play the note. |
(private) _ratioForPitchInterval(interval) → {number}
Calcuate the frequency ratio for a given musical interval.
Parameters:
| Name | Type | Description |
|---|---|---|
interval |
number | the pitch interval to convert. |
Returns:
a ratio corresponding to the input interval.
- Type
- number
(private) _selectSampleIndexForNote(note, samples) → {index}
The samples array for each instrument is the set of pitches of the available audio samples. This function selects the best one to use to play a given input note, and returns its index in the samples array.
Parameters:
| Name | Type | Description |
|---|---|---|
note |
number | the input note to select a sample for. |
samples |
Array.<number> | an array of the pitches of the available samples. |
Returns:
the index of the selected sample in the samples array.
- Type
- index
_setInstrument(instNum, util, mapMidi)
Internal code to select an instrument for playing notes. If mapMidi is true, set the instrument according to the MIDI to Scratch instrument mapping.
Parameters:
| Name | Type | Description |
|---|---|---|
instNum |
number | the instrument number. |
util |
object | utility object provided by the runtime. |
mapMidi |
boolean | whether or not instNum is a MIDI instrument number. |
(private) _stackTimerNeedsInit(util) → {boolean}
Check if the stack timer needs initialization.
Parameters:
| Name | Type | Description |
|---|---|---|
util |
object | utility object provided by the runtime. |
Returns:
- true if the stack timer needs to be initialized.
- Type
- boolean
(private) _startStackTimer(util, duration)
Start the stack timer and the yield the thread if necessary.
Parameters:
| Name | Type | Description |
|---|---|---|
util |
object | utility object provided by the runtime. |
duration |
number | a duration in seconds to set the timer for. |
_storeSound(filePath, index, playerArray) → {Promise}
Decode a sound and store the player in an array.
Parameters:
| Name | Type | Description |
|---|---|---|
filePath |
string | the audio file name. |
index |
number | the index at which to store the audio player. |
playerArray |
array | the array of players in which to store it. |
Returns:
- a promise which will resolve once the sound has been stored.
- Type
- Promise
(private) _updateTempo(tempo)
Update the current tempo, clamping it to the min and max allowable range.
Parameters:
| Name | Type | Description |
|---|---|---|
tempo |
number | the tempo to set, in beats per minute. |
changeTempo(args)
Properties:
| Name | Type | Description |
|---|---|---|
TEMPO |
number | the amount to change the tempo, in beats per minute. |
Change the current tempo by some amount.
Parameters:
| Name | Type | Description |
|---|---|---|
args |
object | the block arguments. |
getInfo() → {object}
Returns:
metadata for this extension and its blocks.
- Type
- object
getTempo() → {number}
Get the current tempo.
Returns:
- the current tempo, in beats per minute.
- Type
- number
midiPlayDrumForBeats(args, util)
Play a drum sound for some number of beats according to the range of "MIDI" drum codes supported. This block is implemented for compatibility with old Scratch projects that use the 'drum:duration:elapsed:from:' block.
Parameters:
| Name | Type | Description |
|---|---|---|
args |
object | the block arguments. |
util |
object | utility object provided by the runtime. |
midiSetInstrument(args, util)
Properties:
| Name | Type | Description |
|---|---|---|
INSTRUMENT |
int | the MIDI number of the instrument to select. |
Select an instrument for playing notes according to a mapping of MIDI codes to Scratch instrument numbers. This block is implemented for compatibility with old Scratch projects that use the 'midiInstrument:' block.
Parameters:
| Name | Type | Description |
|---|---|---|
args |
object | the block arguments. |
util |
object | utility object provided by the runtime. |
playDrumForBeats(args, util)
Properties:
| Name | Type | Description |
|---|---|---|
DRUM |
int | the number of the drum to play. |
BEATS |
number | the duration in beats of the drum sound. |
Play a drum sound for some number of beats.
Parameters:
| Name | Type | Description |
|---|---|---|
args |
object | the block arguments. |
util |
object | utility object provided by the runtime. |
playNoteForBeats(args, util)
Properties:
| Name | Type | Description |
|---|---|---|
NOTE |
number | the pitch of the note to play, interpreted as a MIDI note number. |
BEATS |
number | the duration in beats of the note. |
Play a note using the current musical instrument for some number of beats. This function processes the arguments, and handles the timing of the block's execution.
Parameters:
| Name | Type | Description |
|---|---|---|
args |
object | the block arguments. |
util |
object | utility object provided by the runtime. |
restForBeats(args, util)
Properties:
| Name | Type | Description |
|---|---|---|
BEATS |
number | the duration in beats of the rest. |
Rest for some number of beats.
Parameters:
| Name | Type | Description |
|---|---|---|
args |
object | the block arguments. |
util |
object | utility object provided by the runtime. |
setInstrument(args, util)
Properties:
| Name | Type | Description |
|---|---|---|
INSTRUMENT |
int | the number of the instrument to select. |
Select an instrument for playing notes.
Parameters:
| Name | Type | Description |
|---|---|---|
args |
object | the block arguments. |
util |
object | utility object provided by the runtime. |
setTempo(args)
Properties:
| Name | Type | Description |
|---|---|---|
TEMPO |
number | the tempo, in beats per minute. |
Set the current tempo to a new value.
Parameters:
| Name | Type | Description |
|---|---|---|
args |
object | the block arguments. |