Skip to content
Sup

SupVideo

The SupVideo object represents a video. Returning one from the main() function will display the video in the chat.

Example Video
SupVideo: {
  "url": "https://user-uploads.cdn.overworld.xyz/v8hd62jka9lpqmxn4wfr3tcy.m3u8",
  "filename": "screen-recording.mp4"
}

Properties

filename

type: string | undefined

The filename of the video, if available. This is usually set when the video is uploaded as an asset in the patch editor.

url

type: string

Gets the CDN URL for the video. Note: This URL may sometimes be an M3U8 playlist URL.

width

type: number | undefined

The width of the video in pixels. This is automatically populated when video metadata is available.

height

type: number | undefined

The height of the video in pixels. This is automatically populated when video metadata is available.

duration

type: number | undefined

The duration of the video in seconds. This is automatically populated when video metadata is available.

thumbnailUrl

type: string | undefined

A URL to a thumbnail image of the video. This is automatically generated and populated when video metadata is available.

firstFrame

type: SupImage | undefined

The first frame of the video as an image object. Accessed lazily when needed.

lastFrame

type: SupImage | undefined

The last frame of the video as an image object. Accessed lazily when needed.

audio

type: SupAudio | undefined

The audio track extracted from the video. Accessed lazily when needed.

Creating Videos from Images

You can create videos from images using sup.video() with a SupImage parameter. By default, image-to-video conversion creates a 3-second video clip.

// Create a 3-second video from an image (default duration)
const imageVideo = sup.video(sup.image("photo.jpg"));


// Customize the duration using the edit cursor
const longerImageVideo = sup.video(sup.image("slide.png"))
  .edit()
  .duration(5)  // Make it 5 seconds instead of 3
  .render();


// Add effects to image-based videos
const enhancedImageVideo = sup.video(sup.image("background.jpg"))
  .edit()
  .duration(8)
  .fadeIn(1)
  .fadeOut(1)
  .addAudio(sup.audio("music.mp3"), 'mix')
  .render();

This is useful for creating slide presentations, static backgrounds with audio, or transitional elements in video sequences.

Methods

edit()

Returns a SupVideoEditCursor that allows you to chain video editing operations.

const editedVideo = sup.video("video.mp4")
  .edit()
  .addAudio(sup.audio("music.mp3"), 'mix')
  .addOverlay(sup.image("logo.png"), 'topRight')
  .duration(10)
  .fadeIn(1)
  .fadeOut(1)
  .addCaption("Hello World!", { position: 'bottom' })
  .render();

Video Editing Operations

  • addAudio(audio: SupAudio | string, mode?: 'mix' | 'replace') - Add audio track
  • addOverlay(media: SupImage | SupVideo | string, position: 'topLeft' | 'topRight' | 'bottomLeft' | 'bottomRight' | 'center') - Add overlay
  • duration(seconds: number) - Set video duration (useful for customizing image-to-video duration)
  • fadeIn(seconds: number) - Add fade in effect
  • fadeOut(seconds: number) - Add fade out effect
  • trimStart(seconds: number) - Trim from beginning
  • trimEnd(seconds: number) - Trim from end
  • addCaption(text: string, options?: { position?: 'top' | 'center' | 'bottom' }) - Add text caption
  • render() - Apply all edits and return new SupVideo

Video Sequences

Create sequences of multiple video clips using sup.sequence(). The SupSequence object represents a sequence of video clips that can be combined into a single video, supporting mixing of videos, images, URLs, and asset filenames.

Basic Sequence
const sequence = sup.sequence([
  "intro.mp4",                               // Asset filename
  "https://example.com/middle.mp4",          // Full URL
  sup.video("main.mp4"),                     // SupVideo object
  sup.image("end-slide.jpg")                 // Images become 3-second video clips
]);


const finalVideo = sequence.render();

Sequence Editing

Like individual videos, sequences support the same editing operations:

const editedSequence = sup.sequence([
  "clip1.mp4",                               // Asset filename
  "clip2.mp4",                               // Asset filename
  "https://example.com/clip3.mp4"            // Full URL
])
  .addAudio(sup.audio("background-music.mp3"), 'mix')
  .addOverlay(sup.image("watermark.png"), 'bottomRight')
  .fadeIn(2)
  .fadeOut(2)
  .render();


// Customize image clip durations in sequences
const customDurationSequence = sup.sequence([
  sup.video(sup.image("intro.jpg")).edit().duration(5).render(),  // 5-second intro
  sup.video("main-content.mp4"),
  sup.video(sup.image("outro.jpg")).edit().duration(2).render()   // 2-second outro
]).render();

Mixed Media Examples

// Presentation-style video
function main() {
  const sequence = sup.sequence([
    sup.image("title-slide.jpg"),    // 3-second image clip
    sup.video("presentation.mp4"),
    sup.image("thank-you.jpg")       // 3-second image clip
  ]);


  return sequence
    .addAudio(sup.audio("background.mp3"), 'mix')
    .addOverlay(sup.image("logo.png"), 'topRight')
    .render();
}

Output

Returning a SupVideo from a patch’s main() function will display the video in the chat.

function main() {
  return sup.video("https://example.com/video.mp4");
}