P2D version 0.82 Documentation

p2d − photos to dvd

p2d [OPTION]... CONFIG_FILE OUTPUT_DIRECTORY

Assemble a series of digital photos, with optional audio tracks into a mpeg 3 stream. p2d is a command line tool. It is driven from the text configuration file, CONFIG_FILE and all output is put in OUTPUT_DIRECTORY. The configuration file specifies images to display, zoom and pan transitions, and many different ways to dissolve from one image to the next.

p2d supports a number of command line OPTIONS.

−c

check to see if dependent utilities are available and exit.

−d

output debug information

−v

verbose output. Output descriptions for each scene generated and each frame

−m

generate individual ppm images instead of the mpeg output (no mpeg)

−n

don’t generate any output images (ppm or mpeg). This (debug) option allows p2d to go thru the motions quickly without spending the time to process the images.

−p

generate images in PAL format rather than NTSC format

−s

inhibit printing the computed storyboard

−w

generate half resolution video for web presentations

Consider the resultant mpeg movie to be made up of a number of scenes. Each scene is a photo that is displayed for some period of time. Some scenes are transitions from one photo to another. The configuration file contains the instructions on how this is done. It also contains descriptions of how to insert audio clips and some miscellaneous control information.

Blank lines and lines that begin with a pound sign are ignored in the configuration file. Each command must is a single line. If a line ends in a backslash it is joined with the next line before processing. The following looks at a few simple configuration lines and builds up to the full specification of configuration file lines.

Note: in the discussion below, assume that we are generating NTSC output, (which means that all images will be resized to 720x480) and that the input image, foo.jpg is 2880x1920 pixels in size.

<duration> <image>

<duration>

is a an integer followed by a f, a number followed by a s, or simply a integer. It is how long to display this picture. For example 1.5s would generate enough frames to display the image for one and a half seconds. Using either an integer or an integer followed by a f (preferred), indicates the number of frames to display the image. A NTSC movie almost has 30 frames per second, so entering 30f would be the same as 1s − unless you specified PAL format, where 25f is 1s.

<image>

is the name of the file containing the photo to be displayed. If the name has embedded spaces or begins with something other than a letter it should be quoted. The first character of the name cannot be a minus sign, (−). A name beginning with a minus sign is treated specially, and used as the name of a color to use instead of an image, the string following the minus sign is any name ImageMagick accepts as a color name (run the command ’identify -list color’, for a list of valid colors).

Some examples:
Display the image foo.jpg for 5 seconds.

5s foo.jpg

Display the file ’my Mothers Family.jpg’ for 1 second

1s "my Mothers Family.jpg"

Generate a black image and display it for 30 frames.

30f "-black"

Whenever you specify an image to be displayed you can also specify a zoom or magnification factor and the location of the center of the viewable image.

<duration> <image spec>
where
<image spec> = <image> <location> <zoom>

<location>

The location of the center of the viewable image. This can be specified as a fixed location in pixels relative to the original image, such as 1300,850 or using one of the following words topright, top, topleft, left, bottomleft, bottom, bottomright, right or center. The location specified will be adjusted, based on the zoom so that the resultant image fills the frame.

<zoom>

the amount of zoom (or magnification) to apply. This value can be either a number which specifies how much to reduce or enlarge the photo by, or as a percentage of the original (e.g. 200%). If a number is specified, it is how to scale the image. For example, a photo that is 2880x1920 pixels is normally reduced to 720x480 pixels (for NTSC). This would be 100% zoom or 0.25 magnification. 200% would be the same as 0.50 and would use 1440x960 of the pixels from the original image. If no location is specified, the image is cropped around the edges to fill the frame.

<location> and <zoom> can be specified in either order.

Some examples: Using foo.jpg that is 2880x1920 pixels and we are generating a NTSC image. The following will place the center of the image at 720,960 and magnify the image to 200%

3s foo.jpg 200% left

Using the same image, this command will leave the center at 1440x960. You could also specify center as the location.

3s foo.jpg 200%

This will zoom in to 200% and make the center of the left edge of the photo be the center of the left edge of the final image.

The <image spec> described above always adjusts the values you specify so that the resultant image fills the full output frame. There are times when this is not desired. Say you really want to have a 50% zoom, with black around the outside of the image. Another qualifier on the image spec allows this.

<image spec> = <image> <location> <zoom> fill

fill

The optional modifier fill says that it’s ok for p2d to fill in missing pixels around the edges if the image is too small to fit.

If we wanted the image to be in the center of the screen with black bars around the edges, we could say:

3s foo.jpg 50% fill

You may ask, but I don’t want black bars around the edges. I want blue bars, or I want another image to be used. You can specify the background to be used when fill is in effect, with the following configuration line:

background <image spec>

In addition to the basic ability to specify the center of an image and the zoom, you can generate a scene where the image is panned from one location to another, and/or where the image is zoomed. The command for this is

<duration> <image spec> pan <image spec>

The second image spec does not include another file name.

This will adjust the center and magnification values between the first and last frames generated so that the image is gradually panned and zoomed between the initial and final values. If the second <location> or <zoom> is not specified, it uses the value from the first <image spec>. There is an alternative pan command

<duration> <image spec> pand <location> <zoom>

The pand version delays the adjustment of center and magnification values until the frame is actually generated. The difference between these two pan commands is subtle. As an example, using foo.jpg, and the command

3s foo.jpg 500% 1250,1400 pan 100%

The start and finish center values are precomputed and are 1250,1400 and 1440,960. As the image is panned and zoomed, the center of the image will gradually move up to the center of the image 1440,960. It will move up faster than the bottom expands, giving a sensation that the camera was being moved up and back down as the zoom occurred (if this scene was actually generated with a motion picture camera). The command

3s foo.jpg 500% 1250,1400 pand 100%

Does not precompute the start and finish center values. Instead it uses 1250,1400 for each frame, and then adjusts it only if needed. This will hold the center of the image constant at 1250,1400 as the zoom begins. Once the image is expanded to the bottom of the image, the center will gradually move up ending at the center. (Try it on one of your photos and see what you think.)

p2d supports a number of commands to generate transitions between two images.

<duration> <image spec> dissolve <image spec>

The first image spec is dissolved into the second over the time period specified in the duration. An example:

1.5s black.png dissolve foo.jpg 1865,1012 200%

Wipe transitions gradually replace the first image with the second, with the position of both images remaining fixed. In a slide transition the image appears to slide on or off the screen.

<duration> <image spec> <WipeSlide> <fromDirection> <image spec> <WipeSlide>

<WipeSlide> = wipe | slide

The second <WipeSlide> is optional and wipe is assumed if it is not specified.

<fromDirection> = fromtop | frombottom | fromleft | fromright | fromtopleft | fromtopright |frombottomleft | frombottomright

If the <fromDirection> is one of the first four values the transition is a side transition, otherwise it is a corner wipe. Corner wipes do not support slides. Examples of these:

1.5s foo.jpg 200% wipe fromleft bar.jpg wipe

Imagine a vertical line that travels from the left to the right of the image. This transition reveals the new picture as the line moves across the screen. The second <WipeSlide> is how to remove the original image. The following command is equivalent to the last command:

1.5s foo.jpg 200% wipe fromleft bar.jpg wipe

With this one, the new image appears to slide in from the bottom

1.5s foo.jpg 200% slide frombottom bar.jpg

The following is a corner wipe:

1.5s foo.jpg 200% slide fromtopleft bar.jpg

Imagine a diagonal line going from the specified corner to the opposite corner, as the line proceeds the new image is revealed. It doesn’t make sense to ’slide’ either image on the diagonal so slide is not supported.

A number of transitions consist of expanding a shape, like a box from the center of the image out to the outer edges. As the shape expands, the new picture is revealed. You can also start at the outer edges and wipe in to the center.

The first of these is in fact the Box Wipe. A box wipe gradually expands a box from the center of the image out to the outer edges. As this box expands, the new picture is revealed.

<duration> <image> box <direction> <image>

<direction> = in | out

These two examples illustrate the box wipes.

0.75s foo.jpg 150% box out bar.jpg
0.75s bar.jpg box in foo.jpg 150%

A diamond wipe is like the box wipes, except the shape is a diamond.

0.75s foo.jpg 150% diamond out bar.jpg
0.75s bar.jpg diamond in foo.jpg 150%

p2d has basic labeling support. You can specify a title and/or a subtitle to be applied to any scene. titles and subtitles are part of the image spec.

<image spec> = <image> <location> <zoom> fill <title> <subtitle>

This is the full definition for <image spec>. Other than <image>, everything else is optional. <image> must be first. but the order in which the other items appear doesn’t matter.

<title> = <string> <location> <fontsize> <fontname> color <colorname> <opacity> <height>

<subtitle> = <string> <location> <fontsize> <fontname> color <colorname> <opacity> <height> outline

The <string> in <title> and <subtitle> is required and must be first. The font height must follow <fontsize> or <opacity>, so to specify <height> you must specify either <fontsize> or <opacity>. Specifying outline, outlines the font, rather than using solid color.

There are defaults for most of the values in <title> and <subtitle>. You can change the defaults with the commands

title <location> <fontsize> <fontname> color <colorname> <opacity> <height>
subtitle <location> <fontsize> <fontname> color <colorname> <opacity> <height>

The defaults are set, as if you entered the commands:

title 80,50 48 helvitica color black 50% 0
subtitle 0,325 24 helvetica color black 50% 0

The <location> is the bottom left corner of the box that contains the text. The title is left justified, and the subtitle is horizontally centered on the image. <fontsize> is the size of the font., <colorname> is the name of the color or the hex value (#000000 for black). <opacity> and <height> allow specifying a opaque white background for the font. If <height> is 0 no white box is generated, otherwise it specifies the height of the box, and <opacity> specifies the opacity of the image. Here are simple examples:

3s foo.jpg title Joe’s Trip to Rome
1s foo.jpg title Welcome to Rome subtitle Joe and Mary

Use of all these options can cause a very long command line to be generated.

Audio clips are specified much like images are.

<duration> <audiofilename> audio fadein <fadein_time> fadeout <fadeout_time> trim <seconds>

The audio file, but be either a ogg, mp3 or wav file, and the extension of the file must likewise match. The output is converted to ac3. The only modifiers for an audio clip are the optional fadein, fadeout and trim times. For example:

12s intro.mp3 audio fadeout 1

Will use the first 12 seconds of intro.mp3 to accompany the images following this command. The fadeout modifier causes the volume to gradually decrease to zero between seconds 11 and 12 of the clip.

The audio clip will be truncated if another audio clip is specified before the previous one finishes, or if the end of the video is reached. If the clip is not long enough, silence will be generated to fill the remaining time.

There are two special cases for the value of <duration> that makes the integration of audio and video easier. On an audio command, if the duration is a minus sign, it indicates to use the length of the audio clip as the duration.

− intro.mp3 audio

Likewise, if a minus sign is used for the duration of an image, it will be displayed until the current audio clip has finished.

Written by Stephen A. Dum.

Report bugs and enhancements using the bug database and RFE database at http://p2d.sourceforge.net.

Copyright © 2005 Stephen A. Dum
Licensed under the Open Software License version 2.1
This is free software; see the source for copying conditions. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.