Add the av_player_will_play_tags hook (#1842)

A general version of the reviewer_will_play_question_sounds and reviewer_will_play_answer_sounds hooks

qt/aqt/browser/previewer.py

@@ -216,11 +216,11 @@ class Previewer(QDialog):
                     audio = c.question_av_tags()
                 else:
                     audio = c.answer_av_tags()
-                av_player.play_tags(audio)
             else:
+                audio = []
                 self._web.setPlaybackRequiresGesture(True)
-                av_player.clear_queue_and_maybe_interrupt()
+            gui_hooks.av_player_will_play_tags(audio, self._state, self)
-
+            av_player.play_tags(audio)
             txt = self.mw.prepare_card_text_for_display(txt)
             txt = gui_hooks.card_will_show(txt, c, f"preview{self._state.capitalize()}")
             self._last_state = self._state_and_mod()

qt/aqt/clayout.py

@@ -548,10 +548,16 @@ class CardLayout(QDialog):
                     audio = c.question_av_tags()
                 else:
                     audio = c.answer_av_tags()
-                av_player.play_tags(audio)
             else:
+                audio = []
                 self.preview_web.setPlaybackRequiresGesture(True)
-                av_player.clear_queue_and_maybe_interrupt()
+            side = "question" if self.pform.preview_front.isChecked() else "answer"
+            gui_hooks.av_player_will_play_tags(
+                audio,
+                side,
+                self,
+            )
+            av_player.play_tags(audio)
 
         self.updateCardNames()
 

qt/aqt/reviewer.py

@@ -340,12 +340,11 @@ class Reviewer:
             self.web.setPlaybackRequiresGesture(False)
             sounds = c.question_av_tags()
             gui_hooks.reviewer_will_play_question_sounds(c, sounds)
-            av_player.play_tags(sounds)
         else:
             self.web.setPlaybackRequiresGesture(True)
-            av_player.clear_queue_and_maybe_interrupt()
             sounds = []
             gui_hooks.reviewer_will_play_question_sounds(c, sounds)
+        gui_hooks.av_player_will_play_tags(sounds, self.state, self)
         av_player.play_tags(sounds)
         # render & update bottom
         q = self._mungeQA(q)
@@ -392,11 +391,10 @@ class Reviewer:
         if c.autoplay():
             sounds = c.answer_av_tags()
             gui_hooks.reviewer_will_play_answer_sounds(c, sounds)
-            av_player.play_tags(sounds)
         else:
-            av_player.clear_queue_and_maybe_interrupt()
             sounds = []
             gui_hooks.reviewer_will_play_answer_sounds(c, sounds)
+        gui_hooks.av_player_will_play_tags(sounds, self.state, self)
         av_player.play_tags(sounds)
         a = self._mungeQA(a)
         a = gui_hooks.card_will_show(a, c, "reviewAnswer")

qt/tools/genhooks_gui.py

@@ -925,6 +925,29 @@ gui_hooks.webview_did_inject_style_into_page.append(mytest)
         args=["player: aqt.sound.Player", "tag: anki.sound.AVTag"],
     ),
     Hook(name="av_player_did_end_playing", args=["player: aqt.sound.Player"]),
+    Hook(
+        name="av_player_will_play_tags",
+        args=[
+            "tags: list[anki.sound.AVTag]",
+            "side: str",
+            "context: Any",
+        ],
+        doc="""Called before playing a card side's sounds.
+
+        `tags` can be used to inspect and manipulate the sounds
+        that will be played (if any).
+
+        `side` can either be "question" or "answer".
+
+        `context` is the screen where the sounds will be played (e.g., Reviewer, Previewer, and CardLayout).
+
+        This won't be called when the user manually plays sounds
+        using `Replay Audio`.
+
+        Note that this hook is called even when the `Automatically play audio`
+        option is unchecked; This is so as to allow playing custom
+        sounds regardless of that option.""",
+    ),
     # Addon
     ###################
     Hook(