Skip to content

Visualize Your Ideas With Code

docs: add media chapter (#237)

Tan to the Dashie5d5ffe610b8
diff --git a/packages/docs/docs/getting-started/media.mdx b/packages/docs/docs/getting-started/media.mdx
new file mode 100644
index 00000000..b814d5b8
--- /dev/null
+++ b/packages/docs/docs/getting-started/media.mdx
@@ -0,0 +1,179 @@
+---
+sidebar_position: 13
+slug: /media
+---
+
+import AnimationPlayer from '@site/src/components/AnimationPlayer';
+
+# Media
+
+In this chapter we will take a look at all the different types of media Motion
+Canvas lets you add to your animations.
+
+## Audio
+
+One type of media Motion Canvas supports is audio. To add an audio track to your
+animation you need to edit your `project.ts` file. First we need to import the
+audio file we want to use as follows:
+
+```ts
+// my-animation/
+// ├─ audio/
+// │ └─ voice.mp3
+// ├─ src/
+// ...
+import audio from '../audio/voice.mp3';
+```
+
+Once imported we need to let Motion Canvas know that we want to use this audio
+file. We can do this by specifying the
+[`audio`](/api/core/index/ProjectConfig#audio) property in the
+[`ProjectConfiguration`](/api/core/index/ProjectConfig):
+
+```ts
+export default makeProject({
+ // ...
+ audio: audio,
+});
+```
+
+If we open the editor now, we should see that your audio track has been added.
+
+![](@site/static/img/media/editor-audio-track.png)
+
+However, it's not always ideal to start with the audio at the beginning.
+Sometimes it's better to start with a bit of delay. This can be done by using
+the [`audioOffset`](/api/core/index/ProjectConfig#audioOffset) property and
+specifying a amount of seconds.
+
+```ts
+export default makeProject({
+ // ...
+ audio: audio,
+ audioOffset: 1.5, // delays the audio by 1.5 second
+});
+```
+
+![](@site/static/img/media/editor-audio-track-delayed.png)
+
+### Supported Formats
+
+A list of supported file formats can be found
+[here](https://developer.mozilla.org/en-US/docs/Web/Media/Formats/Audio_codecs#common_codecs)
+
+## Images
+
+Another type of media Motion Canvas supports are images. To use an image in the
+animation, we need to import the image:
+
+```ts
+// my-animation/
+// ├─ images/
+// │ └─ example.png
+// ├─ src/
+// ...
+import examplePng from '../../images/example.png';
+```
+
+Then we can use Motion Canvas [`Image`](/api/2d/components/Image) component to
+display the image:
+
+```tsx
+import {makeScene2D} from '@motion-canvas/2d/lib/scenes';
+import {Image} from '@motion-canvas/2d/lib/components';
+
+import examplePng from '../../images/example.png';
+
+export default makeScene2D(function* (view) {
+ view.add(<Image src={examplePng} />);
+});
+```
+
+Images can also be animated like every other component in Motion Canvas. For
+this, we need to create a [`Reference`](/docs/references) and pass that to
+the [`Image`](/api/2d/components/Image):
+
+```tsx
+// ...
+import {createRef} from '@motion-canvas/core/lib/utils';
+import {all} from '@motion-canvas/core/lib/flow';
+
+export default makeScene2D(function* (view) {
+ const imageRef = createRef<Image>();
+
+ view.add(<Image ref={imageRef} src={examplePng} scale={2} />);
+
+ yield* all(
+ imageRef().scale(2.5, 1.5).to(2, 1.5),
+ imageRef().absoluteRotation(90, 1.5).to(0, 1.5),
+ );
+});
+```
+
+<AnimationPlayer name="media-image" small />
+
+### Supported Formats
+
+A list of supported file formats can be found
+[here](https://developer.mozilla.org/en-US/docs/Web/Media/Formats/Image_types)
+
+## Video
+
+Videos in Motion Canvas work similar to images. First, we need to import our
+video we want to display:
+
+```ts
+// my-animation/
+// ├─ videos/
+// │ └─ example.mp4
+// ├─ src/
+// ...
+import exampleMp4 from '../../videos/example.mp4';
+```
+
+Then we can use Motion Canvas [`Video`](/api/2d/components/Video) component to
+display the video as follows:
+
+```tsx
+import {makeScene2D} from '@motion-canvas/2d/lib/scenes';
+import {Video} from '@motion-canvas/2d/lib/components';
+
+import exampleMp4 from '../../videos/example.mp4';
+
+export default makeScene2D(function* (view) {
+ view.add(<Video ref={videoRef} src={exampleMp4} />);
+});
+```
+
+However this will only display the video and will not play it. In order to play
+the video we need to create a [`Reference`](/docs/references) to the element.
+
+```tsx
+// ...
+import {createRef} from '@motion-canvas/core/lib/utils';
+
+export default makeScene2D(function* (view) {
+ const videoRef = createRef<Video>();
+
+ view.add(<Video ref={videoRef} src={exampleMp4} />);
+});
+```
+
+Now that we have a [`Reference`](/docs/references) to the
+[`Video`](/api/2d/components/Video) element, we can use it to animate the video,
+as well as [`play`](/api/2d/components/Video#play) and
+[`pause`](/api/2d/components/Video#pause) it.
+
+```ts
+export default makeScene2D(function* (view) {
+ // ...
+
+ videoRef().play();
+ yield* videoRef().scale(1.25, 1.5).to(1, 1.5);
+});
+```
+
+### Supported Formats
+
+A list of supported file formats can be found
+[here](https://developer.mozilla.org/en-US/docs/Web/Media/Formats/Containers)
diff --git a/packages/docs/static/img/media/editor-audio-track-delayed.png b/packages/docs/static/img/media/editor-audio-track-delayed.png
new file mode 100644
index 00000000..ddb720e3
Binary files /dev/null and b/packages/docs/static/img/media/editor-audio-track-delayed.png differ
diff --git a/packages/docs/static/img/media/editor-audio-track.png b/packages/docs/static/img/media/editor-audio-track.png
new file mode 100644
index 00000000..e8073f47
Binary files /dev/null and b/packages/docs/static/img/media/editor-audio-track.png differ
diff --git a/packages/examples/assets/example.mp4 b/packages/examples/assets/example.mp4
new file mode 100644
index 00000000..6a7156a5
Binary files /dev/null and b/packages/examples/assets/example.mp4 differ
diff --git a/packages/examples/assets/logo.svg b/packages/examples/assets/logo.svg
new file mode 100644
index 00000000..82fd7a5e
--- /dev/null
+++ b/packages/examples/assets/logo.svg
@@ -0,0 +1 @@
+<?xml version="1.0" encoding="UTF-8"?><svg id="a" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 48 48"><defs><style>.b{fill:#99c47a;}.c{fill:#ff6470;}.d{fill:#ffc66d;}.e{fill:#404040;}.f{fill:#68abdf;}</style></defs><rect class="e" x="23.41" y="19.41" width="4" height="12" rx="2" ry="2" transform="translate(-10.53 25.41) rotate(-45)"/><rect class="f" x="24.12" y="11.22" width="4" height="10" rx="2" ry="2" transform="translate(-3.82 23.22) rotate(-45)"/><rect class="b" x="17.05" y="7.15" width="4" height="4" rx="2" ry="2" transform="translate(-.89 16.15) rotate(-45)"/><rect class="d" x="12.45" y="7.95" width="4" height="13" rx="2" ry="2" transform="translate(-5.99 14.45) rotate(-45)"/><rect class="c" x="12.1" y="16" width="4" height="16" rx="2" ry="2" transform="translate(-12.84 17) rotate(-45)"/><rect class="e" x="22.31" y="26.38" width="4" height="12" rx="2" ry="2" transform="translate(6.5 68.74) rotate(-117)"/><rect class="e" x="28.6" y="29.58" width="4" height="12" rx="2" ry="2" transform="translate(66.38 65.94) rotate(171)"/><rect class="e" x="33.58" y="24.6" width="4" height="12" rx="2" ry="2" transform="translate(71.37 .24) rotate(99)"/><rect class="e" x="30.38" y="18.31" width="4" height="12" rx="2" ry="2" transform="translate(14.57 -12.05) rotate(27)"/></svg>
\ No newline at end of file
diff --git a/packages/examples/package.json b/packages/examples/package.json
index 1d49fcb4..f05ee2f6 100644
--- a/packages/examples/package.json
+++ b/packages/examples/package.json
@@ -4,7 +4,7 @@
"version": "0.0.0",
"scripts": {
"serve": "vite",
- "build": "tsc && vite build"
+ "build": "tsc && vite build --base /examples/"
},
"dependencies": {
"@motion-canvas/2d": "*",
diff --git a/packages/examples/src/media-image.meta b/packages/examples/src/media-image.meta
new file mode 100644
index 00000000..0e33e3fe
--- /dev/null
+++ b/packages/examples/src/media-image.meta
@@ -0,0 +1,3 @@
+{
+ "version": 0
+}
\ No newline at end of file
diff --git a/packages/examples/src/media-image.ts b/packages/examples/src/media-image.ts
new file mode 100644
index 00000000..dfba2de6
--- /dev/null
+++ b/packages/examples/src/media-image.ts
@@ -0,0 +1,7 @@
+import {makeProject} from '@motion-canvas/core';
+
+import scene from './scenes/media-image?scene';
+
+export default makeProject({
+ scenes: [scene],
+});
diff --git a/packages/examples/src/media-video.meta b/packages/examples/src/media-video.meta
new file mode 100644
index 00000000..0e33e3fe
--- /dev/null
+++ b/packages/examples/src/media-video.meta
@@ -0,0 +1,3 @@
+{
+ "version": 0
+}
\ No newline at end of file
diff --git a/packages/examples/src/media-video.ts b/packages/examples/src/media-video.ts
new file mode 100644
index 00000000..338f5ac6
--- /dev/null
+++ b/packages/examples/src/media-video.ts
@@ -0,0 +1,7 @@
+import {makeProject} from '@motion-canvas/core';
+
+import scene from './scenes/media-video?scene';
+
+export default makeProject({
+ scenes: [scene],
+});
diff --git a/packages/examples/src/scenes/media-image.meta b/packages/examples/src/scenes/media-image.meta
new file mode 100644
index 00000000..857af9b8
--- /dev/null
+++ b/packages/examples/src/scenes/media-image.meta
@@ -0,0 +1,4 @@
+{
+ "version": 1,
+ "seed": 3374664546
+}
\ No newline at end of file
diff --git a/packages/examples/src/scenes/media-image.tsx b/packages/examples/src/scenes/media-image.tsx
new file mode 100644
index 00000000..0cf1c6b0
--- /dev/null
+++ b/packages/examples/src/scenes/media-image.tsx
@@ -0,0 +1,17 @@
+import {makeScene2D} from '@motion-canvas/2d/lib/scenes';
+import {Image} from '@motion-canvas/2d/lib/components';
+import {createRef} from '@motion-canvas/core/lib/utils';
+import {all} from '@motion-canvas/core/lib/flow';
+
+import logoSvg from '@motion-canvas/examples/assets/logo.svg';
+
+export default makeScene2D(function* (view) {
+ const imageRef = createRef<Image>();
+
+ view.add(<Image ref={imageRef} src={logoSvg} scale={2} />);
+
+ yield* all(
+ imageRef().scale(2.5, 1.5).to(2, 1.5),
+ imageRef().absoluteRotation(90, 1.5).to(0, 1.5),
+ );
+});
diff --git a/packages/examples/src/scenes/media-video.meta b/packages/examples/src/scenes/media-video.meta
new file mode 100644
index 00000000..857af9b8
--- /dev/null
+++ b/packages/examples/src/scenes/media-video.meta
@@ -0,0 +1,4 @@
+{
+ "version": 1,
+ "seed": 3374664546
+}
\ No newline at end of file
diff --git a/packages/examples/src/scenes/media-video.tsx b/packages/examples/src/scenes/media-video.tsx
new file mode 100644
index 00000000..73eb5c67
--- /dev/null
+++ b/packages/examples/src/scenes/media-video.tsx
@@ -0,0 +1,14 @@
+import {makeScene2D} from '@motion-canvas/2d/lib/scenes';
+import {Video} from '@motion-canvas/2d/lib/components';
+import {createRef} from '@motion-canvas/core/lib/utils';
+
+import exampleMp4 from '@motion-canvas/examples/assets/example.mp4';
+
+export default makeScene2D(function* (view) {
+ const videoRef = createRef<Video>();
+
+ view.add(<Video ref={videoRef} src={exampleMp4} />);
+
+ videoRef().play();
+ yield* videoRef().scale(1.25, 2).to(1, 2);
+});
diff --git a/packages/examples/vite.config.ts b/packages/examples/vite.config.ts
index a7f5f297..6c7dd9b3 100644
--- a/packages/examples/vite.config.ts
+++ b/packages/examples/vite.config.ts
@@ -16,6 +16,8 @@ export default defineConfig({
'./src/layout.ts',
'./src/layout-group.ts',
'./src/positioning.ts',
+ './src/media-image.ts',
+ './src/media-video.ts',
],
}),
],