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:

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")

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))

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:

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

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.

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:

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:

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.

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:

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.