From 908e1341c152c383316fb96aebe11700d222057a Mon Sep 17 00:00:00 2001
From: Cooper Dalrymple <dcooperdalrymple@gmail.com>
Date: Tue, 16 Sep 2025 08:33:17 -0500
Subject: [PATCH 1/3] Return self object from `play` methods to allow for
 chaining

---
 shared-bindings/audiodelays/Chorus.c        | 4 ++--
 shared-bindings/audiodelays/Echo.c          | 4 ++--
 shared-bindings/audiodelays/MultiTapDelay.c | 4 ++--
 shared-bindings/audiodelays/PitchShift.c    | 4 ++--
 shared-bindings/audiofilters/Distortion.c   | 4 ++--
 shared-bindings/audiofilters/Filter.c       | 4 ++--
 shared-bindings/audiofilters/Phaser.c       | 4 ++--
 shared-bindings/audiofreeverb/Freeverb.c    | 4 ++--
 shared-bindings/audiomixer/Mixer.c          | 4 ++--
 9 files changed, 18 insertions(+), 18 deletions(-)

diff --git a/shared-bindings/audiodelays/Chorus.c b/shared-bindings/audiodelays/Chorus.c
index c6bfa2ffa7eb1..67b9bc32745c4 100644
--- a/shared-bindings/audiodelays/Chorus.c
+++ b/shared-bindings/audiodelays/Chorus.c
@@ -206,7 +206,7 @@ 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.
 //|
@@ -228,7 +228,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 pos_args[0];
 }
 MP_DEFINE_CONST_FUN_OBJ_KW(audiodelays_chorus_play_obj, 1, audiodelays_chorus_obj_play);
 
diff --git a/shared-bindings/audiodelays/Echo.c b/shared-bindings/audiodelays/Echo.c
index 5ae849b19aa41..68216d2355b70 100644
--- a/shared-bindings/audiodelays/Echo.c
+++ b/shared-bindings/audiodelays/Echo.c
@@ -230,7 +230,7 @@ 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.
 //|
@@ -252,7 +252,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 pos_args[0];
 }
 MP_DEFINE_CONST_FUN_OBJ_KW(audiodelays_echo_play_obj, 1, audiodelays_echo_obj_play);
 
diff --git a/shared-bindings/audiodelays/MultiTapDelay.c b/shared-bindings/audiodelays/MultiTapDelay.c
index 5b057eaf80d1b..ce11b2f1d3c61 100644
--- a/shared-bindings/audiodelays/MultiTapDelay.c
+++ b/shared-bindings/audiodelays/MultiTapDelay.c
@@ -233,7 +233,7 @@ 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.
 //|
@@ -255,7 +255,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 pos_args[0];
 }
 MP_DEFINE_CONST_FUN_OBJ_KW(audiodelays_multi_tap_delay_play_obj, 1, audiodelays_multi_tap_delay_obj_play);
 
diff --git a/shared-bindings/audiodelays/PitchShift.c b/shared-bindings/audiodelays/PitchShift.c
index df2189945aa5d..e595beec6b8de 100644
--- a/shared-bindings/audiodelays/PitchShift.c
+++ b/shared-bindings/audiodelays/PitchShift.c
@@ -190,7 +190,7 @@ 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.
 //|
@@ -211,7 +211,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 pos_args[0];
 }
 MP_DEFINE_CONST_FUN_OBJ_KW(audiodelays_pitch_shift_play_obj, 1, audiodelays_pitch_shift_obj_play);
 
diff --git a/shared-bindings/audiofilters/Distortion.c b/shared-bindings/audiofilters/Distortion.c
index cb888d0c71b7b..3120111ca9a80 100644
--- a/shared-bindings/audiofilters/Distortion.c
+++ b/shared-bindings/audiofilters/Distortion.c
@@ -309,7 +309,7 @@ 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.
 //|
@@ -331,7 +331,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 pos_args[0];
 }
 MP_DEFINE_CONST_FUN_OBJ_KW(audiofilters_distortion_play_obj, 1, audiofilters_distortion_obj_play);
 
diff --git a/shared-bindings/audiofilters/Filter.c b/shared-bindings/audiofilters/Filter.c
index 2a4887a4d42a2..2d8829d8a815d 100644
--- a/shared-bindings/audiofilters/Filter.c
+++ b/shared-bindings/audiofilters/Filter.c
@@ -179,7 +179,7 @@ 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.
 //|
@@ -201,7 +201,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 pos_args[0];
 }
 MP_DEFINE_CONST_FUN_OBJ_KW(audiofilters_filter_play_obj, 1, audiofilters_filter_obj_play);
 
diff --git a/shared-bindings/audiofilters/Phaser.c b/shared-bindings/audiofilters/Phaser.c
index e7ddd986176b3..daff50e983492 100644
--- a/shared-bindings/audiofilters/Phaser.c
+++ b/shared-bindings/audiofilters/Phaser.c
@@ -214,7 +214,7 @@ 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.
 //|
@@ -236,7 +236,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 pos_args[0];
 }
 MP_DEFINE_CONST_FUN_OBJ_KW(audiofilters_phaser_play_obj, 1, audiofilters_phaser_obj_play);
 
diff --git a/shared-bindings/audiofreeverb/Freeverb.c b/shared-bindings/audiofreeverb/Freeverb.c
index 62c9237a0d271..5e4c9644d2e8d 100644
--- a/shared-bindings/audiofreeverb/Freeverb.c
+++ b/shared-bindings/audiofreeverb/Freeverb.c
@@ -196,7 +196,7 @@ 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.
 //|
@@ -218,7 +218,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 pos_args[0];
 }
 MP_DEFINE_CONST_FUN_OBJ_KW(audiofreeverb_freeverb_play_obj, 1, audiofreeverb_freeverb_obj_play);
 
diff --git a/shared-bindings/audiomixer/Mixer.c b/shared-bindings/audiomixer/Mixer.c
index dda6d06bd500c..0944f58ddbe45 100644
--- a/shared-bindings/audiomixer/Mixer.c
+++ b/shared-bindings/audiomixer/Mixer.c
@@ -160,7 +160,7 @@ 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.
 //|
@@ -189,7 +189,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 pos_args[0];
 }
 MP_DEFINE_CONST_FUN_OBJ_KW(audiomixer_mixer_play_obj, 1, audiomixer_mixer_obj_play);
 

From 2e6dbaf5a00be4429592a8240c2f95c0e1add8ac Mon Sep 17 00:00:00 2001
From: Cooper Dalrymple <dcooperdalrymple@gmail.com>
Date: Tue, 16 Sep 2025 10:09:22 -0500
Subject: [PATCH 2/3] Improve clarity of self reference

---
 shared-bindings/audiodelays/Chorus.c        | 2 +-
 shared-bindings/audiodelays/Echo.c          | 2 +-
 shared-bindings/audiodelays/MultiTapDelay.c | 2 +-
 shared-bindings/audiodelays/PitchShift.c    | 2 +-
 shared-bindings/audiofilters/Distortion.c   | 2 +-
 shared-bindings/audiofilters/Filter.c       | 2 +-
 shared-bindings/audiofilters/Phaser.c       | 2 +-
 shared-bindings/audiofreeverb/Freeverb.c    | 2 +-
 shared-bindings/audiomixer/Mixer.c          | 2 +-
 9 files changed, 9 insertions(+), 9 deletions(-)

diff --git a/shared-bindings/audiodelays/Chorus.c b/shared-bindings/audiodelays/Chorus.c
index 67b9bc32745c4..94360ee558d5a 100644
--- a/shared-bindings/audiodelays/Chorus.c
+++ b/shared-bindings/audiodelays/Chorus.c
@@ -228,7 +228,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 pos_args[0];
+    return MP_OBJ_FROM_PTR(self);
 }
 MP_DEFINE_CONST_FUN_OBJ_KW(audiodelays_chorus_play_obj, 1, audiodelays_chorus_obj_play);
 
diff --git a/shared-bindings/audiodelays/Echo.c b/shared-bindings/audiodelays/Echo.c
index 68216d2355b70..273d0e8e18dcb 100644
--- a/shared-bindings/audiodelays/Echo.c
+++ b/shared-bindings/audiodelays/Echo.c
@@ -252,7 +252,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 pos_args[0];
+    return MP_OBJ_FROM_PTR(self);
 }
 MP_DEFINE_CONST_FUN_OBJ_KW(audiodelays_echo_play_obj, 1, audiodelays_echo_obj_play);
 
diff --git a/shared-bindings/audiodelays/MultiTapDelay.c b/shared-bindings/audiodelays/MultiTapDelay.c
index ce11b2f1d3c61..75b029600a2c0 100644
--- a/shared-bindings/audiodelays/MultiTapDelay.c
+++ b/shared-bindings/audiodelays/MultiTapDelay.c
@@ -255,7 +255,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 pos_args[0];
+    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);
 
diff --git a/shared-bindings/audiodelays/PitchShift.c b/shared-bindings/audiodelays/PitchShift.c
index e595beec6b8de..c8b4ea4b81c79 100644
--- a/shared-bindings/audiodelays/PitchShift.c
+++ b/shared-bindings/audiodelays/PitchShift.c
@@ -211,7 +211,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 pos_args[0];
+    return MP_OBJ_FROM_PTR(self);
 }
 MP_DEFINE_CONST_FUN_OBJ_KW(audiodelays_pitch_shift_play_obj, 1, audiodelays_pitch_shift_obj_play);
 
diff --git a/shared-bindings/audiofilters/Distortion.c b/shared-bindings/audiofilters/Distortion.c
index 3120111ca9a80..956a14e97e345 100644
--- a/shared-bindings/audiofilters/Distortion.c
+++ b/shared-bindings/audiofilters/Distortion.c
@@ -331,7 +331,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 pos_args[0];
+    return MP_OBJ_FROM_PTR(self);
 }
 MP_DEFINE_CONST_FUN_OBJ_KW(audiofilters_distortion_play_obj, 1, audiofilters_distortion_obj_play);
 
diff --git a/shared-bindings/audiofilters/Filter.c b/shared-bindings/audiofilters/Filter.c
index 2d8829d8a815d..d82208d11ed81 100644
--- a/shared-bindings/audiofilters/Filter.c
+++ b/shared-bindings/audiofilters/Filter.c
@@ -201,7 +201,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 pos_args[0];
+    return MP_OBJ_FROM_PTR(self);
 }
 MP_DEFINE_CONST_FUN_OBJ_KW(audiofilters_filter_play_obj, 1, audiofilters_filter_obj_play);
 
diff --git a/shared-bindings/audiofilters/Phaser.c b/shared-bindings/audiofilters/Phaser.c
index daff50e983492..8472b01505cec 100644
--- a/shared-bindings/audiofilters/Phaser.c
+++ b/shared-bindings/audiofilters/Phaser.c
@@ -236,7 +236,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 pos_args[0];
+    return MP_OBJ_FROM_PTR(self);
 }
 MP_DEFINE_CONST_FUN_OBJ_KW(audiofilters_phaser_play_obj, 1, audiofilters_phaser_obj_play);
 
diff --git a/shared-bindings/audiofreeverb/Freeverb.c b/shared-bindings/audiofreeverb/Freeverb.c
index 5e4c9644d2e8d..de061734997a0 100644
--- a/shared-bindings/audiofreeverb/Freeverb.c
+++ b/shared-bindings/audiofreeverb/Freeverb.c
@@ -218,7 +218,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 pos_args[0];
+    return MP_OBJ_FROM_PTR(self);
 }
 MP_DEFINE_CONST_FUN_OBJ_KW(audiofreeverb_freeverb_play_obj, 1, audiofreeverb_freeverb_obj_play);
 
diff --git a/shared-bindings/audiomixer/Mixer.c b/shared-bindings/audiomixer/Mixer.c
index 0944f58ddbe45..5e5bfdc1f3df9 100644
--- a/shared-bindings/audiomixer/Mixer.c
+++ b/shared-bindings/audiomixer/Mixer.c
@@ -189,7 +189,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 pos_args[0];
+    return MP_OBJ_FROM_PTR(self);
 }
 MP_DEFINE_CONST_FUN_OBJ_KW(audiomixer_mixer_play_obj, 1, audiomixer_mixer_obj_play);
 

From 734209078660bc06103cb48eee460b1625323546 Mon Sep 17 00:00:00 2001
From: Cooper Dalrymple <dcooperdalrymple@gmail.com>
Date: Tue, 16 Sep 2025 10:15:47 -0500
Subject: [PATCH 3/3] Add return type documentation

---
 shared-bindings/audiodelays/Chorus.c        | 6 +++++-
 shared-bindings/audiodelays/Echo.c          | 6 +++++-
 shared-bindings/audiodelays/MultiTapDelay.c | 6 +++++-
 shared-bindings/audiodelays/PitchShift.c    | 6 +++++-
 shared-bindings/audiofilters/Distortion.c   | 6 +++++-
 shared-bindings/audiofilters/Filter.c       | 6 +++++-
 shared-bindings/audiofilters/Phaser.c       | 6 +++++-
 shared-bindings/audiofreeverb/Freeverb.c    | 6 +++++-
 shared-bindings/audiomixer/Mixer.c          | 6 +++++-
 9 files changed, 45 insertions(+), 9 deletions(-)

diff --git a/shared-bindings/audiodelays/Chorus.c b/shared-bindings/audiodelays/Chorus.c
index 94360ee558d5a..87922ff110b1b 100644
--- a/shared-bindings/audiodelays/Chorus.c
+++ b/shared-bindings/audiodelays/Chorus.c
@@ -210,7 +210,11 @@ MP_PROPERTY_GETTER(audiodelays_chorus_playing_obj,
 //|         """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) {
diff --git a/shared-bindings/audiodelays/Echo.c b/shared-bindings/audiodelays/Echo.c
index 273d0e8e18dcb..dbb496c61b975 100644
--- a/shared-bindings/audiodelays/Echo.c
+++ b/shared-bindings/audiodelays/Echo.c
@@ -234,7 +234,11 @@ MP_PROPERTY_GETTER(audiodelays_echo_playing_obj,
 //|         """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) {
diff --git a/shared-bindings/audiodelays/MultiTapDelay.c b/shared-bindings/audiodelays/MultiTapDelay.c
index 75b029600a2c0..2126dbf990435 100644
--- a/shared-bindings/audiodelays/MultiTapDelay.c
+++ b/shared-bindings/audiodelays/MultiTapDelay.c
@@ -237,7 +237,11 @@ MP_PROPERTY_GETTER(audiodelays_multi_tap_delay_playing_obj,
 //|         """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) {
diff --git a/shared-bindings/audiodelays/PitchShift.c b/shared-bindings/audiodelays/PitchShift.c
index c8b4ea4b81c79..b94df7d9edd08 100644
--- a/shared-bindings/audiodelays/PitchShift.c
+++ b/shared-bindings/audiodelays/PitchShift.c
@@ -194,7 +194,11 @@ MP_PROPERTY_GETTER(audiodelays_pitch_shift_playing_obj,
 //|         """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) {
diff --git a/shared-bindings/audiofilters/Distortion.c b/shared-bindings/audiofilters/Distortion.c
index 956a14e97e345..8de4c1d1ea331 100644
--- a/shared-bindings/audiofilters/Distortion.c
+++ b/shared-bindings/audiofilters/Distortion.c
@@ -313,7 +313,11 @@ MP_PROPERTY_GETTER(audiofilters_distortion_playing_obj,
 //|         """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) {
diff --git a/shared-bindings/audiofilters/Filter.c b/shared-bindings/audiofilters/Filter.c
index d82208d11ed81..426fff226168f 100644
--- a/shared-bindings/audiofilters/Filter.c
+++ b/shared-bindings/audiofilters/Filter.c
@@ -183,7 +183,11 @@ MP_PROPERTY_GETTER(audiofilters_filter_playing_obj,
 //|         """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) {
diff --git a/shared-bindings/audiofilters/Phaser.c b/shared-bindings/audiofilters/Phaser.c
index 8472b01505cec..9f713afce5f72 100644
--- a/shared-bindings/audiofilters/Phaser.c
+++ b/shared-bindings/audiofilters/Phaser.c
@@ -218,7 +218,11 @@ MP_PROPERTY_GETTER(audiofilters_phaser_playing_obj,
 //|         """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) {
diff --git a/shared-bindings/audiofreeverb/Freeverb.c b/shared-bindings/audiofreeverb/Freeverb.c
index de061734997a0..12eb7ef70ab79 100644
--- a/shared-bindings/audiofreeverb/Freeverb.c
+++ b/shared-bindings/audiofreeverb/Freeverb.c
@@ -200,7 +200,11 @@ MP_PROPERTY_GETTER(audiofreeverb_freeverb_playing_obj,
 //|         """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) {
diff --git a/shared-bindings/audiomixer/Mixer.c b/shared-bindings/audiomixer/Mixer.c
index 5e5bfdc1f3df9..516d079cd2a09 100644
--- a/shared-bindings/audiomixer/Mixer.c
+++ b/shared-bindings/audiomixer/Mixer.c
@@ -166,7 +166,11 @@ MP_PROPERTY_GETTER(audiomixer_mixer_voice_obj,
 //|
 //|         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) {