github-featured/heygen-com--hyperframes
2
0
Fork 0
Code Issues Pull Requests Deployments Models Agent Notes Packages Projects Releases Wiki Activity

chore: initial repo setup with README, LICENSE, and contributor docs

Browse Source 
- README with hero section, quick start, HTML schema example, package overview, and Remotion comparison
- MIT LICENSE (copyright HeyGen)
- CONTRIBUTING.md with dev setup, commit conventions, and project structure
- GitHub issue templates (bug report, feature request) and PR template
- .gitignore for Node.js/TypeScript projects

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
James
2026-03-10 01:57:26 +00:00
parent a200dac7a9
commit c60a246283
7 changed files with 309 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.github/ISSUE_TEMPLATE/bug_report.md
+34
View File
@@ -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.
.github/ISSUE_TEMPLATE/feature_request.md
+23
View File
@@ -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.
.github/pull_request_template.md
+19
View File
@@ -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)
.gitignore
+38
View File
@@ -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/
CONTRIBUTING.md
+86
View File
@@ -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).
LICENSE
+21
View File
@@ -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.
README.md
+88
View File
@@ -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
<div id="stage" data-composition-id="my-video"
data-start="0" data-width="1920" data-height="1080">
<video id="clip-1" data-start="0" data-duration="5"
data-track="0" src="intro.mp4" muted playsinline></video>
<img id="overlay" data-start="2" data-duration="3"
data-track="1" src="logo.png" />
<audio id="bg-music" data-start="0" data-duration="9"
data-track="2" data-volume="0.5" src="music.wav"></audio>
</div>
```
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)