On this page:
2.1 Video Basics
2.2 Filters
2.3 Playlists
2.4 Transitions
2.5 Multitracks and Merges
2.6 Video Properties
2.7 Command Line Interaction
7.8

2 Getting Started

Video Language (or just Video) is a functional-declarative language for manipulating videos from many input sources: images, video files, even live streams.

The video module is a language and includes all of the bindings in racket. Users that want to use Video as an API embedded in other languages can use the video/base module instead.

2.1 Video Basics

Rather than evaluating programs for their effects, expressions in Video combine to describe a single video stream. Thus, Video allows authors to write videos in a similar fashion to how LaTeX enables authors to write documents.

All VidLang programs begin with #lang video, the remaining program is a description of the resulting video. Each top level expression is a producer which is anything that produces a video stream. For example, the color producer generates a stream of green frames:

#lang video ; green.vid
(color "green")

When the module above is converted into a video, the output looks something like:

image

This picture also shows an example of playback controls. These are shown whenever previewing a video. The easiest way to preview a video is to press the Preview Video button in the DrRacket toolbar. Alternatively, the raco video tool can also preview videos. For example, say the above video was saved as "green.vid", then the preview can be ran with:

raco video --preview green.vid

Note that simply running a program is not enough to render a video. Every Video programs describes a single vid data structure. Thus, a renderer (or streamer) can prepare the Video in many different formats. Additionally, Video programs can include the vid structure from other programs. Evaluating vid in DrRacket’s REPL after running the module shows the resulting structure:

Example:
> vid

#<playlist>

The color function creates an infinitely long producer. The producer’s length can optionally be set explicitly with its properties. If the length is not set, the producers length will automatically set itself to fit the surrounding context. Another function, clip does create a producer from a file:

#lang video
(clip "spinning_square.mp4")

image

Like color, clips can also set their length with properties

#lang video
(clip "spinning_square.mp4"
      #:start 2
      #:end 8)

The clip function uses optional keywords for #:start and #:end. These are syntactic sugar for the properties table directly:

#lang video
(clip "spinnin_square.mp4"
      #:properties (hash "start" 2 "end" 8))

image

2.2 Filters

Filters can be attached to every producer. These filters modify the producers behavior: turning it grayscale, changing the aspect ratio, etc. The attach-filter function attaches filters to an existing producer. For example, we can use the grayscale-filter to remove the color from the rotating square clip earlier:

#lang video
(attach-filter (clip "spinning_square.mp4")
               (grayscale-filter))

image

An alternative approach would be to use the #:filters keyword associated with producers.

#lang video
(clip "spinning_square.mp4"
      #:filters (list (grayscale-filter)))

image

2.3 Playlists

Video shines when combining multiple producers. The language provides two ways of combining producers, playlists and multitracks. To a first approximation, playlists run producers sequentially, while multitracks play them simultaneously.

Every Video module is implicitly a playlist. Alternatively, playlists can be created with the playlist function.

#lang video
(clip "spinning_square.mp4"
      #:start 0 #:end 4)
(clip "spinning_square.mp4"
      #:properties (hash "start" 0 "end" 4)
      #:filters (list (grayscale-filter)))

image

#lang video
(playlist
 (clip "spinning_square.mp4"
       #:properties (hash "start" 0 "end" 4))
 (clip "spinning_square.mp4"
       #:properties (hash "start" 0 "end" 4)
       #:filters (list (grayscale-filter))))

image

Playlists are themselves producers. As such, the playlist function also serves to append multiple playlists together. This example combines the playlist from above with another similar clip of a ball dropping:

#lang video
square-movie
ball-movie
(define square-movie
  (playlist
   (clip "spinning_square.mp4"
         #:properties (hash "start" 0 "end" 2))
   (clip "spinning_square.mp4"
         #:properties (hash "start" 2 "end" 4)
         #:filters (list (grayscale-filter)))))
(define ball-movie
  (playlist
   (clip "ball_drop.mp4"
         #:properties (hash "start" 0 "end" 2))
   (clip "ball_drop.mp4"
         #:properties (hash "start" 2 "end" 4)
         #:filters (list (grayscale-filter)))))

image

This clip also introduces define in Video. Unlike many other racket-based languages, module level variables are defined for the whole module, not just after their definition.

This is also true of functions created with λ/video and define/video. But this feature is experimental.

2.4 Transitions

Transitions determine how one clip transitions into another clip in a playlist. For example, a transition can create a fading or swiping effect from one clip to another.

Transitions can be placed directly in a playlist, and combine the producers directly before and after them:

#lang video
(clip "ball_drop.mp4"
      #:properties (hash "start" 0 "end" 5))
(fade-transition 2)
(clip "ball_drop.mp4"
      #:properties (hash "start" 5 "end" 10)
      #:filters (list (grayscale-filter)))

image

Alternatively, transitions can be attached with the #:transitions keyword. This parameter takes a list of transitions that use #:start and #:end to specify what producers it connects:

#lang video
(define colored
  (clip "ball_drop.mp4"
        #:properties (hash "start" 0 "end" 5)))
(define black+white
  (clip "ball_drop.mp4"
        #:properties (hash "start" 5 "end" 10)
        #:filters (list (grayscale-filter))))
(playlist
 colored
 black+white
 #:transitions (list (fade-transition 2
                                      #:start colored
                                      #:end black+white)))

Transitions themselves are not producers, but server to combine producers in a playlist. However, properties can still be attached to a transition.

2.5 Multitracks and Merges

Multitracks play multiple producer simultaneously. Unlike in a playlist, only the top most track will be rendered. Merges combine different tracks in a multitrack. These can be anything from a video overlay, to a chroma key effect. As with transitions in playlists, composite merges can be inlined with the producers in the multitrack’s.

#lang video
(multitrack
 (blank #f)
 (composite-merge 0 0 1/2 1)
 (clip "spinning_square.mp4")
 (composite-merge 1/2 0 1/2 1)
 (clip "dropping_ball.mp4"))

image

Merges can also be listed separately with the #:merges keyword. This keyword takes a list of merges that specify their associated tracks with the #:top and #:bottom keywords:

#lang video
(multitrack
 bg
 spinning-square
 dropping-ball
 #:merges (list (composite-merge 0 0 1/2 1
                                 #:top spinning-square
                                 #:bottom bg)
                     (composite-merge 1/2 0 1/2 1
                                      #:top dropping-ball
                                      #:bottom bg)))
(define bg (blank #f))
(define spinning-square (clip "spinning_square.mp4"))
(define dropping-ball (clip "dropping_ball.mp4"))

image

2.6 Video Properties

Every video object contains a set of run-time properties, which are a hash mapping s to any value. They can be set with the #:properties keyword and retrieved with the get-property function:

#lang video
(define the-ultimate-color
  (color "green"
         #:properties (hash "the-ultimate-property" 42)))
(get-property the-ultimate-color
              "the-ultimate-property") ; => 42

Some properties are implicitly associated with an object by the Video runtime. Such as the width and height of an image, or the length of a clip. For example, the following module will play the first half of the "epic.mp4" movie.

2.7 Command Line Interaction

The raco video tool is the most simple way to render video files. To get a list of its current set of features, run:

raco video --help

By default, raco video will render your file to a pre-specified format. You can also open up a preview window playing the program with the --preview flag.