Video pipeline (videoPipeline)

painter.videoPipeline(source?) is the recommended API when several edits belong to one project: trim, deterministic segment replacement, captions, file audio, and procedural SFX. It uses a validated layer stack and isolated internal workspaces rather than asking application code to manage a chain of temporary output files.

Also on: painter.video.videoPipeline() (same VideoStack entry).

Basics (single ops): Video overview · Timeline · Text overlays · Video audio · createAudio

#When to use what

Requirements and source policy are the same as createVideo: FFmpeg/ffprobe plus the centralized Buffer/local/HTTP(S) resolver described in Video overview.

#Layer stack model

Each builder call adds or updates a validated layer:

##Stable layer IDs

• Same id on source / trim / splice replaces the previous layer with that id.
• Same id on text / audio merges overlays or tracks.
• pushLayer(layer, { replace: true }) explicitly replaces instead of merging.
• Invalid mutations are transactional: a rejected edit does not leave the stack partially changed.

This makes IDs suitable for editor timeline rows and deterministic project updates.

#Execution order and splice determinism

Rendering is normalized to this order:

1. source resolution;
2. trim;
3. splices, sorted by targetStartTime and then id;
4. text overlays;
5. audio mix;
6. optional preview encode.

Overlapping splice ranges are rejected. Multiple durationPolicy: 'preserve' splices are rejected because changing total timeline length would make later source coordinates ambiguous.

The render result exposes the plan that actually ran:

1const result = await pipeline.render({ outputPath: './out.mp4' });2 3console.log(result.passes);4console.log(result.executionPlan);5// e.g. ['trim', 'splice:broll', 'text', 'audio']

passes is the actual internal FFmpeg stage count, not an estimate.

#Full example — trim, B-roll, titles, music + synth SFX

1import { ApexPainter } from 'apexify.js';2 3const painter = new ApexPainter({ type: 'buffer' });4 5const pipeline = painter6  .videoPipeline('./uploads/user-clip.mp4')7  .trim(0, 60, 'trim')8  .splice(9    {10      targetStartTime: 10,11      targetEndTime: 15,12      replacementVideo: './uploads/b-roll.mp4',13      replacementStartTime: 0,14      replacementDuration: 5,15      durationPolicy: 'fit',16    },17    'broll'18  )19  .text(20    [21      {22        text: 'Before B-roll',23        x: 48,24        y: 80,25        startTime: 0,26        endTime: 10,27        font: { size: 42, family: 'Arial' },28        decorations: { bold: true },29        fill: { color: '#ffffff' },30        effects: { shadow: { color: 'rgba(0,0,0,0.5)', offsetY: 3, blur: 8 } },31        transitionIn: { type: 'fade', duration: 0.3 },32      },33      {34        text: 'B-roll',35        x: 48,36        y: 80,37        startTime: 10,38        endTime: 15,39        font: { size: 42, family: 'Arial' },40        fill: { color: '#fbbf24' },41        transitionIn: { type: 'slideLeft', duration: 0.4 },42      },43    ],44    'titles'45  )46  .audio(47    [48      { type: 'file', source: './music.mp3', startTime: 0, volume: 0.35 },49      { type: 'preset', preset: 'whoosh', startTime: 9.8, gain: 1.1 },50    ],51    { keepOriginalAudio: true, originalVolume: 0.85, durationPolicy: 'video' },52    'sound'53  );54 55const result = await pipeline.render({56  outputPath: './out/final.mp4',57  overwrite: true,58  onProgress: ({ percent, speed }) => console.log(percent, speed),59});60 61console.log('Done:', result.outputPath);62console.log('Passes:', result.passes);63console.log('Plan:', result.executionPlan);

#Text layers — createText parity

.text() accepts VideoTextOverlayClip: the TextProperties styling surface plus timed video fields.

Unicode, quotes, newlines, multiple overlays, timed visibility, and transitions are handled without shell command interpolation. Later overlays in the same text layer are applied after earlier ones.

Single-op equivalent: Text overlays.

#Audio layers — files + procedural audio

.audio(tracks, options?, id?) accepts:

Audio-layer options include original-audio retention/volume/speed/pitch and durationPolicy: 'video' | 'shortest' | 'longest'.

1pipeline.audio(2  [3    { type: 'file', source: './bed.mp3', startTime: 0, volume: 0.3, pan: -0.2, fadeIn: 0.5 },4    { type: 'preset', preset: 'coin', startTime: 2.5, gain: 0.9 },5    { type: 'sequence', startTime: 0, events: [{ at: 0, preset: 'laser' }, { at: 0.2, preset: 'explosionSmall' }] },6  ],7  { keepOriginalAudio: false, durationPolicy: 'video' },8  'sfx'9);

#Undo / redo

The builder keeps bounded project history for editor-style mutations:

1pipeline.text(caption, 'caption');2 3if (pipeline.canUndo()) pipeline.undo();4if (pipeline.canRedo()) pipeline.redo();

undo() and redo() return false when no corresponding history entry exists. A new successful mutation clears redo history.

#Versioned saved projects

toJSON() emits a versioned snapshot:

1const snapshot = pipeline.toJSON();2console.log(snapshot.version); // 13 4await db.projects.save(JSON.stringify(snapshot));

For path/URL-backed projects, restore the persisted layer array through the public painter entry:

1const snapshot = JSON.parse(await db.projects.load());2 3if (snapshot.version !== 1) {4  throw new Error(`Unsupported video pipeline snapshot version: ${snapshot.version}`);5}6 7const restored = painter.videoPipeline(undefined, snapshot.layers);8await restored.render({ outputPath: './export.mp4' });

For durable editor projects, prefer stable path/URL/object-storage references rather than embedding large media Buffers in database JSON.

#render options

1await pipeline.render({2  outputPath: './out/final.mp4',3  preset: 'export', // 'preview' performs a real final proxy encode4  signal: controller.signal,5  timeoutMs: 120_000,6  overwrite: false,7  onProgress: (p) => console.log(p.percent, p.speed),8});

• preset: 'export' keeps the full export path.
• preset: 'preview' adds a real low-quality proxy encode, constrained to a maximum 960-pixel dimension while preserving aspect ratio.
• signal, timeoutMs, overwrite, and onProgress use the same shared execution controls as createVideo.

#Pipeline vs chained createVideo

Operations that are not pipeline layer kinds (for example LUT, stabilization, or batch orchestration) remain single createVideo operations and can run before or after a pipeline export.

#Combine with Scene export

Typical product flow:

1. renderSceneToVideoFrames or animate for branded/generated segments.
2. videoPipeline to trim uploads, splice generated segments, burn captions, and mix file/procedural audio.

See Render scene to video.