Skip to content

Visualize Your Ideas With Code

docs: add ffmpeg exporter (#675)

Jacob7b48ff6efff9
diff --git a/packages/docs/docs/getting-started/quickstart.mdx b/packages/docs/docs/getting-started/quickstart.mdx
index 644e330c..2f6872d2 100644
--- a/packages/docs/docs/getting-started/quickstart.mdx
+++ b/packages/docs/docs/getting-started/quickstart.mdx
@@ -28,7 +28,9 @@ node -v
### Creating a new project
-Run the following command in order to scaffold a new Motion Canvas project:
+Run the following command in order to scaffold a new Motion Canvas project (If
+the command fails check out the [troubleshooting](#troubleshooting) section
+below):
```bash
npm init @motion-canvas@latest
@@ -39,24 +41,34 @@ to use; either TypeScript or plain JavaScript. We recommend using TypeScript in
your first project, since that's the language we're using throughout this
documentation.
-To complete the scaffolding process, run the following command in your newly
-created project directory:
-
-```shell
-npm install
-```
-
-### Starting the editor
-
-To start the editor, run:
-
-```shell
-npm run serve
-```
-
-The editor can be accessed by visiting
-[http://localhost:9000/](http://localhost:9000/). We'll use it to preview our
-animation, but for now there's not much to see.
+You'll also be asked to choose how you'd like to export your animations. Motion
+Canvas comes with a built-in [_Image sequence_](/docs/rendering/image-sequence)
+exporter - perfect if you want to import your animations into a video editor.
+However, if you want to directly produce a finished video, you can choose to
+install the [_Video (FFmpeg)_](/docs/rendering/video) exporter. Don't worry, you
+can select multiple exporters, and you can always
+[add more](/docs/rendering/video#existing-project) later.
+
+To complete the scaffolding process, you'll need to run the following commands:
+
+1. **C**hange **D**irectory (`cd`) to the project root (You should replace
+ `<project-path>` with the path you picked during scaffolding):
+ ```shell
+ cd <project-path>
+ ```
+2. Install necessary dependencies:
+ ```shell
+ npm install
+ ```
+3. Start the editor:
+ ```shell
+ npm run serve
+ ```
+ You may see a yellow error message in the terminal saying "Could not
+ auto-determine entry point", but it's not important, and you can safely
+ ignore it. The editor can be accessed by visiting
+ [http://localhost:9000/](http://localhost:9000/). We'll use it to preview our
+ animation, although for now there's not much to see.
### Programming an animation
diff --git a/packages/docs/docs/getting-started/rendering/image-sequence.mdx b/packages/docs/docs/getting-started/rendering/image-sequence.mdx
new file mode 100644
index 00000000..f26d8cfa
--- /dev/null
+++ b/packages/docs/docs/getting-started/rendering/image-sequence.mdx
@@ -0,0 +1,33 @@
+---
+slug: /rendering/image-sequence
+---
+
+# Image sequence
+
+The built-in exporter for Motion Canvas. It stores the rendered frames as a
+sequence of images, which can then be imported into a video editor for further
+processing.
+
+## Configuration
+
+After selecting the Image sequence exporter in the Video Settings tab, the
+following configuration options will become available:
+
+### File Type
+
+The type of image file to which Motion Canvas will convert the frames. Current
+options are PNG, JPEG, and WebP. Note that Motion Canvas depends on the
+capabilities of your browser to generate image files, and so WebP may not work
+on Safari or older browsers.
+
+### Quality
+
+The quality target for compression from 0 to 100, where a lower setting will
+result in smaller file sizes but might degrade image quality. A setting of 100
+will result in lossless images, such that no detail is lost, but lower settings
+will often produce no discernible difference.
+
+### Group by scene
+
+When enabled, each scene will be rendered into a separate image sequence located
+in a subdirectory called the same as the scene.
diff --git a/packages/docs/docs/getting-started/rendering.mdx b/packages/docs/docs/getting-started/rendering/index.mdx
similarity index 65%
rename from packages/docs/docs/getting-started/rendering.mdx
rename to packages/docs/docs/getting-started/rendering/index.mdx
index 5ca64fe7..ec25c212 100644
--- a/packages/docs/docs/getting-started/rendering.mdx
+++ b/packages/docs/docs/getting-started/rendering/index.mdx
@@ -5,6 +5,8 @@ slug: /rendering
import {VideoSettings} from '@site/src/Icon/VideoSettings';
import {PhotoCamera} from '@site/src/Icon/PhotoCamera';
+import DocCardList from '@theme/DocCardList';
+import {useCurrentSidebarCategory} from '@docusaurus/theme-common';
# Rendering
@@ -13,8 +15,8 @@ to the display of your animation. You can open it by pressing the <VideoSettings
className="icon-inline"
alt="Video Settings"
title="Video Settings"
-/> icon. Here, you can configure various settings related to your animation,
-initialize the rendering process, and enter the presentation mode.
+/> icon. Here, you can configure various animation settings, initialize the
+rendering process, and enter the presentation mode.
## Configuration
@@ -89,42 +91,29 @@ The HTML Canvas color space to use when previewing or rendering the animation.
Current options include sRGB, a common color space for images and video, and
DCI-P3, a wide-gamut color space.
-### File Type
+### Exporter
-The type of image file to which Motion Canvas will convert the frames. Current
-options are PNG, JPEG, and WebP. Note that Motion Canvas depends on the
-capabilities of your browser to generate image files, and so WebP may not work
-on Safari or older browsers.
+The exporter to use when rendering the animation. Exporters are responsible for
+processing the rendered frames and saving them to the output directory. If you
+don't see this option, it means that you don't have any additional exporters
+installed and the default _Image sequence_ exporter will be used.
-### Quality
-
-The quality target for compression from 0 to 1, where a lower setting will
-result in smaller file sizes but might degrade image quality. A setting of 1
-will result in lossless images, such that no detail is lost, but lower settings
-will often produce no discernible difference. Note that output to a file type of
-PNG does not allow for different quality settings, so this option will be
-ignored when outputting to PNG.
-
-### Group by scene
-
-When enabled, each scene will be rendered into a separate image sequence located
-in a subdirectory called the same as the scene.
+<DocCardList items={useCurrentSidebarCategory().items} />
## Rendering
-Clicking the `RENDER` button will initialize rendering. Motion Canvas will play
-through the animation and save each frame as an image to `/output` in your
-project directory. You can
-[change the output directory](/docs/configuration#output) in the configuration
-file.
+Clicking the `RENDER` button will initialize rendering (The button will change
+to `RENDERING` for the duration of the process). Motion Canvas will play through
+the animation and save the result to `/output` in your project directory. You
+can [change the output directory](/docs/configuration#output) in the
+configuration file. You can use the `OUTPUT DIRECTORY` button to reveal the
+current output directory in your file explorer.
-The rendering process will finish once the playhead reaches the end of the
-selected range. You can also stop the process at any time by pressing the
-`RENDER` button again.
+The rendering process will finish once the button changes back to `RENDER`.
+Usually, this happens when the playhead reaches the end of the selected range
+but some exporters may take longer to finish processing the frames.
-After rendering, you can import the rendered image sequence into a video editor
-of your choice, or convert the frames directly to a video using a tool like
-`ffmpeg`.
+You can also abort the process at any time by pressing the `RENDERING` button.
## Taking Snapshots
diff --git a/packages/docs/docs/getting-started/rendering/video.mdx b/packages/docs/docs/getting-started/rendering/video.mdx
new file mode 100644
index 00000000..4ba6fba0
--- /dev/null
+++ b/packages/docs/docs/getting-started/rendering/video.mdx
@@ -0,0 +1,66 @@
+---
+slug: /rendering/video
+---
+
+# Video (FFmpeg)
+
+An exporter that uses [FFmpeg](https://ffmpeg.org/) to turn your animation into
+a finished video.
+
+## Installation
+
+:::info
+
+You do **not** need to install FFmpeg yourself. It will be installed
+automatically together with the exporter.
+
+:::
+
+### New project
+
+When [scaffolding a new project](/docs/quickstart#creating-a-new-project), you
+can select _Video (FFmpeg)_ in the list of available exporters. This will
+automatically install the required dependencies and add the necessary
+configuration.
+
+### Existing project
+
+If you want to install the exporter in an existing project, run the following
+command:
+
+```bash
+npm install --save @motion-canvas/ffmpeg
+```
+
+And then configure it in your `vite.config.ts` file:
+
+```diff
+ import {defineConfig} from 'vite';
+ import motionCanvas from '@motion-canvas/vite-plugin';
++ import ffmpeg from '@motion-canvas/ffmpeg';
+
+ export default defineConfig({
+ plugins: [
+ motionCanvas(),
++ ffmpeg(),
+ ],
+ });
+```
+
+## Configuration
+
+After selecting the Video (FFmpeg) exporter in the Video Settings tab, the
+following configuration options will become available:
+
+### Include audio
+
+When enabled, the audio track will be included in the rendered video. This
+option is only available if you've [set up audio](/docs/media#audio) for the
+current project.
+
+### Fast start
+
+When enabled, the video will be rendered with the Fast Start option. It's an
+optimization for videos that will be served over the web. It rearranges the
+video data in the file, allowing the video to begin playing before it has
+finished downloading.