# SlideCrunch Documentation

SlideCrunch is a "Swiss Army knife" for anything related to the management of slide-based presentations. It can be used to produce slideshows from multiple input files. Moreover, if you provide information regarding slide duration or text, it can also generate annotated handouts, mixing scripts for producing a timed video and even matching subtitles.

As an example, this slidecast was generated automatically with SlideCrunch.

Get SlideCrunch on the SourceForge project page.

## Quick Start

SlideCrunch can be invoked very easily and assumes many default values for the input and output files. All these values can be overriden through command line options.

1. To merge a sequence of slide files into a single output PDF, type:

slidecrunch slideshow


SlideCrunch will look for the list of files to combine in slideshow.txt and output them into slideshow.pdf. If the list contains multi-layered SVG files, they are converted into multi-page PDF according to the conventions of InkscapeSlide. (This option requires pdftk + inkscapeslide for SVG management, see the requirements.)

2. To produce a handout from a set of slides, type:

slidecrunch handout


SlideCrunch will look for the slides in slideshow.pdf, place them vertically at 4 per page, with the text associated to each slide taken from slideshow.txt. The resulting document will be handout.pdf. (This option requires LaTeX, see the requirements.)

3. To produce a subtitle file from a set of slides, type:

slidecrunch subtitles


SlideCrunch will look for the text associated to each slide and timing information taken from slideshow.txt. The resulting document will be slideshow.srt.

4. To split a slideshow into individual bitmaps (i.e. image files), type:

slidecrunch burst


SlideCrunch will split the slides taken from slideshow.pdf into individual JPEG files called slideshow-1.jpg, slideshow-2.jpg, and so on. Each image will have a resolution of 800x600 pixels.

5. To produce an AVISynth mixing script from a set of slides, type:

slidecrunch avisynth


SlideCrunch will look for a list of images numbered slideshow-1.png, slideshow-2.png, and take the timing information from slideshow.txt to produce a script for AVISynth. (No requirement, but you need AVISynth to execute the resulting script, see the requirements.)

## Installing and executing

SlideCrunch consists of a single PHP script, called slidecrunch. Just copy it in your working directory (or anywhere else). You can invoke it in two ways.

• php slidecrunch: this calls the PHP interpreter to run the file
• Under Linux: ./slidecrunch if you set the file as executable (with chmod u+x slidecrunch). You can also copy the file into, e.g. /usr/local/bin so that you can run it from anywhere.

## What to put in slideshow.txt

The file slideshow.txt is a simple text file required by SlideCrunch for almost all its options. Think of it as some form of "movie script" that describes what is in you slideshow; each option looks into that file for different kinds of information:

1. The list of input files (PDF or SVG) from which the slides are taken. To tell SlideCrunch to include a file, start a new line using the pipe (|) character followed by the file name, e.g.:

  | myfirstfile.pdf
| mysecondfile.svg
| etc.


SlideCrunch will take that list of files, produce the corresponding PDF (if the file is SVG), and then merge all these files together in the order they appear to produce the resulting slideshow. The same filename can appear multiple times (it will be repeated as many times as it appears), and the list needs not be grouped: filenames can be interspersed with other lines of information. SlideCrunch reads the whole file to find all the inputs.

2. Text associated to each slide. You can use the slideshow file to put text for each slide, such as comments on the slide or a direct transcript of your talk. To tell SlideCrunch you give information on a slide, you start a new line with a slide marker, most commonly the star (*) character, followed by any lines of text you like:

* This is some text associated to a slide.
The text spans multiple lines.

* This is the text for the following slide.
Again we have multiple lines and it's OK.


Everything that follows the marker is considered as text for the slide, until a new marker is found, which starts another slide. Blank lines count, too: hence in the previous example, the carriage return between the two blocks of text counts as text for the first slide. (This is important if you want to produce paragraphs in handouts.)

The symbols < and > are also slide markers. They matter only if you want to produce a handout and you don't want all slides to be displayed on paper; for all other options they behave exactly like the star. See How to create handouts.

3. Slide timing and numbering. Right next to the slide marker, you can specify the slide number and the time this slide should be displayed, expressed in number of minutes:seconds.xxx since the start of the presentation.

*1*00:00.000* This is the first slide at the beginning
of the presentation.

*2*00:10.500* This is the second slide, that appears 10.5 seconds
after the beginning.

*3*00:15.500* This is the third slide, that appears 15.5 seconds
after the beginning. Since the previous slide appeared at 10.5 s,
the second slide effectively lasts 5 seconds.


Beware, the time is not the slide duration, but the elapsed time since the beginning!

If you use timing, you should also place one last slide marker to indicate the end of the presentation (and the length of the last slide). Hence if the complete presentation lasts 32 minutes and 52 seconds, you write:

*END*32:52.000*

4. Slideshow metadata. You can have the output PDF have some of its fields filled with relevant information, such as author, title, keywords, etc. Many applications use the information in the PDF for display purposes, e.g. showing the PDF's title metadata in the window's title bar, etc. To specify metadata, just write the field followed by its value:

Author: Donald Duck
Title:  Title of my presentation


This information can also be used in the handout: the title and author are displayed at the top of the first page. You can specify any fields you want, but they have to be at the top of the file. Once SlideCrunch sees a slide marker, it stops looking for metadata. (This is to avoid the confusion between a line of text that starts with a word and a colon.)

5. Comments. Any line that starts with two slashes (//) is ignored. You can use it to put annotations and comments into your file, for more readability

// This is my first presentation with SlideCrunch
// Made by me on 11-11-11

| 1.pdf
| 2.pdf
// | 3.pdf <- this file won't be added

// Then the slides
* Hello, this is slide one.
...


No single part of the file is mandatory: each option looks for different pieces of information. Namely:

• slideshow only looks for input files and metadata, if any
• handout only looks for slide text
• subtitles looks for slide text and timing information
• avisynth only looks for timing information

## Walkthrough #1: How to create handouts

A handout displays mini-slides and their associated text side-by-side, and is useful as presentation notes that you can print and distribute. SlideCrunch can be used to automatically generate a PDF handout from your slides and text. You need:

• A PDF of your slides, with each page being a slide. We assume the file is called slideshow.pdf.
• The list of slides and their associated text, marked in the format described above. The file is called slideshow.txt.

To simplify things, the commands to SlideCrunch assume the file names given above. Try to have the same filenames as in the tutorial --you can rename the files to your liking once you're done. Otherwise, make sure you replace the names appearing here with your own filenames; use the command line options.

### Create the handout: default version

If you don't want to change anything, simply type:

slidecrunch handout


SlideCrunch will look for the slides in slideshow.pdf, place them vertically at around 4 per page (this depends on the amount of text), with the text associated to each slide taken from slideshow.txt. The resulting document will be handout.pdf.

### Overlays and "animation"

Some of your slides may consist of elements that are progressively shown or hidden, such as a bullet list where items are added one by one. In the resulting PDF file, this means that the same "slide" is repeated multiple times, each with one more element added to the previous one. In a handout, these "animation" effects create a lot of repeated slides; it is more appropriate to simply keep the "complete" slide and not include the partial animations.

You can tell SlideCrunch that a slide should not be displayed by replacing the normal slide marker (*) with either < or >. The choice of which marker to use depends on what you want to do with the text associated to that slide: < asks SlideCrunch to merge it with the text of the last displayed slide, while > merges the text with that of the next displayed slide. Consider the following example:

* This is slide 1.
> This is slide 2.
> This is slide 3.
* This is slide 4.
* This is slide 5.
< This is slide 6.


The handout for this presentation will have three slides, those numbered 1, 4 and 5, with the following text for each:

 (Slide 1) This is slide 1. (Slide 4) This is slide 2. This is slide 3. This is slide 4. (Slide 5) This is slide 5. This is slide 6.

### Changing the template

SlideCrunch provides a default template for creating handouts. You can override these defaults and provide your own template, written as a LaTeX file structured as follows:

\documentclass <- whatever declarations
\usepackage... <- whatever packages
\begin{document}
...
%%SLIDE_CONTENT_HERE
...
%%BEGIN_SLIDE_TEMPLATE
...
(Template for each slide)
...
%%END_SLIDE_TEMPLATE
...
\end{document}


When producing the handout, SlideCrunch will take what's inside the %%BEGIN%%END block as the code template for each slide. (This block is a declaration, it won't be part of the resulting document in itself.) It will then insert the generated content for all slides at the location of the %%SLIDE_CONTENT_HERE marker. All the rest of the document can be whatever LaTeX code you like.

SlideCrunch will replace special words in you LaTeX file with information from the presentation and current slide. All text is properly escaped to form a valid LaTeX input.

#### Global words (work anywhere)

• %%AUTHOR: the author of the presentation, if specified in slideshow.txt
• %%TITLE: the title of the presentation, if specified in slideshow.txt
• %%SLIDE_WIDTH: the width given to slide thumbnails; the default (3in) can be overridden through the command-line switch --width

#### Slide words (works in slide template only)

• %%SLIDE_TEXT: put it at the location in the file where you want the text of the current slide to be shown.
• %%PAGE_NO: the page number in the source PDF for the current slide
• %%FILE_NAME: the filename of the source PDF

To replace the default template, either:

1. Put in your working directory a file called handout-template.tex; SlideCrunch looks for such a file every time it is run; or
2. Use the command-line argument -t to specify a filename for the template to use

### Cue markers

You can also add cue markers throughout the text to indicate the moments where slides change. This is useful in particular when text from multiple slides is merged into a single entry, to know where along the text one is expected to move forward in the "animation". The command-line option --show-cues enables this behaviour.

When activated, SlideCrunch will add in the text at the proper location a call to a user-defined command \curmarker{p}, where p is the current page number in the source PDF. If the slide change corresponds to a slide that is not being displayed in the handout, then SlideCrunch inserts \cuemarker{p} instead (notice the difference: cue vs. cur). It is up to you to define what such a marker should look like by defining your own LaTeX commands. (SlideCrunch's default template provides an example.)

## Walkthrough #2: How to create a slidecast

You need to have all these files, copied in the same folder for convenience:

• A slideshow PDF, where each page is one slide. You can create such slideshows with SlideCrunch itself, or use any other PDF.
• The recording of your slidecast in an audio file (such as MP3, WAV or OGG). Mine was called slideshow.mp3. I won't tell you how to record yourself properly, I guess there are tutorials for that.
• The complete text of your slidecast in a plain-text file. Mine was called slideshow.txt.

To simplify things, the commands to SlideCrunch assume the file names given above. Try to have the same filenames as in the tutorial --you can rename the files to your liking once you're done. Otherwise, make sure you replace the names appearing here with your own filenames; use the command line options.

### What software you need

If you don't have the following, please install them using the default options before moving on. All of these are free.

• VirtualDub, a video file editor (or AviDemux for Linux users, both work essentially the same way)
• AviSynth, a non-linear video processing engine
• An audio player, such as Winamp, foobar2000, Windows Media Player. This will be used to figure out the time points where you change your slides. If you want to be more precise and don't mind the (slightly) extra complexity, you can use a full-fledged audio editor such as Audacity.
• SlideCrunch, obviously.

### Step 0: split the PDF into separate images

This is a pre-step: simply run

slidecrunch burst


and SlideCrunch will produce a set of image files (in JPEG format, but this can also be changed), numbered sequentially from 1 to whatever number of slides you have. In my example, the files are called slideshow-001.png to slideshow-125.png.

### Step 1: setup the time points

The first part of the work is the most tedious one: you must write down the moments in the audio file where you move to the next slide. These will be expressed in the number of minutes and seconds elapsed from the beginning of your speech.

To do so, open slideshow.mp3 in your audio player, and start playing the file with your slideshow at hand. When the audio reaches the moment where you need to go to the next slide, press Pause on the audio player and write down the elapsed time. Most audio players have a cursor that you can move around to jump back or forward, so if you missed the cue, you can rewind a few seconds and try again.

You will then insert these "cuepoints" throughout the text file slideshow.txt containing the transcript of your audio, as follows. Suppose this is the text for the beginning of my presentation:

Hello, my name is Sylvain, and this is my super duper
presentation. You will see how the sildes change

You see? Now we are at the second slide, and if we
...


Your first cuepoint is (obviously) slide number 1 at the beginning of the first paragraph. This corresponds to the beginning of the audio file, so 0 minutes and 0 seconds. You write this as *#*mm:ss.xxx*, where:

• # is the slide number
• mm:ss.xxx is the elapsed time, with mm minutes, ss seconds and xxx milliseconds

If your media player doesn't show milliseconds, you can just replace them with "000". So the first cuepoint is written *1*00:00.000*, and you place it at the beginning of your file, in front of the first paragraph:

*1*00:00.000* Hello, my name is Sylvain, and this is my super duper
presentation. You will see how the sildes change

You see? Now we are at the second slide, and if we
...



Suppose now you measured that the second slide should be shown at 7.5 seconds from the beginning, you insert the second cuepoint at its appropriate location in the text:

*1*00:00.000* Hello, my name is Sylvain, and this is my super duper
presentation. You will see how the sildes change

*2*00:07.500* You see? Now we are at the second slide, and if we
...


...and so on. A slide change can occur in the middle of a sentence:

...
If we continue talking, you will realize that

*3*00:14.000* I switched to the next slide while
I talked.


Just make sure that a cuepoint begins at the start of the new line. Similarly, a paragraph that doesn't start with a cue point is just that: a paragraph, and is considered as the continuation of the text for the current slide.

Finally, finish your text with the end time for your audio file. Mine was 32 minutes and 52 seconds long, so I put this as the last line of my text file:

*END*32:52.000*


### Step 2: Generate the slideshow

The first step was rather tedious, but once your text is annotated with the slidechanges and time points, a lot of fun things can be done automatically.

If you used the filenames in this tutorial, the default values are setup properly. Just run:

slidecrunch avisynth


The script will create a file slideshow.avs with a bunch of commands like these:

# --------------------------------------------------
# Auto-generated file by slidecrunch
# (C) 2010-2011 Sylvain Hallé
# --------------------------------------------------

video = ImageSource("Slide_001.jpg", fps=4).BicubicResize(640,480).Trim(0,98)
video = video + ImageSource("Slide_002.jpg", fps=4).BicubicResize(640,480).Trim(0,79)
video = video + ImageSource("Slide_003.jpg", fps=4).BicubicResize(640,480).Trim(0,60)
...


### Step 3: Save the slide show as a video

Now open VirtualDub, an in the File menu, click Open and select Slidecast.avs. (You may not see the file in the list; if this is the case, make sure that the "Files of type" drop-down list at the bottom is set to "AVIFile input driver".)

Your file should open as a video, showing the first slide:

VirtualDub provides controls to play the file. However an AviSynth script file like the one you just loaded is a bit different; don't press the Play button or move around the file unless you know what you're doing. (If you're curious, more on that later.)

To export your presentation as a video, you must setup compression settings for audio and video:

1. In the Audio menu, choose Direct Stream Copy
2. In the Video menu, choose Full Processing Mode if it is not already checked
3. Go back to the Video menu, and choose Compression...
4. At the left is a list of compression formats, or codecs. You can pick any one, but for this tutorial select "MidiVid JPEG Codec". (If you think using DivX or other stuff, see below.)

5. Leave the Quality slider to a relatively high value (say, at least 80). Click OK.
6. In the File menu, choose Save as AVI. Save it as Slidecast.avi.

Depending on your computer's speed and the length of your slidecast, the process can take from a few seconds to several minutes. Be patient.

Once this is done, you can double-click on Slidecast.avi or open it into any media player, such as Windows Media Player. It should show the slides that change along with the audio, at the timepoints you gave in your text file. Voilà!

### Bonus: generate the subtitles

Since you have the complete transcript of your slidecast AND a bunch of cuepoints telling how that text is distributed over time, for free you can also generate a subtitle file that can be used to display text over your video, like in movies.

Of course, you realize that you probably say a lot of text over a single slide --certainly much more that what can fit in one or two lines of text at the bottom of the screen. The trick is this: since we know how long each slide lasts, we will split its associated text into 1 or 2-line snippets and spread them evenly over the total duration of the slide. I tried it with my own slidecast, and I was surprised how closely the text follows the audio --almost as if someone used a teleprompter!

Doing so is really simple with SlideCrunch: just run

slidecrunch subtitles


This time, the script produces another text file called slideshow.srt that looks like this:

0
00:00:00,000 --> 00:00:03,750
Hello, my name is Sylvain, and this is
my super duper
presentation. You will see how the

1
00:00:03,750 --> 00:00:07,500
sildes change
topic.

2
00:00:07,500 --> 00:00:10,750
You see? Now we are at the second
slide, and if we

3
00:00:10,750 --> 00:00:14,000
If we continue
talking, you will realize that



This is a file in the SubRip (SRT) format. Each bunch of text is one subtitle; notice how the text for the first slide in our example (lasting 7.5 seconds) has been split into two cards lasting 3.75 seconds each.

If you re-open slideshow.avi in your media player, this time the subtitles, taken from the file, should also be shown as you talk (this happens every time an xxx.srt file exists in the same folder as xxx.avi. In my case, the result was spookily faithful.

Some online services, such as YouTube, allow you to attach subtitles to an online video.

## Command-line options

Usage:

slidecrunch [--help] action [inputfile] [options]


Possible values for action:

slideshow
Produce a full-screen PDF slideshow from input file
handout
Produce a PDF handout of slides
subtitles
Produce a subtitle (SRT) file
avisynth
Produce an AviSynth script
burst
Burst PDF into multiple images
clean
Remove PDFs generated from SVGs

Global options:

-o file
Output to file (default: slideshow.xxx, depending on action)
-v n
Set verbosity level to n (0 = no output)
--no-clean
Don't remove temporary files at the end
--clean
Do remove temporary files at the end
--force-recompile
Re-process all input files even if they have not been modified

Options for handout:

-i file
PDF source file (default: slideshow.pdf)
--show-cues
Add a cue symbol in text at each slide change
--no-compile
Don't compile LaTeX source
--width x
Set slide width to x
-t file
Use file as template

Options for avisynth and subtitles:

--fps n
Set frame rate of output video to n (default: 4)
--audio file
Specify audio input to file (default: slideshow.mp3)

Options for avisynth, subtitles and burst:

--width n
Set image width to n (default: 800)
--height n
Set image height to n (default: 600)
--format x
Set image format for slides (default: jpg)

## Requirements

SlideCrunch is mostly the "glue" between a bunch of existing applications to help producing slideshows. Hence to run SlideCrunch, you need some other software installed, depending on your use. All of them are free:

• A PHP interpreter. SlideCrunch is written in PHP. PHP is free and there are distributions for all OSes, see php.net for a starting point. (Required all the time.)
• pdftk, the PDF toolkit. This is necessary to join/split PDF files (i.e. the burst and slideshow options).
• LaTeX, if you want to create handouts. (You can also tell SlideCrunch to produce the LaTeX file without calling LaTeX to compile it, see the options.)
• InkscapeSlide, if you want to automatically split multi-layer SVG files into multi-page PDFs (in the slidedhow option).
• ImageMagick, if you want to convert PDFs automatically into image files (e.g. in the burst option).
• AviSynth, a powerful frameserver, to produce the video file from a set of slides. Actually, SlideCrunch does not require AviSynth, but you need AviSynth to process the file that SlideCrunch produces.