Skip to content

Play a finished motion-graphics ad in sync with the rough drafts it grew from, and export the breakdown as MP4.

docs: tighten README first screen, add Discord CTA, FAQ, and Null Studio note

Kaihan Wasely31d18c7cdfbb
diff --git a/README.md b/README.md
index 81e56e3..55d55c1 100644
--- a/README.md
+++ b/README.md
@@ -1,65 +1,67 @@
<p align="center">
- <img src="docs/logo.png" width="104" alt="Null logo">
+ <img src="docs/logo.png" width="96" alt="Null logo">
</p>
<h1 align="center">Null Motion</h1>
<p align="center">
- <b>From rough drafts to a finished ad.</b>
+ <b>Watch a finished motion-graphics ad play over the rough drafts it grew from, frame-synced.<br>Then export the whole breakdown as one MP4.</b>
+</p>
+
+<p align="center">
+ <a href="https://discord.gg/zEB4VjmfSb"><img src="https://img.shields.io/badge/Join%20the%20Discord-questions%2C%20help%2C%20show%20your%20renders-5865F2?style=for-the-badge&logo=discord&logoColor=white" alt="Join the Discord: questions, help, show your renders"></a>
</p>
<p align="center">
<a href="https://github.com/blixvip/NullMotion/stargazers"><img src="https://img.shields.io/github/stars/blixvip/NullMotion?style=flat-square&color=ff5a1f" alt="GitHub stars"></a>
+ <a href="https://github.com/blixvip/NullMotion/releases"><img src="https://img.shields.io/github/v/release/blixvip/NullMotion?style=flat-square&color=111" alt="Latest release"></a>
<img src="https://img.shields.io/badge/node-22%2B-111?style=flat-square" alt="Node 22+">
<img src="https://img.shields.io/badge/dependencies-none-111?style=flat-square" alt="No runtime dependencies">
- <img src="https://img.shields.io/badge/drafts-HTML%20%2B%20GSAP-111?style=flat-square" alt="Drafts in HTML and GSAP">
<img src="https://img.shields.io/badge/export-MP4%20%C2%B7%20WebCodecs-ff5a1f?style=flat-square" alt="MP4 export with WebCodecs">
- <a href="https://discord.gg/zEB4VjmfSb"><img src="https://img.shields.io/badge/Discord-Join%20the%20community-5865F2?style=flat-square&logo=discord&logoColor=white" alt="Discord"></a>
</p>
<p align="center">
- <a href="https://www.nullmotion.com/"><strong>nullmotion.com</strong></a>
- &nbsp;·&nbsp; <a href="https://www.nullmotion.com/mcp">Edit with Claude, Codex, or Cursor</a>
- &nbsp;·&nbsp; <a href="https://www.nullmotion.com/youtube-clip-maker">YouTube</a>
- &nbsp;·&nbsp; <a href="https://www.nullmotion.com/twitch-clip-maker">Twitch</a>
- &nbsp;·&nbsp; <a href="https://www.nullmotion.com/kick-clip-maker">Kick</a>
+ <img src="docs/demo-infinite.gif" width="820" alt="The Infinite ad playing on top, its black-and-white drafts underneath, in sync">
</p>
<p align="center">
- <img src="docs/demo-infinite.gif" width="820" alt="Infinite ad playing above its drafts">
+ <sub>Top: the finished ad. Bottom: one plain black-and-white HyperFrames draft per section. The playhead and the orange outline follow the film frame for frame.</sub>
</p>
-<p align="center">
- <sub>A finished motion-graphics ad plays on top. Underneath: the simple black-and-white HyperFrames drafts it grew from, one per section, in sync with the film.<br>
- <b>Null Studio</b> cuts pauses, captions the words, and turns long videos into vertical clips. You review the edit on a timeline.</sub>
-</p>
+## Quick start
+
+```sh
+git clone https://github.com/blixvip/NullMotion.git && cd NullMotion # 1. get it
+npm start # 2. run it (Node 22+, nothing to install)
+```
+
+3. Open **<http://127.0.0.1:4343>**, pick a reference, and press **Download → Whole preview** (Chrome or Edge) to get the MP4.
+
+No `npm install`, no API keys, no account. Three references ship with the repo, so it works on the first run.
+
+> **Not the same as Null Studio.** This repo is the free, local launch-film preview. Pause cuts, captions, and YouTube, Twitch, and Kick clips are **Null Studio**, a separate hosted product at [nullmotion.com](https://www.nullmotion.com/). They are not in this code.
<p align="center">
- <a href="#why">Why</a> ·
<a href="#what-it-does">What it does</a> ·
<a href="#showcase">Showcase</a> ·
- <a href="#quick-start">Quick start</a> ·
<a href="#how-it-works">How it works</a> ·
<a href="#bring-your-own-references">Bring your own references</a> ·
+ <a href="#faq-and-troubleshooting">FAQ</a> ·
<a href="#project-layout">Project layout</a> ·
- <a href="#notes">Notes</a> ·
+ <a href="#contributing">Contributing</a> ·
<a href="#community">Community</a>
</p>
---
-## Why
-
-Motion-graphics ads look effortless, but every one starts as a rough plan: which idea goes in which section, and when each move lands. Null Motion puts that plan and the finished film side by side, frame-synced, so you can study how a great ad is built, pitch a concept, or export the whole breakdown as one video.
-
## What it does
-Every great ad starts as a rough draft. Null shows both at once:
+Motion-graphics ads look effortless, but every one starts as a rough plan: which idea goes in which section, and when each move lands. Null Motion puts that plan and the finished film side by side, so you can study how a great ad is built, pitch a concept, or export the whole breakdown as one video.
- **The final film on top.** The full ad, full width, playing on a loop.
- **Its drafts underneath.** Each section (Hook, Reveal, App, End card…) has a plain HyperFrames scene: black and white, Arial type, flat shapes, one simple move. It shows the idea before the polish.
- **Everything in sync.** A playhead runs across the drafts. The draft for the section on screen follows the film frame for frame and gets an orange outline. The others keep looping their own part.
-- **One-click export.** **Download → Whole preview** renders the film and its drafts frame by frame into a smooth, high-bitrate MP4 with the film's audio.
+- **One-click export.** **Download → Whole preview** renders the film and its drafts frame by frame into a 1920-wide, 24 Mbps MP4 with the film's audio.
<p align="center">
<img src="docs/screenshot.jpg" width="820" alt="The Null Motion page: film, drafts, and the video library">
@@ -81,26 +83,9 @@ The repo ships three references with their drafts, ready to play:
These clips come from other creators and are used as examples. They are not claims of commissioned work.
-## Quick start
-
-```sh
-git clone https://github.com/blixvip/NullMotion.git
-cd NullMotion
-npm start
-```
-
-Open **<http://127.0.0.1:4343>**. You need only Node.js 22 or newer: there's nothing to install and no keys to configure. Export needs Chrome or Edge (WebCodecs).
-
-### Requirements
-
-| | Needed for |
-|---|---|
-| **Node.js 22+** | Running the local server (`npm start`). No `npm install` step: there are no dependencies. |
-| **Chrome or Edge** | MP4 export (WebCodecs + `requestVideoFrameCallback`). |
-| **FFmpeg / ffprobe** (optional) | Importing your own references, planning sections, and rebuilding the showcase. |
-| **Python 3** (optional) | `scripts/import-motionclone.py`. |
+### 🎬 Show what you made
-Set `PORT` or `HOST` to change the bind address (default `127.0.0.1:4343`).
+Exported a breakdown or built drafts for your own ad? Post it in the **[Discord](https://discord.gg/zEB4VjmfSb)**. We'd love to see it.
## How it works
@@ -109,6 +94,15 @@ Set `PORT` or `HOST` to change the bind address (default `127.0.0.1:4343`).
3. **Playback.** The page drives every draft's timeline from the film's clock. The active section follows the film, and the others loop.
4. **Export.** A hidden copy of the film plays at half speed. `requestVideoFrameCallback` captures every decoded frame, the drafts are drawn at that frame's exact time, and WebCodecs encodes it at 24 Mbps with the frame's own timestamp. The audio is copied from the reference, and [mp4-muxer](https://github.com/Vanilagy/mp4-muxer) writes the MP4. Nothing is recorded in real time, so no frames are dropped.
+### Requirements
+
+| | Needed for |
+|---|---|
+| **Node.js 22+** | Running the local server (`npm start`). No dependencies to install. |
+| **Chrome or Edge** | MP4 export (WebCodecs + `requestVideoFrameCallback`). Playback works in any modern browser. |
+| **FFmpeg / ffprobe** (optional) | Importing your own references, planning sections, rebuilding the showcase, and extracting audio for imported references. |
+| **Python 3** (optional) | `scripts/import-motionclone.py`. |
+
## Bring your own references
With Python, FFmpeg and ffprobe installed:
@@ -118,9 +112,37 @@ python scripts/import-motionclone.py --source /path/to/MotionClone
node scripts/plan-sections.mjs # sections + scene cuts + contact sheets
```
-Imported media stays local in `.local-media/` and `public/references/` (both ignored by Git) and takes precedence over the showcase. Videos are hard-linked, so the MotionClone folder must be on the same drive as this repo. Describe each section's beats in `public/references/drafts.json`. Undescribed sections get placeholder drafts. `npm run showcase` rebuilds `showcase/` from the local library.
+Imported media stays local in `.local-media/` and `public/references/` (both ignored by Git) and takes precedence over the showcase. Describe each section's beats in `public/references/drafts.json`. Undescribed sections get placeholder drafts. `npm run showcase` rebuilds `showcase/` from the local library.
+
+The importer creates non-destructive segments, extracts thumbnails, and hard-links the source videos when they are on the same drive as this repo (otherwise it copies them). Original files are only read. The server streams byte ranges, so seeking never reads a whole video into memory.
+
+## FAQ and troubleshooting
+
+**The Download button says "Needs Chrome or Edge".**
+Export uses WebCodecs and `requestVideoFrameCallback`. Use a current Chrome or Edge. Firefox and Safari can play the preview but can't export.
+
+**How long does an export take?**
+The film is rendered at half speed so no frame is skipped, so expect it to take at least twice the film's length (a minute or more for the 30-second Infinite ad). Keep the tab in front while it renders, because browsers slow down video in background tabs.
-The importer creates non-destructive segments, extracts thumbnails, and links the source videos. Original files are read only. The server streams byte ranges, so seeking never reads a whole video into memory.
+**My export has no sound.**
+The showcase ships its audio. For your own imported references the server extracts the audio with FFmpeg on first export, so FFmpeg must be on your `PATH`.
+
+**The import failed with "Invalid cross-device link" (EXDEV).**
+Older versions only hard-linked videos, which only works on one drive. Pull the latest `main`: the importer now copies the video when a link isn't possible. A copy uses extra disk space, so keep MotionClone on the same drive as this repo if space is tight.
+
+**"No data/ folder in …" when importing.**
+`--source` must point at the MotionClone project folder (the one that contains `data/`), not at a single video.
+
+**Port 4343 is already in use, or I want to open it from another device.**
+Set `PORT` and/or `HOST`, for example `PORT=5000 npm start` or `HOST=0.0.0.0 npm start` (default `127.0.0.1:4343`).
+
+**The template gallery or editor says "generation not connected".**
+That's intentional. Generation, rendering services, and Premiere are not connected in this repo, and the server answers those calls with `501 NOT_CONNECTED`. The drafts are authored, not AI-generated.
+
+**Can I make vertical clips, cut pauses, or add captions with this?**
+No. Those are features of Null Studio at [nullmotion.com](https://www.nullmotion.com/), a separate hosted product.
+
+Stuck on something else? Ask in the **[Discord](https://discord.gg/zEB4VjmfSb)** or [open an issue](https://github.com/blixvip/NullMotion/issues/new/choose).
## Project layout
@@ -143,10 +165,18 @@ npm test # node --test
## Notes
-- The browser only calls this project's own origin. Generation, rendering services and Premiere are not connected. The drafts are authored, not AI-generated.
+- The browser only calls this project's own origin.
- The earlier launch editor (reference timeline, trimming, brand overlay) is at `/editor`, and the original Null Motion template gallery is at `/index.html`.
- Bundled GSAP and mp4-muxer keep their licenses; see [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md). Brand artwork and reference footage belong to their respective owners. No project-wide open-source license has been selected.
+## Contributing
+
+Bug reports, draft ideas, and pull requests are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for setup and checks. For questions, the [Discord](https://discord.gg/zEB4VjmfSb) is the fastest place to ask.
+
## Community
-💬 [Join the Discord](https://discord.gg/zEB4VjmfSb) for questions, help, feedback, and updates.
+<p align="center">
+ <a href="https://discord.gg/zEB4VjmfSb"><img src="https://img.shields.io/badge/Discord-Join%20Insider%20AI-5865F2?style=for-the-badge&logo=discord&logoColor=white" alt="Join the Insider AI Discord"></a>
+</p>
+
+💬 Questions, help, feedback, release news, and your renders all go in **[Insider AI on Discord](https://discord.gg/zEB4VjmfSb)**. If Null Motion helped you, a ⭐ helps other people find it.