pomalevi

pomalevi

PowerPoint-based maintainable lecture videos command-line tool

Simple and effective.

If you are afraid of using the command-line, this is not for you.

What pomalevi is

PowerPoint allows recording slide shows with narration and even a webcam insert with its SlideShow⟶RecordSlideShow function. The media files are stored within the PPT file on a per-slide basis. This can be turned into a video via "File⟶SaveAs⟶*.wmv"

pomalevi converts such a video file (or any other) as follows:

• it turns the huge video produced by PowerPoint into a much smaller one by applying more reasonable compression settings
• it can split the video into parts (separate, shorter videos) based on when a user-defined splitlogo appears in the video
• it produces an HTML page with table of content hyperlinks for these parts based on a very simple text file containing parts descriptions
• it provides a simple HTML player that will stop the video when a user-defined stoplogo appears in the video, so that the audience can ponder a question.

Why pomalevi exists

I have previously used Camtasia to record lecture videos with Camtasia's PowerPoint plugin. I have inserted the stops I wanted (after I'd asked the viewers a question) manually in the Camtasia Editor and then cut the video into the five-or-so pieces (of 10-20 minutes each) I want and exported ("produced") each piece individually using the Batch Production feature.

This gives nice results, but is a lot of manual work. It is acceptable for a one-time process, but what if I want to modify two of the slides next year? Or modify my narration? Aw!

PowerPoint's "Record" function is a good answer to this: Each slide can be re-recorded individually. Then just re-export the whole video.

But I did not want to give up my chopping-into-five-parts and even less so the automated stops that Camtasia's SmartPlayer allows. That's when the idea of pomalevi was born: Let's combine the strengths of PowerPoint's slidewise recording with fully automated postprocessing. A couple of couples of hours later here we go.

Pros and cons

Pro:

• Pomalevi-plus-Powerpoint produces very useful output with little effort
• Subsequent changes are easy to make, your lecture videos become maintainable

Con:

• Depending on how fast your computer is, re-creating a pomalevi video takes a substantial amount of time during which your machine is very busy.

In my case, it is typically about 1.5x the video play time, the bigger part of which is needed by the Powerpoint video export.

How to install pomalevi

pomalevi is tested on Windows, but should also work on WSL or Linux proper. It is a command-line application, so you need to work in cmd.exe or Powershell.

• Install a recent version of Python (3.8 or higher) from https://python.org.
  Commands python and pip must end up on your PATH.
• Start cmd.exe or powershell and perform pip install pomalevi
• That's all!
  You should now be able to call pomalevi.

Caveats:

• The above should work on personal computers.
  If you have a pre-installed version of Python but are not allowed to use pip as shown (you should be!),
  • use pip install --user pomalevi instead to install to your personal directory instead
  • use pip show pomalevi to see (in the "Location:" entry) where it ended up, e.g. c:\Users\<name>\AppData\Roaming\Python\Python310\site-packages
  • put the neighboring Scripts directory in your Path, e.g. c:\Users\<name>\AppData\Roaming\Python\Scripts.
    (To modify Path, use the Windows key, search for "environment"`, and call "Edit environment variables for your account" (not "for system"). If your Windows is not running in English, the name will be different, but the English search term should still work.) Pomalevi should now work like after the original procedure.
    Alternatively, you could perform an additional install of Python in "for me only" fashion and use the pip of that.
• The above installation procedure is a shortcut: If used, pomalevi could in principle interfere with other Python packages installed on your machine (although that is unlikely to be a problem).
  A cleaner way would use pipx instead of pip, which installs a package in an isolated environment. To do that,
  • first install pipx by pip install pipx
  • then install pomalevi by pipx install pomalevi
  • and then put the path displayed by pipx into your PATH

How to use pomalevi

View demo.pptx (1 minute)

Find the pomalevi install directory tree in the directory ending in site-packages which is shown when you execute python -c "import sys; print(sys.path)".

From the pomalevi install directory tree, copy ppt/demo.pptx to any of your own directories.
Open the copy with Powerpoint,
choose "Powerpoint⟶Slide Show",
check the boxes for "Play Narrations" and "Use Timings",
start the slide show.
View it, end it. Imagine this was your own presentation which you want to publish as several videos in pomalevi style.

To do that, "File⟶Save as" this file, select file format "Windows Media Video (*.wmv)", and save it as myslides.wmv. This file you can use as the myslides.wmv in the subsequent examples.

Very basic use: Compression only

pomalevi mydir/myslides.wmv

The output is a directory mydir/myslides/ with several files. You can either use mydir/myslides/index.html to get the pomalevi player or just the video itself: mydir/myslides/v1.mp4.

Inserting stops: -stop-at

• In Powerpoint, choose a unique graphic or text string that will appear in your video to indicate to pomalevi where to insert a stop.
• For instance, I use "Insert⟶Icons⟶Business" pick the two people with the question mark (I have PowerPoint 2019), keep the default size, fill the icon with my highlight color (dark red), and put it in the lower left corner of my slide. (Any corner can be made to work easily, other places are possible if needed.)
• You could in principle also use the string "STOP!" or whatever other fixed-and-unique visual element you like.
• Insert an Entrance animation for the logo at the appropriate moment, perhaps insert an Exit animation shortly thereafter. Only the entrance moment is relevant; it is the stop moment.
  Note that the player is not capable of stopping at exactly this moment; expect a tolerance of +0.25 seconds (0.5 seconds for Firefox).
• Export the video from PowerPoint.
  Play it at original scale (that is, size 100%).
  Stop it when the logo is visible.
  Make a rectangular-area screenshot of only the logo.
  Store it as PNG, e.g. stoplogo.png.
• Here is what the result looks like in my case:
• pomalevi makes a pixel-by-pixel search for this image and expects a match of at least 80%, so beware of non-rectangular or transparent logos if the slide background behind it will not always be the same. See also section "Caveats" below.
• Now produce the video with pomalevi:
  pomalevi --stop-at ll:stoplogo.png mydir/myslides.wmv
  (ll stands for "lower left")
• Searching for a stoplogo is a slooow process if done over the whole image. Therefore, pomalevi expects the logo to be in one of the four corners of the slide: one of ul, ur, ll, lr in the --stop-at specification, meaning upper left, upper right, lower left, lower right, respectively.
  It will find it there with a tolerance of up to half a logo width and half a logo height towards the middle of the video. If the logo hangs over the edge of the video even a bit, it cannot be found reliably.
  The part after the position specifier can be a pathname.
• In principle, you can also specify the search area by hand thusly:
  --stop-at x=900..1000,y=500..600:stoplogo.png would look for the logo (specifically: the upper-left corner of the logo) in that region of the video (near the middle).
  x=0,y=0 is the upper left corner.
• Unlike for basic use, this time the v1.mp4 file is not helpful, because it knows nothing about the stops.
  Instead, you need to use mydir/myslides/index.html, which calls the pomalevi player and feeds it the proper list of stop times.
• Like most pomalevi options, --stop-at has friendly defaults:
  • --stop-at ll:stoplogo.png will be assumed by default, but if stoplogo.png is not found, no stoplogo search will be performed.
  • The stoplogo will be searched for in several places:
    • ./stoplogo.png, in the local directory
    • mydir/stoplogo.png, in the input file directory
    • mydir/../stoplogo.png, in the parent of the input file directory
    • mydir/toc/stoplogo.png, in the toc subdirectory of the input file directory (see the description of --toc below).

Splitting into parts: --split-at

The output of pomalevi appears a bit silly unless you let pomalevi split your video into several parts.

• Splitting works much the same as stopping (described above):
  Decide on a logo (of course not the same one as for stopping),
  insert it in your presentation (preferably again in the lower right),
  make a screenshot of it in the original size,
  store it as (preferably) splitlogo.png, and
  call pomalevi with it:
  pomalevi --split-at ll:splitlogo.png input.wmv
• Splitting creates a separate video file for each part, called v1.mp4, v2.mp4, etc.
• mydir/myslides/index.html provides navigation between those videos.
• The same friendly defaults apply as for --stop-at.

Navigation with content description: --toc

All you get so far for navigation in the HTML file are generic section titles "part 1", "part 2", etc. that are hyperlinks which load the respective part of the video. You can get a text to the right of each number that describes the content of that video part and also get a meaningful title for the HTML page by using the --toc filename option (table of contents):

The file given must be a UTF-8-encoded plain-text file with a paragraph structure. Use any text editor (for instance MS Windows' notepad) to produce them. Paragraphs are separated simply by an empty line.

The first paragraph (paragraph 0) provides the title of the index.html page.
Subsequent paragraphs 1..N provide the content description for video parts 1..N.

Example:

This is the title

This is the description of video part 1. It is a longer one that
takes multiple lines. Those lines will be rendered as a flowing
paragraph of text on the HTML page.

This is the description of the second video part, number 2.

Like most pomalevi options, --toc has friendly defaults:

• --toc myslides-toc.txt will be assumed by default, but if myslides-toc.txt is not found, the generic toc will be produced instead.
• The toc file will be searched for in several places:
  • ./myslides-toc.txt, in the local directory
  • mydir/myslides-toc.txt, in the input file directory
  • mydir/toc/stoplogo.png, in the toc subdirectory of the input file directory.

Output directory: --out

So far, we have always used the friendly default to tell pomalevi where we want the output to end up: If the input file is mydir/myslides.wmv, the output will go to mydir/myslides/*.

If you don't want this, specifiy a target directory with --out:
pomalevi --out outputdir mydir/myslides.wmv.

Friendly defaults rough summary

Taking all of the above together, the explicit pomalevi call could be:
pomalevi --split-at ll:splitlogo.png --stop-at ll:stoplogo.png --toc mydir/myslides-toc.txt --out mydir/myslides mydir/myslides.wmv
but the following is equivalent, courtesy of the defaults:
pomalevi mydir/myslides.wmv

Overlapping Powerpoint export and pomalevi: waiting

• Powerpoint export takes a long time, pomalevi encoding also takes a long time. It would be nice if we could start pomalevi before Powerpoint has finished exporting.
  Consider it done!
• pomalevi will automatically wait until the given input file appears to have been exported completely and only then start the actual pomalevi work.

Encoding type and quality: --format

pomalevi can produce either *.mp4 video files (encoded with H.264 video and AAC audio) or *.webm video files (encoded with VP8 video and Opus audio).

webm encoding currently uses rather naive settings and is not recommended.

mp4 encoding is available with four different sets of settings, called q1 to q4, that produce different quality levels and file sizes.
q1 creates the smallest files with the lowest audio and video quality,
q4 creates the largest files with the highest quality.

These are selected using
--format mp4q1
--format mp4q2
--format mp4q3
--format mp4q4
--format webm

mp4q3 is the default.

How pomalevi works internally

pomalevi uses ffmpeg's find_rect filter to find all frames that contain the respective logo PNG content. It uses the time information of these frames to drive the splitting into parts and to feed the pomalevi player with the stop times for each part.

find_rect cannot cope with scaling or rotation of the target image, works only with a rectangular image, and it considers only a grayscale version of it with no alpha channel.

If you use a logo file mylogo.png, its grayscale derivative mylogo.pgm will appear in the output directory during encoding (and then disappear again).

Caveats

• On my machine, the MP4 files produced by PowerPoint's "Export" function are always broken: After a slide transition, when the new slide is already visible, the old one shortly reappears for varying lengths of time from a single frame to several tenths of a second.
  So I use "Save as" with target format WMV instead. That's sort of silly (because WMV is the inferior format) but at least it works.

• Because of how pomalevi works (see above), the search for stop logo or split logo may fail if the background of the logo is colored. There must be enough contrast between the logo color(s) and the background color when converted to grayscale.

• Because of how it works (see above), the search for stop logo or split logo may fail if the logo has transparent parts and is placed onto other
  material. The logo match is fuzzy, but expects at least an 80% match.

• Unless you place your logo precisely in the corner, fine details in the logo will make the match worse. Prefer simple logos.

TODO

Improvements waiting to be made:

• make demo.ppt
• command keywords encode, compress, patch, get-logos, get-demo.
• --ffmpeg-a, --ffmpeg-v to submit encoding options
• highlight current video in toc
• make pomalevi.css mobile-ready
• --favicon file: Name of a 32x32 pixel PNG file to be used as the favicon.

Versions

• 0.7, 2022-03-18
  • initial version, with most of the functionality: encode with splits and stops, basic CSS, TOC
• 0.8, 2022-04-28:
  • lots of small additions to functionality
  • obtain actual video resolution
  • modularized internal structure
  • friendly defaults for --split-at, --stop-at, --toc, --out.
• 0.9, 2022-04-29:
  • use static-ffmpeg Python package, no longer the system's ffmpeg
  • use Poetry build system and produce pomalevi.exe
• 1.0, 2022-05-06
  • add --format
  • add ppt/demo.pptx