--- title: Use HyperFrames with invideo description: Bring a HyperFrames composition into invideo as an MP4, or have your agent rebuild it as an editable timeline, then add voice, music and captions. --- It depends on what you are making. HyperFrames is strong at motion graphics written as HTML, rendered by your coding agent; invideo is where that motion meets real footage, voice, music and captions on a timeline a person can review and change. Your agent brings the composition in as a rendered MP4, or rebuilds its elements on the timeline from the HTML. ## When to use both Use both when the motion piece is one part of a longer video. HyperFrames makes the animated parts. invideo cuts them together with everything else. - **Animated titles inside a real edit.** A title card, a chart or a product callout from HyperFrames sits between interview clips or b-roll. - **The voice and music come later.** You record or generate the voice after the motion is done, and mix it with music on the timeline. - **A person reviews the cut.** Someone without a code editor watches the timeline in the browser and leaves changes. - **Variants.** Several hooks or end cards, each on its own branch, around the same render. ## Hand-off: from HyperFrames into invideo There are two paths in. The render comes in as footage, or your agent rebuilds the composition as clips, text and keyframes. ### Bring the render in as footage HyperFrames renders a composition with its CLI: ```bash npx hyperframes lint npx hyperframes render --output intro.mp4 ``` The HyperFrames docs list `mp4`, `webm`, `mov`, `gif`, `png-sequence` and `hls` as render formats. Use MP4 for the hand-off. Your agent knows these commands from the HyperFrames skills, installed with `npx skills add heygen-com/hyperframes`. They include `/hyperframes` for making and rendering, `/hyperframes-cli` for commands, and `/media-use` for music, voiceover and images. Then your agent brings the MP4 into invideo: - **A public link.** `add_media` with `media_url`. - **A file on your computer.** `start_upload` with the `file_name`, a PUT of the bytes to the `upload_url`, then `add_media` with the `upload_id`. In a terminal, `invideo asset upload `. - **A file in a chat app.** You drag the file into the chat. It arrives through `file` on `add_media`. Each file becomes a sequence in the project, with its own sequence URL. On a timeline's URL, `add_media` also puts it in that timeline's media bin. The MP4 becomes a clip like any other. It is footage, so the text and shapes inside it are pixels, not editable layers. To keep them editable, take the second path. ### Rebuild the composition on a timeline The second path keeps each element editable. Your agent reads the HTML, CSS and JavaScript: the root's `data-width` and `data-height`, each element's `data-start` and `data-duration`, and the GSAP tweens and rebuilds each element with edit operations, on a branch. [Rebuild a Remotion, HyperFrames or Tesseract composition as an editable timeline](/how-to/developers/composition-to-timeline) gives the steps. The mapping in short: - **Size and timing.** `set_timeline_settings` with the composition's size and `fps`. HyperFrames times are in seconds, so the agent multiplies them by the frame rate. CSS `z-index` sets the layer order. - **Text.** `add_text`, `set_text_style` and `style_text_range`, with fonts uploaded through `add_media`. - **Images and video.** `add_media`, then `insert_media` or `place_media`, with `set_position` and `set_zoom`. - **Motion.** `add_keyframe_lane` and `add_keyframes` for position and zoom, `set_keyframes` for opacity and rotation. - **Layers with no op.** Canvas, WebGL or a third-party component: render that layer alone in HyperFrames and place it as a clip. ### The finish On either path, the agent finishes the video: - **Footage and b-roll** placed around the render with `place_media`, from your files or `search_library`. - **Voice** from `elevenlabs_text_to_speech.elevenlabs_tts_v4` with `generate`, or your own recording. - **Music** from `search_library` in `stock_music`, mixed with `set_audio_gain` and `set_audio_fades`. - **Captions** with `media` `audio.transcript` on the voice, then `add_captions`. ## Hand-off: from invideo to HyperFrames The way back is an MP4. `export` with `format` `video` renders the timeline, and a HyperFrames composition takes it as a video clip, as the HyperFrames guide "Add images and video clips" describes. For an editor, `export` with `format` `premiere`, `davinci` or `final_cut` makes a project file for Premiere Pro, DaVinci Resolve or Final Cut Pro. ## Steps Your agent sets up with [invideo for AI agents](/agents) first. These steps follow the render path. For the rebuild, your agent follows the steps on the rebuild page. Edits and exports are free. Generation and transcripts cost credits. Paid stock costs a small credit charge, or one of your workspace's iStock licenses. Your agent runs a dry run first and tells you the price before it spends anything. Your agent runs a dry run first. For any call that costs 1 credit or more, it tells you the price and waits for your yes. A call under 1 credit runs without asking, and your agent tells you what it cost. The agent runs `npx hyperframes lint`, fixes the errors, then renders to MP4. Expected result: an MP4 on disk. The agent calls `start_upload`, puts the bytes, then `add_media` on the timeline URL. Expected result: a sequence URL and a media bin id. The agent creates a branch with `timeline_history` and places the render, footage and music with `edit_timeline`. Expected result: a new `state_token`. If you have no recording, the agent runs `find_models` with the voice-over in words, picks one, and reads its inputs with `get_model`. A good pick is `elevenlabs_text_to_speech.elevenlabs_tts_v4`. The agent can search for others with `find_models`. It picks a `voice_id` with `search_library`, calls `generate` with `dry_run: true` and the real inputs, and tells you the price. Expected result: a price and no charge. The agent calls `generate` with `max_credits` set to that price and an `idempotency_key`. Expected result: a thread URL, then a sequence URL when the voice lands. The agent reads that URL with `read`, and never calls `generate` again to check. The agent prices `audio.transcript` with `dry_run`, starts it, and calls again after `retry_after_s` for the words. Then it sends `add_captions`. Expected result: a caption clip. The agent calls `capture` at the joins between the render and the footage, and `check_timeline`. Then it calls `export`. Expected result: an export card with status `completed`. The voice from a terminal: ```bash invideo agent register --name export INVIDEO_AS= invideo gen models --query "voice-over from a script" invideo gen model \ --model elevenlabs_text_to_speech.elevenlabs_tts_v4 invideo library search \ --library elevenlabs_text_to_speech_voices --query "calm" invideo gen run \ --model elevenlabs_text_to_speech.elevenlabs_tts_v4 --dry-run \ -i prompt=@script.txt -i voice_id= invideo gen run \ --model elevenlabs_text_to_speech.elevenlabs_tts_v4 \ -i prompt=@script.txt -i voice_id= \ --max-credits --idempotency-key voice-1 ``` `` comes from `invideo project new` or `list_projects`. `` is the name you choose in `invideo agent register`. `` is a page that `invideo notebook show ` lists. `` is the price the dry run returns. `` is an `id` that `invideo library search` returns. ## When to stay in HyperFrames Stay in HyperFrames when the whole video is motion graphics from code and nobody else edits it. Stay there too when you need what invideo's `export` does not make: a transparent render (HyperFrames keeps transparency in WebM and MOV), a GIF, or an HLS stream. For changes to a rendered animation, change the HTML and render again, then swap the clip in invideo with `place_media` mode `replace`. After a rebuild, change the element on the timeline instead. ## If something goes wrong | Symptom | Fix | | --- | --- | | `add_media` with `media_url` is refused | The link must be public. Download the file, then upload it with `start_upload` and `add_media` with the `upload_id`. | | Text in the render cannot be changed in invideo | It is part of the picture. Rebuild that text with `add_text`, or change the HTML, render again, and replace the clip with `place_media` mode `replace`. | | `get_model` or `generate` refuses the model as not found | Models retire. Run `find_models` with the job in words, use the best match, and tell the person which model you used. | | Avoid: call `generate` again to check on a run | Instead: read the thread or sequence URL with `read`. A second `generate` starts a second paid run. | ## Related - [When to use HyperFrames vs invideo](/compare/hyperframes) - [Use Remotion with invideo](/integrations/remotion) - [Intro, outro and logo animation](/how-to/creators/intro-outro-logo-animation) - [Launch video](/how-to/marketing/launch-video) - [Rebuild a composition as an editable timeline](/how-to/developers/composition-to-timeline) - [Check your video before you say it is done](/how-to/check-your-video) Not as a file. Your agent reads the HTML, CSS and JavaScript and rebuilds the elements as clips, text and keyframes you can edit. A rendered MP4 stays one clip: its text, shapes and timing are part of the picture, so a change to it means a new render in HyperFrames. Yes. When the render has sound, your agent places it with `place_media` and `linked_audio` set to true. The sound then moves with the picture on the timeline.