diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md new file mode 100644 index 0000000000..fefce97d71 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -0,0 +1,34 @@ +--- +name: Bug Report +about: Report a bug to help us improve +title: "" +labels: bug +assignees: "" +--- + +## Describe the bug + +A clear description of what the bug is. + +## To reproduce + +Steps to reproduce the behavior: + +1. ... +2. ... +3. ... + +## Expected behavior + +What you expected to happen. + +## Environment + +- OS: [e.g., macOS 15, Ubuntu 24.04, Windows 11] +- Node.js version: [e.g., 22.x] +- FFmpeg version: [e.g., 7.x] +- Hyperframes version: [e.g., 0.1.0] + +## Additional context + +Any other context, screenshots, or error logs. diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md new file mode 100644 index 0000000000..d78f7dc1d4 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.md @@ -0,0 +1,23 @@ +--- +name: Feature Request +about: Suggest an idea for Hyperframes +title: "" +labels: enhancement +assignees: "" +--- + +## Problem + +What problem does this solve? What's the use case? + +## Proposed solution + +How should it work? + +## Alternatives considered + +Any alternative approaches you've thought about. + +## Additional context + +Any other context, mockups, or examples. diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 0000000000..0ea369e352 --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,19 @@ +## What + +Brief description of the change. + +## Why + +Why is this change needed? + +## How + +How was this implemented? Any notable design decisions? + +## Test plan + +How was this tested? + +- [ ] Unit tests added/updated +- [ ] Manual testing performed +- [ ] Documentation updated (if applicable) diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000000..f2b20b9267 --- /dev/null +++ b/.gitignore @@ -0,0 +1,38 @@ +# Dependencies +node_modules/ + +# Build output +dist/ +*.tsbuildinfo + +# Environment +.env +.env.local +.env.*.local + +# OS +.DS_Store +Thumbs.db + +# IDE +.vscode/ +.idea/ +*.swp +*.swo + +# Test +coverage/ + +# Rendered output +*.mp4 +*.webm +*.mov +output/ + +# Logs +*.log +npm-debug.log* + +# Temporary +tmp/ +.tmp/ diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000000..410a36b4f1 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,86 @@ +# Contributing to Hyperframes + +Thanks for your interest in contributing to Hyperframes! This guide will help you get started. + +## Getting Started + +1. Fork the repository +2. Clone your fork: `git clone https://github.com/YOUR_USERNAME/hyperframes.git` +3. Install dependencies: `pnpm install` +4. Create a branch: `git checkout -b my-feature` + +## Development Setup + +### Prerequisites + +- [Node.js](https://nodejs.org/) 22+ +- [pnpm](https://pnpm.io/) 9+ +- [FFmpeg](https://ffmpeg.org/) (for rendering) + +### Install & Build + +```bash +pnpm install +pnpm build +``` + +### Run Tests + +```bash +pnpm test +``` + +## Making Changes + +### Code Style + +- TypeScript throughout +- ESLint + Prettier for formatting (run `pnpm lint` to check) +- Write tests for new functionality + +### Commit Messages + +Use [conventional commits](https://www.conventionalcommits.org/): + +``` +feat(core): add CSS frame adapter +fix(producer): handle missing FFmpeg gracefully +docs: update quick start guide +``` + +### Pull Requests + +1. Keep PRs focused — one feature or fix per PR +2. Update documentation if your change affects the public API +3. Ensure all tests pass +4. Add a clear description of what changed and why + +## Project Structure + +``` +hyperframes/ +├── packages/ +│ ├── core/ # @hyperframes/core +│ ├── cli/ # @hyperframes/cli +│ ├── producer/ # @hyperframes/producer +│ ├── studio/ # @hyperframes/studio +│ ├── mcp/ # @hyperframes/mcp +│ └── create-hyperframe/ # scaffolding CLI +├── templates/ # starter templates +├── docs/ # documentation +└── examples/ # extended examples +``` + +## Reporting Issues + +- Use [GitHub Issues](https://github.com/heygen-com/hyperframes/issues) for bug reports and feature requests +- Search existing issues before creating a new one +- Include reproduction steps for bugs + +## Code of Conduct + +Be respectful. We're building something together. + +## License + +By contributing, you agree that your contributions will be licensed under the [MIT License](LICENSE). diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000000..95706d1dfc --- /dev/null +++ b/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2026 HeyGen + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/README.md b/README.md new file mode 100644 index 0000000000..5ad0c60fdd --- /dev/null +++ b/README.md @@ -0,0 +1,88 @@ +# Hyperframes + +**Write HTML. Render video. Built for agents.** + +Hyperframes is an open-source video rendering framework that lets you create, preview, and render HTML-based video compositions — with first-class support for AI agents via MCP. + +## Why Hyperframes? + +- **HTML-native** — AI agents already speak HTML. No React required. +- **Frame Adapter pattern** — bring your own animation runtime (GSAP, Lottie, CSS, Three.js). +- **Deterministic rendering** — same input = identical output. Built for automated pipelines. +- **AI-first design** — not a bolted-on afterthought. + +## Quick Start + +```bash +npx create-hyperframe my-video +cd my-video +npx hyperframes dev # preview in browser +npx hyperframes render # render to MP4 +``` + +## How It Works + +Define your video as HTML with data attributes: + +```html +
+ + + +
+``` + +Preview instantly in the browser. Render to MP4 locally. Let AI agents compose videos using tools they already understand. + +## Packages + +| Package | Description | +|---------|-------------| +| `@hyperframes/core` | Types, schema, parsers, compiler, runtime, frame adapters | +| `@hyperframes/cli` | `npx hyperframes dev \| render \| validate \| init` | +| `@hyperframes/producer` | Local rendering engine (Node.js + Puppeteer + FFmpeg) | +| `@hyperframes/studio` | Browser-based preview/editor | +| `@hyperframes/mcp` | MCP server for AI agent integration | +| `create-hyperframe` | Project scaffolding (`npx create-hyperframe`) | + +## AI Agent Integration + +Hyperframes ships with an MCP server that gives AI agents direct access to video composition tools: + +```bash +npx @hyperframes/mcp +``` + +Works with Claude Code, Cursor, Windsurf, and any MCP-compatible client. Agents can create projects, add elements, set animations, preview frames, and render videos — all through natural language. + +## Comparison with Remotion + +| | Remotion | Hyperframes | +|---|---|---| +| **Composition model** | React components | HTML + data attributes | +| **Animation runtime** | React only | Any (GSAP, Lottie, CSS, Three.js) | +| **AI story** | Added retroactively | AI-native from day 1 | +| **License** | Custom source-available | MIT | +| **Rendering** | Puppeteer + FFmpeg + Lambda | Puppeteer + FFmpeg (Docker-optional) | + +## Requirements + +- Node.js 22+ +- FFmpeg (system install) +- Chromium (auto-downloaded by Puppeteer) + +## Documentation + +Visit [hyperframes.dev](https://hyperframes.dev) for full documentation, guides, and API reference. + +## Contributing + +See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines on how to contribute. + +## License + +[MIT](LICENSE)