diascope: actions

General action syntax

Diascope knows eight actions: fadein, fadeout, crop, blur, unblur, kbrn, sequ, and create. The first five of these act on single images, the fifth on existing frame sequences, and the last one creates coloured frames. The syntax of all actions follows the general pattern

<action> <duration> <image> <crop spec> [options] [title|image spec]


action = fadein | fadeout | crop | blur | unblur | kbrn | create
duration = t_act | t_hold,t_act | t_hold,t_act,t_hold
image = filename | colour
crop spec = xyw=X,Y,W [xyw=X,Y,W [...]]
options = opt1[=val1] [opt2[=val2] [...]]
title spec = title=<tduration> [dir=<dir>] <"Text"|@textfile>
image spec = image=<tduration> [dir=<dir>] <@imagefile>
tduration = t_title | t_fadein,t_title | t_fadein,t_title,t_fadeout | t_delay,t_fadein,t_title,t_fadeout
dir = none|rl|lr|td|tm|mt|bu|bm|mb

For the duration, t_act is the time the action itself should take, and t_hold specifies the time during which the first and/or the last frame are held still.

For the title duration, t_title is the time during which the title is displayed. If specified, t_fadein and t_fadeout specify fade times for the title and t_delay is a delay from the start of the action before the title appears. In the optional dir argument the letter pairs describe the direction into which the title or image overlay slides: rl=right-left, lr=left-right, td=top-down, bu=bottom-up. In the combinations with m (tm,mt,bm,mb) the start or end point is the middle of the screen. The default case is "none" in which case the title is static, i.e. it does not slide. See the title settings and the title examples for further customisation.

An xyw=X,Y,W crop specification gives the top left corner X,Y and the width W of the area of an image to be viewed. Note that the height is calculated internally as 3/4 W. One crop specification can be given for the fadein, fadeout, crop, blur, unblur and sequ actions. More than one crop specifications can be given for the kbrn action. If left out, the full image is the default crop spec. As of diascope 0.1.2 percentages are allowed for the entries, i.e. xyw=x%,y%,w%. Combinations of absolute and percentage values are also possible.

All options are provided either as single key words or in a key=value format. The general options are


If redo is given diascope will forcibly recalculate this action during the following run even if the action hasn't been modified. Under normal circumstances you shouldn't need this option.
Mirror will mirror the image after cropping it, i.e. the crop specification refers to the unmirrored image.
Rotate rotates the image by an angle x (in degrees) before cropping it, i.e. the crop specification refers to the rotated image. If you find this inconsistent you're perhaps right.

See below for the action specific options.

Back to top

Fadein / fadeout

Fade in or fade out an image from or into a colour.


fadein  <duration> <image> [crop spec] [options]
fadeout <duration> <image> [crop spec] [options]


View example
Back to top


Crop an area from an image.


crop <duration> <image> [crop spec]
View example
Back to top

Blur / unblur

Blur in an image, or blur out an image.


blur   <duration> <image> [crop spec] [options]
unblur <duration> <image> [crop spec] [options]



Blur dynamically blurs the image starting from the original image to one which is blurred by the maximum radius X. The radius is measured relative to the size of the image. The default is rad=0.1 which corresponds to 10% of the image width. The larger the radius the slower the blurring operation. Unblur does the reverse operation.

This is really one of the less useful actions that diascope provides.

View example
Back to top

Pan and zoom ("Ken Burns effect")

Pan and zoom between specified crop areas.

If only one crop spec is given diascope will start from there and zoom out to the full image. If two crop specs are given then a linear pan and zoom is performed. If more than two crop specs are given then the pan is performed along an interpolating cubic spline path. Although not necessary, some understanding of the characteristic behaviour of splines may be useful to prevent undesired oscillating paths.


kbrn <duration> <image> <crop spec> [<crop spec> [...]] [options]


accel=X       # useful values are X = 1 .. 100
over=Y        # useful values are Y = 1 .. 3

As of Diascope 0.2 path plots are generated for each pan and zoom to visualise the chosen path. See here for an example.

The speed at which the pan is carried out can be influenced by the "accel" option. A value of 0.01 gives essentially constant speed, a value of 50 yields a pan that initially accelerates and finally decelerates strongly

Diascope scales the image such that the minimum pixel width during the pan is equal to the output frame width (i.e. 720 pixel for PAL or NTSC) to avoid a jerky pan. Under some circumstances, such as with a high "accel" value, this is not sufficient for a smooth effect. In this case the picture can be oversampled using the option "over".

Note that the resize setting changes the way diascope scales kbrn frames. In difficult cases you may need to "set resize=resize" to prevent a wobbly pan and zoom, however, the rendering time will increase.

View example
Back to top


Import a sequence of externally prepared frames.


sequ <duration> <pattern> [crop spec] start=X end=Y

Pattern is a format string that contains a "%0nd" for sprintf to write to, i.e. for example image%04d.jpg. Start and end provide the integer range that identifies the images of the sequence. If the number of frames required to play for the requested duration is not equal to end-start then diascope will duplicate or drop frames in its sole discretion.

Note that the resize setting changes the way diascope scales sequ frames. In difficult cases you may need to "set resize=resize" to improve the quality, however, the rendering time will increase.

View example
Back to top


Create frames of a colour or a vertical gradient.


create <duration> <colour>
create <duration> <colour1-colour2>
View example
Back to top