dvd-slideshow(1)

📦 version 0.8.6.1, in debian bookworm, debian trixie, ubuntu jammy, ubuntu noble, ubuntu questing, ubuntu resolute, ubuntu stonking

💿 dvd-slideshow — the manual page, bestie edition 💖

okay so. welcome to the dvd-slideshow(1) manual, section 1 of the whole thing. grab a snack, we're gonna make a whole DVD out of your camera roll. ✨

✨ NAME ✨

dvd-slideshow — makes a slideshow movie in DVD video format out of a list of pictures and effects. that's the whole job. it slays at it. 💅

🌸 SYNOPSIS 🌸

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

like. it's a lot of brackets. it's giving "choose your own adventure" and honestly? we love that for us. 🦋

🎀 DESCRIPTION 🎀

So basically: this thing creates a video from a bunch of images. iconic behavior.

The default video format is designed to produce DVDs, but other formats can be created for the web also (.flv). iykyk.

You can add music on the command line or in the text input file. Both! You contain multitudes. 🫶

It supports several effects, and here they are, no gatekeeping:

  • fadein
  • fadeout
  • crossfade
  • crop
  • kenburns

dvd-slideshow is designed to work with dvd-menu to create a dvd navigation menu that you can then burn onto a dvd. the collab we deserve. 🤝

There are also some helper scripts to convert a directory of pictures or your favorite online photo album to a dvd. because doing it by hand is not the vibe. 🙈

💅 OPTIONS 💅

okay here's the menu. every single flag. no skipping, that would be disrespectful to the flags. 🎀

  • [-n <Slideshow name>] — The program uses this string as the filename base for the output files, so you can tell this slideshow apart from the other slideshows you're sending to the same output directory. main character needs a name. If not specified, the default value is the name of the input file.
  • [-f] <Input text file> — See the INPUT FILE section. (it's coming, bestie, we're getting there 👀)
  • [-o <Output directory>] — Directory where the final .vob and dvdauthor .xml files will be written. Defaults to the current working directory. it lives where you live. 🏠
  • [-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. cute little default moment. 🌈
  • [-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. again. again. as many times as you want. 🔥
  • [-p] — Use PAL output video format instead of NTSC. pick your continent bestie 🌍
  • [-mpeg2enc] — Force use of mpeg2enc with mp2 audio even if ffmpeg is installed. Use this if you have problems with ffmpeg. Usually ffmpeg is much faster at encoding video. (so like, this is the "my ffmpeg is acting up" button 🩹)
  • [-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. ngl the AC3 stability thing is real, so know what you're giving up 👑
  • [-s WidthxHeight] — Use output size other than the standard DVD output size (720x480 for NTSC). Used when specifying alternate output formats with -flv or -mp4.
  • [-flv] — Render a flash video instead of a mpeg2 .vob. Default output size is 320x240. web vibes only 🦋
  • [-mp4] — Render a mp4 video instead of a mpeg2 .vob.
  • [-mpg] — Render a .mpg video instead of a mpeg2 .vob. Allows for alternate (non DVD compatible) sizing with -s. living dangerously, love that 🌈
  • [-vcd] — (alpha) Renders video in vcd-compatible output.
  • [-svcd] — (alpha) Renders video in svcd-compatible output.
  • [-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. fast and ugly, the classic combo 💀
  • [-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. so it tells you. polite king 👑
  • [-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. aesthetic is a valid config choice 🎀
  • [-border N] — Make a border of N pixels around each image. Does not apply to title slides. title slides said "not today" 🙅♀️
  • [-sharpen] — Sharpen images. ✨crisp✨
  • [-r] — Autocrop images near the DVD output aspect ratio to fill the whole window. no letterboxing era 🫶
  • [-w] — [alpha] Render widescreen (16:9) output instead of standard (4:3). cinema mode, periodt 🎬
  • [-nosmp] — Disable multiple threads in some processes when possible. If you have little memory or a slow machine, this may help if you experience problems with disk memory caching. (your laptop is doing its best ok 😭)
  • [-nocleanup] — Leave temporary files in the temporary directory. Useful for debugging. the crime scene stays intact 🔍
  • [-q] — Quiet output mode. Reduce amount of information on screen, but keep a progressbar indicator. still need the bar. always need the bar. 💅
  • [-V 1|2] — Increase verbose debug output. 1 adds more than the default, and 2 adds a lot.
  • -h — Prints help file (basically this manpage). hi hello yes it's me, the manpage 👋

more parts coming, don't go anywhere bestie 💖

✨ INPUT FILE ✨

Note: the -f is optional if the input filename is the last argument on the comand-line. 🫶

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. 🖤🤍

🔄 Transitions 🔄

Transitions do not add time to the overall slideshow, they just get overlaid on top of the adjacent images. Because of this, the transition duration can not be greater than half of the adjacent image duration.

  • 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

If you want to concatenate two audio files, just place them one right after another in the .txt file. 🎧

💖 CONFIGURATION 💖

okay so this is the part where you become the main character of your own slideshow 🎬 because dvd-slideshow lets you specify so many variables and options all over the place. Settings can be passed on the command line, in a default ~/.dvd-slideshow/dvd-slideshowrc file, or within the input text file. Three places, one icon.

The order in which the script reads the settings is literally this:

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. it's giving power ranking, ngl 👑

🏠 ~/.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 (so go off with your commentary, she's not listening 💅).

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
high_quality=0 # use high-quality mode (set to 1)
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"
subtitle_location_x=0
subtitle_location_y=105

## 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=1  # 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.

# logo:
logo=path/to/logofile.png  # will be overlaid on top of all frames.  Must be pre-sized manually.
logo_gravity=SouthEast   # Position of logo overlay. North | South | East | West | NorthEast | NorthWest | SouthEast | SouthWest

that's the whole vibe file, bestie ✨ write it once, live your truth forever.

📝 Input text file 📝

The same syntax used in ~/.dvd-slideshow/dvd-slideshowrc can be used in the input text file. Which is lowkey genius because it means you can specify settings that are specific to the slideshow you're working on right now without ever touching your default settings. one-off fits, no commitment, we love that for you 🦋

🎨 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. That's it. That's the whole theme. a folder with opinions 💅

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

This will be explained more later... (she's teasing, and honestly? respect 😌)

📁 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. heavily-commented is the best kind of commented, fr fr — go read them, they ate 🍓

👑 AUTHORS 👑

🔭 SEE ALSO 🔭

and that's the whole page, no cap 🌈 this was dvd-slideshow(1), version 0.8.4, written by Scott Dylewski — go make something gorgeous, bestie, you're literally the moment 💜🦋✨

📦 where this page comes from