pomalevi 1.0

Description:

pomalevi 1.0

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