3 Video API
(require video/base) | package: video-unstable |
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?) = '()
If length is #f, then the producer generates as many blank frames as its surrounding multitrack requires.
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?) = '()
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.
> (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?) = '()
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)
> (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)
As with playlist, the first and last elements must be producers, and no two merges can appear without a producer between them.
> (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
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-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
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)
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.
> (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)
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-unstable.
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)
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-unstable.
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)
x, y, width, and height are all specified in pixels.
> (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)
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.
(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
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-unstable.
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
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-unstable.
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
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-unstable.
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-unstable.
procedure
(remove-video) → filter?
Added in version 0.2.2 of package video-unstable.
procedure
(remove-audio) → filter?
Added in version 0.2.2 of package video-unstable.
procedure
> (clip "action.wmv" #:filters (list (grayscale-filter))) #<file>
procedure
(sepia-filter) → filter?
procedure
(color-channel-mixer-filter table) → filter?
table : (hash/c string? (between/c -2 2))
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
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"
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
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?
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?)
height is the desired height of the output video in pixels.
width is the desired width of the output video in pixels.
> (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?)
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?)
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 ...))
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.
> (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
Similar to dict-set.
procedure
(remove-property producer key) → producer?
producer : properties? key : string?
Similar to dict-remove.
3.7 Misc. Functions
syntax
(external-video module)
3.8 Alternate Units
(require video/units) | package: video-unstable |
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?