diff --git a/README.md b/README.md
index f84b4d4f64..e4fc97da5d 100644
--- a/README.md
+++ b/README.md
@@ -17,12 +17,12 @@
Write HTML. Render video. Built for agents.
- Studio |
- Quickstart |
- Showcase |
- Playground |
- Catalog |
- Docs |
+ Studio |
+ Quickstart |
+ Showcase |
+ Playground |
+ Catalog |
+ Docs |
Discord
@@ -124,7 +124,7 @@ This writes `dist/hyperframes-plugin.zip` with a `hyperframes/` root folder and
| `/reverse-any-video` | Rebuilding any video file as an editable HyperFrames project (motion graphics, talking heads, live action, AI-generated footage), checked frame by frame against the original. HyperFrames Pro. |
| `/style-sampling` | Making a new episode on your topic in one of five proven styles: Collage Explainer, Finance Explainer, Animated Science Explainer, 3D Brand Explainer, 3D True Crime. HyperFrames Pro. |
-For visual design handoff workflows, see the [Claude Design guide](https://hyperframes.heygen.com/guides/claude-design) and [Open Design guide](https://hyperframes.heygen.com/guides/open-design).
+For visual design handoff workflows, see the [Claude Design guide](https://hyperframes.heygen.com/guides/design-tools?utm_source=github&utm_medium=readme#start-from-claude-design-or-open-design) and [Open Design guide](https://hyperframes.heygen.com/guides/design-tools?utm_source=github&utm_medium=readme#start-from-claude-design-or-open-design).
### Manually with the CLI
@@ -139,7 +139,7 @@ npx hyperframes render # render to MP4
## What You Can Build
-Need ideas? Browse the [Showcase](https://hyperframes.heygen.com/showcase) for finished videos you can watch, read, run, and remix.
+Need ideas? Browse the [Showcase](https://hyperframes.heygen.com/examples?utm_source=github&utm_medium=readme) for finished videos you can watch, read, run, and remix.
- Product launch videos and feature announcements
- PR walkthroughs with animated code diffs, narration, and captions
@@ -159,57 +159,57 @@ The output is a `DESIGN.md` superset your whole toolchain can read. Atoms stay s
-Browse and remix them all at [hyperframes.studio/design](https://hyperframes.studio/design).
+Browse and remix them all at [hyperframes.studio/design](https://hyperframes.studio/design?utm_source=github&utm_medium=readme).
## How It Works
@@ -253,16 +253,16 @@ Preview instantly in the browser. Render locally or in Docker. The renderer seek
HyperFrames is the open-source rendering engine, plus a growing set of tools around HTML-native video creation.
-| Piece | Status | What it does |
-| ------------------------------------------------- | ------------------- | ------------------------------------------------------------------------------------------------- |
-| CLI | Available | Scaffold, preview, lint, inspect, and render local video projects |
-| Core / Engine / Producer | Available | Parse compositions, drive headless Chrome, encode video, and mix audio |
-| Catalog | Available | Reusable blocks and components for transitions, overlays, captions, charts, maps, and effects |
-| Agent skills | Available | Teach coding agents the video-production patterns that generic web docs miss |
-| Studio | Available, evolving | Browser surface for previewing and editing compositions |
-| AWS Lambda rendering | Available | Deploy a distributed render stack and drive renders from your laptop or CI |
-| [hyperframes.studio](https://hyperframes.studio/) | Available | Community playground for previewing, iterating, sharing, and rendering HTML-native video projects |
-| [frame.md](https://hyperframes.studio/design) | Available | Invert your design system for the camera — a DESIGN.md superset an agent can compose video from |
+| Piece | Status | What it does |
+| ------------------------------------------------------------------------------------- | ------------------- | ------------------------------------------------------------------------------------------------- |
+| CLI | Available | Scaffold, preview, lint, inspect, and render local video projects |
+| Core / Engine / Producer | Available | Parse compositions, drive headless Chrome, encode video, and mix audio |
+| Catalog | Available | Reusable blocks and components for transitions, overlays, captions, charts, maps, and effects |
+| Agent skills | Available | Teach coding agents the video-production patterns that generic web docs miss |
+| Studio | Available, evolving | Browser surface for previewing and editing compositions |
+| AWS Lambda rendering | Available | Deploy a distributed render stack and drive renders from your laptop or CI |
+| [hyperframes.studio](https://hyperframes.studio/?utm_source=github&utm_medium=readme) | Available | Community playground for previewing, iterating, sharing, and rendering HTML-native video projects |
+| [frame.md](https://hyperframes.studio/design?utm_source=github&utm_medium=readme) | Available | Invert your design system for the camera — a DESIGN.md superset an agent can compose video from |
## Catalog
@@ -274,7 +274,7 @@ npx hyperframes add instagram-follow # social overlay
npx hyperframes add data-chart # animated chart
```
-Browse the catalog at [hyperframes.heygen.com/catalog](https://hyperframes.heygen.com/catalog/blocks/data-chart).
+Browse the catalog at [hyperframes.heygen.com/catalog](https://hyperframes.heygen.com/catalog/blocks/data-chart?utm_source=github&utm_medium=readme).
## Why HyperFrames?
@@ -298,19 +298,19 @@ HyperFrames is inspired by [Remotion](https://www.remotion.dev). Both tools rend
| Distributed rendering | Local and AWS Lambda render paths | Remotion Lambda, mature cloud renderer |
| License | Apache 2.0 | Source-available Remotion License |
-Read the full comparison in the [HyperFrames vs Remotion guide](https://hyperframes.heygen.com/guides/hyperframes-vs-remotion).
+Read the full comparison in the [HyperFrames vs Remotion guide](https://hyperframes.heygen.com/guides/hyperframes-vs-remotion?utm_source=github&utm_medium=readme).
## Documentation
-Full documentation: [hyperframes.heygen.com/introduction](https://hyperframes.heygen.com/introduction)
+Full documentation: [hyperframes.heygen.com/introduction](https://hyperframes.heygen.com/introduction?utm_source=github&utm_medium=readme)
-- [Quickstart](https://hyperframes.heygen.com/quickstart)
-- [Showcase](https://hyperframes.heygen.com/showcase)
-- [Guides](https://hyperframes.heygen.com/guides/gsap-animation)
-- [API Reference](https://hyperframes.heygen.com/packages/core)
-- [Catalog](https://hyperframes.heygen.com/catalog/blocks/data-chart)
-- [Examples](https://hyperframes.heygen.com/examples)
-- [AWS Lambda rendering](https://hyperframes.heygen.com/deploy/aws-lambda)
+- [Quickstart](https://hyperframes.heygen.com/quickstart?utm_source=github&utm_medium=readme)
+- [Showcase](https://hyperframes.heygen.com/examples?utm_source=github&utm_medium=readme)
+- [Guides](https://hyperframes.heygen.com/guides/gsap-animation?utm_source=github&utm_medium=readme)
+- [API Reference](https://hyperframes.heygen.com/packages/core?utm_source=github&utm_medium=readme)
+- [Catalog](https://hyperframes.heygen.com/catalog/blocks/data-chart?utm_source=github&utm_medium=readme)
+- [Examples](https://hyperframes.heygen.com/examples?utm_source=github&utm_medium=readme)
+- [AWS Lambda rendering](https://hyperframes.heygen.com/deploy/aws-lambda?utm_source=github&utm_medium=readme)
## Packages
@@ -327,7 +327,7 @@ Full documentation: [hyperframes.heygen.com/introduction](https://hyperframes.he
## Community
-HyperFrames is used in production at [HeyGen](https://www.heygen.com), with community examples from teams like [tldraw](https://tldraw.com), [TanStack](https://tanstack.com), and others in [ADOPTERS.md](ADOPTERS.md). Open a PR if your team is using HyperFrames.
+HyperFrames is used in production at [HeyGen](https://www.heygen.com?utm_source=github&utm_medium=readme), with community examples from teams like [tldraw](https://tldraw.com), [TanStack](https://tanstack.com), and others in [ADOPTERS.md](ADOPTERS.md). Open a PR if your team is using HyperFrames.
- Questions and ideas: [Discord](https://discord.gg/fzbdWyjphr)
- Bugs and feature requests: [GitHub Issues](https://github.com/heygen-com/hyperframes/issues)
diff --git a/docs/docs.json b/docs/docs.json
index b6aca7a5f8..1ad3c55479 100644
--- a/docs/docs.json
+++ b/docs/docs.json
@@ -326,13 +326,13 @@
"item": "Community",
"icon": "users",
"description": "Videos people made",
- "href": "https://hyperframes.studio/?view=community"
+ "href": "https://hyperframes.studio/?view=community&src=docs-navbar"
},
{
"item": "App changelog",
"icon": "sparkles",
"description": "What's new in the app",
- "href": "https://hyperframes.studio/changelog"
+ "href": "https://hyperframes.studio/changelog?src=docs-navbar"
}
]
},
diff --git a/docs/studio-app/export.mdx b/docs/studio-app/export.mdx
index 3356362485..65b5c3a501 100644
--- a/docs/studio-app/export.mdx
+++ b/docs/studio-app/export.mdx
@@ -73,7 +73,7 @@ Watch the exported file once from start to end before you send it.
- **The video was made but could not be saved to your Downloads folder**: free up space or check that the Downloads
folder exists, then export again.
- **HyperFrames could not start its built-in FFmpeg**: the app may be damaged. Reinstall it from
- [hyperframes.studio/studio](https://hyperframes.studio/studio).
+ [hyperframes.studio/studio](https://hyperframes.studio/studio?src=docs-export).
## Related topics
diff --git a/packages/cli/src/commands/auth/status-guidance.ts b/packages/cli/src/commands/auth/status-guidance.ts
index 866dc17212..7f3dc8390d 100644
--- a/packages/cli/src/commands/auth/status-guidance.ts
+++ b/packages/cli/src/commands/auth/status-guidance.ts
@@ -8,6 +8,7 @@
*/
import { c } from "../../ui/colors.js";
+import { cliSourced } from "../../utils/sourceTag.js";
export interface UnconfiguredContext {
/** A human can act on guidance now — a TTY, or a coding agent driving the CLI. */
@@ -88,7 +89,7 @@ export function buildUnconfiguredLines(
"Sign in or sign up (browser OAuth, writes ~/.hyperframes — no per-repo .env):",
` ${c.accent("npx hyperframes auth login")} ${c.dim("# browser sign-in / sign-up")}`,
"",
- "Or paste an existing HeyGen API key (get one at app.heygen.com/settings/api):",
+ `Or paste an existing HeyGen API key (get one at ${cliSourced("https://app.heygen.com/settings/api")}):`,
` ${c.accent("npx hyperframes auth login --api-key")} ${c.dim("# paste at the prompt")}`,
"",
...offlineEngineLines(engines),
diff --git a/packages/cli/src/commands/init.ts b/packages/cli/src/commands/init.ts
index f9d6c5acbc..eb901b7a4e 100644
--- a/packages/cli/src/commands/init.ts
+++ b/packages/cli/src/commands/init.ts
@@ -60,6 +60,7 @@ import {
VIEWPORT_META_SIZE_RE,
} from "@hyperframes/parsers";
import { decodableAudioStream } from "@hyperframes/parsers/media-streams";
+import { cliSourced } from "../utils/sourceTag.js";
function resolveScaffoldTemplateId(exampleFlag: string | undefined, hasMediaFile: boolean): string {
const example = exampleFlag === "agent" ? "blank" : exampleFlag;
@@ -997,7 +998,9 @@ export default defineCommand({
console.log(
` ${c.dim('"Using /hyperframes, create a 15-second intro about [your topic]"')}`,
);
- console.log(` ${c.dim("More patterns: hyperframes.heygen.com/prompting/overview")}`);
+ console.log(
+ ` ${c.dim(`More patterns: ${cliSourced("https://hyperframes.heygen.com/prompting/overview")}`)}`,
+ );
console.log();
console.log(` ${c.accent("4.")} Preview in the browser:`);
console.log(` ${c.accent(`cd ${name}`)} && ${c.accent("npm run dev")}`);
@@ -1008,7 +1011,7 @@ export default defineCommand({
console.log(` ${c.accent("6.")} Render to MP4 when ready:`);
console.log(` ${c.accent(`cd ${name}`)} && ${c.accent("npm run render")}`);
console.log();
- console.log(` ${c.dim("Full docs: hyperframes.heygen.com")}`);
+ console.log(` ${c.dim(`Full docs: ${cliSourced("https://hyperframes.heygen.com")}`)}`);
return;
}
diff --git a/packages/cli/src/commands/lambda/prebuiltHandler.test.ts b/packages/cli/src/commands/lambda/prebuiltHandler.test.ts
index 9817463e6c..f07f1d67fa 100644
--- a/packages/cli/src/commands/lambda/prebuiltHandler.test.ts
+++ b/packages/cli/src/commands/lambda/prebuiltHandler.test.ts
@@ -109,7 +109,9 @@ describe("stagePrebuiltHandler with nothing to deploy", () => {
const message = noHandlerMessage(false);
expect(message).toMatch(/npm install -g @hyperframes\/aws-lambda@/);
expect(message).toMatch(/HYPERFRAMES_REPO_ROOT/);
- expect(message).toMatch(/^Docs: https:\/\/hyperframes\.heygen\.com\/deploy\/aws-lambda$/m);
+ expect(message).toMatch(
+ /^Docs: https:\/\/hyperframes\.heygen\.com\/deploy\/aws-lambda\?utm_source=cli$/m,
+ );
expect(downloads).toEqual([]);
});
diff --git a/packages/cli/src/commands/lambda/prebuiltHandler.ts b/packages/cli/src/commands/lambda/prebuiltHandler.ts
index 2a6df0fae6..481b6098d5 100644
--- a/packages/cli/src/commands/lambda/prebuiltHandler.ts
+++ b/packages/cli/src/commands/lambda/prebuiltHandler.ts
@@ -16,8 +16,9 @@ import { downloadFile } from "../../utils/download.js";
import { isMissingPackageError } from "../../utils/missingPackage.js";
import { VERSION } from "../../version.js";
import { hyperframesCacheDir } from "@hyperframes/core/cache-dir";
+import { cliSourced } from "../../utils/sourceTag.js";
-const DOCS_URL = "https://hyperframes.heygen.com/deploy/aws-lambda";
+const DOCS_URL = cliSourced("https://hyperframes.heygen.com/deploy/aws-lambda");
const HANDLER_CACHE_DIR = hyperframesCacheDir("lambda-handler");
type AdapterSdk = typeof import("@hyperframes/aws-lambda/sdk");
diff --git a/packages/cli/src/commands/publish.ts b/packages/cli/src/commands/publish.ts
index f81c4d937e..2584165245 100644
--- a/packages/cli/src/commands/publish.ts
+++ b/packages/cli/src/commands/publish.ts
@@ -29,6 +29,7 @@ import {
readTeamProject,
writeTeamProject,
} from "../utils/projectLink.js";
+import { cliSourced } from "../utils/sourceTag.js";
export const examples: Example[] = [
["Publish the current project privately to a stable URL", "hyperframes publish"],
@@ -313,7 +314,7 @@ export default defineCommand({
} else {
const claimUrl = new URL(published.url);
claimUrl.searchParams.set("claim_token", published.claimToken);
- console.log(` ${c.dim("Claim URL")} ${c.accent(claimUrl.toString())}`);
+ console.log(` ${c.dim("Claim URL")} ${c.accent(cliSourced(claimUrl.toString()))}`);
console.log(` ${c.dim("Access")} ${c.accent("Sign in required to claim")}`);
console.log();
console.log(
diff --git a/packages/cli/src/utils/sourceTag.test.ts b/packages/cli/src/utils/sourceTag.test.ts
new file mode 100644
index 0000000000..09c5dc00b7
--- /dev/null
+++ b/packages/cli/src/utils/sourceTag.test.ts
@@ -0,0 +1,27 @@
+import { describe, expect, it } from "vitest";
+import { cliSourced } from "./sourceTag.js";
+
+describe("cliSourced", () => {
+ it("tags our sites with utm_source=cli, keeping the query and fragment", () => {
+ expect(cliSourced("https://hyperframes.heygen.com/prompting/overview")).toBe(
+ "https://hyperframes.heygen.com/prompting/overview?utm_source=cli",
+ );
+ expect(cliSourced("https://hyperframes.studio/p/abc?claim_token=t#top")).toBe(
+ "https://hyperframes.studio/p/abc?claim_token=t&utm_source=cli#top",
+ );
+ expect(cliSourced("https://app.heygen.com/settings/api")).toBe(
+ "https://app.heygen.com/settings/api?utm_source=cli",
+ );
+ });
+
+ it("leaves other hosts, look-alikes, an existing source and non-URLs alone", () => {
+ for (const url of [
+ "https://github.com/heygen-com/hyperframes",
+ "https://hyperframes.app/",
+ "https://notheygen.com/",
+ "https://hyperframes.studio/?utm_source=github",
+ "not a url",
+ ])
+ expect(cliSourced(url)).toBe(url);
+ });
+});
diff --git a/packages/cli/src/utils/sourceTag.ts b/packages/cli/src/utils/sourceTag.ts
new file mode 100644
index 0000000000..496474cbc7
--- /dev/null
+++ b/packages/cli/src/utils/sourceTag.ts
@@ -0,0 +1,10 @@
+// A link the CLI prints to one of our sites says it came from the CLI; a link that already names a source keeps it.
+const OUR_HOST = /(^|\.)(hyperframes\.studio|hyperframes\.heygen\.com|heygen\.com)$/;
+
+export function cliSourced(url: string): string {
+ if (!URL.canParse(url)) return url;
+ const parsed = new URL(url);
+ if (!OUR_HOST.test(parsed.hostname) || parsed.searchParams.has("utm_source")) return url;
+ parsed.searchParams.set("utm_source", "cli");
+ return parsed.toString();
+}