Added basic support for adding subcaptions via :meth:.Scene.add_subcaption (#2314)

* added new depependency for subcaption parsing library

* added implementation for subcaptions

* added test for subcaptions

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* fix typo

* added comment to explain offset

* added remark about start time of subcaption

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* clarify documentation entry

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>

Author: behackl

manim/scene/scene.py

@@ -3,6 +3,7 @@
 __all__ = ["Scene"]
 
 import copy
+import datetime
 import inspect
 import platform
 import random
@@ -12,6 +13,8 @@
 from queue import Queue
 from typing import List, Optional
 
+import srt
+
 from manim.scene.section import DefaultSectionType
 
 try:
@@ -899,8 +902,50 @@ def get_run_time(self, animations):
         else:
             return np.max([animation.run_time for animation in animations])
 
-    def play(self, *args, **kwargs):
+    def play(
+        self,
+        *args,
+        subcaption=None,
+        subcaption_duration=None,
+        subcaption_offset=0,
+        **kwargs,
+    ):
+        r"""Plays an animation in this scene.
+
+        Parameters
+        ----------
+
+        args
+            Animations to be played.
+        subcaption
+            The content of the external subcaption that should
+            be added during the animation.
+        subcaption_duration
+            The duration for which the specified subcaption is
+            added. If ``None`` (the default), the run time of the
+            animation is taken.
+        subcaption_offset
+            An offset (in seconds) for the start time of the
+            added subcaption.
+        kwargs
+            All other keywords are passed to the renderer.
+
+        """
+        start_time = self.renderer.time
         self.renderer.play(self, *args, **kwargs)
+        run_time = self.renderer.time - start_time
+        if subcaption:
+            if subcaption_duration is None:
+                subcaption_duration = run_time
+            # The start of the subcaption needs to be offset by the
+            # run_time of the animation because it is added after
+            # the animation has already been played (and Scene.renderer.time
+            # has already been updated).
+            self.add_subcaption(
+                content=subcaption,
+                duration=subcaption_duration,
+                offset=-run_time + subcaption_offset,
+            )
 
     def wait(self, duration=DEFAULT_WAIT_TIME, stop_condition=None):
         self.play(Wait(run_time=duration, stop_condition=stop_condition))
@@ -1242,6 +1287,55 @@ def update_to_time(self, t):
         self.update_meshes(dt)
         self.update_self(dt)
 
+    def add_subcaption(
+        self, content: str, duration: float = 1, offset: float = 0
+    ) -> None:
+        r"""Adds an entry in the corresponding subcaption file
+        at the current time stamp.
+
+        The current time stamp is obtained from ``Scene.renderer.time``.
+
+        Parameters
+        ----------
+
+        content
+            The subcaption content.
+        duration
+            The duration (in seconds) for which the subcaption is shown.
+        offset
+            This offset (in seconds) is added to the starting time stamp
+            of the subcaption.
+
+        Examples
+        --------
+
+        This example illustrates both possibilities for adding
+        subcaptions to Manimations::
+
+            class SubcaptionExample(Scene):
+                def construct(self):
+                    square = Square()
+                    circle = Circle()
+
+                    # first option: via the add_subcaption method
+                    self.add_subcaption("Hello square!", duration=1)
+                    self.play(Create(square))
+
+                    # second option: within the call to Scene.play
+                    self.play(
+                        Transform(square, circle),
+                        subcaption="The square transforms."
+                    )
+
+        """
+        subtitle = srt.Subtitle(
+            index=len(self.renderer.file_writer.subcaptions),
+            content=content,
+            start=datetime.timedelta(seconds=self.renderer.time + offset),
+            end=datetime.timedelta(seconds=self.renderer.time + offset + duration),
+        )
+        self.renderer.file_writer.subcaptions.append(subtitle)
+
     def add_sound(self, sound_file, time_offset=0, gain=None, **kwargs):
         """
         This method is used to add a sound to the animation.

manim/scene/scene_file_writer.py

@@ -12,6 +12,7 @@
 from typing import Any, Dict, List, Optional
 
 import numpy as np
+import srt
 from PIL import Image
 from pydub import AudioSegment
 
@@ -71,6 +72,7 @@ def __init__(self, renderer, scene_name, **kwargs):
         self.init_audio()
         self.frame_count = 0
         self.partial_movie_files: List[str] = []
+        self.subcaptions: List[srt.Subtitle] = []
         self.sections: List[Section] = []
         # first section gets automatically created for convenience
         # if you need the first section to be skipped, add a first section by hand, it will replace this one
@@ -449,6 +451,8 @@ def finish(self):
         elif is_png_format() and not config["dry_run"]:
             target_dir, _ = os.path.splitext(self.image_file_path)
             logger.info("\n%i images ready at %s\n", self.frame_count, target_dir)
+        if self.subcaptions:
+            self.write_subcaption_file()
 
     def open_movie_pipe(self, file_path=None):
         """
@@ -712,6 +716,13 @@ def flush_cache_directory(self):
             {"par_dir": self.partial_movie_directory},
         )
 
+    def write_subcaption_file(self):
+        """Writes the subcaption file."""
+        subcaption_file = Path(config.output_file).with_suffix(".srt")
+        with open(subcaption_file, "w") as f:
+            f.write(srt.compose(self.subcaptions))
+        logger.info(f"Subcaption file has been written as {subcaption_file}")
+
     def print_file_ready_message(self, file_path):
         """Prints the "File Ready" message to STDOUT."""
         config["output_file"] = file_path

poetry.lock

@@ -55,6 +55,7 @@ dearpygui = { version = "^0.8", optional = true }
 screeninfo = "^0.6.7"
 skia-pathops = "^0.7.0"
 isosurfaces = "0.1.0"
+srt = "^3.5.0"
 
 [tool.poetry.extras]
 webgl_renderer = ["grpcio","grpcio-tools"]

pyproject.toml

@@ -1,6 +1,9 @@
+import datetime
+
 import pytest
 
 from manim import Circle, FadeIn, Mobject, Scene, Square, config, tempconfig
+from manim.animation.animation import Wait
 
 
 def test_scene_add_remove():
@@ -46,3 +49,25 @@ def test_scene_time():
         scene.renderer._original_skipping_status = True
         scene.play(FadeIn(Square()), run_time=5)  # this animation gets skipped.
         assert pytest.approx(scene.renderer.time) == 7.5
+
+
+def test_subcaption():
+    with tempconfig({"dry_run": True}):
+        scene = Scene()
+        scene.add_subcaption("Testing add_subcaption", duration=1, offset=0)
+        scene.wait()
+        scene.play(
+            Wait(),
+            run_time=2,
+            subcaption="Testing Scene.play subcaption interface",
+            subcaption_duration=1.5,
+            subcaption_offset=0.5,
+        )
+        subcaptions = scene.renderer.file_writer.subcaptions
+        assert len(subcaptions) == 2
+        assert subcaptions[0].start == datetime.timedelta(seconds=0)
+        assert subcaptions[0].end == datetime.timedelta(seconds=1)
+        assert subcaptions[0].content == "Testing add_subcaption"
+        assert subcaptions[1].start == datetime.timedelta(seconds=1.5)
+        assert subcaptions[1].end == datetime.timedelta(seconds=3)
+        assert subcaptions[1].content == "Testing Scene.play subcaption interface"