music.playInstructions() missing?

https://arcade.makecode.com/developer/sound#sound-instructions mentions a music.playInstructions() API, does that currently work?

For background, I wanted to try modifying a white noise effect. The playMelody API works using music.playMelody("~5 !200", 60), but it’s not very flexible.

I tried creating a sound instruction buffer, but got stuck trying to play it:

const mySound: Buffer = hex`0500010102027f7f00000101`;
music.playInstructions(mySound)

This shows an error in the editor: Property ‘playInstructions’ does not exist on type ‘typeof music’.

I poked around in pxt-common-packages/blob/master/libs/mixer/melody.ts , and it doesn’t look as if playInstructions(buffer) exists. There’s a queuePlayInstructions(when, buffer), but that’s apparently not exported?

Am I missing something, or is this currently not implemented?

As a side note, it seems that the noise output ignores the frequency. That seems by design for white noise, but it’s not very flexible. Would you be open to adding a simple square wave + pseudorandom selector combination, similar to what the 8-bit Atari POKEY chip used? See https://www.atariarchives.org/dere/chapt07.php for more discussion of that. Maybe expose this as a new implementation of the removed-but-still-documented metallic waveform? (See pxt-common-packages PR #875.)

Ah, sorry! I think you found the correct function and at some point we made it private.

Add this to your project to get it back:

namespace music {
    //% shim=music::queuePlayInstructions
    export function playInstructions(timeDelta: number, buf: Buffer) { }
}

The actual function is implemented in C++, that’s why there’s no body. The shim annotation tells the compiler to link things up correctly.

Thanks, that works perfectly. In case it helps someone else, here’s my current sound effect after some tweaking:

// ww = waveform
// ffFF = frequency, low byte first
// ddDD = duration in milliseconds
// vvVV = volume
// wwWW = end volume
// ggGG = end frequency 
//                          ww--ffFFddDDvvVVwwWWggGG
const mySound: Buffer = hex`050001010101111100000101`;
music.playInstructions(0, mySound)

Also, here’s some code you might find useful:

I wrote this a while ago. It’s a snippet of code to generate sound buffers with separate envelopes for amplitude and pitch. Press A to here a sound effect