Merge pull request #10635 from relic-se/audio-chaining

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

Author: dhalbert

shared-bindings/audiodelays/Chorus.c

@@ -206,11 +206,15 @@ MP_DEFINE_CONST_FUN_OBJ_1(audiodelays_chorus_get_playing_obj, audiodelays_chorus
 MP_PROPERTY_GETTER(audiodelays_chorus_playing_obj,
     (mp_obj_t)&audiodelays_chorus_get_playing_obj);
 
-//|     def play(self, sample: circuitpython_typing.AudioSample, *, loop: bool = False) -> None:
+//|     def play(self, sample: circuitpython_typing.AudioSample, *, loop: bool = False) -> Chorus:
 //|         """Plays the sample once when loop=False and continuously when loop=True.
 //|         Does not block. Use `playing` to block.
 //|
-//|         The sample must match the encoding settings given in the constructor."""
+//|         The sample must match the encoding settings given in the constructor.
+//|
+//|         :return: The effect object itself. Can be used for chaining, ie:
+//|           ``audio.play(effect.play(sample))``.
+//|         :rtype: Chorus"""
 //|         ...
 //|
 static mp_obj_t audiodelays_chorus_obj_play(size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) {
@@ -228,7 +232,7 @@ static mp_obj_t audiodelays_chorus_obj_play(size_t n_args, const mp_obj_t *pos_a
     mp_obj_t sample = args[ARG_sample].u_obj;
     common_hal_audiodelays_chorus_play(self, sample, args[ARG_loop].u_bool);
 
-    return mp_const_none;
+    return MP_OBJ_FROM_PTR(self);
 }
 MP_DEFINE_CONST_FUN_OBJ_KW(audiodelays_chorus_play_obj, 1, audiodelays_chorus_obj_play);
 

shared-bindings/audiodelays/Echo.c

@@ -230,11 +230,15 @@ MP_DEFINE_CONST_FUN_OBJ_1(audiodelays_echo_get_playing_obj, audiodelays_echo_obj
 MP_PROPERTY_GETTER(audiodelays_echo_playing_obj,
     (mp_obj_t)&audiodelays_echo_get_playing_obj);
 
-//|     def play(self, sample: circuitpython_typing.AudioSample, *, loop: bool = False) -> None:
+//|     def play(self, sample: circuitpython_typing.AudioSample, *, loop: bool = False) -> Echo:
 //|         """Plays the sample once when loop=False and continuously when loop=True.
 //|         Does not block. Use `playing` to block.
 //|
-//|         The sample must match the encoding settings given in the constructor."""
+//|         The sample must match the encoding settings given in the constructor.
+//|
+//|         :return: The effect object itself. Can be used for chaining, ie:
+//|           ``audio.play(effect.play(sample))``.
+//|         :rtype: Echo"""
 //|         ...
 //|
 static mp_obj_t audiodelays_echo_obj_play(size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) {
@@ -252,7 +256,7 @@ static mp_obj_t audiodelays_echo_obj_play(size_t n_args, const mp_obj_t *pos_arg
     mp_obj_t sample = args[ARG_sample].u_obj;
     common_hal_audiodelays_echo_play(self, sample, args[ARG_loop].u_bool);
 
-    return mp_const_none;
+    return MP_OBJ_FROM_PTR(self);
 }
 MP_DEFINE_CONST_FUN_OBJ_KW(audiodelays_echo_play_obj, 1, audiodelays_echo_obj_play);
 

shared-bindings/audiodelays/MultiTapDelay.c

@@ -233,11 +233,15 @@ MP_DEFINE_CONST_FUN_OBJ_1(audiodelays_multi_tap_delay_get_playing_obj, audiodela
 MP_PROPERTY_GETTER(audiodelays_multi_tap_delay_playing_obj,
     (mp_obj_t)&audiodelays_multi_tap_delay_get_playing_obj);
 
-//|     def play(self, sample: circuitpython_typing.AudioSample, *, loop: bool = False) -> None:
+//|     def play(self, sample: circuitpython_typing.AudioSample, *, loop: bool = False) -> MultiTapDelay:
 //|         """Plays the sample once when loop=False and continuously when loop=True.
 //|         Does not block. Use `playing` to block.
 //|
-//|         The sample must match the encoding settings given in the constructor."""
+//|         The sample must match the encoding settings given in the constructor.
+//|
+//|         :return: The effect object itself. Can be used for chaining, ie:
+//|           ``audio.play(effect.play(sample))``.
+//|         :rtype: MultiTapDelay"""
 //|         ...
 //|
 static mp_obj_t audiodelays_multi_tap_delay_obj_play(size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) {
@@ -255,7 +259,7 @@ static mp_obj_t audiodelays_multi_tap_delay_obj_play(size_t n_args, const mp_obj
     mp_obj_t sample = args[ARG_sample].u_obj;
     common_hal_audiodelays_multi_tap_delay_play(self, sample, args[ARG_loop].u_bool);
 
-    return mp_const_none;
+    return MP_OBJ_FROM_PTR(self);
 }
 MP_DEFINE_CONST_FUN_OBJ_KW(audiodelays_multi_tap_delay_play_obj, 1, audiodelays_multi_tap_delay_obj_play);
 

shared-bindings/audiodelays/PitchShift.c

@@ -190,11 +190,15 @@ MP_PROPERTY_GETTER(audiodelays_pitch_shift_playing_obj,
     (mp_obj_t)&audiodelays_pitch_shift_get_playing_obj);
 
 
-//|     def play(self, sample: circuitpython_typing.AudioSample, *, loop: bool = False) -> None:
+//|     def play(self, sample: circuitpython_typing.AudioSample, *, loop: bool = False) -> PitchShift:
 //|         """Plays the sample once when loop=False and continuously when loop=True.
 //|         Does not block. Use `playing` to block.
 //|
-//|         The sample must match the encoding settings given in the constructor."""
+//|         The sample must match the encoding settings given in the constructor.
+//|
+//|         :return: The effect object itself. Can be used for chaining, ie:
+//|           ``audio.play(effect.play(sample))``.
+//|         :rtype: PitchShift"""
 //|         ...
 //|
 static mp_obj_t audiodelays_pitch_shift_obj_play(size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) {
@@ -211,7 +215,7 @@ static mp_obj_t audiodelays_pitch_shift_obj_play(size_t n_args, const mp_obj_t *
     mp_obj_t sample = args[ARG_sample].u_obj;
     common_hal_audiodelays_pitch_shift_play(self, sample, args[ARG_loop].u_bool);
 
-    return mp_const_none;
+    return MP_OBJ_FROM_PTR(self);
 }
 MP_DEFINE_CONST_FUN_OBJ_KW(audiodelays_pitch_shift_play_obj, 1, audiodelays_pitch_shift_obj_play);
 

shared-bindings/audiofilters/Distortion.c

@@ -309,11 +309,15 @@ MP_DEFINE_CONST_FUN_OBJ_1(audiofilters_distortion_get_playing_obj, audiofilters_
 MP_PROPERTY_GETTER(audiofilters_distortion_playing_obj,
     (mp_obj_t)&audiofilters_distortion_get_playing_obj);
 
-//|     def play(self, sample: circuitpython_typing.AudioSample, *, loop: bool = False) -> None:
+//|     def play(self, sample: circuitpython_typing.AudioSample, *, loop: bool = False) -> Distortion:
 //|         """Plays the sample once when loop=False and continuously when loop=True.
 //|         Does not block. Use `playing` to block.
 //|
-//|         The sample must match the encoding settings given in the constructor."""
+//|         The sample must match the encoding settings given in the constructor.
+//|
+//|         :return: The effect object itself. Can be used for chaining, ie:
+//|           ``audio.play(effect.play(sample))``.
+//|         :rtype: Distortion"""
 //|         ...
 //|
 static mp_obj_t audiofilters_distortion_obj_play(size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) {
@@ -331,7 +335,7 @@ static mp_obj_t audiofilters_distortion_obj_play(size_t n_args, const mp_obj_t *
     mp_obj_t sample = args[ARG_sample].u_obj;
     common_hal_audiofilters_distortion_play(self, sample, args[ARG_loop].u_bool);
 
-    return mp_const_none;
+    return MP_OBJ_FROM_PTR(self);
 }
 MP_DEFINE_CONST_FUN_OBJ_KW(audiofilters_distortion_play_obj, 1, audiofilters_distortion_obj_play);
 

shared-bindings/audiofilters/Filter.c

@@ -179,11 +179,15 @@ MP_DEFINE_CONST_FUN_OBJ_1(audiofilters_filter_get_playing_obj, audiofilters_filt
 MP_PROPERTY_GETTER(audiofilters_filter_playing_obj,
     (mp_obj_t)&audiofilters_filter_get_playing_obj);
 
-//|     def play(self, sample: circuitpython_typing.AudioSample, *, loop: bool = False) -> None:
+//|     def play(self, sample: circuitpython_typing.AudioSample, *, loop: bool = False) -> Filter:
 //|         """Plays the sample once when loop=False and continuously when loop=True.
 //|         Does not block. Use `playing` to block.
 //|
-//|         The sample must match the encoding settings given in the constructor."""
+//|         The sample must match the encoding settings given in the constructor.
+//|
+//|         :return: The effect object itself. Can be used for chaining, ie:
+//|           ``audio.play(effect.play(sample))``.
+//|         :rtype: Filter"""
 //|         ...
 //|
 static mp_obj_t audiofilters_filter_obj_play(size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) {
@@ -201,7 +205,7 @@ static mp_obj_t audiofilters_filter_obj_play(size_t n_args, const mp_obj_t *pos_
     mp_obj_t sample = args[ARG_sample].u_obj;
     common_hal_audiofilters_filter_play(self, sample, args[ARG_loop].u_bool);
 
-    return mp_const_none;
+    return MP_OBJ_FROM_PTR(self);
 }
 MP_DEFINE_CONST_FUN_OBJ_KW(audiofilters_filter_play_obj, 1, audiofilters_filter_obj_play);
 

shared-bindings/audiofilters/Phaser.c

@@ -214,11 +214,15 @@ MP_DEFINE_CONST_FUN_OBJ_1(audiofilters_phaser_get_playing_obj, audiofilters_phas
 MP_PROPERTY_GETTER(audiofilters_phaser_playing_obj,
     (mp_obj_t)&audiofilters_phaser_get_playing_obj);
 
-//|     def play(self, sample: circuitpython_typing.AudioSample, *, loop: bool = False) -> None:
+//|     def play(self, sample: circuitpython_typing.AudioSample, *, loop: bool = False) -> Phaser:
 //|         """Plays the sample once when loop=False and continuously when loop=True.
 //|         Does not block. Use `playing` to block.
 //|
-//|         The sample must match the encoding settings given in the constructor."""
+//|         The sample must match the encoding settings given in the constructor.
+//|
+//|         :return: The effect object itself. Can be used for chaining, ie:
+//|           ``audio.play(effect.play(sample))``.
+//|         :rtype: Phaser"""
 //|         ...
 //|
 static mp_obj_t audiofilters_phaser_obj_play(size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) {
@@ -236,7 +240,7 @@ static mp_obj_t audiofilters_phaser_obj_play(size_t n_args, const mp_obj_t *pos_
     mp_obj_t sample = args[ARG_sample].u_obj;
     common_hal_audiofilters_phaser_play(self, sample, args[ARG_loop].u_bool);
 
-    return mp_const_none;
+    return MP_OBJ_FROM_PTR(self);
 }
 MP_DEFINE_CONST_FUN_OBJ_KW(audiofilters_phaser_play_obj, 1, audiofilters_phaser_obj_play);
 

shared-bindings/audiofreeverb/Freeverb.c

@@ -196,11 +196,15 @@ MP_DEFINE_CONST_FUN_OBJ_1(audiofreeverb_freeverb_get_playing_obj, audiofreeverb_
 MP_PROPERTY_GETTER(audiofreeverb_freeverb_playing_obj,
     (mp_obj_t)&audiofreeverb_freeverb_get_playing_obj);
 
-//|     def play(self, sample: circuitpython_typing.AudioSample, *, loop: bool = False) -> None:
+//|     def play(self, sample: circuitpython_typing.AudioSample, *, loop: bool = False) -> Freeverb:
 //|         """Plays the sample once when loop=False and continuously when loop=True.
 //|         Does not block. Use `playing` to block.
 //|
-//|         The sample must match the encoding settings given in the constructor."""
+//|         The sample must match the encoding settings given in the constructor.
+//|
+//|         :return: The effect object itself. Can be used for chaining, ie:
+//|           ``audio.play(effect.play(sample))``.
+//|         :rtype: Freeverb"""
 //|         ...
 //|
 static mp_obj_t audiofreeverb_freeverb_obj_play(size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) {
@@ -218,7 +222,7 @@ static mp_obj_t audiofreeverb_freeverb_obj_play(size_t n_args, const mp_obj_t *p
     mp_obj_t sample = args[ARG_sample].u_obj;
     common_hal_audiofreeverb_freeverb_play(self, sample, args[ARG_loop].u_bool);
 
-    return mp_const_none;
+    return MP_OBJ_FROM_PTR(self);
 }
 MP_DEFINE_CONST_FUN_OBJ_KW(audiofreeverb_freeverb_play_obj, 1, audiofreeverb_freeverb_obj_play);
 

shared-bindings/audiomixer/Mixer.c

@@ -160,13 +160,17 @@ MP_PROPERTY_GETTER(audiomixer_mixer_voice_obj,
 
 //|     def play(
 //|         self, sample: circuitpython_typing.AudioSample, *, voice: int = 0, loop: bool = False
-//|     ) -> None:
+//|     ) -> Mixer:
 //|         """Plays the sample once when loop=False and continuously when loop=True.
 //|         Does not block. Use `playing` to block.
 //|
 //|         Sample must be an `audiocore.WaveFile`, `audiocore.RawSample`, `audiomixer.Mixer` or `audiomp3.MP3Decoder`.
 //|
-//|         The sample must match the Mixer's encoding settings given in the constructor."""
+//|         The sample must match the Mixer's encoding settings given in the constructor.
+//|
+//|         :return: The mixer object itself. Can be used for chaining, ie:
+//|           ``audio.play(mixer.play(sample))``.
+//|         :rtype: Chorus"""
 //|         ...
 //|
 static mp_obj_t audiomixer_mixer_obj_play(size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) {
@@ -189,7 +193,7 @@ static mp_obj_t audiomixer_mixer_obj_play(size_t n_args, const mp_obj_t *pos_arg
     mp_obj_t sample = args[ARG_sample].u_obj;
     common_hal_audiomixer_mixervoice_play(voice, sample, args[ARG_loop].u_bool);
 
-    return mp_const_none;
+    return MP_OBJ_FROM_PTR(self);
 }
 MP_DEFINE_CONST_FUN_OBJ_KW(audiomixer_mixer_play_obj, 1, audiomixer_mixer_obj_play);