Add support for embedding videos in documentation pages

This is more efficient than GIFs, animated PNGs or WebPs, while also
providing controls and audio playback if needed.

conf.py

@@ -18,6 +18,7 @@ extensions = [
     "notfound.extension",
     "sphinxext.opengraph",
     "sphinx_copybutton",
+    "sphinxcontrib.video",
 ]
 
 # Warning when the Sphinx Tabs extension is used with unknown

contributing/documentation/docs_image_guidelines.rst

@@ -1,16 +1,19 @@
 .. _docs_image_guidelines:
 
-Creating documentation images
-=============================
+Creating documentation images and videos
+========================================
 
-Throughout documentation images are often needed to make the explanation
+Throughout the documentation, images are often needed to make the explanation
 of a feature or concept as clear as possible for a reader. This page will
 explain the process from beginning to end.
 
+Images
+------
+
 Capturing an image
-------------------
+^^^^^^^^^^^^^^^^^^
 
-To take a picture of something in Godot a screen capture tool can be used.
+To take a picture of something in Godot, a screen capture tool can be used.
 
 On Windows 10 and 11 that would be the Snip & Sketch program.
 Pressing :kbd:`Windows + Shift + S` lets you take a screenshot
@@ -34,7 +37,7 @@ resolution screen the screenshot should be scaled down. There are instructions
 on how to do this later on this page.
 
 Format conversion
------------------
+^^^^^^^^^^^^^^^^^
 
 The current format for images in Godot's documentation is WebP (``.webp``).
 While some Linux programs will support saving screenshots in this format, macOS
@@ -43,7 +46,7 @@ editing, such as precise cropping or adding outlines, Squoosh can be used.
 `Squoosh <https://squoosh.app/>`_ is a converter developed by Google, is open
 source, and doesn't give Google any image rights by using it. When choosing
 compression if you can get an image that's under 300KB in size use lossless
-compression. If it's over 300KB use just enough lossy compression to get it
+compression. If it's over 300KB, use just enough lossy compression to get it
 under that size. If this results in noticable compression artifacts using less
 compression is fine, even if the file size is bigger.
 
@@ -51,9 +54,9 @@ If you already have an image editor such as GIMP, Krita or Photoshop installed
 it may have the ability to open an image then save it as a WebP file.
 
 Cropping
---------
+^^^^^^^^
 
-For a screenshot of a 2D or 3D scene in the editor the above steps will be enough.
+For a screenshot of a 2D or 3D scene in the editor, the above steps will be enough.
 But for most UI images some extra work should be done, specifically cropping to
 make an image look clean. Below is an example of good cropping.
 
@@ -86,7 +89,7 @@ Krita and can be adjusted. Click on the image with your cropping tool still sele
 and the controls will return.
 
 Scaling down an image
----------------------
+^^^^^^^^^^^^^^^^^^^^^
 
 As explained earlier on this page, all images taken on a screen that is a higher resolution
 than 1080p should be scaled down. To do this in Krita click on **Image** on the top bar, and
@@ -98,7 +101,7 @@ sure the **Constrain Proportions** box at the bottom of the menu is checked so y
 to change 1 value.
 
 Saving as WebP in Krita
------------------------
+^^^^^^^^^^^^^^^^^^^^^^^
 
 To save an image as webp if it isn't already one, Go to **File > Save As**. Select **webp** from the
 **Save as type:** dropdown, then choose wherever you want to save it. After clicking **Save** a menu
@@ -110,8 +113,8 @@ If it's still over 300KB change to lossy compression and slowly increase the com
 300KB. If this results in noticable compression artifacts using less compression is fine, even if the file
 size is bigger.
 
-Outlines arrows and text
-------------------------
+Outlines, arrows and text
+^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Sometimes an image needs something extra to properly direct the readers
 attention, or make something clear. Outlines and arrows can be used
@@ -136,7 +139,7 @@ be used if appropriate. For example, if yellow blends into the image, or if ther
 multiple outlines in multiple colors.
 
 Adding an image to a documentation page
----------------------------------------
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Once you've finished working on your image, it can be added to the documentation.
 All images are stored in folders named ``img`` next to the page they are used in.
@@ -150,3 +153,93 @@ images should be included with the following code snippet::
 Where ``documentation_image.webp`` would be changed to the name of the image you
 created. Name your images in a way that makes their meaning clear, possibly with
 a prefix that makes their relationship to a documentation page explicit.
+
+Videos
+------
+
+Capturing a video
+^^^^^^^^^^^^^^^^^
+
+To record a video of something in Godot, a screen capture tool can be used.
+Operating systems generally don't come with tools that are flexible enough
+for this, so you'll need to install a third-party utility.
+
+`OBS Studio <https://obsproject.com/>`__ is the most popular option, but
+`SimpleScreenRecorder <https://www.maartenbaert.be/simplescreenrecorder/>`__
+can be used as an alternative on Linux. `ShareX <https://getsharex.com/>`__
+can be used as an alternative on Windows. All these tools can be configured
+to record the entire screen, a specific window or a predetermined rectangle.
+
+The recommended framerate for video recordings is 60 FPS, although you can use
+30 FPS for longer videos to reduce their file size. For fullscreen videos,
+use a resolution of 1280×720.
+
+.. note::
+
+    Godot's :ref:`Movie Maker mode <doc_creating_movies>` can be used to record
+    the output of a running project, including its audio. This doesn't require
+    installing any third-party software and avoids any frame drops (even when
+    recording on a slow device), but it's less flexible.
+
+Compressing the captured video
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The recommendation is to record your video in the highest quality possible
+(without dropping frames due to excessive CPU/GPU utilization), then re-encode
+it later to reduce its file size. This results in more efficient compression
+than directly aiming for a small file size, as real-time compression methods are
+less efficient than slower compression methods.
+
+To re-encode videos for a smaller file size, use `HandBrake <https://handbrake.fr/>`__
+or the `FFmpeg <https://ffmpeg.org/>` command line below:
+
+::
+
+    ffmpeg -i input.mp4 -crf 23 output.webm
+
+The number after ``-crf`` adjusts the video quality, with higher numbers
+resulting in *lower* quality (and smaller file sizes). A CRF of ``23`` is a good
+starting point, but you may need to use a higher value for longer videos to
+ensure the file size remains reasonable. Try to aim for a file size under 2 MB
+if possible.
+
+If the video was recorded in a higher resolution or framerate, you can adjust
+its output resolution and framerate as follows:
+
+::
+
+    ffmpeg -i input.mp4 -crf 23 -vf scale=1280:-2 -r 30 output.webm
+
+This results in a video resolution around 1280×720 at 30 FPS. The exact
+video resolution will vary depending on the source's aspect ratio.
+
+.. tip::
+
+    If the video was recorded with an audio track but this audio track is not
+    necessary, consider stripping it by adding the ``-an`` option to the FFmpeg
+    command line (before the output file name). This will reduce file size and
+    also ensure audio controls don't show up on the video when played in a
+    browser.
+
+Adding a video to a documentation page
+--------------------------------------
+
+Once you've finished working on your video, it can be added to the documentation.
+All videos are stored in folders named ``video`` next to the page they are used in.
+
+To add your video, add it to the ``video`` folder that's in the same folder as the
+``.rst`` file for the page (create it if it doesn't exist). In the ``.rst`` page,
+videos should be included with the following code snippet::
+
+    .. video:: video/csg_tools.webm
+       :alt: Put a text description of the video here
+       :autoplay:
+       :loop:
+       :muted:
+
+Where ``documentation_video.webp`` would be changed to the name of the video you
+created. Name your videos in a way that makes their meaning clear, possibly with
+a prefix that makes their relationship to a documentation page explicit.
+
+The ``:autoplay:``, ``:loop:`` and ``:muted:`` flags should always be specified
+unless the video needs to play audio. In this case, do not specify *any* of these flags.

requirements.txt

@@ -26,3 +26,6 @@ sphinxcontrib-htmlhelp==2.0.1
 sphinxcontrib-qthelp==1.0.3
 sphinxcontrib-serializinghtml==1.1.5
 sphinxcontrib-devhelp==1.0.2
+
+# `.. video::` directive support to embed videos in documentation pages.
+sphinxcontrib-video==0.2.1rc0

tutorials/3d/csg_tools.rst

@@ -25,7 +25,11 @@ Interior environments can be created by using inverted primitives.
           `TrenchBroom <https://kristianduske.com/trenchbroom/>`__ and import
           them in Godot.
 
-.. image:: img/csg.gif
+.. video:: video/csg_tools.webm
+   :alt: CSG being used to subtract a torus shape from a box
+   :autoplay:
+   :loop:
+   :muted:
 
 .. seealso::