Allow for audio chaining by returning self object from audio effects and audio mixer

[relic-se]

The idea of audio effect/mixer chaining was theorized in one of the first audio effects PRs, #9640 (comment), but never actually implemented.

The updates in this PR are relatively simple. Instead of returning None within play(...) methods of audio objects which allow both input and output (effects and mixer), it instead returns a reference to itself.

With this minor update, rather than building audio chains the old way:

effect.play(sample)
mixer.play(effect)
dac.play(mixer)

You can instead directly chain each source into its destination:

dac.play(mixer.play(effect.play(sample)))

Note: The only method that is missing this chaining ability is audiomixer.MixerVoice.play. I felt that it made sense to allow audiomixer.Mixer.play to support this but thought it would result in confusing implementation to support MixerVoice. (ie: dac.play(mixer.voice[0].play(sample)) vs dac.play(mixer.play(sample)).

[dhalbert]

I have seen this kind of chaining more with properties than function calls, but it's neat how they can be stacked.

I think it would be good to document that self is returned for all these cases, using :return: and :rtype:, and probably give an example of chaining for each case

[relic-se]

I think it would be good to document that self is returned for all these cases, using :return: and :rtype:, and probably give an example of chaining for each case

I've got some basic documentation in there. If you have any suggestions on the language used, I'd be happy to update. Thank you for the review!

[dhalbert]

@todbot You use synthio a lot, and I do not. Would you have any comment? Thanks!

[todbot]

@todbot You use synthio a lot, and I do not. Would you have any comment? Thanks!

Looks neat! I remember advocating for something similar with digitalio long time ago.

I didn't realize mixer.play(playable, voice=num) existed. Is that equivalent to mixer.voice[num].play(playable)?

My only concern (as w/ everything in the core modules now) is that the added feature will push out other modules on ports that are at the limit.

[dhalbert]

Thanks!

@todbot I'm not worried about size - the code growth should be tiny or non-existent in this case.

[relic-se]

Thanks for the review, @dhalbert and @todbot ! This update will definitely tidy up a lot of audio examples.