pixeltable.functions.video

​

UDFs

​

clip() _udf

• ffmpeg needs to be installed and in PATH

clip(
    video: Video,
    start_time: Float,
    end_time: Optional[Float],
    duration: Optional[Float]
)-> Optional[Video]

• video (Video): Input video file
• start_time (Float): Start time in seconds
• end_time (Optional[Float]): End time in seconds
• duration (Optional[Float]): Duration of the clip in seconds

• Optional[Video]: New video containing only the specified time range or None if start_time is beyond the end of the video.

​

concat_videos() _udf

• ffmpeg needs to be installed and in PATH

concat_videos(videos: Json)-> Video

• videos (Json): List of videos to merge.

• Video: A new video containing the merged videos.

​

extract_audio() _udf

extract_audio(
    video_path: Video,
    stream_idx: Int,
    format: String,
    codec: Optional[String]
)-> Audio

• stream_idx (Int): Index of the audio stream to extract.
• format (String): The target audio format. ('wav', 'mp3', 'flac').
• codec (Optional[String]): The codec to use for the audio stream. If not provided, a default codec will be used.

• Audio: The extracted audio.

tbl.add_computed_column(extracted_audio=tbl.video_col.extract_audio(format='flac'))

​

extract_frame() _udf

extract_frame(
    video: Video,
    timestamp: Float
)-> Optional[Image]

• video (Video): The video from which to extract the frame.
• timestamp (Float): Extract frame at this timestamp (in seconds).

• Optional[Image]: The extracted frame as a PIL Image, or None if the timestamp is beyond the video duration.

tbl.select(tbl.video.extract_frame(0.0)).collect()

tbl.select(tbl.video.extract_frame(tbl.video.get_metadata().streams[0].duration_seconds - 0.1)).collect()

​

get_duration() _udf

get_duration(video: Video)-> Optional[Float]

• video (Video): The video for which to get the duration.

• Optional[Float]: The duration in seconds, or None if the duration cannot be determined.

​

get_metadata() _udf

get_metadata(video: Video)-> Json

• video (Video): The video for which to get metadata.

• Json: A dict such as the following:

{
    'bit_exact': False,
    'bit_rate': 967260,
    'size': 2234371,
    'metadata': {
        'encoder': 'Lavf60.16.100',
        'major_brand': 'isom',
        'minor_version': '512',
        'compatible_brands': 'isomiso2avc1mp41',
    },
    'streams': [
        {
            'type': 'video',
            'width': 640,
            'height': 360,
            'frames': 462,
            'time_base': 1.0 / 12800,
            'duration': 236544,
            'duration_seconds': 236544.0 / 12800,
            'average_rate': 25.0,
            'base_rate': 25.0,
            'guessed_rate': 25.0,
            'metadata': {
                'language': 'und',
                'handler_name': 'L-SMASH Video Handler',
                'vendor_id': '[0][0][0][0]',
                'encoder': 'Lavc60.31.102 libx264',
            },
            'codec_context': {'name': 'h264', 'codec_tag': 'avc1', 'profile': 'High', 'pix_fmt': 'yuv420p'},
        }
    ],
}

tbl.select(tbl.video_col.get_metadata()).collect()

​

overlay_text() _udf

• ffmpeg needs to be installed and in PATH

overlay_text(
    video: Video,
    text: String,
    font: Optional[String],
    font_size: Int,
    color: String,
    opacity: Float,
    horizontal_align: String,
    horizontal_margin: Int,
    vertical_align: String,
    vertical_margin: Int,
    box: Bool,
    box_color: String,
    box_opacity: Float,
    box_border: Optional[Json]
)-> Video

• video (Video): Input video to overlay text on.
• text (String): The text string to overlay on the video.
• font (Optional[String]): Font family or path to font file. If None, uses the system default.
• font_size (Int): Size of the text in points.
• color (String): Text color (e.g., 'white', 'red', '#FF0000').
• opacity (Float): Text opacity from 0.0 (transparent) to 1.0 (opaque).
• horizontal_align (String): Horizontal text alignment ('left', 'center', 'right').
• horizontal_margin (Int): Horizontal margin in pixels from the alignment edge.
• vertical_align (String): Vertical text alignment ('top', 'center', 'bottom').
• vertical_margin (Int): Vertical margin in pixels from the alignment edge.
• box (Bool): Whether to draw a background box behind the text.
• box_color (String): Background box color as a string.
• box_opacity (Float): Background box opacity from 0.0 to 1.0.
• box_border (Optional[Json]): Padding around text in the box in pixels.
  • [10]: 10 pixels on all sides
  • [10, 20]: 10 pixels on top/bottom, 20 on left/right
  • [10, 20, 30]: 10 pixels on top, 20 on left/right, 30 on bottom
  • [10, 20, 30, 40]: 10 pixels on top, 20 on right, 30 on bottom, 40 on left

• Video: A new video with the text overlay applied.

tbl.select(tbl.video.overlay_text('Sample Text')).collect()

tbl.select(
    tbl.video.overlay_text(
        'Caption text',
        font_size=32,
        color='white',
        opacity=1.0,
        box=True,
        box_color='black',
        box_opacity=0.8,
        box_border=[6, 14],
        horizontal_margin=10,
        vertical_align='bottom',
        vertical_margin=70,
    )
).collect()

tbl.select(
    tbl.video.overlay_text(
        'Important Message',
        font_size=32,
        color='yellow',
        box=True,
        box_color='black',
        box_opacity=0.6,
        box_border=[20, 10],
    )
).collect()

​

segment_video() _udf

• ffmpeg needs to be installed and in PATH

segment_video(
    video: Video,
    duration: Float
)-> Json

• video (Video): Input video file to segment
• duration (Float): Approximate duration of each segment (in seconds).

• Json: List of file paths for the generated video segments.

tbl.select(segment_paths=tbl.video.segment_video(duration=60)).collect()

duration = tbl.video.get_duration()
tbl.select(segment_paths=tbl.video.segment_video(duration=duration / 2 + 1)).collect()

​

with_audio() _udf

• ffmpeg needs to be installed and in PATH

with_audio(
    video: Video,
    audio: Audio,
    video_start_time: Float,
    video_duration: Optional[Float],
    audio_start_time: Float,
    audio_duration: Optional[Float]
)-> Video

• video (Video): Input video.
• audio (Audio): Input audio.
• video_start_time (Float): Start time in the video input (in seconds).
• video_duration (Optional[Float]): Duration of video segment (in seconds). If None, uses the remainder of the video after video_start_time. video_duration determines the duration of the output video.
• audio_start_time (Float): Start time in the audio input (in seconds).
• audio_duration (Optional[Float]): Duration of audio segment (in seconds). If None, uses the remainder of the audio after audio_start_time. If the audio is longer than the output video, it will be truncated.

• Video: A new video file with the audio track added.

tbl.select(tbl.video.with_audio(tbl.music_track)).collect()

tbl.select(tbl.video.with_audio(tbl.music_track, video_start_time=5.0, audio_start_time=5.0)).collect()

tbl.select(
    tbl.video.with_audio(
        tbl.music_track, video_start_time=30.0, video_duration=10.0, audio_start_time=15.0, audio_duration=10.0
    )
).collect()