Video Manipulation
Trelae supports non-destructive, queued video transformations. Chain one or more operations and apply them via .save().
- Video jobs default to async; poll with
getVideoStatus(operationId). - Optionally run in sync mode:
.save({ mode: 'sync' })(use for short/fast operations only).
Quick Start (async + polling)
Operations
Change Format / Codecs
Convert container, set codecs, CRF, and preset.
Method: file.changeVideoFormat(params)
Trim
Cut by start + duration or start + end.
Method: file.trimVideo({ start?, duration?, end? })
Scale
One dimension → aspect kept. Both dimensions → aspect forced (not kept).
Method: file.scaleVideo({ width?, height?, keepAspect? })
Rotate / Flip
Method: file.rotateFlipVideo({ rotate?, hflip?, vflip? })
Remove Audio
Method: file.removeAudio()
Speed
Change playback rate of video and/or audio.
Method: file.speedVideo({ videoSpeed?, audioSpeed? })
Crop
Method: file.cropVideo({ x, y, width, height })
Mute Segment
Silence audio for a time window.
Method: file.muteSegment({ start, duration })
Visual Fade (in/out)
Method: file.fadeVideo({ type: 'in' | 'out', startTime, duration })
Timed Text Overlay
Method: file.addTextVideo({ text, x, y, fontSize?, fontColor?, fontFile?, startTime?, endTime? })
Add Border
Method: file.addBorderVideo({ color?, top?, bottom?, left?, right? })
Reverse
Method: file.reverseVideo({ video?, audio? })
Audio Fade (in/out)
Method: file.audioFadeVideo({ type, startTime, duration })
Motion Blur
Method: file.motionBlurVideo({ frames?, weights?, outputFps? })
Grayscale
Method: file.grayscaleVideo()
Color EQ
Method: file.colorEQVideo({ brightness?, contrast?, saturation?, gamma? })
Hue Rotate
Method: file.hueRotateVideo({ degrees, saturation? })
Box Blur (time-bounded)
Method: file.boxBlurVideo({ lumaRadius?, lumaPower?, startTime?, endTime? })
Sharpen
Method: file.sharpenVideo({ amount?, size? })
Volume (gain)
Method: file.volumeVideo({ gain })
Sync vs Async
- Async (default): returns immediately with
{ type: 'video', status, operationId }. Poll viagetVideoStatus(). - Sync:
await file.trimVideo({...}).save({ mode: 'sync' }). Prefer for quick ops; long jobs should be async.
Parameter Reference (Cheat Sheet)
All operations are validated at runtime; invalid combinations will throw.
Defaults are shown in bold when applicable.
Enumerations & Allowed Values
Formats (for changeFormat.format)
mp4 · m4v · mov · mkv · webm · avi · flv · f4v · ogg · ogv · ts · m2ts · mts · mpg · mpeg · ps · vob · 3gp · 3g2 · asf · wmv · mxf · gxf · dv · nut · y4m · apng · gif
Video Codecs (for changeFormat.videoCodec)
libx264 · h264 · h264_nvenc · h264_qsv · h264_amf ·
libx265 · hevc · hevc_nvenc · hevc_qsv · hevc_amf ·
libvpx · vp8 · libvpx-vp9 ·
prores · prores_ks · dnxhd · dnxhr · mpeg4 · msmpeg4 · copy
Audio Codecs (for changeFormat.audioCodec)
aac · libmp3lame · mp3 · libopus · libvorbis · ac3 · eac3 · flac · alac · pcm_s16le · pcm_s24le · copy
Presets (x264/x265)
ultrafast · superfast · veryfast · faster · fast · medium · slow · slower · veryslow
Rotate (for rotateFlip.rotate)
“90” · “180” · “270”
Operations & Parameters
changeFormat
| Param | Type | Default / Range | Notes |
|---|---|---|---|
| format | string | — | See Formats above. |
| videoCodec | string | — | Use copy to stream-copy video. |
| audioCodec | string | — | Use copy to stream-copy audio. |
| crf | number | 0..51 | Lower = higher quality (x264/x265). |
| preset | string | medium | See Presets above. |
trim
| Param | Type | Default / Range | Notes |
|---|---|---|---|
| start | number | ≥ 0 | With duration or with end. |
| duration | number | > 0 | Mutually exclusive with end. |
| end | number | > start | Mutually exclusive with duration. |
scale
| Param | Type | Default / Range | Notes |
|---|---|---|---|
| width | number? | > 0 | If only one of width/height is set → keepAspect forced true. |
| height | number? | > 0 | If both are set → keepAspect forced false (exact reshape). |
| keepAspect | boolean? | auto | Overridden by rules above. |
rotateFlip
| Param | Type | Default | Notes |
|---|---|---|---|
| rotate | “90” | “180” | “270” | — | Clockwise. |
| hflip | boolean | false | Horizontal flip. |
| vflip | boolean | false | Vertical flip. |
removeAudio
Removes all audio streams from the output (no parameters).
speed
| Param | Type | Default / Range | Notes |
|---|---|---|---|
| videoSpeed | number? | > 0 | e.g. 0.5, 1.25, 2. |
| audioSpeed | number? | > 0 | If omitted, backend may auto-sync A/V as needed. |
crop
| Param | Type | Default / Range | Notes |
|---|---|---|---|
| x | number | ≥ 0 | Left origin (px). |
| y | number | ≥ 0 | Top origin (px). |
| width | number | > 0 | Pixels. |
| height | number | > 0 | Pixels. |
muteSegment
| Param | Type | Default / Range | Notes |
|---|---|---|---|
| start | number | ≥ 0 | Seconds. |
| duration | number | > 0 | Seconds. |
fade (visual)
| Param | Type | Default / Range | Notes |
|---|---|---|---|
| type | “in” | “out” | — | Visual fade. |
| startTime | number | ≥ 0 | Seconds. |
| duration | number | > 0 | Seconds. |
addText (visual)
| Param | Type | Default / Range | Notes |
|---|---|---|---|
| text | string | — | Overlay string. |
| x / y | number | px | Position. |
| fontSize | number? | 24 | Pixels. |
| fontColor | string? | white | Any valid color string. |
| fontFile | string? | — | Absolute path to .ttf on server. |
| startTime | number? | ≥ 0 | Optional show window start (s). |
| endTime | number? | > start | Optional show window end (s). |
addBorder
| Param | Type | Default / Range | Notes |
|---|---|---|---|
| color | string? | black | Border color. |
| top/bottom | number? | ≥ 0 | Thickness px. |
| left/right | number? | ≥ 0 | Thickness px. |
reverse
| Param | Type | Default | Notes |
|---|---|---|---|
| video | boolean? | true | Reverse video track. |
| audio | boolean? | false | Reverse audio track. |
audioFade
| Param | Type | Default / Range | Notes |
|---|---|---|---|
| type | “in” | “out” | — | Audio fade. |
| startTime | number | ≥ 0 | Seconds. |
| duration | number | > 0 | Seconds. |
motionBlur
| Param | Type | Default / Range | Notes |
|---|---|---|---|
| frames | number? | 5, 2..64 | Frames to blend. |
| weights | string? | — | e.g. "1 2 3 2 1". |
| outputFps | number? | ≤ 240 | Override output FPS. |
grayscale
Desaturates frames (no parameters).
colorEQ
| Param | Type | Default / Range | Notes |
|---|---|---|---|
| brightness | number? | 0, −1..1 | |
| contrast | number? | 1, 0..10 | |
| saturation | number? | 1, 0..10 | |
| gamma | number? | 1, 0.1..10 |
hueRotate
| Param | Type | Default / Range | Notes |
|---|---|---|---|
| degrees | number | −360..360 | Hue rotation. |
| saturation | number? | 1 | Optional gain. |
boxBlur
| Param | Type | Default / Range | Notes |
|---|---|---|---|
| lumaRadius | string? | — | e.g. "2", "4:2". |
| lumaPower | number? | 1..16 | Strength. |
| startTime | number? | ≥ 0 | Optional start (s). |
| endTime | number? | > start | Optional end (s). |
sharpen
| Param | Type | Default / Range | Notes |
|---|---|---|---|
| amount | number? | 1, 0..5 | Sharpen amount. |
| size | number? | 5, odd 3..11 | Kernel size. |
volume
| Param | Type | Default / Range | Notes |
|---|---|---|---|
| gain | number | 1, 0..10 | Linear gain factor |
Tips & Gotchas
- Sync vs Async — Use
save({ mode: 'sync' })only for short jobs. Long encodes should be async with status polling. - Scale rules — One dimension → aspect kept; both → forced reshape. The SDK auto-sets
keepAspect. - Copy codecs —
videoCodec: 'copy'/audioCodec: 'copy'only when the output container supports the input streams. - CRF — Lower CRF → higher quality (and larger files). Typical range 18–28 for H.264/H.265.