PicShow Documentation
Description
PicShow generates video streams from JPEG images with animated zooming and scaling (»Ken Burns effect«) and smooth wipe transitions.
PicShow does not deal with audio and it does not generate multiplexed audio/video system streams. The output will always be an Elementary Stream, containing video only.
Command Line Parameters
All command-line options are long options and may be prefixed with either one or two dashes (-, --). Arguments must be separated from commands by using whitespace, GNU getopt-style syntax (like »-opt=arg«) is not allowed.
General options
-h or -help- Displays a help screen and exits.
-version- Displays the program's name and version number and exists.
-c <file> or -cfg <file> or -config <file> or -include <file>- Reads further options from an external configuration file.
A configuration file is a text file that can contain any number of options and arguments, separated from each other by any amount of whitespace or line breaks. If a line contains a hash mark (#), it will be ignored together with the remainder of that line. Arguments that contain whitespace or hash marks must be enclosed in either single or double quotes. Arguments that contain single quotes must be enclosed in double quotes and vice-versa. (Note that there's currently no way to have arguments that contain both types of quotes.)
The options loaded from the file are parsed as if they were specified on the command line at the position of the -c option.
Configuration files can again include other configuation files, but they must not include themselves, neither directly nor indirectly.
-v or -verbose- Enables verbose mode. This will output a slide summary and detailed encoder setup information on the console.
-q or -quiet- Enables quiet mode. In this mode, as many status output as possible will be suppressed. In particular, no progress indicator will be shown.
-silent or -really-quiet- Enables silent mode. In this mode, PicShow will generate no output on the console at all, unless errors occur.
Note that currently, quiet mode and silent mode are identical, i.e. quiet mode will already lead to completely silent operation.
Output options
-o <file> or -output <file>- Specifies the output stream file name. If this option is not specified, no output will be generated.
-preview and -no-preview- Enables or disables the preview window (default: disabled). This window shows the generated frames prior to encoding and can be used to monitor the rendering process or to verify that everything looks correct.
-full-size and -half-size- Specifies the preview window size.
-full-size will set up the preview window so that it has the same dimensions as the output frame, while -half-size will display a preview window with exactly half the number of pixels horizontally and vertically. If neither of these options is present, SD resolutions will be displayed in full size and HD resolutions will be displayed with half size. If the preview window is disabled, these options are ignored.
-lq or -draft- Enables fast, low-quality, unfiltered scaling. Image quality will be very bad, but the processing speed will be much higher. This option is only useful for preview purposes.
-hq or -no-lq- Enables slower, high-quality, filtered scaling (the default).
-rt and -realtime- Enables real-time mode. In this mode, PicShow will not render the output at a fixed framerate. Instead, it will run in realtime at whatever framerate the computer is capable of handling. This is only useful in preview mode; in fact, if real-time mode is used together with normal video file encoding, the encoded file will be unusable because the framerate will be completely wrong and, above all, not constant.
-no-rt and -no-realtime- Disables real-time mode. This is the default setting.
-rt-preview- Enables real-time mode and preview at once. This is equivalent to specifying both
-rt and -preview.
-size <width>x<height> or -res <width>x<height>- Specifies the output video size in pixels (default: 640x480).
-aspect <width>:<height> and -aspect <num>/<den>- Specifies the aspect ratio of the output. This option is necessary to produce anamorphic video.
If the argument is specifed as a fraction of two integers separated by a colon (:), it is interpreted as the desired display aspect ratio (DAR). Common values for this are 4:3 or 16:9.
If the argument is specifed as a fraction of two integers separated by a slash (/), it is interpreted as the desired sample (or pixel) aspect ratio (SAR or PAR). Values greater than one mean wide pixels, values lower than one mean tall pixels. The default value is one (1/1), meaning that square pixels are assumed.
-fps <framerate> or -fps <num>/<den>- Specifies the frame rate of the output (default: 25 fps). If the argument is a integer number (without decimal dots), it will be interpreted as the frame rate directly. If the argument is a decimal fraction, it is assumed to be a multiple of 1/1001. Common examples for this are 23.976 (NTSC film with 3:2 pulldown), 29.97 (NTSC frame rate) and 59.94 (NTSC field rate). Alternatively, the frame rate can be specified as a fraction of two integers separated by a slash (
/).
-enc <encoder> or -encoder <encoder>- Specifies the type of video encoder to use. The following encoder types are defined:
auto- auto-detect the encoder type based on the extension of the output file name (default)
yuv or raw- raw 8-bit planar 4:2:0 YCbCr dumps
the chroma sample locations are the same as in MPEG-2 (centered vertically, co-sited horizontally)
yuv4mpeg or y4m- YUV4MPEG2 format as used by mjpegtools
mpeg2 or ffmpeg2- MPEG-2 encoding using FFmpeg's libavcodec
mpeg4 or ffmpeg4- MPEG-4 SP/ASP encoding using FFmpeg's libavcodec
xvid- MPEG-4 SP/ASP encoding using the XviD encoder
x264- H.264 (MPEG-4 AVC) encoding using the x264 encoder
Note that depending on your build configuration, not all of the aforementioned encoders may be available; only the raw YUV and YUV4MPEG2 encoders are guaranteed to be available in any case.
Also note that for the raw YUV and YUV4MPEG2 encoders, all other encoding options except interlaced encoding and the color space option are ignored.
-cbr <bitrate> or -bitrate <bitrate>- Enables constant bitrate (CBR) encoding with a specified bitrate in bits per second. SI suffixes and decimal fractions can be used for the bitrate specification, e.g.
4.5M is equal to 4500000.
-abr <bitrate>- Enables average bitrate (ABR) encoding with a specified bitrate in bits per second. SI suffixes and decimal fractions can be used for the bitrate specification, e.g.
4.5M is equal to 4500000.
ABR encoding means that the specified bitrate is only a loose target and the decoder may use more or less bits per second, based on scene complexity. Not every encoder supports this mode. If this mode is unsupported by an encoder, CBR mode will be used instead.
-cqp <qp> or -quantizer <qp>- Enables constant quantizer (CQP) encoding with a specified quantization parameter (QP) value. Note that the range and meaning of the QP value is dependent on the type of encoder used.
-crf <qp>- Enables constant rate factor (CRF) encoding with a specified target quantization parameter (QP) value. In this mode, the specified QP is just a coarse target; the encoder may be reduce or increase the QP dependent on image features.
Not every encoder supports this mode. If this mode is unsupported by an encoder, CQP mode will be used instead.
Note that the range and meaning of the QP value is dependent on the type of encoder used.
-keyint <frames>- Specifies the maximum key frame interval (or IDR frame interval in case of H.264), in frames.
-bframes <frames>- Specifies the maximum number of B frames between two consecutive I or P frames.
-refs <frames>- Specifies the maximum number of reference frames that may be used for prediction in a picture. (H.264 only)
-encflags <flags> or -flags <flags>- Sets up encoding options by enabling or disabling various flags that control encoding speed and quality.
Flags can either be specified as a simple comma-separated list (»flag1,flag2«) or as a FFmpeg-style on/off list with plus and minus signs specifying whether each option shall be turned on or off (e.g. »+flag1-flag2+flag3«).
The following flags are defined. Unless stated otherwise, each flag increases the encoding quality at the expense of speed:
rd or rdo- use rate-distortion (RD) optimization
trell or trellis- use trellis-searched quantization
psy or psycho- use psychovisual enhancements
hqme- use high-quality motion estimation
chromame- perform motion estimation for both luma and chroma channels
mv0- try to use the zero motion vector (FFmpeg only)
4mv- use up to 4 motion vectors per macroblock (MPEG-4 SP/ASP only)
qpel- use quarter-pel motion compensation (MPEG-4 SP/ASP only)
gmc- use Global Motion Compensation (MPEG-4 SP/ASP only)
cabac- use Context Adaptive Binary Arithmetic Coding (H.264 only)
bpyramid- use reference B frames to construct B frame pyramids (H.264 only)
deblock- use in-loop deblocking filter (H.264 only; enabled by default)
8x8 or 8x8dct- use 8×8 transforms (H.264 only)
weight or weighted- use weighted prediction (H.264 only)
mixed or mixedrefs- use multiple reference frames per macroblock (H.264 only)
main or mp- force Main Profile (H.264 only; this will override some other settings)
baseline or bp- force Baseline Profile (H.264 only; this will override some other settings)
hq- set all quality-increasing flags at once to ensure optimum encoding quality
Note that not all encoders support all flags. Flags that are not supported by an encoder are ignored.
-interlace and -no-interlace or -progressive- Enables or disables interlaced (field-based) encoding, as opposed to progressive (frame-based) encoding, which is the default.
If interlaced encoding is used, PicShow will not render frames, but fields at double the frame rate, thus slowing down the rendering process almost by factor 2.
-tff and -bff- Specifies the field order for interlaced encoding to be top-field-first (TFF) or bottom-field-first (BFF). This option is ignored for progressive encoding.
-bt709 and -no-bt709- Enables or disables the BT.709 color matrix, which is the default color matrix for HDTV. By default, the BT.470 color matrix is used, which is the default matrix for SD television.
Slide options
- <filename>
- If the name of a JPEG file is specified on the command line or in an option file without preceding dashes, a new slide will be created, containing the image from the file whose name has been specified. The file must be an Exif-compliant JPEG file. (This does not mean that is needs to have actual Exif headers in it – it's just required to meet the restrictions of the Exif specification.)
The newly created slide is made the current slide for all following options that modify or operate on slides.
-empty- Creates a new slide with no image in it, i.e. a slide filled completely with its background color.
The newly created slide is made the current slide for all following options that modify or operate on slides.
-set-defaults or -defaults- This option is used to specify the default settings for newly-created slides. For all following options that modify or operate on slides, the current slide will not refer to a specific slide, but rather the default settings that are used when new slides are created after that.
-t <time> or -duration <time>- Specifies the core duration of the current slide (if any), in seconds. The core duration is the time that the slide will be on screen alone, without any transitions running. The total display duration for a slide is thus the sum of the core duration and the durations of the transitions before and after it. In other words, the core duration is the time between the end of the transition before the current slide and the start of the transition after the current slide. It may be any non-negative length, including zero, in which case the transitions following the slide will start immediately after the transition preceding the slide has ended. The default core duration is 5 seconds.
Note that the -t/-duration option affects either the current slide or the current transition, depending on the current context, i.e. -t/-duration only affects slides if there is a current slide as defined by -empty, an image filename or -set-defaults.
-color <color> or -background <color>- Specifies the background color for the current slide. The background color is the color that is shown outside the image region if the zoom area crosses the image's edges. It is also used as the fill color for empty slides.
The notation used for the background color option is the same as for hexadecimal colors in HTML: If six hexadecimal digits are specified, the value is interpreted as a RGB color with 8 bits per component in rrggbb form, e.g. ffff00 means yellow. If three hexadecimal digits are specified, the value is interpreted as a RGB color with 4 bits per component in rgb form, e.g. 080 means dark green. No other formats are allowed. The colors may be preceded by a hash mark (#). The default background color is black.
-pos <position> or -position <position>- Specifies the position of the zoom area of the current slide without animation. For details on the syntax of the position argument, see Position Specifier Syntax below. The default position is
center.
-anim <startpos>;<endpos>- Specifies the position of the zoom area of the current slide, creating an animation between the start and end positions. For details on the syntax of the position arguments, see Position Specifier Syntax below. The start and end positions are separated by a semi-colon (
;). The start position refers to the position of the zoom area at the start of the total display period of the slide, i.e. at the start of the transition preceding it. Likewise, the end position refers to the position of the zoom area at the end of the total display period, i.e. at the end of the transition following the slide.
Either position may be left blank. In this case, it will we auto-animated, i.e. a position will be generated randomly. In particular, if the argument contains of the semi-colon (»;«), both positions will be auto-animated, creating a slow zoom across the image (also see -autoanim below).
-startpos <position>- Specifies of the position of the zoom area of the current slide at the beginning of the total display period. For details on the syntax of the position arguments, see Position Specifier Syntax below.
-endpos <position>- Specifies of the position of the zoom area of the current slide at the end of the total display period. For details on the syntax of the position arguments, see Position Specifier Syntax below.
-autoanim or -auto-anim- Auto-animates the current slide, i.e. randomly assigns both the start and end positions of the zoom are of the slide. This will generate a slow zoom across the image.
-scroll- Sets up a »scrolling« animation for the current slide. If the slide is wider than the output screen, it will be scrolled from left to right. If the slide is taller than the screen, it will be scrolled from the top downwards. To reverse the scrolling direction, use the
-reverse option described below. If the aspect ratio of the slide is identical to that of the screen, no animation will be done and the slide will be shown fullscreen instead.
-rev or -reverse or -swap- Swaps the start and end positions of the zoom area of the current slide, i.e. reverses the direction of the animation.
-curve <curve>- Specifies the easing curve for the current slide's animation. The easing curve is a function that re-maps the progress of the animation such that the animation speed can be varied over time. The following easing curves are defined:
linear or default- Simple linear animation.
smooth or cubic- Performs an animation with smooth ends, i.e. the animation will start slow, reach it's maximum speed halfway into the animation, and decelerate again.
accelerate or acc- Performs an accelerating animation, i.e. the animation will start slow and accelerate over time.
decelerate or dec- Performs an decelerating animation, i.e. the animation will start with a high speed which decreases over time.
Note that the -curve option, like -t/-duration, is shared between slides and transitions, i.e. the current slide is only affected if it has been defined by -empty, an image filename or -set-defaults.
-linear and -smooth- These two options are short-hands for
-curve smooth and -curve linear.
-seed <value>- Sets the random seed for the pseudo-random number generator used for creating automatic animations. The seed value can be any number or text string. Note that this option is global, i.e. any occurence of this option overrides all occurences before that.
-iso and -aniso or -no-aniso and -no-iso- Enables or disables generation of isotropic movements when creating automatic animations. If isotropic mode is enabled, the animation start and end points are guaranteed to be to further away from the center of the image than the minimum of the horizontal and vertical areas available. For instance, if the output size is 640x480, but the input image is in portrait orientation at 768x1024 and 75% zoom (meaning that 576x432 pixels of the source image will be visible), the limiting dimension is the horizontal one. If isotropic mode is used, the zoom area can't move further away than (768 - 576) / 2 = 96 pixels from the center in either direction. In anisotropic mode, the zoom area can be placed everywhere in the original image. Note that this option is global, i.e. any occurence of this option overrides all occurences before that.
-scale-limit <value>- Specifies the maximum zoom amount to use in automatic animations. The value must be specified as a relative number or (preferrably) a percentage. 100% means that no zoom is allowed for automatic animations at all, higer or lower numbers allow more and more zoom. (See Position Specifier Syntax for details on how the zoom values are usually interpreted.) The default value is 80%. Note that this option is global, i.e. any occurence of this option overrides all occurences before that.
Transition options
-trans- Inserts a transition after the current slide, i.e. between the current slide and the one following it.
The newly created transition is made the current transition for all following options that modify or operate on transitions. Options that refer to the current slide are not valid from that point on.
-set-trans-defaults or -trans-defaults- This option is used to specify the default settings for newly-created transitions. For all following options that modify or operate on transitions the current transition will not refer to a specific transition but rather the default settings that are used when new transitions are created after that.
Note that the similar-sounding option -default-trans has a completely different meaning, so be careful!
-default-trans and -no-default-trans- Enables or disables automatic addition of transitions between slides (disabled by default). If
-default-trans is enabled and a slide is added to the playlist with no transition prior to it, a transition will automatically be added with the default settings as defined by -set-trans-defaults.
-no-trans- This option can be used to mark a point between two slides that shall not be joined with a transition, even if automatic transitions (
-default-trans) are enabled.
-type <type>- Sets the type of the current transition. It is an error if there is no current transition. The following pre-defined transition types are available:
crossfade, dissolve or default- Simple crossfade (or »dissolve«) from the current slide to the next slide.
horizontal or horiz- Horizontal wipe from left to right.
vertical or vert- Vertical wipe from top to bottom.
circular or circle- Circular wipe from the center outwards.
diagonal or diag- Diagonal wipe from the upper-left corner to the lower-right corner.
diagonal-alt, diag-alt or diag2- Diagonal wipe from the upper-right corner to the lower-left corner.
horizontal-center-out or horiz-out- Horizontal wipe from the center outwards to the left and right edges.
vertical-center-out or vert-out- Vertical wipe from the center outwards to the top and bottom edges.
Use the -invert option to reverse the direction of the wipe transitions.
-trans-type <type<- Sets the type of the current transition, just like
-type described above. The difference is that -trans-type automatically creates a new transition if there is no transition at the current position in the playlist yet.
-inv or -invert and -no-inv or -no-invert- Enables or disables reversal of the direction of the current transition. For example, a transition with
-type horizontal will wipe from right to left if -invert is enabled.
Doesn't affect crossfade transitions.
-t <time> or -duration <time>- Specifies the duration of the current transition (if any), in seconds.
Note that the -t/-duration option affects either the current slide or the current transition, depending on the current context, i.e. -t/-duration only affects transitions if there is a current transition as defined by -trans or -set-trans-defaults.
-map <filename>- Specifies the name of a grayscale JPEG image that shall be used as a custom wipe »map« for the current transition. This option must be used instead of
-type if a transition map is desired.
A transition map is an image whose intensity specifies which parts of the image shall be revealed first during a transition. Black pixels are revealed first, white pixels are revealed last. The map image will be scaled such that the picture is completely covered by the map, preserving aspect ratio. If the aspect ratios of the map image and the output don't match, borders will be cropped accordingly so that only the center portion of the map image is used. Map images are assumed to have square pixels.
-curve <curve>- Specifies the easing curve for the current transition. The supported values are the same as in the
-curve option for slides, except that they don't affect a slide's animation but a transition's speed if a current transition has been defined by -trans or -set-trans-defaults.
-linear and -smooth- These two options are short-hands for
-curve smooth and -curve linear and work for transitions just as they work for slides.
-band-size <value>- Specifies the size of the map band for the current transition. The map band is the area in which the wipe transition takes place, expressed as a fractional value (decimal fraction or percentage) relative to the total length of the transition. The map band size is a measure of the smoothness of the transition: if set to a value close to zero, the transition will be very thin and harsh, becoming gradually softer as the value increases. The value
1.0 (or 100%), which is also the default, means that when the transition reaches the far part of the wipe (or the white parts of the map image), the close parts (or black parts) will just have completely finished their transition.
-map-curve <curve>- Specifies the easing curve for the map band of the current transition. The supported values values are the same as in
-curve, but the easing curve is not interpreted as a function of time, but a function of space, evaluated along the map band. The default value is smooth.
Position Specifier Syntax
A position specifier is an argument that specifies the zoom area, a subrectangle of a source image that shall be zoomed to the target screen size. As such, it normally consists of two parts: the size of the source rectangle and the position of the source rectangle.
A position specifier can be one of the following:
auto (auto-animate)- This code means that the position shall be auto-animated.
<size> (size only)- If only a size is specified, the position of the source rectangle will be centered in the source image.
<position> (position only)- If only the position is specified, the size will be assumed to be
100% (see below for an explanation what this means).
<size>@<position> (both size and position, joined with an 'at' symbol)- Specifies both a specific size and a specific position.
<x0>,<y0>/<x1>,<y1> (coordinate range)- Specifies the source rectangle by its upper left (
<x0>,<y0>) and lower-right (<x1>,<y1>) pixel coordinates (not including the lower-right edges itself). This is primarily useful to set up a specific rectangle read off an image processing application, for example.
Note that in this mode, the aspect ratio will not be preserved automatically – instead, it's the responsibility of the user to supply a rectangle with the same aspect ratio as the output.
The size can be represented as one of the following:
<percentage>%- Sets up an aspect ratio preserving zoom.
100% (the default) means that the source image will be zoomed such that the smallest dimension fits the output screen. For example, if the image is 4:3 and the output is 16:9, a zoom of 100% will make the source image fill the width of the output screen, cropping away from the top and/or bottom edges.
A zoom value of less or more than 100% will zoom further into the image, e.g. 50% or 200% will do a 2x zoom compared to the 100% setting, 33% or 300% will do a 3x zoom and so on.
<fraction>- Zoom can also be specified as a decimal fraction, e.g.
1.2. This is equivalent to specifying the respective percentage (which is 120% in the example).
<percentX>%x<percentY>% or <fractX>x<fractY>- If two percentage or fractional values are specified, the zoom will be different for the horizontal and vertical dimensions, effectively distorting the image.
<width>x<height>- Specifies the source area size in (integer) pixels. This is useful for directly specifying values determined in an image processing application. Note that this mode doesn't preserve the source image's aspect ratio – instead, it's the responsibility of the user to supply an area with the same aspect ratio as the output.
The position can be represented as one of the following:
<percentX>%,<percentY>%- Specifies the relative position of the source area inside the source image.
0%,0% will put the upper-left corner of the source image into the upper-left corner of the output, 100%,100% puts the lower-right corners of the source image and the output together. 50%,50% (the default) centers the source area in the source image.
<fractX>,<fractY>- The relative position can also be specified as decimal fractions, just like the size.
<x>,<y>- If integer coordinates are specified, these are interpreted as absolute pixel coordinates of the upper-left corner of the display area inside the source image. This is again useful for specifying values taken from an image processing application.
c, center, default, standard- Puts the source area into the center of the source image.
l, left, w, west- Puts the source area into the center of the left edge of the source image.
r, right, e, east- Puts the source area into the center of the right edge of the source image.
t, top, u, up, upper, n, north- Puts the source area into the center of the upper edge of the source image.
b, bottom, s, south- Puts the source area into the center of the lower edge of the source image.
ul, upper-left, tl, top-left, nw, northwest- Puts the source area into the upper-left corner of the source image.
ur, upper-right, tr, top-right, ne, northeast- Puts the source area into the upper-right corner of the source image.
bl, bottom-left, ll, lower-left, sw, southwest- Puts the source area into the lower-left corner of the source image.
br, bottom-right, lr, lower-right, se, southeast- Puts the source area into the lower-right corner of the source image.
Note that all numerical position specifiers can be negative or above 100% (or the image size if absolute positioning is used). In this case, the border (drawn in the color specified by the -color or -background option) will be visible in the output.
Examples
Consider the following option script called demo.opts:
-aspect 16:9 # set output aspect ratio to 16:9
-autoanim # set up automatic animation unless specified otherwise
-t 5 # set default slide duration to 5 seconds
-default-trans # enable automatic transitions between slides; if we enable it
# right here, at the beginning of the script, we will also get
# a fade in effect
# Now the first image follows, with standard parameters:
image1.jpg
# The next image will be just a static image:
image2.jpg -pos center
# We'll scroll over the next image, from bottom/right to top/left:
image3.jpg -scroll -reverse
# For the next images, we change the default duration to 10 seconds and the
# transition duration to 3 seconds:
-set-defaults -t 10
-set-trans-defaults -t 3
# Now a more complex example: zoom out from the upper-left corner to the
# lower-right corner:
image4.jpg -anim 20%@ul;lr
# ^^^ ^^ ^^
# initial zoom | end position (zoom of 100% is the default, so we didn't
# initial position -/ need to specify it here explicitly)
# The next animation has been determined using an image editor, with explicit
# pixel coordinates and sizes:
image5.jpg -anim 3484x1960@0,56;1266x712@1104,936
# We use a fancy map transition between this image and the next:
-trans -map clouds.jpg
# Finally, another image with a simple zooming animation:
image6.jpg -anim 100%;300%
# At the end of the presentation, we add another black frame, preceded by a
# classic "iris shutter" effect seen in many cartoons at the end:
-trans-type circular -invert # instead, specify the transition explicitly
-band-size 10% # don't make it too soft
-empty -t 0 # put a black frame at the end
-no-default-trans # disable automatic transitions (otherwise we'd
# get another transition at the end of the show)
To see what the show looks like, we can use something like
picshow -c demo.opts -preview -size 512x288
To generate a video stream suitable for decent quality PAL DVD authoring, we could use
picshow -c demo.opts \
-size 720x576 -fps 25 -interlace \
-encflags hq -cqp 5 \
-o demo.m2v
To generate a high-quality HD 720p/30 H.264 video stream for YouTube with additional live preview, we could use
picshow -c demo.opts \
-size 1280x720 -fps 30 -bt709 \
-encflags hq -crf 21 \
-o demo.264 \
-preview
Finally, here's an example how to create an H.264 stream for display on modern mobile phones or PMPs:
picshow -c demo.opts \
-size 640x360 -fps 30 \
-encflags hq,baseline -crf 26 \
-o demo_mobile.264