diff --git a/docs/catalog/index.mdx b/docs/catalog/index.mdx index 560e7b46f6..355b8885a1 100644 --- a/docs/catalog/index.mdx +++ b/docs/catalog/index.mdx @@ -7,40 +7,52 @@ The Catalog is a library of visuals you can add to a project instead of building Use a **block** when you want a larger scene or self-contained visual. Use a **component** when you want a smaller effect or behavior inside an existing scene. -## Find the right starting point +## Start with the job - Typing, diffs, highlights, editor scenes, terminal scenes, and 3D code treatments. + Show code being typed, changed, highlighted, scrolled, or transformed. - Readable subtitle styles and more expressive word-level treatments. + Keep speech readable or emphasize selected words without designing a caption system from zero. - CSS and shader transitions for moving between scenes. + Move between scenes with a quiet cut treatment or a more expressive transition. - Posts, follow prompts, notifications, lower thirds, and platform-inspired cards. + Show posts, follow prompts, notifications, names, roles, and platform-inspired cards. - Charts, counters, maps, and geographic flows. + Explain a number, comparison, trend, location, or geographic movement. - Larger examples that combine design, media, and animation. + Start from a larger scene that already combines design, media, and animation. -## Add an item +## Use an item in a real project -Each catalog page shows what the item does and where it belongs. Ask your agent to add it, or use the command shown on the item page. +1. Open an item and watch the motion preview. +2. Check that its communication job matches the scene. +3. Copy the plain-language request from the item page into your agent chat. +4. Replace the example content with real project content. +5. Match the project's type, color, spacing, and motion language. +6. Review the item inside the complete video, not only in isolation. -After adding an item: +The terminal command and source details remain available on each item page for people who need them. -1. Replace its example content with your real content. -2. Match the colors and type to your project. -3. Check timing in the complete video, not only in isolation. -4. Keep the parts that serve the story; remove decorative motion that does not. +## Before you keep it - Catalog items are starting points. A good result usually needs content, timing, and styling changes to feel native to your project. + A Catalog item is a starting point, not a finished design decision. Keep it only when it makes the scene clearer or faster to understand. Remove decorative motion that competes with the story. + +Check: + +- Can the viewer understand why the visual is present? +- Is the real content readable at the final size? +- Does its timing fit the scenes around it? +- Does it feel like part of this project rather than a pasted demo? +- Is a quieter alternative more effective? + +[Learn how to add Catalog items in Studio →](/studio/assets-and-blocks) diff --git a/docs/developers/index.mdx b/docs/developers/index.mdx index 0d242c9c99..fbda8041b8 100644 --- a/docs/developers/index.mdx +++ b/docs/developers/index.mdx @@ -7,33 +7,55 @@ This section is for people integrating HyperFrames, automating it, extending the If you only want to create or edit a video, begin with [Guides](/guides) or [Studio](/studio). +## Choose the smallest surface + +```mermaid +flowchart TD + A["What does your system need to do?"] --> B["Run commands or CI jobs"] + A --> C["Inspect or edit compositions in an app"] + A --> D["Embed playback"] + A --> E["Operate custom render infrastructure"] + A --> F["Generate or validate raw composition source"] + B --> G["CLI"] + C --> H["SDK"] + D --> I["Player"] + E --> J["Focused packages and deployment guides"] + F --> K["HTML schema and animation reference"] +``` + - Choose the command for creating, checking, rendering, publishing, and automating projects. + Create, check, render, publish, and automate projects from a terminal or CI job. - - Query and edit compositions, persist changes, and build custom editing surfaces. + + Open a composition, query or edit it, persist changes, and build custom editing surfaces. + + + Embed a seekable HyperFrames composition and control playback from an application. - Use the framework as focused packages for parsing, playback, rendering, Studio, and infrastructure. - - - Reference the composition elements, timing attributes, tracks, variables, and media contract. + Add focused parsing, playback, rendering, Studio, or infrastructure capabilities. Render with managed cloud infrastructure, AWS Lambda, or Google Cloud Run. - - Work on the framework, Catalog, tests, and releases. + + Reference composition elements, timing attributes, tracks, variables, and the media contract. -## Start with the smallest surface +## A good first technical result -- Use the **CLI** for normal project and render automation. -- Use the **SDK** when your application needs to inspect or edit compositions. -- Use the **Player** when you need embedded playback. -- Install individual **packages** when you are building infrastructure or a custom product surface. -- Read the raw **schema** when generating or validating composition source. +Choose one result rather than installing the whole repository: -Most applications do not need to depend on every package. +- render one known project from a script or CI job; +- open one composition with the SDK and change one value; +- embed one project with the Player and seek to a timestamp; +- deploy one minimal render path; +- validate one generated composition against the schema. + +Continue to package or reference pages only when that working path requires more control. Most integrations should not depend on every HyperFrames package. + +## Working on HyperFrames itself? + +Use [Contributing](/contributing) for repository setup, tests, Catalog contributions, and releases. Product integrations should begin with one of the surfaces above instead. diff --git a/docs/docs.json b/docs/docs.json index 3394953382..46a4f7ceee 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -57,7 +57,7 @@ "guides/index", "introduction", "quickstart", - "guides/choose-your-path", + "workflows", "guides/project-tour", "guides/authentication", "guides/mcp" @@ -66,17 +66,10 @@ { "group": "Create with an agent", "pages": [ - "guides/create-with-agent", - "guides/skills", "guides/prompting", "guides/pipeline", "guides/design-tools", - "guides/claude-design-hyperframes", - "guides/claude-design-send-to-hyperframes", - "guides/open-design-hyperframes", - "guides/figma", - "guides/antigravity", - "guides/copilot-cli" + "guides/figma" ] }, { @@ -88,6 +81,7 @@ "guides/captions-and-recuts", "guides/motion-graphics", "guides/music-to-video", + "guides/slideshow", "guides/general-video" ] }, @@ -138,7 +132,7 @@ { "group": "Help", "pages": [ - "guides/help", + "help", "guides/common-questions", "guides/troubleshooting", "guides/feedback" @@ -421,6 +415,14 @@ "packages/lint" ] }, + { + "group": "Agent setup", + "pages": [ + "guides/skills", + "guides/antigravity", + "guides/copilot-cli" + ] + }, { "group": "SDK", "pages": [ @@ -530,6 +532,18 @@ "source": "/guides/common-mistakes", "destination": "/guides/troubleshooting" }, + { + "source": "/guides/create-with-agent", + "destination": "/workflows" + }, + { + "source": "/guides/choose-your-path", + "destination": "/workflows" + }, + { + "source": "/guides/help", + "destination": "/help" + }, { "source": "/contributing/studio-manual-dom-editing", "destination": "/studio/canvas" diff --git a/docs/guides/captions-and-recuts.mdx b/docs/guides/captions-and-recuts.mdx index b5009649c1..606f72b8b3 100644 --- a/docs/guides/captions-and-recuts.mdx +++ b/docs/guides/captions-and-recuts.mdx @@ -31,6 +31,17 @@ and a side panel for the two statistics mentioned in the transcript. The recut workflow uses the transcript to place designed information around the existing clip. +## Approve the treatment + +Confirm: + +- whether the footage and audio must remain untouched; +- the aspect ratio and safe space around the speaker; +- caption density, line length, and emphasis style; +- names, titles, terms, and numbers that need manual verification; +- which moments deserve overlays; +- whether the result must work without sound. + ## Review - Correct names and wording before styling. @@ -40,3 +51,22 @@ The recut workflow uses the transcript to place designed information around the - Watch once with sound and once muted. Use [Captions in Studio](/studio/captions) for text, timing, and style changes. + +## Common problems + +| Problem | Better direction | +| --- | --- | +| Every spoken word is emphasized | Reserve emphasis for the few words that change meaning. | +| Overlays cover the speaker or source footage | Establish safe regions before styling. | +| A pull quote repeats the caption underneath | Use overlays to add structure or context. | +| Captions are correct but too fast to read | Reduce words per line and adjust holds. | +| The request actually needs speech editing | Use the custom video workflow and say the footage may change. | + + + + Correct words, timing, and visual treatment. + + + Return to the source-and-outcome chooser. + + diff --git a/docs/guides/choose-your-path.mdx b/docs/guides/choose-your-path.mdx deleted file mode 100644 index 0e33c32ae9..0000000000 --- a/docs/guides/choose-your-path.mdx +++ /dev/null @@ -1,39 +0,0 @@ ---- -title: "Choose your path" -description: "Decide whether to begin with an agent, Studio, the Catalog, or developer tools." ---- - -There is no single required way to use HyperFrames. Start from what you already have and what you are trying to accomplish. - -| You have | Start here | Why | -| --- | --- | --- | -| You want to explore without local setup | [Browser Playground](https://www.hyperframes.dev/) | Open and remix public HyperFrames work in the browser. | -| You want to create inside a supported AI chat | [HyperFrames MCP](/guides/mcp) | Use a hosted connector and cloud rendering without the local CLI. | -| An idea, URL, script, PR, song, or video file | [Create with an agent](/guides/create-with-agent) | The agent can choose the right workflow and build the first version. | -| A HyperFrames project you want to review or edit | [Studio](/studio) | Studio is the visual workspace for timing, design, animation, and export. | -| A specific effect or scene you want to reuse | [Catalog](/catalog) | Browse ready-made blocks and components instead of rebuilding them. | -| An application or automation you want to integrate | [Developers](/developers) | Use the CLI, SDK, player, packages, schemas, and deployment tools. | - -## Agent or Studio? - -Most projects use both. - -Use the **agent** when the change needs planning, new scenes, new media, source-code work, or coordination across the project. - -Use **Studio** when you can point at what you want to change: move an element, edit text, trim timing, adjust a keyframe, change a style, or export a version. - - - A useful rule: if you can fix it by selecting something visible, try Studio. If you need to explain a broader outcome, ask the agent. - - -## Catalog or custom work? - -Use the Catalog when a reusable visual already matches the job: a lower third, transition, chart, caption style, social card, or code animation. - -Ask the agent for custom work when the visual needs to carry your particular story, product interface, brand system, or data. - -## Human guide or developer reference? - -The **Guides** and **Studio** sections explain what to do and what you should see. - -The **Developers** section explains commands, APIs, packages, schemas, deployment, and implementation details. You should not need it for normal review and editing. diff --git a/docs/guides/common-questions.mdx b/docs/guides/common-questions.mdx index 69da4bea25..3bd987e8b5 100644 --- a/docs/guides/common-questions.mdx +++ b/docs/guides/common-questions.mdx @@ -7,13 +7,13 @@ description: "Short answers to the questions people most often ask when they beg No. Most people can describe the result they want, let an agent build it, and use Studio to review and adjust the result. -You may still see project files and terminal commands because those are how the agent and HyperFrames work underneath. Start with [Create with an agent](/guides/create-with-agent). +You may still see project files and terminal commands because those are how the agent and HyperFrames work underneath. Start with [Make your first video](/quickstart). ## What can I make? HyperFrames can create product videos, explainers, motion graphics, captioned or recut footage, music-led videos, code-change videos, and interactive slideshows. -Use [Choose your path](/guides/choose-your-path) to find the shortest workflow for your input. +Use [Choose a creation workflow](/workflows) to find the shortest path for your input. ## How do I open Studio? diff --git a/docs/guides/create-with-agent.mdx b/docs/guides/create-with-agent.mdx deleted file mode 100644 index b0fc2e1a33..0000000000 --- a/docs/guides/create-with-agent.mdx +++ /dev/null @@ -1,105 +0,0 @@ ---- -title: "Create with an agent" -sidebarTitle: "Overview" -description: "Give an AI agent the right input and let HyperFrames choose the matching creation workflow." ---- - -You do not need to memorize the HyperFrames workflows. Start with `/hyperframes`, describe the result, and let the router choose. - -## Install once - -```bash -npx hyperframes skills update -``` - -Then begin your request with `/hyperframes`. - -## Choose by what you have - -| Starting material | Ask for | HyperFrames workflow | -| --- | --- | --- | -| A product URL, website, app, or launch brief | A promo, launch video, site tour, or product showcase | Product launch video | -| Notes, an article, or a topic without a product site | A visual explainer with invented visuals | Faceless explainer | -| A GitHub pull request | A change summary, feature reveal, or fix explanation | PR to video | -| Talking-head footage that only needs subtitles | Captions without changing the footage | Embedded captions | -| Talking-head, interview, or podcast footage | Designed titles, quotes, lower thirds, and information overlays | Talking-head recut | -| A short motion-first idea | A title, statistic, chart, logo sting, or overlay | Motion graphics | -| A music track | A beat-synced lyric video, slideshow, or promo | Music to video | -| A presentation | An interactive deck with reveals, notes, and navigation | Slideshow | -| An existing Remotion composition | A source migration to HyperFrames HTML | Remotion to HyperFrames | -| Anything else | A custom video or composition | General video | - -## Write a useful request - -The agent needs direction, not a technical implementation. - -```text -/hyperframes Create a 45-second product video for https://example.com. -The audience is small design teams. Focus on how quickly they can go -from an idea to a shared result. Use the real product interface, keep -the pacing confident rather than frantic, and end with “Try it together.” -``` - -Good information to include: - -- **Goal:** what should the viewer understand, feel, or do? -- **Audience:** who is watching? -- **Source:** URL, file, text, PR, or music. -- **Format:** landscape, vertical, square, or presentation. -- **Length:** only when it matters. -- **Tone:** a few useful words, preferably with a reference. -- **Must-haves:** exact claims, visuals, words, or constraints. - -Avoid filling the request with animation instructions unless a particular motion is essential. Let the first creative direction solve the communication problem. - -## Review the brief before the build - -For a fresh project, the agent confirms the direction before building. Check the message, audience, format, pacing, and required content. - -This is the cheapest moment to correct a misunderstanding. - -## Give feedback on the visible result - -Useful feedback names the moment, the problem, and the desired effect: - -```text -At the opening, I cannot tell what the product is until too late. -Show the interface by three seconds, but keep the first headline. -``` - -Less useful feedback describes a mood without locating the problem: - -```text -Make it pop more. -``` - -You can combine both: - -```text -The proof section feels flat. Keep the copy, but make the three numbers -arrive one at a time and hold long enough to read. -``` - -## Use Studio during the review - -Open [Studio](/studio) to inspect the storyboard, play the project, select elements, adjust timing, edit animation, and export versions. - -Ask the agent for changes that affect several scenes or require new assets. Make direct adjustments in Studio when the target is visible and specific. - -## Install options for advanced users - - - Open the interactive picker: - - ```bash - npx skills add heygen-com/hyperframes --full-depth - ``` - - Install the full set only when you explicitly want every workflow available up front: - - ```bash - npx skills add heygen-com/hyperframes --all --full-depth - ``` - - Agent and non-interactive environments should normally use `npx hyperframes skills update`. - diff --git a/docs/guides/faceless-explainer.mdx b/docs/guides/faceless-explainer.mdx index 0b64fd47b7..aee54815ec 100644 --- a/docs/guides/faceless-explainer.mdx +++ b/docs/guides/faceless-explainer.mdx @@ -7,6 +7,8 @@ Use a faceless explainer when the source is an idea or piece of text—not a pro The agent invents the visual language from typography, diagrams, abstract graphics, data visualization, icons, and generated media. +Use a [product and website video](/guides/product-launch-video) when the real product interface should provide the visual proof. Use captions or a recut when existing footage must remain underneath. + ## Start with the point ```text @@ -25,6 +27,17 @@ Include: - whether narration is wanted; - claims or examples that must remain exact. +## Approve the explanation before the visuals + +Confirm: + +- the question the opening creates; +- what the audience already knows; +- the minimum sequence needed to explain the idea; +- which facts or examples require verification; +- the visual language and narration choice; +- the one conclusion the viewer should remember. + ## Review the explanation Check the storyboard before judging visual polish: @@ -36,3 +49,22 @@ Check the storyboard before judging visual polish: 5. Can the audience repeat the conclusion afterward? Use the [Storyboard](/studio/storyboard) for the reasoning and [Studio](/studio) for timing, type, diagrams, and animation. + +## Common problems + +| Problem | Better direction | +| --- | --- | +| The visuals decorate but do not explain | Ask what each visual makes easier to understand. | +| Too many abstract claims arrive at once | Use one concrete example before the general rule. | +| The pace is fast because the script is crowded | Remove ideas rather than shortening every hold. | +| A generated statistic sounds authoritative | Verify the source or remove the claim. | +| Every scene uses a different visual metaphor | Choose a small, consistent visual system. | + + + + Refine the storyboard, typography, diagrams, timing, and animation. + + + Return to the source-and-outcome chooser. + + diff --git a/docs/guides/general-video.mdx b/docs/guides/general-video.mdx index a6a61e3e59..77206c331f 100644 --- a/docs/guides/general-video.mdx +++ b/docs/guides/general-video.mdx @@ -24,6 +24,18 @@ Use this route when: - the structure is deliberately unusual; - you want to co-direct the work rather than hand over one narrow task. +## Approve the production shape + +Because this route is flexible, agree on more before the build: + +- the final deliverable and audience; +- source material and usage constraints; +- story structure and approximate length; +- whether existing footage may be edited; +- narration, music, and sound direction; +- review checkpoints; +- aspect ratios and required versions. + ## Keep the review loop clear 1. Agree on the brief. @@ -33,3 +45,22 @@ Use this route when: 5. Validate and export. Studio and the agent are complementary. Make direct visible changes in [Studio](/studio); use the agent for changes that cross scenes, files, media, or the overall story. + +## Common problems + +| Problem | Better direction | +| --- | --- | +| “Custom” becomes permission to skip the brief | Agree on the outcome and checkpoints before exploring. | +| Story and visual feedback are mixed together | Fix message and structure before polishing motion. | +| Every source file is included | Keep only material that serves the final narrative. | +| Multiple aspect ratios are treated as simple crops | Plan layout changes for each required format. | +| The scope keeps expanding | Name a reviewable first version and defer optional ideas. | + + + + Inspect the whole result, make direct edits, and export versions. + + + Return to the chooser when a narrower creation path would work better. + + diff --git a/docs/guides/help.mdx b/docs/guides/help.mdx deleted file mode 100644 index cdfb22d298..0000000000 --- a/docs/guides/help.mdx +++ /dev/null @@ -1,34 +0,0 @@ ---- -title: "Get help" -sidebarTitle: "Overview" -description: "Find the problem, collect useful evidence, and get a HyperFrames project moving again." ---- - -Start with what you can observe. Copy the exact error, note when it happens, and say whether the problem appears in Studio preview, during validation, or only in the final render. - - - - Work through project, preview, media, animation, and rendering failures. - - - Solve selection, timeline, preview, editing, and export problems. - - - Report a bug or explain a product problem with enough context to act on it. - - - Search known issues or open a new report. - - - -## What to include when asking for help - -- What you were trying to do. -- The command or visible action you took. -- The exact error or unexpected result. -- Whether it happens every time. -- Your operating system and HyperFrames version. -- A screenshot or short recording when the problem is visual. -- A small reproducible project when the source can be shared. - -Do not paste secrets, access tokens, private media, or credentials into a public issue. diff --git a/docs/guides/index.mdx b/docs/guides/index.mdx index 1108b2c11a..d4e11a8a7c 100644 --- a/docs/guides/index.mdx +++ b/docs/guides/index.mdx @@ -1,28 +1,39 @@ --- -title: "Guides" +title: "What do you need to do?" sidebarTitle: "Overview" -description: "Practical help for creating, reviewing, exporting, and sharing work made with HyperFrames." +description: "Choose the shortest HyperFrames documentation path for what you need right now." --- -Use these guides when you want to finish a task. You can begin with an idea, a website, existing footage, a pull request, a music track, or a project an agent already created. +You do not need to read these docs from beginning to end. Start from your current situation. - - Understand the product and make your first video. + + Understand the product, see a finished result, and choose a relevant next step. - - Choose a workflow, write a useful request, and improve the result. + + Go from source material to a reviewable project in Studio and export it. - - Understand compositions, timing, variables, animation, and reliable rendering. + + Choose the right path for a product, idea, recording, pull request, motion graphic, song, or presentation. - - Use images, footage, audio, captions, backgrounds, and color. + + Review the storyboard, make direct edits, adjust timing and animation, or export a version. - - Choose the right format, resolution, and delivery method. + + Start with the visible symptom and return to the task you were trying to finish. - - Solve common problems and send useful feedback. + + Choose the CLI, SDK, Player, package, schema, or deployment surface you actually need. + +## Useful places after the first task + +- [Examples](/examples) — watch finished work, inspect production projects, or start from a template. +- [Catalog](/catalog) — find reusable scenes, captions, transitions, overlays, and effects. +- [Learn](/concepts) — understand compositions, timing, variables, adapters, and deterministic rendering. +- [What's new](/product-updates) — follow product changes without reading the technical release archive. + + + If a teammate asks “What is HyperFrames?”, send [What is HyperFrames?](/introduction), not this directory page. + diff --git a/docs/guides/motion-graphics.mdx b/docs/guides/motion-graphics.mdx index 19b74fa941..90ae9ea164 100644 --- a/docs/guides/motion-graphics.mdx +++ b/docs/guides/motion-graphics.mdx @@ -27,4 +27,34 @@ Include the exact words or data, intended background, dimensions, duration, and If the piece needs several scenes, narration, or a longer story, use the General Video workflow instead. +## Approve the motion idea + +Confirm: + +- the one message or number; +- the exact duration and dimensions; +- where the graphic will be used; +- the background or transparency requirement; +- the entrance, main action, and clean exit; +- whether the first or final frame must hold. + Review the first and final frames carefully. An overlay must enter and leave cleanly when placed over another edit. + +## Common problems + +| Problem | Better direction | +| --- | --- | +| Too many ideas compete in six seconds | Keep one message and one motion idea. | +| Text is readable only while paused | Hold the resolved state longer. | +| A transparent overlay leaves visible debris | Review the first and final frames over real footage. | +| Motion is energetic but communicates nothing | Tie the movement to the meaning of the word, number, or chart. | +| The result needs narration and several scenes | Move to the custom video workflow. | + + + + Browse titles, charts, lower thirds, overlays, transitions, and effects. + + + Return to the source-and-outcome chooser. + + diff --git a/docs/guides/music-to-video.mdx b/docs/guides/music-to-video.mdx index bfccd01a37..3c6f80da13 100644 --- a/docs/guides/music-to-video.mdx +++ b/docs/guides/music-to-video.mdx @@ -24,6 +24,17 @@ Tell the agent: - where the energy should change; - whether the video must loop. +## Approve the musical structure + +Confirm: + +- the exact section of the track; +- the important beats, drops, phrases, or energy changes; +- which media and lyrics are approved; +- the visual arc from opening to ending; +- whether the edit should loop; +- how long text must remain readable even when the rhythm is fast. + ## Review the rhythm Not every beat needs a cut. Use stronger changes for important musical moments and leave enough visual continuity to understand the material. @@ -37,3 +48,22 @@ Check: - the ending or loop point. Beat markers in the [Studio timeline](/studio/timeline) help refine the cut. + +## Common problems + +| Problem | Better direction | +| --- | --- | +| Every beat causes a cut | Reserve larger changes for stronger musical moments. | +| The edit is rhythmic but hard to understand | Hold important images and text across several beats. | +| Lyrics drift from the vocal | Correct transcription and timing before visual polish. | +| The ending feels cut off | Choose a musical landing or design a deliberate loop. | +| Supplied media has no visual progression | Assign different material to the intro, build, peak, and ending. | + + + + Use beat markers to adjust cuts, holds, and the ending. + + + Return to the source-and-outcome chooser. + + diff --git a/docs/guides/pr-to-video.mdx b/docs/guides/pr-to-video.mdx index 02ee87b0c6..d90549ed1a 100644 --- a/docs/guides/pr-to-video.mdx +++ b/docs/guides/pr-to-video.mdx @@ -22,6 +22,17 @@ Say who the video is for: - contributors may need architecture and tradeoffs; - a social audience needs one clear change and visible proof. +## Approve the angle + +Confirm: + +- the intended PR and target branch; +- whether the audience cares about user impact, architecture, or both; +- the release state: proposed, merged, released, or planned; +- the before-and-after behavior; +- breaking changes or migration work; +- the maximum level of code detail. + ## Check the facts Before export: @@ -33,3 +44,22 @@ Before export: - confirm issue, version, and product names. Use [Studio Storyboard](/studio/storyboard) to review the explanation and [Source](/studio/source) when a code excerpt needs adjustment. + +## Common problems + +| Problem | Better direction | +| --- | --- | +| The video reads the PR description aloud | Build a story around the user or system change. | +| Refactoring becomes a product claim | Separate internal work from visible behavior. | +| Code appears too briefly to read | Show only the relevant lines and hold them longer. | +| The PR is not released yet | Say that clearly instead of presenting it as shipped. | +| The audience is mixed | Make separate user-facing and contributor-facing versions. | + + + + Check the facts, sequence, code excerpts, timing, and final release language. + + + Return to the source-and-outcome chooser. + + diff --git a/docs/guides/product-launch-video.mdx b/docs/guides/product-launch-video.mdx index b4c6d9c449..dc39a92b0b 100644 --- a/docs/guides/product-launch-video.mdx +++ b/docs/guides/product-launch-video.mdx @@ -7,6 +7,8 @@ Use this workflow when the video should market or explain a product, company, ap Give the agent the real URL when the site’s interface, language, or visual identity should appear in the result. You can also begin from a written brief or script when no site capture is needed. +Use a [faceless explainer](/guides/faceless-explainer) instead when there is no product to show and the visuals should be invented from an idea or text. + ## Start the request ```text @@ -17,6 +19,17 @@ how quickly they can share a first result, and end with “Try it free.” The `/hyperframes` router selects the Product Launch Video workflow. +## Approve the direction + +Before the build, confirm: + +- the audience and single main promise; +- whether the real site should be captured; +- the most important product state or task to show; +- the intended format and length; +- claims, screens, and words that must be exact; +- the final action for the viewer. + ## Decide what kind of product video you need | Goal | Useful direction | @@ -60,3 +73,22 @@ Use the [Storyboard](/studio/storyboard) to check the message and scene sequence Use the [canvas](/studio/canvas) and [timeline](/studio/timeline) to refine the product screens, text, pacing, and transitions. Before export, confirm that claims shown in the video are current and supported by the product. + +## Common problems + +| Problem | Better direction | +| --- | --- | +| The video lists every feature | Choose one audience, one promise, and two or three pieces of proof. | +| It looks like a scrolling screen recording | Reconstruct the useful interaction and use captures as evidence. | +| The opening is generic | Show the product or its result earlier. | +| The UI is too small to understand | Focus each scene on one product area and crop deliberately. | +| The brand feels copied incorrectly | Supply the correct fonts, colors, logo, and approved product states. | + + + + Check the complete story, refine visible details, and export versions. + + + Return to the source-and-outcome chooser. + + diff --git a/docs/guides/slideshow.mdx b/docs/guides/slideshow.mdx new file mode 100644 index 0000000000..606c3f7cbd --- /dev/null +++ b/docs/guides/slideshow.mdx @@ -0,0 +1,96 @@ +--- +title: "Create an interactive presentation" +sidebarTitle: "Create an interactive presentation" +description: "Ask an agent to build a navigable HyperFrames deck with reveals, notes, branches, hotspots, and presenter mode." +--- + +A HyperFrames slideshow is a running presentation, not a video pretending to be a deck. + +It can contain discrete slides, progressive reveals, speaker notes, optional branches, clickable hotspots, presenter controls, and an audience view. + + + Choose this workflow only when the final result should remain interactive. A HyperFrames slideshow is presented with `hyperframes present`; rendering it as one linear MP4 is not currently a supported slideshow output. + + +## Use it when + +- a presenter needs to control the pace; +- points should reveal one at a time; +- the audience may choose a branch or detail path; +- speaker notes and a separate audience view matter; +- an existing interactive page should become a navigable deck. + +Use a normal video workflow when the result should play from beginning to end without a presenter. + +## Give the agent + +- the source notes, document, page, or existing deck; +- the audience and purpose; +- the rough number of slides; +- the main narrative; +- required brand or visual references; +- whether you need fragments, branches, hotspots, media, or speaker notes; +- the environment where it will be presented. + +```text +/hyperframes Build a ten-slide interactive product briefing from these +notes. It is for a sales team introducing the product to design leaders. +Use progressive reveals, include speaker notes, and add a final branch +where the presenter can open either the roadmap or pricing detail. +``` + +## What the agent should confirm + +Before building, agree on: + +1. **Deliverable:** an interactive slideshow rather than a rendered video. +2. **Audience and decision:** what should change after the presentation? +3. **Main line:** the sequence every audience sees. +4. **Branches:** optional detail that should not interrupt the main story. +5. **Interaction:** reveals, hotspots, media, and presenter control. +6. **Handoff:** how and where the deck will be presented. + +## Review the first version + +Check the deck as a presenter, not as a passive video: + +- Does each slide make one clear point? +- Do reveals help the explanation, or merely delay content? +- Can the main line stand without opening a branch? +- Are hotspots obvious enough to use but quiet enough not to distract? +- Do speaker notes help the presenter rather than repeat the slide? +- Does embedded media stop when you leave its slide? +- Can the audience view be shared without exposing presenter notes? + +Use [Studio's Slideshow panel](/studio/slideshows) to review and adjust slide metadata. + +## Present the deck + +Run: + +```bash +npx hyperframes present +``` + +Open the local URL, then click **Present** or press **P**. HyperFrames opens a separate audience view while the original tab becomes the presenter view with the current slide, next-slide preview, notes, and timer. + +For a call: + +- In Google Meet, share the audience **tab**. +- In Zoom, move the audience tab into its own window and share that window. +- Keep presenter notes on your own screen. + +## Supported output + +The primary output is the live, navigable deck. You can also create per-slide snapshots. + +If the final deliverable must be a linear MP4 today, ask the agent to make a normal HyperFrames video from the same source rather than sending the slideshow to the video renderer. + +## If something goes wrong + +- If navigation does nothing, confirm the slideshow project is being served with `hyperframes present`. +- If a branch cannot be opened, ask the agent to check the hotspot target and slide sequence. +- If a reveal lands at the wrong moment, identify the slide and reveal number. +- If the audience view does not play media, interact with the audience tab once so the browser can allow playback. + +[Start from a visible symptom →](/help) diff --git a/docs/help.mdx b/docs/help.mdx new file mode 100644 index 0000000000..27df0f20e1 --- /dev/null +++ b/docs/help.mdx @@ -0,0 +1,150 @@ +--- +title: "Get unstuck" +sidebarTitle: "Get unstuck" +description: "Start with what you can see, try the smallest useful fix, and return to your HyperFrames task." +--- + +Choose the symptom that looks most like yours. You should not need to read the entire documentation site or understand the rendering architecture to solve a normal problem. + + + + The browser never opens, the page is unreachable, or the project does not load. + + + A saved change is missing, playback looks old, or the preview is blank. + + + Selection, canvas controls, timing, or an Inspector field is unavailable. + + + An image, video, font, or audio file is absent or does not render correctly. + + + Motion jumps, drifts, starts at the wrong time, or differs after seeking. + + + Export stops, produces the wrong result, or disagrees with Studio. + + + Preserve the exact message and collect enough context for an agent or issue. + + + Search known issues or report a reproducible problem. + + + +## Studio will not open + +1. Open a terminal in the HyperFrames project folder. +2. Run `npx hyperframes preview`. +3. Keep that process running while Studio is open. +4. Use the local URL printed in the terminal. + +If the command says it cannot find a project, confirm that the folder contains the HyperFrames project rather than its parent folder. + +## Preview is wrong or stale + +Try these in order: + +1. Save the changed file. +2. Reload Studio once. +3. Check the terminal for a build or runtime error. +4. Run the project checks below. + +```bash +npx hyperframes lint +npx hyperframes check +``` + +`lint` checks the composition structure. `check` opens the project in a browser gate and catches runtime, layout, motion, and contrast problems. + +## I cannot select or edit something + +- Open **Layers** and select the element there when clicking the canvas is difficult. +- Confirm that you are in **Preview**, not Storyboard. +- Scrub to a time where the element is visible. +- Check whether the visual lives inside a nested composition. +- Ask the agent when the change affects source structure rather than one visible element. + +[Open Studio troubleshooting →](/studio/troubleshooting) + +## Media is missing or black + +Check: + +- the file still exists inside the project; +- the path and filename capitalization match; +- the source is local and available during rendering; +- the browser can decode the media format; +- the media is visible at the current time; +- the terminal does not report a download, decode, or CORS error. + +Do not rely on a temporary signed URL or a render-time network request. Ask the agent to copy required media into the project. + +## Animation is wrong + +First decide whether the problem happens: + +- during normal playback; +- only after scrubbing; +- only in the final render. + +That distinction helps separate a timeline mistake from non-deterministic animation. HyperFrames animation must be seekable: the same frame should look the same every time it is requested. + +Run `npx hyperframes check`, then share the smallest affected scene and the exact timestamp with your agent. + +## Render failed or differs from preview + +1. Preserve the complete render error. +2. Run `npx hyperframes check`. +3. Confirm that fonts and media are local and load before capture. +4. Check the affected timestamp in Studio. +5. Try the normal MP4 preset before changing codecs or advanced flags. + +Use the [complete troubleshooting guide](/guides/troubleshooting) for codec, browser, FFmpeg, GPU, HDR, and deployment-specific failures. + +## Copy a useful diagnostic + +Send this block to your agent and fill in the visible facts: + +```text +What I was trying to do: + +What I clicked or ran: + +What I expected: + +What happened instead: + +Exact error: + +Where it happens: Studio / lint / check / render + +Does it happen every time? + +HyperFrames version: + +Operating system: + +Affected file or timestamp: +``` + +Add a screenshot or short recording when the failure is visual. Do not paste access tokens, credentials, private media, or other secrets into a public issue. + +## Ask for help + + + + Read short answers to the questions most likely to come up during first use. + + + Diagnose less common project, media, animation, rendering, and environment failures. + + + Explain a confusing or broken experience with useful context. + + + Find known problems or open a reproducible issue. + + + diff --git a/docs/introduction.mdx b/docs/introduction.mdx index d49e7e2c12..ce98248551 100644 --- a/docs/introduction.mdx +++ b/docs/introduction.mdx @@ -1,84 +1,113 @@ --- -title: "Welcome to HyperFrames" -description: "Make videos with an AI agent, refine them in Studio, and export the finished result." +title: "What is HyperFrames?" +sidebarTitle: "What HyperFrames is" +description: "See how an AI agent, a real project, and HyperFrames Studio work together to create a finished video." --- -HyperFrames is a way to create videos with an AI agent and still keep full control over the result. +HyperFrames lets an AI agent create a real video project, then gives you a visual Studio to review, edit, and export it. -Tell your agent what you want to make. It can plan the story, gather media, build the scenes, add motion, and open the project in **HyperFrames Studio**. In Studio, you can watch the video, rearrange timing, edit text and design, adjust animation, and export the finished file. +You can begin with an idea, website, script, pull request, recording, or music track. The agent handles the first build. You stay in control of the direction and the visible result. -You do not need to understand the rendering engine or write HTML to get started. + +