SRT Remotion Video - Main Workflow Orchestration

Complete workflow for converting SRT subtitle files into Remotion videos.

Workflow Overview

text

┌──────────┐   ┌──────────┐   ┌──────────┐   ┌──────────┐   ┌──────────────────────┐   ┌──────────┐
│ Get SRT  │ → │ Dependency │ → │ Project  │ → │ Generate │ → │ Parallel Creator     │ → │ Synthesize│
│ File Path│   │ Precheck/  │   │ Initialization │ │ Storyboard │ │ Planning & Implementation │ │ Video     │
│          │   │ First-time │   │          │   │          │   │ scene-plan + code    │ │          │
│          │   │ Installation │ │          │   │          │   │                      │ │          │
└──────────┘   └──────────┘   └──────────┘   └──────────┘   └──────────────────────┘   └──────────┘

Project Directory Structure

text

<skillRoot>/
├── SKILL.md
├── template/
├── references/
│   ├── storyboard-parser.md
│   └── scene-component-creator.md
└── scripts/
    ├── ensure-template-deps.js
    ├── init-project.js
    ├── generate-storyboard.js
    ├── generate-creator-scenes.js
    ├── generate-scenes-registry.js
    ├── scene-registry-utils.js
    ├── validate-project.js
    └── validate-scene-plan.js

<srtDir>/
├── your-file.srt
└── remotion-video-projects/
    └── {yyyy-mm-dd-hh-mm-ss}/

Path Contract

The main workflow and all SubAgents uniformly use the following absolute path conventions:

```
skillRoot
```
: Absolute path of the current
```
srt-remotion-video
```
skill directory
```
templateRoot
```
:
```
{skillRoot}/template
```
```
referencesRoot
```
:
```
{skillRoot}/references
```
```
scriptsRoot
```
:
```
{skillRoot}/scripts
```
```
srtPath
```
: Absolute path of the SRT file provided by the user

projectBaseDir

{dirname(srtPath)}/remotion-video-projects

```
projectRoot
```
: Directory of the current project instance, formatted as
```
{projectBaseDir}/{projectName}/
```

Mandatory Requirements:

SubAgent prompts must include expanded absolute paths, do not pass only variable names
Stage protocol documents can only be read from
```
referencesRoot
```
Scripts can only be executed from
```
scriptsRoot
```
All runtime states must be explicitly passed by the main Agent

Execution Workflow

Step 0: Obtain SRT File

Ask the user for the SRT file path
If the user provides a relative path, the main Agent must first check whether the file exists
If it exists, the main Agent must resolve it to an absolute path, then use the resolved absolute path as
```
srtPath
```
If it does not exist, clearly inform the user that the path is invalid and request a correct path
All subsequent steps uniformly use the final confirmed absolute path
```
srtPath
```

Step 1: Dependency Precheck and Project Initialization

Key: Templates are always copied from inside the skill, and all work is performed in an independent project directory under the subtitle directory.

1.0 Dependency Precheck (Automatically Installed on First Use)

Execute:

bash

node "{skillRoot}/scripts/ensure-template-deps.js" "{templateRoot}"

The script will:

Check

{templateRoot}/package.json

and

{templateRoot}/package-lock.json

Check whether key template dependencies are installed
If not installed, execute
```
npm install
```
once under
```
{templateRoot}
```
If already installed, skip installation directly
Return a clear error and stop the main workflow if installation or verification fails

1.1 Default Behavior: Create a New Project

Execute:

bash

node "{skillRoot}/scripts/init-project.js" --srt-path "{srtPath}"

The script will:

Ensure

{dirname(srtPath)}/remotion-video-projects/

exists

Create a new project directory

remotion-video-projects/{yyyy-mm-dd-hh-mm-ss}/

Copy template files from
```
{skillRoot}/template/
```
; if template dependencies are already installed, copy the installed dependencies together
Output project information JSON

1.2 User-Specified Project Path (Only When Explicitly Specified by User)

If the user explicitly specifies a project path, use that path directly as

projectRoot

and skip the default directory derivation.

1.3 Record Key Paths

Obtain from script output or user-specified path:

```
projectRoot
```
```
skillRoot
```
```
templateRoot
```
```
referencesRoot
```
```
scriptsRoot
```
```
srtPath
```

All subsequent steps use these absolute paths.

Step 2: Generate Storyboard Script

This step must be executed using a SubAgent.

The main Agent is responsible for:

Calculate and expand absolute paths:

storyboardReference = {referencesRoot}/storyboard-parser.md

storyboardScript = {scriptsRoot}/generate-storyboard.js

Start a SubAgent
Write the actual absolute path values in the prompt

SubAgent prompt template:

text

You are executing the "Storyboard Generation Phase" of the srt-remotion-video workflow.

First read the following reference protocol and strictly follow its steps:
- {storyboardReference}

Input parameters:
- skillRoot: {skillRoot}
- projectRoot: {projectRoot}
- srtPath: {srtPath}

Important:
1. All paths have been expanded to absolute paths, do not guess on your own
2. The script to execute is located at {storyboardScript}
3. After completion, you must return structured results in accordance with the "Return After Completion" contract in the reference protocol

The main workflow must wait for the returned results and read

storyboard.json

to verify that the structure is correct.

Step 3: Use SubAgent to Plan and Implement Scene Components

Read

storyboard.json

to obtain all scene data.

3.0 Preparatory Step: Calculate Grouping

typescript

const SCENES_PER_CREATOR = 5;
const sceneCount = storyboard.scenes.length;
const creatorCount = Math.ceil(sceneCount / SCENES_PER_CREATOR);

The

creatorId

generation rule is fixed as:

typescript

const creatorId = `creator-${String(index + 1).padStart(2, '0')}`;

Example:

1st creator:
```
creator-01
```
2nd creator:
```
creator-02
```
10th creator:
```
creator-10
```

The main workflow must always use this format, do not omit leading zeros, do not change to other naming conventions.

3.1 Plan Creator Tasks

The main workflow is responsible for scheduling:

Generate

scenesDataPath = {projectRoot}/scene-plans/{creatorId}.scenes.json

for each creator

Calculate for each creator:

```
creatorId
```

planPath = {projectRoot}/scene-plans/{creatorId}.json

validateScript = {scriptsRoot}/validate-scene-plan.js

Execute for each creator:

bash

node "{scriptsRoot}/generate-creator-scenes.js" \
  "{projectRoot}/storyboard.json" \
  "{creatorId}" \
  "{SCENES_PER_CREATOR}" \
  "{scenesDataPath}"

The main Agent writes the absolute path of
```
{scenesDataPath}
```
into the SubAgent prompt
Start all creator SubAgents in parallel

3.2 Start All Scene Creators in Parallel

SubAgent prompt template for each Creator:

text

You are executing the "Scene Planning and Implementation Phase" of the srt-remotion-video workflow.

First read the following reference protocol and strictly follow its steps:
- {referencesRoot}/scene-component-creator.md

Input parameters:
- skillRoot: {skillRoot}
- projectRoot: {projectRoot}
- creatorId: {creatorId}
- planPath: {planPath}
- scenesDataPath: {scenesDataPath}
- validateScript: {validateScript}

Important:
1. All paths have been expanded to absolute paths, do not guess on your own
2. The scene data source for the current creator is only allowed to come from {scenesDataPath}
3. During the planning phase, only use {scenesDataPath}, {projectRoot}/cartoon-ui-style-guide.css, {projectRoot}/cartoon-ui-style-guide-reference.md and {skillRoot}/../remotion-best-practices/SKILL.md
4. First generate the scene-plan JSON, then perform validation, and only write scene components after validation passes
5. By default, one subtitle segment corresponds to one beat in `beatPlan`; if adjacent segments clearly belong to the same continuous expression, they can be merged
6. Merging is only allowed between adjacent segments, skip merging is prohibited
7. `beatPlan` only declares `segments` and `action`; actual timing must be derived from `relativeStart / relativeDuration` of scenesData[].segments
8. The main scene rhythm must be bound to scenesData[].segments[].relativeStart / relativeDuration
9. By default, retain the host background, organize the main visual around the middle or upper-middle area of the screen on a transparent root layer; do not rebuild the full-screen background
10. The component interface is fixed as React.FC<{ segments: Segment[] }> and uses default export
11. Only responsible for producing {projectRoot}/src/scenes/SceneXXX.tsx; create the file if it does not exist, only modify the scene files you are responsible for if it already exists
12. Do not manually modify {projectRoot}/src/compositions/Main.tsx or generated-scenes.ts
13. After completion, you must return structured results in accordance with the "Return After Completion" contract in the reference protocol
14. `remotion-best-practices` is at the same level as the current skill, with a fixed entry at {skillRoot}/../remotion-best-practices/SKILL.md

3.3 Wait for All Creators to Complete

Confirm that all target scene component files have been generated.

componentResults
is only used for task completion feedback, not as the real source for final registry file assembly or total duration calculation.

Step 4: Synthesize Video

4.1 Generate Scene Registry File

The normal video generation workflow must not rewrite

{projectRoot}/src/compositions/Main.tsx

Default template output specification:

1920x1080 / 30fps

totalDurationInFrames

generated-scenes.ts

is generated by

generate-scenes-registry.js

, do not modify manually

```
msToFrames
```
in
```
Main.tsx
```
must dynamically obtain the frame rate using
```
useVideoConfig().fps
```
, do not hardcode the
```
FPS
```
constant

Execute:

bash

node "{scriptsRoot}/generate-scenes-registry.js" \
  "{projectRoot}" \
  "{projectRoot}/storyboard.json"

Runtime contract is fixed:

Each
```
SceneXXX.tsx
```
exposes the component via default export

generated-scenes.ts

is responsible for storing

start

duration

segments

Component

```
Main.tsx
```
is responsible for passing segment data to scene components using
```
<Component segments={scene.segments} />
```

4.2 Root.tsx Total Duration Synchronization

Root.tsx

is a read-only template file, there is no need to and it is not allowed to rewrite it in the normal workflow.

Requirements:

Root.tsx

must keep reading

totalDurationInFrames

from

generated-scenes.ts

Do not manually recalculate or fill in the total frame count during the workflow

4.3 Verify Project Product Integrity

Must execute before rendering:

bash

node "{scriptsRoot}/validate-project.js" \
  "{projectRoot}" \
  "{projectRoot}/storyboard.json"

If verification fails, the workflow must be stopped and rendering cannot continue.

4.4 Execute Rendering

bash

cd "{projectRoot}"
npx remotion render Main out/output.mp4

Step 5: Completion

Notify the user:

The video has been generated
Output path:
```
{projectRoot}/out/output.mp4
```
Number of scenes: N
Video duration: X seconds

Debug Mode and Re-Rendering

After the main video generation workflow (Steps 0–5) is completed, the user can request "debug mode" or "re-rendering".

Both operations assume that
projectRoot
exists and scene components have been generated.

Debug Mode

Execute when the user says "debug mode", "preview mode" or similar expressions, and requests to add audio.

TM.0 Obtain Audio File

If the user has provided an audio file path, verify that the file exists and resolve it to an absolute path
```
audioPath
```
If the user has not provided an audio file path, must ask the user for it
Verify that the file exists; if not, inform the user and stop

TM.1 Add Audio to Timeline

Ensure the
```
{projectRoot}/public/
```
directory exists
Copy the audio file as
```
{projectRoot}/public/audio.mp3
```

bash

mkdir -p "{projectRoot}/public"
cp "{audioPath}" "{projectRoot}/public/audio.mp3"

Modify

{projectRoot}/src/compositions/Main.tsx

Add

Audio

and

staticFile

to the import line:

typescript

import { AbsoluteFill, Audio, Sequence, staticFile, useCurrentFrame } from "remotion";

Add the following as the first direct child inside

<AbsoluteFill style={{ backgroundColor: ... }}>

tsx

<Audio src={staticFile("audio.mp3")} />

Start Remotion Studio for user preview:

bash

cd "{projectRoot}"
npx remotion studio

TM.2 Completion Notification

Inform the user that Remotion Studio has been started, audio has been added to the timeline, and they can preview in the browser.

Re-Rendering

Execute when the user says "re-render", "render again" or similar expressions.

RR.0 Remove Audio from Timeline

Before rendering the final video, ensure that there is no audio component in

Main.tsx

Read
```
{projectRoot}/src/compositions/Main.tsx
```
Check if it contains the
```
<Audio
```
tag
If it exists:
- Remove the line
```
<Audio src={staticFile("audio.mp3")} />
```
- Remove
```
Audio
```
  and
```
staticFile
```
  from the import statement (if they are no longer used by other code)
If it does not exist, skip this step

RR.1 Execute Rendering

bash

cd "{projectRoot}"
npx remotion render Main out/output.mp4

RR.2 Completion Notification

Notify the user that the video has been re-rendered, and the output path is

{projectRoot}/out/output.mp4

High Resolution / High Frame Rate Rendering

Execute when the main video generation workflow is completed and the user requests to generate a version with higher specifications than the default configuration (1080p 30fps), such as 4K, 60fps, etc.

This operation assumes that
projectRoot
exists and scene components have been generated.

Key Principle: Separate Design Resolution from Output Resolution

All elements in scene components (cards, icons, text, etc.) use absolute pixel values, designed based on 1920x1080. Directly changing the width/height of Root.tsx to 3840x2160 will cause all elements to shrink in proportion in the frame. The correct approach is to keep the design resolution at 1920x1080 unchanged, and scale the output resolution using Remotion's

--scale

parameter.

Common Mistakes (Prohibited)

Wrong Practice	Consequence
Change Root.tsx to width=3840 height=2160	All scene elements shrink by half
Use `--width 3840 --height 2160` CLI parameters	Same as above
Only change fps without modifying totalDurationInFrames	Only the first half of the video has content, the second half is blank
Hardcode `const FPS = 30` in Main.tsx	Scene timing is messed up after changing Root.tsx fps

HR.0 Confirm User Requirements

Parse user requirements into specific output parameters:

User Requirement	Root.tsx Modification	generated-scenes.ts Modification	Render Command
4K / Ultra HD	No change	No change	`--scale 2`
60fps	`fps={60}`	Convert `totalDurationInFrames` proportionally	No scale needed
4K 60fps	`fps={60}`	Convert `totalDurationInFrames` proportionally	`--scale 2`

HR.1 Modify Frame Rate (Only When User Requests High Frame Rate)

Modify the
```
fps
```
value in
```
{projectRoot}/src/Root.tsx
```
:

typescript

fps={60}  // Changed from 30 to 60

Modify

totalDurationInFrames

{projectRoot}/src/compositions/generated-scenes.ts

typescript

// Frame count = original frame count × (new fps / original fps)
// Example: 30→60fps: 1572 × 2 = 3144
export const totalDurationInFrames = {original frame count × new fps / original fps};

Key: The

width

and

height

<Composition>

{projectRoot}/src/Root.tsx

must not be modified, and must remain

and

. Resolution scaling is done by the

--scale

parameter during rendering, not by modifying the design resolution.

msToFrames
in
Main.tsx
must dynamically obtain the frame rate using
useVideoConfig().fps
. If a hardcoded
FPS
constant is found in
Main.tsx
, it must be fixed to
useVideoConfig().fps
first, otherwise scene timing will be completely messed up after fps changes.

HR.2 Verify Project

bash

node "{scriptsRoot}/validate-project.js" \
  "{projectRoot}" \
  "{projectRoot}/storyboard.json"

If verification fails, must stop and cannot continue rendering.

HR.3 Execute Rendering

bash

cd "{projectRoot}"
npx remotion render Main out/output-4k.mp4 --scale 2

```
--scale 2
```
: Scale the 1920x1080 design canvas by 2x to render as 3840x2160
Vector elements (text, SVG) will be rendered at higher resolution, resulting in clearer image quality
The layout is exactly the same as 1080p, no element shrinking issue
If only 60fps is needed without 4K, remove
```
--scale 2
```

HR.4 Completion Notification

Notify the user:

Output path:
```
{projectRoot}/out/output-4k.mp4
```
Output resolution, frame rate, duration
If fps was modified, remind the user that the fps in Root.tsx has been changed from 30 to the target value

Data Structure Reference

storyboard.json

typescript

interface Storyboard {
  totalDuration: number;
  sceneCount: number;
  scenes: {
    id: string;
    startTime: number;
    duration: number;
    segments: {
      text: string;
      relativeStart: number;
      relativeDuration: number;
    }[];
    semanticTags?: string[];
    visualHint?: string;
  }[];
}

scene-plan JSON

typescript

interface ScenePlanCard {
  sceneId: string;
  goal: string;
  layout: string;
  visualCore: string;
  surface: string;
  emphasis: string;
  screenShouldShow: string[];
  beatPlan: {
    segments: number[];
    action: string;
  }[];
}

SceneComponentResult

typescript

interface SceneComponentResult {
  sceneId: string;
  componentPath: string;
  componentName?: string;
  planPath?: string;
}

Resources

template/

Lightweight template project, distributed with the skill
Dependencies are installed in the template directory on first use, and subsequent projects reuse template dependencies

references/

```
storyboard-parser.md
```
: Storyboard generation phase protocol
```
scene-component-creator.md
```
: Scene planning and implementation phase protocol
```
theme-template-switching.md
```
: Theme template switching guide

scripts/

```
ensure-template-deps.js
```
: Check template dependencies, perform first-time installation if necessary
```
init-project.js
```
: Initialize project based on
```
srtPath
```
```
generate-storyboard.js
```
: Generate storyboard.json based on SRT and groups.json
```
generate-creator-scenes.js
```
: Generate scenesData JSON for the specified creator based on storyboard.json

generate-scenes-registry.js

: Generate

generated-scenes.ts

```
scene-registry-utils.js
```
: Shared utilities for registry and validation
```
validate-project.js
```
: Integrity check before rendering
```
validate-scene-plan.js
```
: Validate scene-plan JSON structure and segment binding

Execution Checklist

Main Workflow

Obtain the absolute path of the SRT file provided by the user
Run
```
ensure-template-deps.js
```
to check template dependencies, complete first-time installation if necessary
Run
```
init-project.js --srt-path
```
to create project

Obtain

projectRoot

skillRoot

templateRoot

referencesRoot

scriptsRoot

Generate

storyboard.json

using

references/storyboard-parser.md

Verify that
```
storyboard.json
```
structure is correct
Calculate Creator grouping
Generate scene-plan and scene components in parallel using
```
references/scene-component-creator.md
```
Run
```
generate-scenes-registry.js
```
Run
```
validate-project.js
```
Execute rendering

Debug Mode

Obtain the absolute path of the audio file provided by the user
Copy audio to
```
{projectRoot}/public/audio.mp3
```
Modify
```
Main.tsx
```
to add
```
<Audio>
```
component
Start Remotion Studio for user preview

Re-Rendering

Check if
```
Main.tsx
```
contains
```
<Audio>
```
tag
If exists, remove
```
<Audio>
```
and related imports
Execute rendering

High Resolution / High Frame Rate Rendering

Parse user requirements into specific output resolution, frame rate and scale values
Confirm that
```
msToFrames
```
in
```
Main.tsx
```
uses
```
useVideoConfig().fps
```
instead of hardcoded constants
Only when high frame rate is required: modify
```
fps
```
in
```
Root.tsx
```
and
```
totalDurationInFrames
```
in
```
generated-scenes.ts
```
Confirm that
```
width
```
/
```
height
```
in
```
Root.tsx
```
remain 1920/1080 unchanged
Run
```
validate-project.js
```
for verification
Execute rendering with
```
--scale 2
```
(for 4K)

Notes

All paths must use absolute paths
SubAgent prompts must pass actual path values, not just variable names
Template resources are located at
```
{skillRoot}/template
```
Templates are distributed in lightweight form, dependency precheck in
```
template/
```
must be completed on first use

Default project directory is located at

{dirname(srtPath)}/remotion-video-projects

```
Main.tsx
```
and
```
Root.tsx
```
belong to the protected host layer
Scene components must actually consume
```
segments
```
Rendering cannot continue if
```
validate-project.js
```
fails
If the user wants to change the theme template, must first refer to
```
references/theme-template-switching.md
```

srt-remotion-video

NPX Install

Tags

SKILL.md Content (Chinese)

SRT Remotion Video - Main Workflow Orchestration

Workflow Overview

Project Directory Structure

Path Contract

Execution Workflow

Step 0: Obtain SRT File

Step 1: Dependency Precheck and Project Initialization

1.0 Dependency Precheck (Automatically Installed on First Use)

1.1 Default Behavior: Create a New Project

1.2 User-Specified Project Path (Only When Explicitly Specified by User)

1.3 Record Key Paths

Step 2: Generate Storyboard Script

Step 3: Use SubAgent to Plan and Implement Scene Components

3.0 Preparatory Step: Calculate Grouping

3.1 Plan Creator Tasks

3.2 Start All Scene Creators in Parallel

3.3 Wait for All Creators to Complete

Step 4: Synthesize Video

4.1 Generate Scene Registry File

4.2 Root.tsx Total Duration Synchronization

4.3 Verify Project Product Integrity

4.4 Execute Rendering

Step 5: Completion

Debug Mode and Re-Rendering

Debug Mode

TM.0 Obtain Audio File

TM.1 Add Audio to Timeline

TM.2 Completion Notification

Re-Rendering

RR.0 Remove Audio from Timeline

RR.1 Execute Rendering

RR.2 Completion Notification

High Resolution / High Frame Rate Rendering

Key Principle: Separate Design Resolution from Output Resolution

Common Mistakes (Prohibited)

HR.0 Confirm User Requirements

HR.1 Modify Frame Rate (Only When User Requests High Frame Rate)

HR.2 Verify Project

HR.3 Execute Rendering

HR.4 Completion Notification

Data Structure Reference

storyboard.json

scene-plan JSON

SceneComponentResult

Resources

template/

references/

scripts/

Execution Checklist

Main Workflow

Debug Mode

Re-Rendering

High Resolution / High Frame Rate Rendering

Notes