1. One line description

A tool to generate a video with synchronized voice over from a slides deck.

2. Overview

This tool (called 'vwvo' which stands for 'Video With Voice Over') takes two input files (a PDF file containing a deck of slides and a TXT file containing what to say on each of them) and generates a video with synchronized voice over:

PDF file ------. 
(slides)        \
                 \     .-------.
                  +--->|vwvo.py|-----> Video file (with voice over)
                 /     '-------'
                /
TXT file ------' 
(what to say)

3. Information for users

3.1. Installation and usage

You don't need to install anything as you can run it directly from PyPI (and you will always get the latest version). For this, make sure you have 'ffmpeg' (a multimedia framework) and 'uv' (a python package manager) installed. Then simply run the 'vwvo' script like this:

$ uvx vwvo --help

...and read all the details.

NOTE 1: The first time you run it a lot of dependencies (~1 GiB) will be downloaded to the "uv" local cache.

NOTE 2: In case you prefer to install it locally (so that you don't need Internet access the next time you want to run it), run this:

$ uv tool install vwvo

...and from that point on you will be able to directly run vwvo like this:

$ vwvo --help

3.2. Example

The 'example' directory contains files 'slides.pdf' and 'script.txt' that you can use to test the tool:

$ uvx vwvo --slides path/to/slides.pdf --script path/to/script.txt

...and then play the resulting 'output/slides.mp4' video file. Enjoy!

4. Information for developers

4.1. Local development

To run locally, clone the repo and, from the top level folder, run this:

$ uv run vwvo

NOTE: The first time you run it a lot of dependencies (~1 GiB) will be downloaded to a ".venv" folder. As long as you don't delete it it will be reused on future invokations.

4.2. Running the code linter

Before merging new changes you must also check that the following command returns an empty list of warnings:

$ ruff check .

NOTE: You might need to install "ruff" first. If so, use you distro's package manager.

4.3. Distribution (PyPI)

Once you are ready to make a release:

1. Increase the "version" number in file "pyproject.toml"

2. Run the next command:

   $ uv build $ uv publish

3. Tell your users that a new version is available and that it will be automatically available when they run this:

   $ uvx run vwvo