Skip to content

Visualize Your Ideas With Code

docs: added intro, installation, and quickstart guide to docs (#46)

Ross Esmonddb50531f12db
diff --git a/README.md b/README.md
index eb1eb869..c2a6b7ed 100644
--- a/README.md
+++ b/README.md
@@ -40,7 +40,7 @@ node -v
`Username` is your GitHub username,
`Password` is the token you just generated.
`Email` is your GitHub email address.
- For instace:
+ For instance:
```text
> Username: Jacob
> Password: ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
diff --git a/package-lock.json b/package-lock.json
index 59fc65ac..b9b3b1c9 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -14681,6 +14681,11 @@
"node": ">=8"
}
},
+ "node_modules/load-script": {
+ "version": "1.0.0",
+ "resolved": "https://registry.npmjs.org/load-script/-/load-script-1.0.0.tgz",
+ "integrity": "sha512-kPEjMFtZvwL9TaZo0uZ2ml+Ye9HUMmPwbYRJ324qF9tqMejwykJ5ggTyvzmrbBeapCAbk98BSbTeovHEEP1uCA=="
+ },
"node_modules/loader-runner": {
"version": "4.3.0",
"resolved": "https://registry.npmjs.org/loader-runner/-/loader-runner-4.3.0.tgz",
@@ -15043,6 +15048,11 @@
"node": ">= 4.0.0"
}
},
+ "node_modules/memoize-one": {
+ "version": "5.2.1",
+ "resolved": "https://registry.npmjs.org/memoize-one/-/memoize-one-5.2.1.tgz",
+ "integrity": "sha512-zYiwtZUcYyXKo/np96AGZAckk+FWWsUdJ3cHGGmld7+AhvcWmQyGCYUh1hc4Q/pkOhb65dQR/pqCyK0cOaHz4Q=="
+ },
"node_modules/meow": {
"version": "8.1.2",
"resolved": "https://registry.npmjs.org/meow/-/meow-8.1.2.tgz",
@@ -18160,6 +18170,21 @@
"webpack": ">=4.41.1 || 5.x"
}
},
+ "node_modules/react-player": {
+ "version": "2.10.1",
+ "resolved": "https://registry.npmjs.org/react-player/-/react-player-2.10.1.tgz",
+ "integrity": "sha512-ova0jY1Y1lqLYxOehkzbNEju4rFXYVkr5rdGD71nsiG4UKPzRXQPTd3xjoDssheoMNjZ51mjT5ysTrdQ2tEvsg==",
+ "dependencies": {
+ "deepmerge": "^4.0.0",
+ "load-script": "^1.0.0",
+ "memoize-one": "^5.1.1",
+ "prop-types": "^15.7.2",
+ "react-fast-compare": "^3.0.1"
+ },
+ "peerDependencies": {
+ "react": ">=16.6.0"
+ }
+ },
"node_modules/react-router": {
"version": "5.3.3",
"resolved": "https://registry.npmjs.org/react-router/-/react-router-5.3.3.tgz",
@@ -22394,7 +22419,7 @@
},
"packages/core": {
"name": "@motion-canvas/core",
- "version": "10.0.0",
+ "version": "10.1.0",
"license": "MIT",
"dependencies": {
"@types/prismjs": "^1.26.0",
@@ -22423,7 +22448,7 @@
},
"packages/create": {
"name": "@motion-canvas/create",
- "version": "10.0.1",
+ "version": "10.1.0",
"license": "MIT",
"dependencies": {
"prompts": "^2.4.2"
@@ -22432,9 +22457,9 @@
"create-motion-canvas": "index.js"
},
"devDependencies": {
- "@motion-canvas/core": "^10.0.0",
- "@motion-canvas/ui": "^10.0.0",
- "@motion-canvas/vite-plugin": "^10.0.0"
+ "@motion-canvas/core": "^10.1.0",
+ "@motion-canvas/ui": "^10.1.0",
+ "@motion-canvas/vite-plugin": "^10.1.0"
}
},
"packages/docs": {
@@ -22447,7 +22472,8 @@
"clsx": "^1.2.0",
"prism-react-renderer": "^1.3.5",
"react": "^17.0.2",
- "react-dom": "^17.0.2"
+ "react-dom": "^17.0.2",
+ "react-player": "^2.10.1"
},
"devDependencies": {
"@docusaurus/module-type-aliases": "^2.0.0",
@@ -22476,10 +22502,10 @@
},
"packages/ui": {
"name": "@motion-canvas/ui",
- "version": "10.0.0",
+ "version": "10.1.0",
"license": "MIT",
"devDependencies": {
- "@motion-canvas/core": "^10.0.0",
+ "@motion-canvas/core": "^10.1.0",
"@preact/preset-vite": "^2.3.0",
"preact": "10.7.3",
"typescript": "^4.6.4",
@@ -22501,7 +22527,7 @@
},
"packages/vite-plugin": {
"name": "@motion-canvas/vite-plugin",
- "version": "10.0.0",
+ "version": "10.1.0",
"license": "MIT",
"dependencies": {
"mime-types": "^2.1.35"
@@ -26265,9 +26291,9 @@
"@motion-canvas/create": {
"version": "file:packages/create",
"requires": {
- "@motion-canvas/core": "^10.0.0",
- "@motion-canvas/ui": "^10.0.0",
- "@motion-canvas/vite-plugin": "^10.0.0",
+ "@motion-canvas/core": "^10.1.0",
+ "@motion-canvas/ui": "^10.1.0",
+ "@motion-canvas/vite-plugin": "^10.1.0",
"prompts": "^2.4.2"
}
},
@@ -26284,6 +26310,7 @@
"prism-react-renderer": "^1.3.5",
"react": "^17.0.2",
"react-dom": "^17.0.2",
+ "react-player": "^2.10.1",
"typedoc": "^0.23.7",
"typedoc-plugin-markdown": "^3.13.3",
"typescript": "^4.7.4"
@@ -26301,7 +26328,7 @@
"@motion-canvas/ui": {
"version": "file:packages/ui",
"requires": {
- "@motion-canvas/core": "^10.0.0",
+ "@motion-canvas/core": "^10.1.0",
"@preact/preset-vite": "^2.3.0",
"preact": "10.7.3",
"typescript": "^4.6.4",
@@ -26319,7 +26346,7 @@
"@motion-canvas/vite-plugin": {
"version": "file:packages/vite-plugin",
"requires": {
- "@types/mime-types": "*",
+ "@types/mime-types": "^2.1.1",
"mime-types": "^2.1.35",
"typescript": "^4.7.4",
"vite": "^3.0.5"
@@ -33533,6 +33560,11 @@
}
}
},
+ "load-script": {
+ "version": "1.0.0",
+ "resolved": "https://registry.npmjs.org/load-script/-/load-script-1.0.0.tgz",
+ "integrity": "sha512-kPEjMFtZvwL9TaZo0uZ2ml+Ye9HUMmPwbYRJ324qF9tqMejwykJ5ggTyvzmrbBeapCAbk98BSbTeovHEEP1uCA=="
+ },
"loader-runner": {
"version": "4.3.0",
"resolved": "https://registry.npmjs.org/loader-runner/-/loader-runner-4.3.0.tgz",
@@ -33807,6 +33839,11 @@
"fs-monkey": "^1.0.3"
}
},
+ "memoize-one": {
+ "version": "5.2.1",
+ "resolved": "https://registry.npmjs.org/memoize-one/-/memoize-one-5.2.1.tgz",
+ "integrity": "sha512-zYiwtZUcYyXKo/np96AGZAckk+FWWsUdJ3cHGGmld7+AhvcWmQyGCYUh1hc4Q/pkOhb65dQR/pqCyK0cOaHz4Q=="
+ },
"meow": {
"version": "8.1.2",
"resolved": "https://registry.npmjs.org/meow/-/meow-8.1.2.tgz",
@@ -36052,6 +36089,18 @@
"@babel/runtime": "^7.10.3"
}
},
+ "react-player": {
+ "version": "2.10.1",
+ "resolved": "https://registry.npmjs.org/react-player/-/react-player-2.10.1.tgz",
+ "integrity": "sha512-ova0jY1Y1lqLYxOehkzbNEju4rFXYVkr5rdGD71nsiG4UKPzRXQPTd3xjoDssheoMNjZ51mjT5ysTrdQ2tEvsg==",
+ "requires": {
+ "deepmerge": "^4.0.0",
+ "load-script": "^1.0.0",
+ "memoize-one": "^5.1.1",
+ "prop-types": "^15.7.2",
+ "react-fast-compare": "^3.0.1"
+ }
+ },
"react-router": {
"version": "5.3.3",
"resolved": "https://registry.npmjs.org/react-router/-/react-router-5.3.3.tgz",
diff --git a/packages/docs/docs/guides/getting-started/installation.md b/packages/docs/docs/guides/getting-started/installation.md
deleted file mode 100644
index 8e8f69e8..00000000
--- a/packages/docs/docs/guides/getting-started/installation.md
+++ /dev/null
@@ -1,7 +0,0 @@
----
-sidebar_position: 1
----
-
-# Installation
-
-TODO
diff --git a/packages/docs/docs/guides/getting-started/quickstart.mdx b/packages/docs/docs/guides/getting-started/quickstart.mdx
new file mode 100644
index 00000000..ea5fc1da
--- /dev/null
+++ b/packages/docs/docs/guides/getting-started/quickstart.mdx
@@ -0,0 +1,240 @@
+---
+sidebar_position: 2
+---
+
+import ReactPlayer from 'react-player'
+
+# Creating an Animation
+
+In this guide, we will start a new Motion Canvas project and create an animation
+in it.
+
+### Prerequisites
+
+Make sure that [Node.js](https://nodejs.org/) version 16 or greater is
+installed on your machine.
+
+If you're using Motion Canvas as part of the Patreon early access, make sure to
+[authenticate to GitHub Packages][autheticate] first.
+
+### Creating a new project
+
+Run the following command in order to scaffold a new Motion Canvas project:
+
+```bash
+npm init @motion-canvas
+```
+
+Answer the prompts to name your project and select which language you would like
+to use, either TypeScript or plain JavaScript.
+
+:::caution
+
+We recommend using TypeScript in your first project, as our Guides use
+TypeScript.
+
+:::
+
+### Starting the Motion Canvas App
+
+From your new Motion Canvas project directory, run
+
+```shell
+npm run serve
+```
+
+This will start the Motion Canvas editor, which you may open by visiting
+[http://localhost:9000/](http://localhost:9000/). We will use the editor to
+preview our animation, but for now there is nothing to see. To do that, we
+must add an element to our scene.
+
+### Programming an animation
+
+The scaffolding command will create several files for you, but for now we're
+going to focus on `src/scenes/example.scene.tsx`, which is where we can add our
+animations. Open `example.scene.tsx` in a text editor, and replace all code in
+the file with the following snippet.
+
+```tsx
+import {makeKonvaScene} from '@motion-canvas/core/lib/scenes';
+import {Circle} from 'konva/lib/shapes/Circle';
+import {useRef} from '@motion-canvas/core/lib/utils';
+
+export default makeKonvaScene(function* example(view) {
+ const myCircle = useRef();
+
+ view.add(
+ <Circle
+ position={{x: -300, y: 0}}
+ ref={myCircle}
+ width={240}
+ height={240}
+ fill="#ccc"
+ />
+ );
+
+ yield* myCircle.value.position({x: 300, y: 0}, 1);
+});
+```
+
+Now save the file. Any changes you make are automatically picked up and
+reflected in the preview. You should see a gray circle in the preview pane at
+the top right of the web application. Press the play button to see the circle
+animate across the screen.
+
+<ReactPlayer loop controls url='/video/animation.mp4' />
+
+Depending on the size of your browser, you may want to zoom the preview out by
+scrolling down on your mouse wheel while hovering over the preview panel.
+
+### Explanation
+
+Motion Canvas is designed to work with different HTML canvas libraries, though
+it currently only ships with [Konva](https://konvajs.org/) integration. To
+create a new konva scene, we need to call `makeKonvaScene` with a generator
+function.
+
+```tsx
+// highlight-next-line
+import {makeKonvaScene} from '@motion-canvas/core/lib/scenes';
+
+// highlight-next-line
+export default makeKonvaScene(function* example(view) {
+ // animation code
+});
+```
+
+The generator function is passed a `view` argument, which we will use to add
+components to the scene.
+
+:::tip
+If you aren't familiar with generator functions from JavaScript, declared with
+`function*`, you can read the MDN documentation on them [here][generators],
+though a thorough understanding of them is not necessary to start using Motion
+Canvas.
+:::
+
+In order to create an animation, we needed something to animate. For that, we
+used the Konva Circle component.
+
+```tsx
+import {makeKonvaScene} from '@motion-canvas/core/lib/scenes';
+// highlight-next-line
+import {Circle} from 'konva/lib/shapes/Circle';
+
+export default makeKonvaScene(function* example(view) {
+ // highlight-start
+ view.add(
+ <Circle
+ width={240}
+ height={240}
+ fill="#ccc"
+ />
+ );
+ // highlight-end
+});
+```
+
+Here we create a new circle instance with `<Circle />` and add it to the scene
+using `view.add()`. This code alone will show a gray circle in the middle of the
+screen, though it won't move.
+
+To animate the circle, we needed to store a reference to it. This is the purpose
+of the `useRef` call.
+
+```tsx
+import {makeKonvaScene} from '@motion-canvas/core/lib/scenes';
+import {Circle} from 'konva/lib/shapes/Circle';
+// highlight-next-line
+import {useRef} from '@motion-canvas/core/lib/utils';
+
+export default makeKonvaScene(function* example(view) {
+ // highlight-next-line
+ const myCircle = useRef();
+
+ view.add(
+ <Circle
+ // highlight-next-line
+ ref={myCircle}
+ width={240}
+ height={240}
+ fill="#ccc"
+ />
+ );
+
+ // myCircle.value available here
+});
+```
+
+Once the `Circle` is created with `ref={myCircle}`, it may be accessed from
+`myCircle.value`, which we can use to edit the circle's properties. In Konva,
+properties are read using `property()`, and written using `property(value)`. To
+update the circle's position, for instance, we use
+
+```tsx
+myCircle.value.position({x: 300, y: 0});
+```
+
+When we edit the properties of a component, however, the changes are immediate.
+In order to _transition_ to a new value over time, we must change our call in
+two ways. We must specify the duration of the transition in seconds to create an
+animation, `position(value, duration)`, and we must `yield*` to the animation.
+
+```tsx
+yield* myCircle.value.position({x: 300, y: 0}, 1);
+```
+
+The `yield*` is important. Calling `position({...}, 1)` alone will not run the
+animation; it simply returns a value called a task, which represents the
+animation.
+
+```tsx
+const task = myCircle.value.position({x: 300, y: 0}, 1);
+```
+
+Yielding a task prompts Motion Canvas to run it. Using `yield*` waits for the
+animation to complete before continuing the scene function, while using `yield`
+plays the animation but continues the scene function immediately.
+
+```tsx
+yield* myCircle.value.position({x: 300, y: 0}, 1);
+// this line will run after the animation has ended
+```
+```tsx
+yield myCircle.value.position({x: 300, y: 0}, 1);
+// this line will run immediately while the animation plays
+```
+
+In our example, we used `yield*` so that the scene wouldn't end until the
+animation was completed.
+
+```tsx
+import {makeKonvaScene} from '@motion-canvas/core/lib/scenes';
+import {Circle} from 'konva/lib/shapes/Circle';
+import {useRef} from '@motion-canvas/core/lib/utils';
+
+// make a new konva scene and pass it the scene function
+export default makeKonvaScene(function* example(view) {
+ // create a reference to store the circle
+ const myCircle = useRef();
+
+ // create a circle and add it to the scene's view
+ view.add(
+ <Circle
+ position={{x: -300, y: 0}} // set an initial position
+ ref={myCircle} // assign the circle instance to the myCircle ref
+ width={240}
+ height={240}
+ fill="#ccc"
+ />
+ );
+
+ // animate to a new position over 1 second and
+ // wait for it to finish before continuing
+ yield* myCircle.value.position({x: 300, y: 0}, 1);
+});
+```
+
+[installation]: /guides/getting-started/installation
+[generators]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function*
+[autheticate]: https://github.com/motion-canvas/motion-canvas#authenticate-to-github-packages
diff --git a/packages/docs/docs/guides/intro.md b/packages/docs/docs/guides/intro.md
index 8e953810..cd201e71 100644
--- a/packages/docs/docs/guides/intro.md
+++ b/packages/docs/docs/guides/intro.md
@@ -4,4 +4,33 @@ sidebar_position: 1
# Introduction
-TODO
+Motion Canvas is a TypeScript library and web application for creating
+animations programmatically. It was invented to accelerate the process of
+combining informative voice overs with supporting animation, but can satisfy a
+variety of use cases. Animations are programmed in either TypeScript or
+JavaScript using the Motion Canvas core library. The Motion Canvas web app then
+displays a preview of the animations with an audio file of your choice.
+
+Though most details of the animation are driven by code, your program may
+selectively defer the timing of some events to be edited in the web app using a
+function called `waitUntil`. From the web app, you may then drag and drop this
+timing event to fine tune your animations. This is most useful for synchronizing
+the timing of animations with your voice over. This way, you may program the
+precise details of your animation in code, but adjust them manually to match the
+imprecise timing of a recorded voice over.
+
+Motion Canvas is not intended to be a full-sale replacement for a video editor
+like Adobe Premiere Pro or DaVinci Resolve, but it may improve your workflow
+when combined with these other tools.
+
+Motion Canvas is Open Source, and relies on your feedback to inform its
+development. If you would like to report a bug or request a feature, you may
+visit [the GitHub repository][repo] to do so. We cannot satisfy every request,
+but we do read every request, and are dedicated to making Motion Canvas work for
+as wide a user base as possible.
+
+If you would like to contribute pull requests, please read [the contribution
+guide][contributing] to learn about our process.
+
+[contributing]: https://github.com/motion-canvas/motion-canvas/blob/main/CONTRIBUTING.md
+[repo]: https://github.com/motion-canvas/motion-canvas
diff --git a/packages/docs/package.json b/packages/docs/package.json
index fff7e376..1d75ee87 100644
--- a/packages/docs/package.json
+++ b/packages/docs/package.json
@@ -21,7 +21,8 @@
"clsx": "^1.2.0",
"prism-react-renderer": "^1.3.5",
"react": "^17.0.2",
- "react-dom": "^17.0.2"
+ "react-dom": "^17.0.2",
+ "react-player": "^2.10.1"
},
"devDependencies": {
"@docusaurus/module-type-aliases": "^2.0.0",
diff --git a/packages/docs/static/video/animation.mp4 b/packages/docs/static/video/animation.mp4
new file mode 100644
index 00000000..24ca1816
Binary files /dev/null and b/packages/docs/static/video/animation.mp4 differ