К основному содержанию
скилл CX Codex

remotion-assemble — скилл для Claude Code: что делает и как установить

Скилл remotion-assemble для Claude Code настраивает сборку видео из сцен HyperFrames, футажей, голоса и звуков по файлу meta.json. Инструкции включаются при редактировании кода в каталоге engines/remotion.

MIT ★ 147 обновлён 2026-11-13

Установить в Claude Code · Через Skills CLI (Vercel) Все способы и платформы ↓
npx skills add notivn/AIEVv2 --skill remotion-assemble -a claude-code
Открыть на GitHub

Что делает remotion-assemble

Скилл собирает готовые компоненты таймлайна из файла манифеста meta.json. Remotion здесь отвечает только за склейку MP4-сцен HyperFrames, исходных футажей, дорожек озвучки и шумов. Моушн-графика в самом Remotion не создаётся — за неё отвечает HyperFrames.

Внутри каталога engines/remotion композиция Assemble.tsx строит таймлайн, а manifest.ts валидирует параметры через Zod. Схема проверяет параметры сцен: зум, кроп, цветовые фильтры CSS, скорость от 0.25 до 4 и переходы вроде fade или slide. Любое значение вне допустимого диапазона вызывает ошибку 400 INVALID_TIMELINE на сервере и прерывает рендер.

Какие задачи решает

  • собрать финальное видео из сцен HyperFrames и озвучки
  • настроить переходы и оверлеи в файле meta.json
  • отредактировать параметры таймлайна в engines/remotion
  • синхронизировать звуковые эффекты по таймкодам кадров

Примеры запросов агенту

  • Собери таймлайн видео в engines/remotion по текущему meta.json
  • Добавь текстовый оверлей и переход fade между сценами в манифесте

Как установить remotion-assemble

1Через Skills CLI (Vercel)

npx skills add notivn/AIEVv2 --skill remotion-assemble -a claude-code

2Вручную: положить файлы

~/.claude/skills/remotion-assemble/SKILL.md

Папка скилла целиком; для одного проекта — .claude/skills/remotion-assemble/

По шагам, с командами для каждой платформы: Как установить скилл в Claude Code: пять способов

Вопросы о remotion-assemble

Как установить remotion-assemble в Claude Code?

Для установки выполните команду npx skills add notivn/AIEVv2 --skill remotion-assemble -a claude-code.

Что делает скилл remotion-assemble?

Он задаёт правила склейки готового видео в Remotion из фрагментов HyperFrames, аудиодорожек и футажей на основе meta.json.

Что произойдёт при указании недопустимых параметров в meta.json?

Серверный валидатор и схема Zod отклонят параметры с ошибкой 400 INVALID_TIMELINE, из-за чего рендер видео остановится.

Исходный текст

SKILL.md · MIT
---
name: remotion-assemble
description: How to use Remotion as the assembly layer - read the project's meta.json and stitch the rendered HyperFrames scenes + footage + voice + sound effects into the finished video. Read this when writing/editing code in engines/remotion or when assembling the timeline for a video.
---

# Remotion Assemble - building the timeline from meta.json

In this system Remotion **does exactly one thing**: assemble the pieces that already exist (scene MP4s rendered by HyperFrames, source footage, voice, sound effects) into the final video. Do not build motion graphics in Remotion - that is HyperFrames' job.

## Structure of engines/remotion

```
engines/remotion/
├── package.json          ← remotion, @remotion/cli, @remotion/renderer
├── remotion.config.ts
└── src/
    ├── Root.tsx               ← registers 3 compositions: "Assemble" + "Poster" + "Thumbnail"
    ├── Assemble.tsx           ← master composition: read manifest → build timeline
    ├── Poster.tsx             ← static poster composition (image projects)
    ├── Thumbnail.tsx          ← static video-thumbnail composition (frame card + title)
    ├── manifest.ts            ← load + validate video props (zod)
    ├── duration.ts            ← scene length incl. `speed` (shared with the web editor; server twin in timeline.ts)
    ├── color.ts               ← timeline color adjust → CSS filter (`colorFilterCss`, `ColorDefs`, preset approximations)
    ├── layerGeometry.ts       ← `layerBox()` - layer position/size/animation/keyframes (shared with the editor's drag frame)
    ├── posterManifest.ts      ← load + validate poster props (zod)
    ├── thumbnailManifest.ts   ← load + validate thumbnail props (zod)
    ├── brandFonts.ts          ← load brand fonts via staticFile (offline)
    ├── media.tsx              ← media URL resolver (staticFile by default; the dashboard preview swaps it)
    ├── index.ts               ← entry point registering Root
    └── components/
        ├── SceneClip.tsx      ← <OffthreadVideo>/<Img> for one scene/footage clip
        ├── Transition.tsx     ← scene transitions inside transitionOverlap (fade, slide, wipe, zoom, blur, none)
        ├── LayerTrack.tsx     ← overlay layers (image / video PiP / text / shape)
        ├── ColorBox.tsx       ← wraps a scene/layer with its color adjust + vignette
        ├── SfxTrack.tsx       ← places <Audio> at sfx[].atFrame
        ├── MusicTrack.tsx     ← background music: loop + fade + deterministic ducking
        ├── CaptionTrack.tsx   ← karaoke captions from word timestamps
        ├── HighlightTrack.tsx ← main/related key bands (key-layout)
        └── vietnameseFont.ts  ← @font-face Inter vietnamese subset
```

Manifest fields beyond scenes/captions/overlays (see `manifest.ts`):
- `watermark` - the Style Design corner logo, stamped by the SERVER (`jobs/assemble.ts`), never by the AI; `null` = the style has no logo.
- `audio.music` - background music `{ file, volume, duckVolume, speech: [[startSec,endSec],...] }` with deterministic ducking over speech ranges (see the `background-music` skill); `null` = no music.
- `scenes[].zoom` - camera move on footage `{ origin?, keys: [{frame, scale, ease?}] }`; `frame` counts from the START OF THE SCENE, applied to the wrapper div (never the video element).
- `audio.sfx[].mediaStart` - seconds skipped at the head of the sfx file (lead silence trim, see noti-tiktok-vn "SFX loudness and lead silence").

### Editor v2 fields (all optional - absent = the old behaviour)

Full contract: `docs/EDITOR-V2-PLAN.md` section 1. The server validator (`apps/server/src/timeline.ts`) rejects anything out of range with `400 INVALID_TIMELINE`, and the zod schema has the same ranges, so an out-of-range value written by hand **kills the render**. Stay inside these ranges.

**Scene** (`scenes[]`):

| Field | Range | Meaning |
|---|---|---|
| `fit` | `"cover"` (default) \| `"contain"` | how the source fills the frame |
| `transform` | `{ x, y: -1..1, scale: 0.1..5, rotate: -180..180, flipH, flipV }` | x/y = OFFSET as a fraction of the frame side (x = 1 moves a full width); scale multiplies the existing `zoom` |
| `crop` | `{ top, right, bottom, left }` each 0..0.45 | crops the SOURCE, then fits the rest (`object-view-box`, no black bars) |
| `color` | ColorAdjust (below) | color on the timeline - does not touch the file |
| `volume` | 0..2 (footage) | `muted: true` still wins |
| `fadeInSec` / `fadeOutSec` | 0..10 (footage) | audio fade of the clip's own sound |
| `speed` | 0.25..4 (footage) | playback rate. **Length = (round(to·fps) − round(from·fps)) / speed** when `durationInFrames` is absent - never compute it yourself with a different formula; the helper is `duration.ts` (server twin `sceneDurationFrames`). `durationInFrames` WINS over `speed`: if the scene has one, rewrite it in the same edit (and pin `to`) or the clip ends early (black tail) / gets cut |
| `transition` | `{ type }` | transition INTO THE NEXT scene, played inside this scene's `transitionOverlap`. Types: `fade` (default, the old crossfade) `slide-left` `slide-right` `slide-up` `slide-down` (push) `wipe-left` `wipe-right` `zoom-in` `zoom-out` `blur` `none`. No overlap = hard cut whatever the type |

**ColorAdjust** (scene `color` and layer `color`): `preset` = one of the 14 ids in `apps/server/src/color.ts` (approximated with CSS), `brightness` `contrast` `saturation` `temperature` `tint` -1..1 (0 = unchanged, saturation -1 = black and white, temperature + = warm), `hue` -180..180°, `vignette` 0..1, `blur` 0..20 px. This is a look on the timeline, not the ffmpeg asset grade of the `color-grading` skill - for HDR/log footage still delog the file first.

**Layers** (top-level `layers[]`) - drawn above the scenes, below highlight/captions/watermark; later entries are on top:

```jsonc
"layers": [
  { "id": "title", "kind": "text", "from": 30, "durationInFrames": 90,
    "text": "Dòng 1\nDòng 2", "width": 0.8, "transform": { "y": -0.6 },
    "style": { "fontSizePx": 84, "color": "#ffffff", "backgroundColor": "rgba(0,0,0,0.6)", "paddingPx": 24, "radiusPx": 20 },
    "animation": { "in": "pop", "out": "fade", "durationSec": 0.4 } },
  { "id": "pip", "kind": "video", "src": "assets/broll.mp4", "mediaStart": 2,
    "from": 120, "durationInFrames": 150, "width": 0.4,
    "transform": { "x": 0.5, "y": 0.55 }, "radiusPx": 24, "muted": true },
  { "id": "logo-openai", "kind": "image", "src": "assets/openai.svg", "aspect": 1, "from": 0, "durationInFrames": 60,
    "keyframes": [ { "frame": 0, "scale": 0.8, "ease": "out" }, { "frame": 20, "scale": 1 } ] }
]
```

- `kind`: `image` | `video` (both need `src`, a project-relative path like every other media path - staged by `jobs/assemble.ts`) | `text` | `shape` (a colored box: `style.backgroundColor`, `aspect` w/h default 16/9).
- `from` / `durationInFrames` are ABSOLUTE frames, like cues. `keyframes[].frame` is RELATIVE to `from`.
- Position: `transform.x/y` is the CENTRE of the box, -1..1 from the frame centre (0,0 = middle, 1 = edge) - different from a scene's `transform`. `width` is a fraction of the frame width (0.05..2, default 0.5); height follows the file's aspect (image/video), `aspect` (shape) or the text.
- Text: `style.fontFamily` is one of the SubtitleTrack ids (`vietnamese` default, `sans`, `serif`, `mono`) - Vietnamese diacritics are safe; `fontSizePx` is in composition pixels.
- `animation.in/out`: `none` `fade` `slide-up` `slide-down` `slide-left` `slide-right` `pop` `zoom`; `durationSec` default 0.4 (capped at half the layer on short layers).
- `mediaAspect` (layer) and `mediaDurationSec` (sfx) are filled by the server/preview at build time (ffprobe) - never write them into `meta.json`. ffprobe often cannot measure an SVG (depends on the ffmpeg build), so for an SVG image layer set `aspect` (w/h) yourself, otherwise the box falls back to 16/9.
- Geometry is computed by `layerBox()` in `layerGeometry.ts`; the editor's drag frame uses the same function, so never re-implement it in a component.
- Logo rule still applies: a brand logo layer must come from `assets/brand-logos/` copied into the project - and never add the Style Design corner logo as a layer (the server stamps it).

**Audio fades**: `audio.sfx[].fadeInSec/fadeOutSec` (0..10, fade-out counts back from the END of the file), `audio.music.fadeInSec/fadeOutSec` (override the 0.5 s / 1 s defaults; 0 = no fade).

## Core principles

1. **A single data-driven `Assemble` composition.** Everything comes from the project's `meta.json`, passed through `defaultProps`/`inputProps`. Adding a new video means no Remotion code changes, only a new manifest.

```bash
npx remotion render Assemble \
  --props="<abs>/video-projects/<name>/props.resolved.json" \
  --output="../../outputs/<name>-v1.mp4" \
  --concurrency 8 --gl angle
```

> ⚠️ Asset paths in the props must be `staging/...` - the backend stages assets into
> `engines/remotion/public/staging/` via hardlinks and then writes `props.resolved.json`.
> **NEVER render straight from `meta.json`** (its paths are relative to the project
> folder, and Remotion cannot resolve those through `staticFile`).
>
> `--gl angle` is MANDATORY on a machine with a GPU - without it Remotion renders with the software renderer,
> CPU at 100% and GPU at 5%. For drafts add `--crf 28 --x264-preset veryfast`. (The backend queue adds these flags automatically.)

2. **Dimensions/fps come from the manifest** - use `calculateMetadata` to set `width/height/fps/durationInFrames` dynamically from the props, never hardcode them in `Root.tsx`.

3. **Embedded video uses `<OffthreadVideo>`**, not `<Video>` - it is more stable server-side and lands on the right frame. Whatever fps a HyperFrames scene was rendered at, the manifest must declare that exact fps; an fps mismatch between scene and composition is the number one source of stuttering.

4. **Timeline = accumulating `durationInFrames`:**

```tsx
let from = 0;
scenes.map((s) => {
  const seq = (
    <Sequence key={s.id} from={from} durationInFrames={s.durationInFrames}>
      <SceneClip scene={s} />
    </Sequence>
  );
  from += s.durationInFrames - (s.transitionOverlap ?? 0);
  return seq;
});
```

When a transition has an overlap, subtract that overlap while accumulating - forgetting to subtract leaves a black gap between scenes.

5. **Audio:**
   - Voice: one `<Audio src={voice}>` running from frame 0 - the voice is the sync backbone, scenes follow the voice and never the other way round.
   - Sound effects: each `sfx[]` entry becomes one `<Sequence from={atFrame}><Audio volume={0.3}/></Sequence>`. Default sfx volume is 0.3 (~10dB below the voice); override it in the manifest with the `volume` field if needed.
   - Do not normalize/mix manually with FFmpeg after rendering - mix inside Remotion so the draft sounds like the final.

6. **Caption and overlay tracks live in `meta.json`, and their timestamps are in FRAMES.**

   `CaptionTrack` and `HighlightTrack` read `props.captions` / `props.overlays` **only**. They never
   open a transcript file. If you leave those arrays empty there are no captions, no matter how good
   the transcript is.

```jsonc
// meta.json
"captions": [
  { "from": 90, "durationInFrames": 75,
    "words": [ { "text": "Trí", "start": 90, "end": 96 },
               { "text": "tuệ", "start": 96, "end": 104, "hi": true } ] }
],
"overlays": [
  { "from": 0, "durationInFrames": 150, "tier": "main", "accent": "hot",
    "kicker": "AI", "parts": [ { "t": "Dựng video" }, { "t": "bằng AI", "hi": true } ] }
]
```

   > ⚠️ **The unit changes here.** A transcript stores `start`/`end` in **seconds**; `captions[].words[]`
   > stores them as **absolute composition frames** (`second * fps`, counted from the start of the whole
   > video, not from the start of the cue). Passing seconds through produces captions that all flash in
   > the first half-second — and nothing errors, so it is easy to ship by accident.
   >
   > `hi: true` marks a highlighted word. `tier: "main"` renders a top band, `"sub"` a bottom pill that
   > lifts itself when captions are present.
   >
   > Any cue (caption, subtitle, overlay) may carry `"transform": { "x", "y", "scale" }` - an offset from
   > the track's default anchor, `x`/`y` as a fraction of the frame width/height (-1..1), `scale`
   > 0.3..3. The user sets it by dragging the cue on the editor's preview. **Leave it alone** when you
   > rewrite a cue's text or timing; only change it when asked to move or resize the text.

7. **Every scene needs `durationInFrames` unless it is a `srcVideo` scene with both `from` and `to`.**
   That is the only case Remotion infers a length for; an image or HyperFrames scene without an explicit
   `durationInFrames` **throws at render time**. This bites hardest on videos with no source footage
   (text-to-video, image-only explainers), where nothing has a natural duration to infer from.

8. **`meta.json` is shared with a human editor.** The dashboard's video editor previews the `Assemble`
   composition live in the browser (`@remotion/player`) and saves the timeline keys (`scenes`, `audio`,
   `captions`, `subtitles`, `subtitleStyle`, `overlays`, `layers`) straight back into `meta.json`. When you assemble
   or adjust the timeline: **re-read `meta.json` right before each change, change it in place with `Edit`,
   never `Write` the whole file from memory, and keep every field you do not recognise** (the schema uses
   `z.looseObject` precisely so extra fields survive). Paths stay relative to the project folder with no
   `..` - the editor's server-side validator rejects anything else, and so does staging.

9. **Asset paths**: Remotion code only loads through `staticFile()` - the backend stages assets into `engines/remotion/public/staging/<project>/` (hardlink) and writes the `staging/...` path into `props.resolved.json`; Remotion never reads an absolute path. This runs on Windows - always use `path.join` on the backend, never string concatenation.

   Inside the `Assemble` tree, get that `staticFile` through **`useMediaSrc()`** (`src/media.tsx`), never by calling `staticFile()` directly. The dashboard editor runs the same `Assemble` in `@remotion/player`, where there is no Remotion `public/`: it wraps the tree in `MediaResolverProvider` and maps project-relative paths to `/media/video-projects/<id>/...` and `fonts/...` to `/media/remotion-fonts/...`. A direct `staticFile()` (or one evaluated at module scope, like the old `vietnameseFontFaceCss` constant) renders fine through the CLI but 404s in the preview. The default resolver IS `staticFile`, so CLI renders produce the same frames as before. Poster/Thumbnail/brandFonts only render through the CLI and keep `staticFile`.

## Draft vs Final

| | Draft | Final |
|---|---|---|
| Command | `--crf 28 --x264-preset veryfast` (+ `--concurrency 8 --gl angle`) | defaults (crf 18) |
| Scene input | `renders/*.draft.mp4` | `renders/*.mp4` (quality standard) |
| Purpose | review pacing, sync, transitions | publishing |

The backend picks the scene input set based on the job type - the Remotion code does not distinguish draft from final, it only takes the paths from the manifest.

## Known issues & how to avoid them

- **Stutter/freeze at a scene boundary**: the scene fps differs from the composition fps, or `durationInFrames` in the manifest does not match the real length of the MP4. Check with `ffprobe -show_streams <file>` before assembling.
- **Audio drifting out of sync toward the end**: a VBR voice mp3 -> convert it to CBR/WAV before putting it in the manifest (`ffmpeg -i voice.mp3 -ar 48000 voice.wav`).
- **Color mismatch between HyperFrames scenes and footage**: both engines render through Chromium so they usually match; if they do not, check whether the footage has an unusual color space tag (`bt709` is the standard) - transcode the footage to bt709 first.
- **Render hanging on Windows**: usually caused by Vietnamese characters/spaces in an asset file path - name asset files in ASCII kebab-case right from the import step.
- **One black frame at every footage cut**: a `srcVideo` scene sized `round((to-from)*fps)` while `OffthreadVideo` plays `round(to*fps) - round(from*fps)` frames - the two differ by one (from=1.02, to=3.98 @30fps: 89 vs 88). Always round EACH END, never the difference; `resolveSceneDurationInFrames` and `frameOf` in `jobs/assemble.ts` must stay in lockstep with `SceneClip`.
- **Sped-up footage (`speed` > 1) going black for the second half of the scene**: since Remotion 4.0.537 (the pinned version) the `Sequence` inside `OffthreadVideo` already divides `(endAt - startFrom)` by `playbackRate` itself, so `endAt` must be the plain SOURCE frame `round(to * fps)`. Converting it again (`startFrom + ceil((endAt - startFrom) / speed)`, which 4.0.500 needed for `speed` < 1) divides twice: speed 2 on a 10 s clip gives a 150-frame scene whose video stops at frame 75. Check `node_modules/remotion/dist/cjs/video/OffthreadVideo.js` again whenever you bump Remotion.
- **Whole render dies on one tiny cue** (`inputRange must be strictly monotonically increasing`): a fade written as `[0, 4, max(5, last-4), last]` is not increasing when a cue is 6 frames or less (a translated cue clamped near the end of the video is enough). Use `fadeInOut()` from `components/fade.ts` for any new track instead of hand-writing the range.
- **Rendering on a machine with no network**: Remotion tries to download Chrome from `remotion.media`. Pass `--browser-executable=<local chrome/headless_shell>` instead.

## Remotion license (keep in mind when scaling up)

Remotion is free for individuals and companies of <= 3 people; beyond that you need a Company License. This note is for planning growth - it does not affect the current stage.

© notivn · MIT · notivn/AIEVv2

Похожие скиллы

Все скиллы по теме «Фронтенд и UI» →
remotion-create remotion-dev Скилл remotion-create для Claude Code и Codex разворачивает проект Remotion с нуля. Инициализирует репозиторий через npx create-video и готовит окружение к вёрстке видео на React. CX Codex +1 375 000установок remotion-captions remotion-dev Скилл remotion-captions для Claude Code и Cursor помогает работать с субтитрами в видеопроектах Remotion. Генерирует тайминги, конвертирует форматы и настраивает анимацию текста на экране. CX Codex +1 373 700установок remotion vercel-labs Превращает JSON-описания видеотайм-лайна в готовые видеокомпозиции через Remotion. Рендерит видео программно и собирает каталоги клипов из данных. CX Codex +1 1 800установок yyl-remotion-video ttfake92-lab Скилл yyl-remotion-video для Claude Code и других агентов: берёт статью, сценарий или заметки и собирает проект Remotion, рендерит mp4 без звука. CX Codex +1 549установок remotion-scaffold ncklrs Скилл remotion-scaffold создаёт базовую структуру папок, заготовки файлов и настройки для видеопроектов на Remotion. Пригодится на старте нового ролика, чтобы не нарезать файлы вручную. CX Codex +1 170установок remotion-video-toolkit shreefentsar Скилл remotion-video-toolkit для Claude Code учит ИИ-агента писать код Remotion: анимации, тайминг, рендер в MP4, субтитры, графики и 3D. Генерирует видео из данных через React-компоненты и собирает их в настоящий MP4. CX Codex +1 804установок

Из того же набора15

Весь набор →
offline-voice Скилл offline-voice для Claude Code объясняет настройку локального движка озвучки VieNeu-TTS и клонирования голоса. Включается при отладке маршрутов /api/tts и озвучки видео. CX Codex +1 ★ 147звёзд репо make-a-video make-a-video — скилл для Claude Code, который ведёт от идеи к готовому MP4 через HyperFrames. Он собирает требования, готовит сценарный план и проверяет видео перед финальным рендером. CX Codex +1 ★ 147звёзд репо auto-cut Скилл auto-cut для Claude Code убирает тишину, оговорки и повторы дублей из видео с говорящей головой до монтажа. Включается по флагу autoCut в брифе или при жалобах на паузы. CX Codex +1 ★ 147звёзд репо ai-illustrations Скилл ai-illustrations для Claude Code добавляет сгенерированные изображения в видеомонтаж. Он включается, когда в задании разрешены AI-иллюстрации или запрошены изображения для видео. CX Codex +1 ★ 147звёзд репо video-pipeline Скилл video-pipeline для Claude Code описывает путь от запроса до MP4 и распределяет работу между HyperFrames и Remotion. Запускается при создании видео или настройке очереди рендеринга. CX Codex +1 ★ 147звёзд репо noti-tiktok-full-text Скилл noti-tiktok-full-text для Claude Code собирает вертикальные TikTok-видео с разбором научных статей через HyperFrames. Включается по стенограмме, иллюстрациям и сканам страниц PDF. CX Codex +1 ★ 147звёзд репо short-form-video Скилл short-form-video для Claude Code помогает собирать и править вертикальные ролики в Hyperframes с говорящей головой, графикой и караоке-субтитрами. Запускается по запросам о TikTok, Reels, Shorts и пересборке короткого видео. CX Codex +1 ★ 147звёзд репо noti-tiktok-vn Скилл noti-tiktok-vn для Claude Code монтирует вертикальные видео 9:16 для TikTok через HyperFrames. Собирает говорящую голову, караоке-субтитры, зумы и типографику по стилю Noti.vn в готовый MP4. CX Codex +1 ★ 147звёзд репо

Спонсоры проекта

Компании, которые помогают держать аналитику открытой