3 Video API

8.13.0.9

3 Video API🔗ℹ

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>

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 x
y
width
height)
[ #:top top
#:bottom bottom
#:properties properties])
→ (or/c merge? field-element?)
  x : (between/c 0 1)
  y : (between/c 0 1)
  width : (between/c 0 1)
  height : (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 x and y coordinates specify the top-left point of overlayed image. 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.

The width and height coordinates specify the width and height of the overlayed image, either in pixels or a ratio.

3.5 Bundled Filters🔗ℹ

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-v0-2

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?

1	Installing
2	Getting Started
3	Video API
4	Player
5	Rendering
6	Graphical Non-Linear Video Editors
7	Core Library
8	Extending Video
	Index

3.1	Bundled Producers
3.2	Video Compositing
3.3	Bundled Transitions
3.4	Bundled Merges
3.5	Bundled Filters
3.6	Properties
3.7	Misc. Functions
3.8	Alternate Units