Provided by: dvd-slideshow_0.8.2-0.1ubuntu4_all bug

NAME

       dvd-slideshow  - Creates a slideshow movie in DVD video format from a list of pictures and
       effects.

SYNOPSIS

       dvd-slideshow [-n <slideshow name>] [-o <output directory>]  [-b  <background  jpeg>]  [-a
       <audiofile1>  -a  <audiofile2> -a <audiofileN>] [-p] [-L] [-H] [-mp2] [-r] [-smp] [-border
       <bordersize>] [-theme <themename>] [-f] <input text file>

DESCRIPTION

       Creates a dvd-compatible mpeg2 video from a bunch of images. You  can  add  music  on  the
       command  line  or  in  the text input file. Supports several effects like fadein, fadeout,
       crossfade, crop, and kenburns.  dvd-slideshow is designed to work with dvd-menu to  create
       a  dvd  navigation  menu  that  you  can  then burn onto a dvd. There are also some helper
       scripts to convert a directory of pictures or your favorite online photo album to a dvd.

OPTIONS

       [-n <Slideshow name>]
              The program uses this string as the filename base for the output files so  you  can
              distinguish  it  from  other  slideshows  that  you  can  send  to  the same output
              directory. If not specified, the default value is the name of the input file.

       [-o <Output directory>]
              Directory where the final .vob and dvdauthor .xml files will be  written.  Defaults
              to the current working directory.

       [-b <Background jpeg>]
              Image  to  use  for  the  background  of the slideshow. All of the pictures will be
              overlaid on top of this background image. If no file is specified,  black  will  be
              used for the slideshow and a blue gradient for the title slide.

       [-a <Audio file>]
              Audio  file to play in background during the slideshow. It will be faded out at the
              end.  Supports mp3, ogg, or wav formats at this  point.   Multiple  files  will  be
              joined.  See also the more flexible text file input method. To pass multiple files,
              use the -a switch again.

       [-p]   Use PAL output video format instead of NTSC.

       [-mp2] Use mp2 audio by default.  AC3 audio seems to be more stable when  playing  in  dvd
              hardware players, but requires ffmpeg.  This will over-ride the AC3 default and use
              the mp2 audio encoder.

       [-L]   Render a low-quality video suitable for debugging. This sets the resolution to  1/2
              of full resolution and decreases the quality of fades/transitions.  It should speed
              up the encoding process by at least a factor of 4.

       [-H]   (Beta) Render a higher-quality video. This uses  the  default  dvd  resolution  and
              keeps all other output parameters the same, but enables some pixel-sampling methods
              that make the scroll effect look better at very slow  velocities.  This  will  make
              dvd-slideshow  take up to 4x longer to process the scroll effect. Only applied when
              needed; the output will explain if it is being used.

       [-theme <themefile>]
              Use the given theme when setting  variables/colors/etc.  Themes  are  installed  in
              /opt/dvd-slideshow/themes or in a local directory ~/.dvd-slideshow/themes

       [-border N]
              Make a border of N pixels around each image. Does not apply to title slides.

       [-sharpen]
              Sharpen images.

       [-r]   Autocrop images near the DVD output aspect ratio to fill the whole window.

       [-w]   [alpha] Render widescreen (16:9) output instead of standard (4:3).

       [-smp] Enable  more  processes  to  run  at  the  same  time  for multiprocessor machines.
              Basically, this just renders each frame of a transition in the  background  at  the
              same  time,  and  then  waits for them to be finished.  WARNING: If you do not have
              enough memory to hold all the frames for one "crossfade" or "kenburns"  effect,then
              linux starts swapping to disk, and your machine may seem to lock up for a while.  I
              have crashed my old machine using this.  Use at your own risk!

       [-mpeg2enc]
              The default mpeg encoder has changed to ffmpeg, so if you are having problems,  you
              can force dvd-slideshow to use mpeg2enc instead.

       [-vcd] (alpha) Renders video in vcd-compatible output.

       [-svcd]
              (alpha) Renders video in svcd-compatible output.

       [-flv] (alpha) Renders a Flash video output.

       [-s WxH]
              (alpha) Force output size to have width W and height H.

       [-f] <Input text file>
              See the INPUT FILE section.

       -h     Prints help file (basically this manpage).

INPUT FILE

       The  input file is a text file that acts like a timeline or storyboard for your slideshow.
       In the most simple form, it is just a list  of  images.   See  EXAMPLES  for  some  simple
       examples  of  these  text  files. The input file also allows for many more special effects
       that are not available on the command line. Each line contains one  image  or  effect.  It
       uses the : character as a separator for the fields. Here is the syntax:

       [image.jpg|keyword]:duration:subtitle:effect:effect_params

       Duration  can be specified in integer seconds like 5 or with up to three decimal points of
       accuracy, like 5.683.

       When passing a picture, you can optionally use the keyword "audio" instead of the duration
       in  seconds.   What  this does is force the duration of that image to be the length of the
       previous audio track.  This is useful for making a music video dvd.

       The subtitle field is optional, but if you are passing effects after the  subtitle  field,
       be sure to include all the colons :: in order for the parser to get the correct info.  You
       can escape a colon in subtitles with a backslash.

       NOTE: the effect parameters are separated by a semicolon ; instead of a colon :.

       KEYWORDS:
              title:duration:title text
              Makes a title slide with text centered in the screen.  Further control of the font,
              size,  and position of the title text can be achieved by setting variables (see the
              VARIABLES section).

              titlebar:duration:Upper title text:Lower title text
              Makes a title slide using <Upper title text> as a title at the top of  the  screen,
              and  <Lower  title  text>  as a lower title, in a band at the bottom of the screen.
              Each title is optional.  If one is missing, it will not be  displayed.  White  ands
              are  underlayed  behind  the text for better contrast. Further control of the font,
              size, and position of the title text can be achieved by setting variables (see  the
              VARIABLES section).

              musictitle:duration:subtitle:Title:Artist;Album
              Makes a black frame with the song info printed in the bottom left corner. Yes, that
              is a semicolon between Artist and Album.

              background:duration:subtitle:image.jpg
              Makes a slide with the current background image (or black if no image  is  passed).
              If  a  new  image  name  is  passed,  the background will be reset to that picture.
              Examples:
              "background:2" will display the current background for 2 seconds.
              "background:2::image.jpg" will set the background to image.jpg and also display  it
              for 2 seconds.
              "background:0::image.jpg"  will set the background image to image.jpg, but will not
              use it until the next picture.
              "black" or "white" can be used instead of an image name to display a black or white
              background.

              fadein:duration:subtitle
              Fades in to the next slide

              fadeout:duration:subtitle
              Fades out to the background

              crossfade:duration:subtitle
              Fades from one slide to the next.

              wipe:duration:subtitle:[up|down|left|right]
              Wipes  from one picture to the next.  The direction is optional and will default to
              left.

              chapter
              Force manual chapter marker timing.  Chapter markers will only be created where the
              "chapter" keyword occurs. The default is to add chapter markers at every slide.

              include:includefile.txt
              Other  input files can be included in the input .txt file. The file includefile.txt
              will be concatenated in the place where the line occurs..

              exit
              Stops the slideshow at the current point as if the input.txt  file  ended  at  this
              point. Useful for debugging

       EFFECTS:
              Effects  are  only  used with images, not keywords. In the following effects, x0,y0
              represents the top left corner of a defined box, and  x1,y1  is  the  bottom  right
              corner.
              NOTE: the effect parameters are separated by a semicolon ; instead of a colon :

              crop
              image.jpg:duration:subtitle:crop:x0,y0;x1,y1
              Crops  the  image about the coordinates specified (in the original image coordinate
              system).
              Crop keyword description:
              Because it is difficult to figure out the exact locations where you want  to  crop,
              it is possible to use special keywords for the locations where you want to crop the
              image.  The basic format is:
                   frame_size%;frame_location
              where frame_size indicates the relative scale(%) in percent of the final dvd window
              width/height,  and frame_location refers to the location of the center point of the
              picture relative to the dvd window.
              Frame_location can be any of the following keywords:
                   topleft        top            topright
                   left           middle         right
                   bottomleft     bottom         bottomright
              or
                   x%,y%
              where % is a percentage of the window  width,height  starting  from  the  top  left
              corner of the dvd window.
              or
                   imagewidth | imageheight
              where  the image width or height will be scaled to fill the full width or height of
              the dvd screen.
              Crop examples:
                   image.jpg:dur:sub:crop:651,390;1134,759
                   image.jpg:dur:sub:crop:30%;60%,60%
                   image.jpg:dur:sub:crop:50%;topleft
                   image.jpg:dur:sub:crop:imageheight;left

              kenburns
              image.jpg:duration:subtitle:kenburns:start_box;end_box
              Where now we have starting (s) and ending (e) boxes, defined in the same way as  in
              the  "crop"  function,  above. The kenburns effect will crop/zoom from the start to
              the end for the given duration.
              Full box description:
                   xs0,ys0;xs1,ys1;xe0,ye0;xe1,ye1
              Specifies the top-left(0) and bottom-right(1) points.
              Keyword description:
                   start_frame_size%;start_location;end_frame_size%;end_location         Kenburns
              examples:
                   image.jpg:5::kenburns:651,390;1134,759;372,330;1365,1089
                   image.jpg:5:sub:kenburns:30%;60%,60%;75%;40%,50%
                   image.jpg:5:sub:kenburns:50%;topleft;50%;bottomright
                   image.jpg:5:sub:kenburns:100%;left;0,0;720,480
                   image.jpg:5:sub:kenburns:100%;left;imageheight;left

              scroll
              image.jpg:duration:subtitle:scroll:left
              image.jpg:duration:subtitle:scroll:right
              image.jpg:duration:subtitle:scroll:up
              image.jpg:duration:subtitle:scroll:down
              This is most useful for displaying panorama-style pictures that are much wider than
              they are tall. For example, "scroll:right" will automatically resize the picture so
              that  the  image height is equal to the video display height (480) before scrolling
              right.

              Note that in high quality mode (-H), some calculations will be made to see how slow
              the  scroll  is,  and if it is slow enough, sub-pixel sampling will be used to make
              the scroll effect look much smoother.  Sounds good, right?  Well, it  will  take  a
              LOT longer to process the frames also!

       AUDIO:
              Audio  tracks  can  be  inter-mixed  with  the  video.  If an audio track is placed
              between two different images/effects, that audio track will begin  playing  at  the
              start of the second image/effect.  When placing audio, use the syntax:

              audiofile:track:effect1:effect1_params:effect2:effect2_params

              The audiofile can be a .ogg, .mp3, or .wav file.
              Track is the resulting dvd audio track.

              Audio  Effects  are  audio  effects  where  you  can specify things like fadein and
              fadeout for the audio.  Example:

              audiofile:1:fadein:3:fadeout:2

              (*NEW in 0.7.3) If you want to concatenate two audio files,  just  place  them  one
              right after another in the .txt file.

CONFIGURATION

       You  can  specify  lots  of  variables  and  options  throughout the dvd-slideshow script.
       Settings can be passed on the command line, in a default  ~/.dvd-slideshow/dvd-slideshowrc
       file,  or within the input text file.  The order in which the script reads the settings is
       as follows:
       Default script settings --> ~/.dvd-slideshow/dvd-slideshowrc --> command  line  -->  input
       text file
       so each successive setting will over-ride the previous settings if they are already set.

       ~/.dvd-slideshow/dvd-slideshowrc:
              With  the  syntax  shown  below,  the  following  variables can be specified in the
              ~/.dvd-slideshowrc file.  All lines  are  optional,  and  everything  after  the  #
              character is not read.

              debug=1        # 0 (low) to 3 (lots of info)
              pal=0          # 0=ntsc 1=pal
              ac3=1          # 0=mp2 1=ac3 audio
              copy=0         # add copies of original images to the output directory
              autocrop=1     # autocrop images to fill full screen
              border=0  # add border of N pixels between image and dvd edge
              sharpen=0 # Enable image sharpening for all images
              widescreen=0   # use widescreen mode (16:9) instead of 4:3

              ## Default font:
              font=/usr/share/fonts/default/Type1/n019004l.pfb # Helvetical bold URW font

              ## Subtitle: subtitle_type="dvd"  # use "render" to force rendering of text.
              subtitle_font_size=24
              subtitle_font='/usr/share/fonts/default/Type1/n019004l.pfb'  #  Helvetical bold URW
              font
              subtitle_color="white"
              subtitle_outline_color="black"
              subtitle_location="bottom"

              ## Title:
              title_font_size=48
              title_font_color="black"  # or use hex "#RRGGBB"
              title_font='/usr/share/fonts/default/Type1/n019004l.pfb' # Helvetical bold URW font

              ## top title:
              toptitle_font_size=48
              toptitle_font_color="black"  # or use hex "#RRGGBB"
              toptitle_bar_height=125  # 0 for no 50% white behind text
              toptitle_text_location_x=80
              toptitle_text_location_y=50

              # bottom title:
              bottomtitle_font_size=36
              bottomtitle_font_color="black"  # or use hex "#RRGGBB"
              bottomtitle_bar_location_y=156 # relative to bottom of image
              bottomtitle_bar_height=55  # 0 for no 50% white behind text
              bottomtitle_text_location_x=0
              bottomtitle_text_location_y=155

              # kenburns:
              kenburns_acceleration=2  # seconds of slow acceleration for kenburns
              # use 0 for no acceleration, or, use a percent of the effect time:
              # kenburns_acceleration=25%  # will accelerate for the first 25% of the effect.

       Input text file:
              The same syntax used in ~/.dvd-slideshow/dvd-slideshowrc can be used in  the  input
              text  file.  This way, you could specify settings specifit to the slideshow you are
              working on without changing your default settings.

THEMES

       A theme is just a file containing a list of configuration  variables,  and  possibly  also
       background images, fonts, or audio in the same directory.

       Any  of the configuration variables can be placed in a dvd-slideshow theme file to control
       dvd-slideshow also..br

       This will be explained more later...

FILES

       dvd-slideshow
       dvd-menu
       dir2slideshow
       gallery1-to-slideshow
       jigl2slideshow

EXAMPLES

       There are a few heavily-commented examples  available  in  the  examples  section  of  the
       dvd-slideshow webpage, which you can find at http://dvd-slideshow.sourceforge.net

AUTHORS

       Scott Dylewski <scott at dylewski dot com>
       http://dvd-slideshow.sourceforge.net/

SEE ALSO

       dvd-menu(1)