Merge pull request #62306 from Calinou/doc-moviewriter

Document the MovieWriter class and associated project settings

3 files changed, 42 insertions, 0 deletions

diff --git a/doc/classes/Image.xml b/doc/classes/Image.xml
index 5472ffe4da..d2baf78a9e 100644
--- a/doc/classes/Image.xml
+++ b/doc/classes/Image.xml
@@ -385,12 +385,16 @@
 			<argument index="0" name="path" type="String" />
 			<argument index="1" name="quality" type="float" default="0.75" />
 			<description>
+				Saves the image as a JPEG file to [code]path[/code] with the specified [code]quality[/code] between [code]0.01[/code] and [code]1.0[/code] (inclusive). Higher [code]quality[/code] values result in better-looking output at the cost of larger file sizes. Recommended [code]quality[/code] values are between [code]0.75[/code] and [code]0.90[/code]. Even at quality [code]1.00[/code], JPEG compression remains lossy.
+				[b]Note:[/b] JPEG does not save an alpha channel. If the [Image] contains an alpha channel, the image will still be saved, but the resulting JPEG file won't contain the alpha channel.
 			</description>
 		</method>
 		<method name="save_jpg_to_buffer" qualifiers="const">
 			<return type="PackedByteArray" />
 			<argument index="0" name="quality" type="float" default="0.75" />
 			<description>
+				Saves the image as a JPEG file to a byte array with the specified [code]quality[/code] between [code]0.01[/code] and [code]1.0[/code] (inclusive). Higher [code]quality[/code] values result in better-looking output at the cost of larger byte array sizes (and therefore memory usage). Recommended [code]quality[/code] values are between [code]0.75[/code] and [code]0.90[/code]. Even at quality [code]1.00[/code], JPEG compression remains lossy.
+				[b]Note:[/b] JPEG does not save an alpha channel. If the [Image] contains an alpha channel, the image will still be saved, but the resulting byte array won't contain the alpha channel.
 			</description>
 		</method>
 		<method name="save_png" qualifiers="const">
diff --git a/doc/classes/MovieWriter.xml b/doc/classes/MovieWriter.xml
index 6cc3829b20..9c713bd7ae 100644
--- a/doc/classes/MovieWriter.xml
+++ b/doc/classes/MovieWriter.xml
@@ -1,8 +1,16 @@
 <?xml version="1.0" encoding="UTF-8" ?>
 <class name="MovieWriter" inherits="Object" version="4.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
 	<brief_description>
+		Abstract class for non-real-time video recording encoders.
 	</brief_description>
 	<description>
+		Godot can record videos with non-real-time simulation. Like the [code]--fixed-fps[/code] command line argument, this forces the reported [code]delta[/code] in [method Node._process] functions to be identical across frames, regardless of how long it actually took to render the frame. This can be used to record high-quality videos with perfect frame pacing regardless of your hardware's capabilities.
+		Godot has 2 built-in [MovieWriter]s:
+		- AVI container with MJPEG for video and uncompressed audio ([code].avi[/code] file extension). Lossy compression, medium file sizes, fast encoding. The lossy compression quality can be adjusted by changing [member ProjectSettings.editor/movie_writer/mjpeg_quality]. The resulting file can be viewed in most video players, but it must be converted to another format for viewing on the web or by Godot with [VideoStreamPlayer]. AVI output is currently limited to a file of 4 GB in size at most.
+		- PNG image sequence for video and WAV for audio ([code].png[/code] file extension). Lossless compression, large file sizes, slow encoding. Designed to be encoded to a video file with another tool such as [url=https://ffmpeg.org/]FFmpeg[/url] after recording. Transparency is currently not supported.
+		If you need to encode to a different format or pipe a stream through third-party software, you can extend the [MovieWriter] class to create your own movie writers. This should typically be done using GDExtension for performance reasons.
+		[b]Editor usage:[/b] A default movie file path can be specified in [member ProjectSettings.editor/movie_writer/movie_file]. Alternatively, for running single scenes, a [code]movie_path[/code] metadata can be added to the root node, specifying the path to a movie file that will be used when recording that scene. Once a path is set, click the video reel icon in the top-right corner of the editor to enable Movie Maker mode, then run any scene as usual. The engine will start recording as soon as the splash screen is finished, and it will only stop recording when the engine quits. Click the video reel icon again to disable Movie Maker mode. Note that toggling Movie Maker mode does not affect project instances that are already running.
+		[b]Note:[/b] MovieWriter is available for use in both the editor and exported projects, but it is [i]not[/i] designed for use by end users to record videos while playing. Players wishing to record gameplay videos should install tools such as [url=https://obsproject.com/]OBS Studio[/url] or [url=https://www.maartenbaert.be/simplescreenrecorder/]SimpleScreenRecorder[/url] instead.
 	</description>
 	<tutorials>
 	</tutorials>
@@ -10,17 +18,26 @@
 		<method name="_get_audio_mix_rate" qualifiers="virtual const">
 			<return type="int" />
 			<description>
+				Called when the audio sample rate used for recording the audio is requested by the engine. The value returned must be specified in Hz. Defaults to 48000 Hz if [method _get_audio_mix_rate] is not overridden.
 			</description>
 		</method>
 		<method name="_get_audio_speaker_mode" qualifiers="virtual const">
 			<return type="int" enum="AudioServer.SpeakerMode" />
 			<description>
+				Called when the audio speaker mode used for recording the audio is requested by the engine. This can affect the number of output channels in the resulting audio file/stream. Defaults to [constant AudioServer.SPEAKER_MODE_STEREO] if [method _get_audio_speaker_mode] is not overridden.
 			</description>
 		</method>
 		<method name="_handles_file" qualifiers="virtual const">
 			<return type="bool" />
 			<argument index="0" name="path" type="String" />
 			<description>
+				Called when the engine determines whether this [MovieWriter] is able to handle the file at [code]path[/code]. Must return [code]true[/code] if this [MovieWriter] is able to handle the given file path, [code]false[/code] otherwise. Typically, [method _handles_file] is overridden as follows to allow the user to record a file at any path with a given file extension:
+				[codeblock]
+				func _handles_file(path):
+				    # Allows specifying an output file with a `.mkv` file extension (case-insensitive),
+				    # either in the Project Settings or with the `--write-movie &lt;path&gt;` command line argument.
+				    return path.get_extension().to_lower() == "mkv"
+				[/codeblock]
 			</description>
 		</method>
 		<method name="_write_begin" qualifiers="virtual">
@@ -29,11 +46,14 @@
 			<argument index="1" name="fps" type="int" />
 			<argument index="2" name="base_path" type="String" />
 			<description>
+				Called once before the engine starts writing video and audio data. [code]movie_size[/code] is the width and height of the video to save. [code]fps[/code] is the number of frames per second specified in the project settings or using the [code]--fixed-fps &lt;fps&gt;[/code] command line argument.
 			</description>
 		</method>
 		<method name="_write_end" qualifiers="virtual">
 			<return type="void" />
 			<description>
+				Called when the engine finishes writing. This occurs when the engine quits by pressing the window manager's close button, or when [method SceneTree.quit] is called.
+				[b]Note:[/b] Pressing [kbd]Ctrl + C[/kbd] on the terminal running the editor/project does [i]not[/i] result in [method _write_end] being called.
 			</description>
 		</method>
 		<method name="_write_frame" qualifiers="virtual">
@@ -41,12 +61,15 @@
 			<argument index="0" name="frame_image" type="Image" />
 			<argument index="1" name="audio_frame_block" type="const void*" />
 			<description>
+				Called at the end of every rendered frame. The [code]frame_image[/code] and [code]audio_frame_block[/code] function arguments should be written to.
 			</description>
 		</method>
 		<method name="add_writer" qualifiers="static">
 			<return type="void" />
 			<argument index="0" name="writer" type="MovieWriter" />
 			<description>
+				Adds a writer to be usable by the engine. The supported file extensions can be set by overridding [method _handles_file].
+				[b]Note:[/b] [method add_writer] must be called early enough in the engine initialization to work, as movie writing is designed to start at the same time as the rest of the engine.
 			</description>
 		</method>
 	</methods>
diff --git a/doc/classes/ProjectSettings.xml b/doc/classes/ProjectSettings.xml
index 3d939a6926..fc86b67c60 100644
--- a/doc/classes/ProjectSettings.xml
+++ b/doc/classes/ProjectSettings.xml
@@ -554,16 +554,31 @@
 			Depending on the platform and used renderer, the engine will fall back to [code]Enabled[/code], if the desired mode is not supported.
 		</member>
 		<member name="editor/movie_writer/disable_vsync" type="bool" setter="" getter="" default="false">
+			If [code]true[/code], requests V-Sync to be disabled when writing a movie (similar to setting [member display/window/vsync/vsync_mode] to [b]Disabled[/b]). This can speed up video writing if the hardware is fast enough to render, encode and save the video at a framerate higher than the monitor's refresh rate.
+			[b]Note:[/b] [member editor/movie_writer/disable_vsync] has no effect if the operating system or graphics driver forces V-Sync with no way for applications to disable it.
 		</member>
 		<member name="editor/movie_writer/fps" type="int" setter="" getter="" default="60">
+			The number of frames per second to record in the video when writing a movie. Simulation speed will adjust to always match the specified framerate, which means the engine will appear to run slower at higher [member editor/movie_writer/fps] values. Certain FPS values will require you to adjust [member editor/movie_writer/mix_rate_hz] to prevent audio from desynchronizing over time.
+			This can be specified manually on the command line using the [code]--fixed-fps &lt;fps&gt;[/code] command line argument.
 		</member>
 		<member name="editor/movie_writer/mix_rate_hz" type="int" setter="" getter="" default="48000">
+			The audio mix rate to use in the recorded audio when writing a movie (in Hz). This can be different from [member audio/driver/mix_rate], but this value must be divisible by [member editor/movie_writer/fps] to prevent audio from desynchronizing over time.
 		</member>
 		<member name="editor/movie_writer/mjpeg_quality" type="float" setter="" getter="" default="0.75">
+			The JPEG quality to use when writing a video to an AVI file, between [code]0.01[/code] and [code]1.0[/code] (inclusive). Higher [code]quality[/code] values result in better-looking output at the cost of larger file sizes. Recommended [code]quality[/code] values are between [code]0.75[/code] and [code]0.90[/code]. Even at quality [code]1.00[/code], JPEG compression remains lossy.
+			[b]Note:[/b] JPEG does not saving an alpha channel. If the [Image] contains an alpha channel, the image will still be saved, but the resulting JPEG file won't contain the alpha channel.
+			[b]Note:[/b] This does not affect the audio quality or writing PNG image sequences.
 		</member>
 		<member name="editor/movie_writer/movie_file" type="String" setter="" getter="" default="&quot;&quot;">
+			The output path for the movie. The file extension determines the [MovieWriter] that will be used.
+			Godot has 2 built-in [MovieWriter]s:
+			- AVI container with MJPEG for video and uncompressed audio ([code].avi[/code] file extension). Lossy compression, medium file sizes, fast encoding. The lossy compression quality can be adjusted by changing [member ProjectSettings.editor/movie_writer/mjpeg_quality]. The resulting file can be viewed in most video players, but it must be converted to another format for viewing on the web or by Godot with [VideoStreamPlayer]. AVI output is currently limited to a file of 4 GB in size at most.
+			- PNG image sequence for video and WAV for audio ([code].png[/code] file extension). Lossless compression, large file sizes, slow encoding. Designed to be encoded to a video file with another tool such as [url=https://ffmpeg.org/]FFmpeg[/url] after recording. Transparency is currently not supported.
+			If you need to encode to a different format or pipe a stream through third-party software, you can extend this [MovieWriter] class to create your own movie writers.
+			When using PNG output, the frame number will be appended at the end of the file name. It starts from 0 and is padded with 8 digits to ensure correct sorting and easier processing. For example, if the output path is [code]/tmp/hello.png[/code], the first two frames will be [code]/tmp/hello00000000.png[/code] and [code]/tmp/hello00000001.png[/code]. The audio will be saved at [code]/tmp/hello.wav[/code].
 		</member>
 		<member name="editor/movie_writer/speaker_mode" type="int" setter="" getter="" default="0">
+			The speaker mode to use in the recorded audio when writing a movie. See [enum AudioServer.SpeakerMode] for possible values.
 		</member>
 		<member name="editor/node_naming/name_casing" type="int" setter="" getter="" default="0">
 			When creating node names automatically, set the type of casing in this project. This is mostly an editor setting.