Audio docs improvements #55
Description
The audio API documentation could use some clarifications around stopping note playback, and the differing behaviours.
Setting volume to zero is the intended "stop note" API. That needs to be made clear. When doing so, if a volume envelope is set then the "release" phase will start. If a channel is already in the "release" phase, the channel will be instantly silenced.
Setting the duration to zero also generally has the effect of stopping a note on a channel, but that's not the advised way as it has interesting interactions with volume envelopes which should be explained. The situation is complex. When the duration is set to zero for a playing channel that has an envelope, the calculations for the envelope will happen as if the duration was always set to zero. Therefore if the elapsed time is any value beyond the cumulative attack + decay envelope phases you'll be straight into the "decay" phase. If the elapsed time is beyond the cumulative attack + decay + release phases then you're past "release" so the channel will go instantly silent. Basically, changing the duration has the effect of making playback on that channel happen as if the duration was always zero.
This is intended behaviour, and not a bug. 😁