creating_movies.rst 16 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377
  1. .. _doc_creating_movies:
  2. Creating movies
  3. ===============
  4. Godot can record **non-real-time** video and audio from any 2D or 3D project.
  5. There are many scenarios where this is useful:
  6. - Recording game trailers for promotional use.
  7. - Recording cutscenes that will be :ref:`displayed as pre-recorded videos <doc_playing_videos>`
  8. in the final game. This allows for using higher quality settings
  9. (at the cost of file size), regardless of the player's hardware.
  10. - Recording procedurally generated animations or motion design. User interaction
  11. remains possible during video recording, and audio can be included as well
  12. (although you won't be able to hear it while the video is recording).
  13. - Comparing the visual output of graphics settings, shaders, or rendering techniques
  14. in an animated scene.
  15. With Godot's animation features such as the AnimationPlayer node, Tweeners,
  16. particles and shaders, it can effectively be used to create any kind of 2D and
  17. 3D animations (and still images).
  18. If you are already used to Godot's workflow, you may find yourself more
  19. productive by using Godot for video rendering compared to Blender. That said,
  20. renderers designed for non-real-time usage such as Cycles and Eevee can result
  21. in better visuals (at the cost of longer rendering times).
  22. Compared to real-time video recording, some advantages of non-real-time recording include:
  23. - Use any graphics settings (including extremely demanding settings) regardless
  24. of your hardware's capabilities. The output video will *always* have perfect
  25. frame pacing; it will never exhibit dropped frames or stuttering.
  26. Faster hardware will allow you to render a given animation in less time, but
  27. the visual output remains identical.
  28. - Render at a higher framerate than the video's target framerate, then
  29. :ref:`post-process to generate high-quality motion blur <doc_creating_movies_motion_blur>`.
  30. This also makes effects that converge over several frames (such as temporal antialiasing,
  31. SDFGI and volumetric fog) look better.
  32. .. warning::
  33. **This feature is not designed for capturing real-time footage during gameplay.**
  34. Players should use something like `OBS Studio <https://obsproject.com/>`__ or
  35. `SimpleScreenRecorder <https://www.maartenbaert.be/simplescreenrecorder/>`__
  36. to record gameplay videos, as they do a much better job at intercepting the
  37. compositor than Godot can do using Vulkan or OpenGL natively.
  38. That said, if your game runs at near-real-time speeds when capturing,
  39. you can still use this feature (but it will lack audible sound playback,
  40. as sound is saved directly to the video file).
  41. Enabling Movie Maker mode
  42. -------------------------
  43. To enable Movie Maker mode, click the "movie reel" button in the top-right
  44. corner of the editor *before* running the project:
  45. .. image:: img/movie_maker_enable.png
  46. The icon turns red when Movie Maker mode is enabled. Movie Maker status is *not*
  47. persisted when the editor quits, so you must re-enable Movie Maker mode again
  48. after restarting the editor if needed.
  49. .. note::
  50. Toggling Movie Maker mode while running the project will not have any
  51. effect until the project is restarted.
  52. Before you can record video by running the project, you still need to configure
  53. the output file path. This path can be set for all scenes in the Project Settings:
  54. .. image:: img/movie_maker_project_settings.png
  55. Alternatively, you can set the output file path on a per-scene basis by adding a
  56. String metadata with the name ``movie_file`` to the scene's **root node**. This
  57. is only used when the main scene is set to the scene in question, or when
  58. running the scene directly by pressing :kbd:`F6` (:kbd:`Cmd + R` on macOS).
  59. .. image:: img/movie_maker_per_scene_metadata.png
  60. The path specified in the project settings or metadata can be either absolute,
  61. or relative to the project root.
  62. Once you've configured and enabled Movie Maker mode, it will be automatically used
  63. when running the project from the editor.
  64. Command line usage
  65. ^^^^^^^^^^^^^^^^^^
  66. Movie Maker can also be enabled from the :ref:`command line <doc_command_line_tutorial>`:
  67. ::
  68. godot --path /path/to/your_project --write-movie output.avi
  69. If the output path is relative, then it is **relative to the project folder**,
  70. not the current working directory. In the above example, the file will be
  71. written to ``/path/to/your_project/output.avi``. This behavior is similar to the
  72. ``--export`` command line argument.
  73. Since Movie Maker's output resolution is set by the window size, you can adjust
  74. the window size on startup to override it:
  75. ::
  76. godot --path /path/to/your_project --write-movie output.avi --resolution 1280x720
  77. Note that the window size is clamped by your display's resolution.
  78. The recording FPS can also be overridden on the command line,
  79. without having to edit the Project Settings:
  80. ::
  81. godot --path /path/to/your_project --write-movie output.avi --fixed-fps 30
  82. .. note::
  83. The ``--write-movie`` and ``--fixed-fps`` command line arguments are both available
  84. in exported projects. Movie Maker mode cannot be toggled while the project is running,
  85. but you can use the :ref:`OS.execute() <class_OS_method_execute>` method to
  86. run a second instance of the exported project that will record a video file.
  87. Choosing an output format
  88. -------------------------
  89. Output formats are provided by the :ref:`MovieWriter <class_MovieWriter>` class.
  90. Godot has 2 built-in :ref:`MovieWriters <class_MovieWriter>`, and more can be implemented by extensions:
  91. AVI (recommended)
  92. ^^^^^^^^^^^^^^^^^
  93. AVI container with MJPEG for video and uncompressed audio. Features lossy video
  94. compression, resulting in medium file sizes and fast encoding. The lossy
  95. compression quality can be adjusted by changing
  96. **Editor > Movie Writer > MJPEG Quality**.
  97. The resulting file can be viewed in most video players, but it must be converted
  98. to another format for viewing on the web or by Godot with the VideoStreamPlayer
  99. node. MJPEG does not support transparency. AVI output is currently limited to a
  100. file of 4 GB in size at most.
  101. To use AVI, specify a path to an ``.avi`` file to be created in the
  102. **Editor > Movie Writer > Movie File** project setting.
  103. PNG
  104. ^^^
  105. PNG image sequence for video and WAV for audio. Features lossless video
  106. compression, at the cost of large file sizes and slow encoding. This is designed to be
  107. :ref:`encoded to a video file with an external tool after recording <doc_creating_movies_converting_avi>`.
  108. Transparency is currently not supported, even if the root viewport is set to be transparent.
  109. To use PNG, specify a ``.png`` file to be created in the
  110. **Editor > Movie Writer > Movie File** project setting. The generated ``.wav``
  111. file will have the same name as the ``.png`` file (minus the extension).
  112. Custom
  113. ^^^^^^
  114. If you need to encode directly to a different format or pipe a stream through
  115. third-party software, you can extend the MovieWriter class to create your own
  116. movie writers. This should typically be done using GDExtension for performance
  117. reasons.
  118. Configuration
  119. -------------
  120. In the **Editor > Movie Writer** section of the Project Settings, there are
  121. several options you can configure. Some of them are only visible after enabling
  122. the **Advanced** toggle in the top-right corner of the Project Settings dialog.
  123. - **Mix Rate Hz:** The audio mix rate to use in the recorded audio when writing
  124. a movie. This can be different from the project's mix rate, but this
  125. value must be divisible by the recorded FPS to prevent audio from
  126. desynchronizing over time.
  127. - **Speaker Mode:** The speaker mode to use in the recorded audio when writing a movie
  128. (stereo, 5.1 surround or 7.1 surround).
  129. - **MJPEG Quality:** The JPEG quality to use when writing a video to an AVI
  130. file, between ``0.01`` and ``1.0`` (inclusive). Higher quality values result
  131. in better-looking output at the cost of larger file sizes. Recommended quality
  132. values are between ``0.75`` and ``0.9``. Even at quality ``1.0``, JPEG
  133. compression remains lossy. This setting does not affect audio quality and is
  134. ignored when writing to a PNG image sequence.
  135. - **Movie File:** The output path for the movie. This can be absolute or
  136. relative to the project root.
  137. - **Disable V-Sync:** If enabled, requests V-Sync to be disabled when writing a
  138. movie. This can speed up video writing if the hardware is fast enough to
  139. render, encode and save the video at a framerate higher than the monitor's
  140. refresh rate. This setting has no effect if the operating system or graphics
  141. driver forces V-Sync with no way for applications to disable it.
  142. - **FPS:** The rendered frames per second in the output movie. Higher values
  143. result in smoother animation, at the cost of longer rendering times and larger
  144. output file sizes. Most video hosting platforms do not support FPS values
  145. higher than 60, but you can use a higher value and use that to generate motion
  146. blur.
  147. .. note::
  148. The output file's resolution is set by the window size. Make sure to resize
  149. the window *before* the splash screen has ended. For this purpose, it's recommended
  150. to adjust the **Display > Window > Size > Window Width Override** and
  151. **Display > Window > Size > Window Height Override** project settings.
  152. To apply a resolution override only when recording a movie, you can override
  153. those settings with the ``movie`` :ref:`feature tag <doc_feature_tags>`.
  154. Quitting Movie Maker mode
  155. -------------------------
  156. To safely quit a project that is using Movie Maker mode, use the X button at the
  157. top of the window, or call ``get_tree().quit()`` in a script.
  158. Pressing :kbd:`F8` (:kbd:`Cmd + .` on macOS) or pressing :kbd:`Ctrl + C` on the
  159. terminal running Godot is **not recommended**, as it will result in an
  160. improperly formatted AVI file with no duration information. For PNG image
  161. sequences, PNG images will not be negatively altered, but the associated WAV file
  162. will still lack duration information.
  163. Some video players may still be able to play the AVI or WAV file with working
  164. video and audio. However, software that makes use of the AVI or WAV file such as
  165. video editors may not be able to open the file.
  166. :ref:`Using a video converter program <doc_creating_movies_converting_avi>`
  167. can help in those cases.
  168. If you're using an AnimationPlayer to control a "main action" in the scene (such
  169. as camera movement), you can enable the **Movie Quit On Finish** property on the
  170. AnimationPlayer node in question. When enabled, this property will make Godot
  171. quit on its own when an animation is done playing *and* the engine is running in
  172. Movie Maker mode. Note that *this property has no effect on looping animations*.
  173. Therefore, you need to make sure that the animation is set as non-looping.
  174. Using high-quality graphics settings
  175. ------------------------------------
  176. The ``movie`` :ref:`feature tag <doc_feature_tags>` can be used to override
  177. specific project settings. This is useful to enable high-quality graphics settings
  178. that wouldn't be fast enough to run in real-time speeds on your hardware.
  179. Remember that putting every setting to its maximum value can still slow down
  180. movie saving speed, especially when recording at higher resolutions. Therefore,
  181. it's still recommended to only increase graphics settings if they make a meaningful
  182. difference in the output image.
  183. This feature tag can also be queried in a script to increase quality settings
  184. that are set in the Environment resource. For example, to further improve SDFGI
  185. detail and reduce light leaking:
  186. ::
  187. extends Node3D
  188. func _ready():
  189. if OS.has_feature("movie"):
  190. # When recording a movie, improve SDFGI cell density
  191. # without decreasing its maximum distance.
  192. get_viewport().world_3d.environment.sdfgi_min_cell_size *= 0.25
  193. get_viewport().world_3d.environment.sdfgi_cascades = 8
  194. Post-processing steps
  195. ---------------------
  196. Some common post-processing steps are listed below.
  197. .. note::
  198. When using several post-processing steps, try to perform all of them in a
  199. single FFmpeg command. This will save encoding time and improve quality by
  200. avoiding multiple lossy encoding steps.
  201. .. _doc_creating_movies_converting_avi:
  202. Converting AVI video to MP4
  203. ^^^^^^^^^^^^^^^^^^^^^^^^^^^
  204. While some platforms such as YouTube support uploading the AVI file directly, many
  205. others will require a conversion step beforehand. `HandBrake <https://handbrake.fr/>`__
  206. (GUI) and `FFmpeg <https://ffmpeg.org/>`__ (CLI) are popular open source tools
  207. for this purpose. FFmpeg has a steeper learning curve, but it's more powerful.
  208. The command below converts an AVI video to a MP4 (H.264) video with a Constant
  209. Rate Factor (CRF) of 15. This results in a relatively large file, but is
  210. well-suited for platforms that will re-encode your videos to reduce their size
  211. (such as most video sharing websites):
  212. ::
  213. ffmpeg -i input.avi -crf 15 output.mp4
  214. To get a smaller file at the cost of quality, *increase* the CRF value in the
  215. above command.
  216. .. _doc_creating_movies_converting_image_sequence:
  217. Converting PNG image sequence + WAV audio to a video
  218. ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  219. If you chose to record a PNG image sequence with a WAV file beside it,
  220. you need to convert it to a video before you can use it elsewhere.
  221. The filename for the PNG image sequence generated by Godot always contains 8
  222. digits, starting at 0 with zero-padded numbers. If you specify an output
  223. path ``folder/example.png``, Godot will write ``folder/example00000000.png``,
  224. ``folder/example00000001.png``, and so on in that folder. The audio will be saved
  225. at ``folder/example.wav``.
  226. The FPS is specified using the ``-r`` argument. It should match the FPS
  227. specified during recording. Otherwise, the video will appear to be slowed down
  228. or sped up, and audio will be out of sync with the video.
  229. ::
  230. ffmpeg -i input%08d.png -i input.wav -r 60 -crf 15 output.mp4
  231. .. _doc_creating_movies_motion_blur:
  232. Cutting video
  233. ^^^^^^^^^^^^^
  234. You can trim parts of the video you don't want to keep after the video is
  235. recorded. For example, to discard everything before 12.1 seconds and keep
  236. only 5.2 seconds of video after that point:
  237. ::
  238. ffmpeg -i input.avi -ss 00:00:12.10 -t 00:00:05.20 -crf 15 output.mp4
  239. Cutting videos can also be done with the GUI tool
  240. `LosslessCut <https://mifi.github.io/lossless-cut/>`__.
  241. Resizing video
  242. ^^^^^^^^^^^^^^
  243. The following command resizes a video to be 1080 pixels tall (1080p),
  244. while preserving its existing aspect ratio:
  245. ::
  246. ffmpeg -i input.avi -f:v "scale=-1:1080" -crf 15 -preset veryfast output.mp4
  247. .. _doc_creating_movies_reducing_framerate:
  248. Reducing framerate
  249. ^^^^^^^^^^^^^^^^^^
  250. The following command changes a video's framerate to 30 FPS, dropping some of
  251. the original frames if there are more in the input video:
  252. ::
  253. ffmpeg -i input.avi -r 30 -crf 15 output.mp4
  254. Generating accumulation motion blur with FFmpeg
  255. ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  256. Godot does not have built-in support for motion blur, but it can still be
  257. created in recorded videos.
  258. If you record the video at a multiple of the original framerate, you can blend
  259. the frames together then reduce the frameate to produce a video with
  260. *accumulation motion blur*. This motion blur can look very good, but it can take
  261. a long time to generate since you have to render many more frames per second (on
  262. top of the time spent on post-processing).
  263. Example with a 240 FPS source video, generating 4× motion blur and decreasing
  264. its output framerate to 60 FPS:
  265. ::
  266. ffmpeg -i input.avi -vf "tmix=frames=4, fps=60" -crf 15 output.mp4
  267. This also makes effects that converge over several frames (such as temporal
  268. antialiasing, SDFGI and volumetric fog) converge faster and therefore look
  269. better, since they'll be able to work with more data at a given time.
  270. See :ref:`doc_creating_movies_reducing_framerate` if you want to get this benefit
  271. without adding motion blur.