On this page:
3.1 Bundled Producers
blank
color
clip
3.2 Video Compositing
playlist
multitrack
field-element?
attach-filter
cut-producer
3.3 Bundled Transitions
fade-transition
L-cut
J-cut
3.4 Bundled Merges
overlay-merge
composite-merge
3.5 Bundled Filters
volume-filter
lowpass-filter
highpass-filter
compand-filter
remove-video
remove-audio
grayscale-filter
sepia-filter
color-channel-mixer-filter
transpose-filter
rotate-filter
envelope-filter
mux-filter
scale-filter
pad-filter
crop-filter
3.6 Properties
get-property
set-property
remove-property
3.7 Misc. Functions
external-video
chapter
3.8 Alternate Units
pixel
seconds
7.8

3 Video API

 (require video/base) package: video

Functions that are deprecated and will be removed or altered in a backwards compatible breaking way are marked as deprecated with a yellow NOTE label.

3.1 Bundled Producers

procedure

(blank [length    
  #:properties properties    
  #:filters filters])  producer?
  length : (or/c integer? #f) = #f
  properties : (hash/c string? any/c) = (hash)
  filters : (listof filter?) = '()
Creates a blank producer of length clips.

If length is #f, then the producer generates as many blank frames as its surrounding multitrack requires.

Examples:
> (blank)

#<producer>

> (blank 10)

#<producer>

procedure

(color color    
  [c2    
  c3    
  #:length length    
  #:properties properties    
  #:filters filters])  producer?
  color : 
(or/c string?
      (is-a?/c color%)
      (list/c byte? byte? byte?)
      byte?)
  c2 : (or/c byte? #f) = #f
  c3 : (or/c byte? #f) = #f
  length : (or/c nonnegative-integer? #f) = #f
  properties : (hash/c string? any/c) = (hash)
  filters : (listof filter?) = '()
Creates a producer that is a solid color.

The given color can be a string from color-database<%>, a color% object, a list of three bytes, or thee seperate bytes.

If a byte is given for color, then c2 and c3 must also contain a byte. Otherwise c2 and c3 must be #f.

If provided, length is syntactic sugar for the "length" value in the properties table. It determines a length for the given color.

Examples:
> (color "green")

#<producer>

> (color "yellow" #:properties (hash "length" 10))

#<producer>

> (color 255 255 0)

#<producer>

procedure

(clip file    
  [#:start start    
  #:end end    
  #:length length    
  #:properties properties    
  #:filters filters])  producer?
  file : (or/c path-string? path?)
  start : (or/c nonnegative-integer? #f) = #f
  end : (or/c nonnegative-integer? #f) = #f
  length : (or/c nonnegative-integer? #f) = #f
  properties : (hash/c string? any/c) = (hash)
  filters : (listof filter?) = '()
Creates a producer from a video or image file. The start, end, length arguments are (if provided), are syntactic sugar to set the "start", "end", or "length" values in the properties table.

Examples:
> (clip "groovy.mp4")

#<file>

> (clip "fancy.png")

#<file>

3.2 Video Compositing

procedure

(playlist producer    
  ...    
  [#:transitions transitions    
  #:properties properties])  producer?
  producer : (or/c producer? transition?)
  transitions : (listof field-element?) = '()
  properties : (dictof string? any/c) = (hash)
Creates a playlist out of the given producers. The first and last element of the list must be producers. Additionally, no two transitions can appear without a producer in between them.

Examples:
> (playlist)

#<playlist>

> (playlist (color "blue"))

#<playlist>

> (playlist (color "green" #:properties (hash "length" 10))
            (fade-transition 42)
            (clip "movie.mp4"))

#<playlist>

procedure

(multitrack producer    
  ...    
  [#:transitions transitions    
  #:properties properties])  producer?
  producer : (or/c producer? merge?)
  transitions : (listof field-element?) = '()
  properties : (dictof string? any/c) = (hash)
Creates a multitrack. This form is syntactically similar to playlist, but the result renders clips in parallel rather than sequentially. Additionally, multitracks contain merges instead of transitions.

As with playlist, the first and last elements must be producers, and no two merges can appear without a producer between them.

Examples:
> (multitrack)

#<multitrack>

> (multitrack (clip "hyper.mp4"))

#<multitrack>

> (multitrack (color "black")
              (overlay-merge 10 10 50 50)
              (clip "space.mp4"))

#<multitrack>

procedure

(field-element? elem)  boolean?

  elem : any/c
Returns #t if elem is a field element, returns #f otherwise.

Field elements are an extension to either a transition or a merge. It stipulates the two tracks it should be attached to. This enables the element to be added to the playlist’s #:transitions list, or the multitrack’s #:merges list.

Field elements are not constructed directly. Rather, they are created as part of transition and merge construction.

procedure

(attach-filter producer filter ...)  producer?

  producer : producer?
  filter : filter?
Attach a new filter to an existing producer. Unlike the #:filters keyword, this procedure will create a new producer identical to the old one, but with a filter attached to it.

Examples:
> (attach-filter (clip "dance.wmv")
                 (grayscale-filter))

#<file>

> (let ()
    (define auto (clip "driving.mov"))
    (attach-filter auto
                   (sepia-filter)))

#<file>

procedure

(cut-producer producer    
  [#:start start    
  #:end end])  producer?
  producer : producer?
  start : (or/c nonnegative-integer? #f) = #f
  end : (or/c nonnegative-integer? #f) = #f
Create a producer identical to producer, but trimmed based on #:start and #:end.

NOTE: This function is deprecated; use set-property, instead. This function may be removed or moved to a convenience library.

3.3 Bundled Transitions

procedure

(fade-transition length 
  [#:start start 
  #:end end 
  #:properties properties]) 
  (or/c transition? field-element?)
  length : nonnegative-integer?
  start : (or/c any/c #f) = #f
  end : (or/c any/c #f) = #f
  properties : (hash/c string? any/c) = (hash)
A simple transition that creates a fade effect from one clip to the next.

length specifies how long the transition should last, in terms of seconds. Remember that length seconds get removed from both producers, making the total playlist length seconds shorter.

Example:
> (playlist
   (clip "splash.png" #:properties (hash "length" 15))
   (fade-transition 5)
   (clip "intro.mp4"))

#<playlist>

procedure

(L-cut delay 
  [#:start start 
  #:end end 
  #:properties properties]) 
  (or/c transition? field-element?)
  delay : nonnegative-integer?
  start : (or/c any/c #f) = #f
  end : (or/c any/c #f) = #f
  properties : (hash/c string? any/c) = (hash)
A transition between two clips, where the audio of the first clip continues for delay seconds into the video of the second clip. (The result looks like an “L” in a traditional NLVE.)

The length of the resulting clip is the length of the two other clips minus delay seconds.

See J-cut

Added in version 0.2.2 of package video.

procedure

(J-cut delay 
  [#:start start 
  #:end end 
  #:properties properties]) 
  (or/c transition? field-element?)
  delay : nonnegative-integer?
  start : (or/c any/c #f) = #f
  end : (or/c any/c #f) = #f
  properties : (hash/c string? any/c) = (hash)
A transition between two clips, where the video of the first clip continues for delay seconds into the audio of the second clip. (The result looks like a J in a traditional NLVE.)

The length of the resulting clip is the length of the two other clips minus delay seconds.

See L-cut.

Added in version 0.2.2 of package video.

3.4 Bundled Merges

procedure

(overlay-merge x 
  y 
  width 
  height 
  [#:top top 
  #:bottom bottom 
  #:properties properties]) 
  (or/c merge? field-element?)
  x : number?
  y : number?
  width : number?
  height : number?
  top : (or/c any/c #f) = #f
  bottom : (or/c any/c #f) = #f
  properties : (hash/c string? any/c) = (hash)
Overlays one clip on top of another. The x and y coordinates specify the top-left corner of the image, while width and height describe how the image should be scaled.

x, y, width, and height are all specified in pixels.

Example:
> (multitrack
   (clip "presentation.ogv")
   (overlay-merge 0 0 100 100)
   (clip "logo.png"))

#<multitrack>

procedure

(composite-merge x1 
  y1 
  x2 
  y2 
  [#:top top 
  #:bottom bottom 
  #:properties properties]) 
  (or/c merge? field-element?)
  x1 : (between/c 0 1)
  y1 : (between/c 0 1)
  x2 : (between/c 0 1)
  y2 : (between/c 0 1)
  top : (or/c any/c #f) = #f
  bottom : (or/c any/c #f) = #f
  properties : (hash/c string? any/c) = (hash)
The x1 and y1 coordinates specify the top-left point of overlayed image, and the x1 and y1 coordinates specify the bottom-right point.

If a pixel? struct is provided then the point is in terms of pixels, otherwise the point is a number between 0 and 1, 0 being top-left, and 1 being bottom-right.

For example putting an inner clip half the size in the middle of the screen can be done with:
(multitrack
  (blank #f)
  (composite-merge 1/4 1/4 3/4 3/4)
  (clip "inner.mp4"))

3.5 Bundled Filters

procedure

(volume-filter volume    
  [#:precision precision    
  #:replaygain replaygain    
  #:replaygain-preamp replaygain-preamp])  filter?
  volume : (and/c real? (>=/c real?))
  precision : (or/c 'fixed 'float 'double #f) = #f
  replaygain : (or/c 'drop 'ignore 'track 'album #f) = #f
  replaygain-preamp : (or/c real? #f) = #f
Sets the volume of the audio track, leaving video track unaffected. The unchanged volume for the track is 1. When volume is less than 1 result in a quieter track, while values more than 1 result in a louder one.

The precision determines the sample precision used for the increase.

The replaygain and replaygain-preamp are options. They only affect the audio if the track has external ReplayGain metadata.

Added in version 0.2.2 of package video.

procedure

(lowpass-filter [#:frequency frequency    
  #:poles poles    
  #:width width    
  #:width-type width-type    
  #:channels channels])  filter?
  frequency : (or/c nonnegative-integer? #f) = #f
  poles : (or/c nonnegative-integer? #f) = #f
  width : (or/c nonnegative-integer? #f) = #f
  width-type : (or/c 'h 'q 'o 's 'k) = h
  channels : #f = #f
Creates a lowpass filter at frequency with poles and width.

The width type can be specified in Hz ('h, Q-factor ('Q), octave ('o), slope ('s), or KHz ('k).

Added in version 0.2.1 of package video.

procedure

(highpass-filter [#:frequency frequency    
  #:poles poles    
  #:width width    
  #:width-type width-type    
  #:channels channels])  filter?
  frequency : (or/c nonnegative-integer? #f) = #f
  poles : (or/c nonnegative-integer? #f) = #f
  width : (or/c nonnegative-integer? #f) = #f
  width-type : (or/c 'h 'q 'o 's 'k) = h
  channels : #f = #f
Creates a highpass filter at frequency with poles and width.

The width type can be specified in Hz ('h, Q-factor ('Q), octave ('o), slope ('s), or KHz ('k).

Added in version 0.2.1 of package video.

procedure

(compand-filter [#:attacks attacks    
  #:decays decays    
  #:points points    
  #:soft-knee soft-knee    
  #:gain gain    
  #:volume volume    
  #:delay delay])  filter?
  attacks : (listof real?) = '()
  decays : (listof real?) = '()
  points : 
(listof (or/c (cons/c real? real?)
                              complex?))
 = '()
  soft-knee : (or/c real? #f) = #f
  gain : (or/c real? #f) = #f
  volume : (or/c real? #f) = #f
  delay : (or/c real? #f) = #f

Added in version 0.2.1 of package video.

procedure

(remove-video)  filter?

Added in version 0.2.2 of package video.

procedure

(remove-audio)  filter?

Added in version 0.2.2 of package video.

procedure

(grayscale-filter)  filter?

A video producer that attaches this filter will become grayscale.

Example:
> (clip "action.wmv"
        #:filters (list (grayscale-filter)))

#<file>

procedure

(sepia-filter)  filter?

Similar to grayscale-filter, but turns the producer emulate a sepia color instead.

procedure

(color-channel-mixer-filter table)  filter?

  table : (hash/c string? (between/c -2 2))
A more general version of grayscale-filter and sepia-filter. Converts the color based on a matrix encoded in table.

The keys in the table are strings with two characters, where both the first and second characters are either #\r, #\g, #\b, or #\a. The first character encodes the value of the source channel that is fed into the output as encoded by the second character.

For example, the following matrix encodes the grayscale-filter listed above:

(color-channel-mixer-filter (hash "rr" 0.3 "rg" 0.4 "rb" 0.3 "ra" 0
                                  "gr" 0.3 "gg" 0.4 "gb" 0.3 "ga" 0
                                  "br" 0.4 "bg" 0.4 "bb" 0.3 "ba" 0
                                  "ar" 0   "ag" 0   "ab" 0   "aa" 0))

procedure

(transpose-filter [direction flip])  filter?

  direction : 
(or/c 'clock
      'counter-clock
      #f)
 = #f
  flip : boolean? = #f
Transpose the video, either clockwise or counter clockwise, possibly with a flip.

direction sets the direction for the transpose, clock for a 90 degree clockwise transpose or counter-clock for a -90 degree transpose. If not provided (or #f) it defaults to counterclockwise.

Set flip to #t to additionally flip the video as well as rotate it.

procedure

(rotate-filter angle    
  [#:bilinear? bilinear?    
  #:fill-color color])  filter?
  angle : real?
  bilinear? : boolean? = #t
  color : 
(or/c string?
      (is-a?/c color%)
      (list/c byte? byte? byte?))
 = "black"
This filter rotates its producer by angle radians.

The bilinear? flag determines if the filter should do bilinear interpolation. It defaults to #t.

The #:fill-color sets the color that should surround the resulting rotates producer. It defaults to "black".

procedure

(envelope-filter #:length length    
  #:direction direction    
  [#:curve curve])  filter?
  length : nonnegative-integer?
  direction : (or/c 'in 'out)
  curve : (or/c #f) = #f
An audio filter that provides a fade in or out effect.

The direction is determined by direction, and can be either 'in or 'out.

The length of the enveloping effect is determined by length.

An optional curve argument can set the curve of the filter. However at the moment the only valid value for the curve is #f.

procedure

(mux-filter #:type type #:index index)  filter?

  type : (or/c 'v 'video 'a 'audio)
  index : exact-nonnegative-integer?
A filter that returns a single stream from a multistream producer. This is mostly useful for files with multiple streams. Often produced by live broadcasting devices

Note that audio channels and audio streams are different. One stream can contain multiple channels.

procedure

(scale-filter width height)  filter?

  width : (and/c real? positive?)
  height : (and/c real? positive?)
A video filter that scales the given video by height and width.

height is the desired height of the output video in pixels.

width is the desired width of the output video in pixels.

Example:
> (attach-filter (clip "action.mp4")
                 (scale-filter 200 100))

#<file>

procedure

(pad-filter x y width height)  filter?

  x : (and/c real? positive?)
  y : (and/c real? positive?)
  width : (and/c real? positive?)
  height : (and/c real? positive?)
Similar to scale-filter, except adds black padding to meet the output size, rather than resizing the video itself. The resulting video must not be smaller than the source video.

x and y control where the source image are placed in the output, while width and height control the size of the output image.

x, y, width, and height are all in terms of pixels.

procedure

(crop-filter x y width height)  filter?

  x : (and/c real? positive?)
  y : (and/c real? positive?)
  width : (and/c real? positive?)
  height : (and/c real? positive?)
Similar to scale-filter, but trims the edges to fit the output size.

x and y control where the source image are placed in the output, while width and height control the size of the output image.

x, y, width, and height are all in terms of pixels.

3.6 Properties

Each producer has a table of properties attached to it. These tables contain both values given to it with the #:prop keyword when the producer is created, and innate properties based on the producer type. Different producers will have different types of innate properties, but some common ones are: "length", "width", and "height".

procedure

(get-property producer key [fail-thunk])  any/c

  producer : properties?
  key : string?
  fail-thunk : (-> any/c) = (λ () (error ...))
Gets the attached property associated with producer. Similar to dict-get.

If an explicit property was given for key to the producer when it is created, that is returned first.

If no explicit property was given for key, then it searches for an innate property.

If no explicit or innate property is associated with the producer, then fail-thunk is called. By default, fail-thunk throws an error.

Examples:
> (get-property (color "blue")
                "length")

+inf.0

> (get-property (color "green")
                "not-a-property")

get-property: Key not found: not-a-property

procedure

(set-property producer key value)  producer?

  producer : properties?
  key : string?
  value : any/c
Functionally sets the property key to value in producer. The original video remains unmodified, and a new one is returned with the value.

Similar to dict-set.

procedure

(remove-property producer key)  producer?

  producer : properties?
  key : string?
Removes an explicit property key stored in producer. This will not remove any implicitly stored properties. If an explicit property is shadowing the implicit one, the value changes to the implicit one.

Similar to dict-remove.

3.7 Misc. Functions

syntax

(external-video module)

Given a module path to a video file, dynamically require that file, and place its vid values in place of external-video.

procedure

(chapter producer)  producer

  producer : producer?
Creates a new producer identical to producer, except the resulting producer will be added to the chapters list of the rendered video.

3.8 Alternate Units

 (require video/units) package: video

NOTE This module is still highly experimental. The API WILL break.

The units API attempts to allow authors to describe videos in natural units, rather than arbitrary machine units. At the moment, this API should not be used because no math operations work with them.

struct

(struct pixel (value)
    #:extra-constructor-name make-pixel)
  value : nonnegative-integer?

struct

(struct seconds (value)
    #:extra-constructor-name make-seconds)
  value : number?