SlidesToLectures

Turn a directory of slideshow PDFs into:

• Bookmarked PDFs: a copy of each deck with a [N] Slide title bookmark per topic, plus one combined PDF of every deck.
• Slide text: a Markdown file per deck with one ## [N] Title section per slide, from the PDF's text layer or transcribed from slide images by Claude.
• Lecture transcripts: a spoken, word-for-word lecture per deck, written by Claude to cover every point on every slide.
• Narrated audio: an MP3 per lecture with a chapter per slide, using Speechify text-to-speech.

Slides are numbered across the whole set (from the numbers printed on them when present), so bookmarks, text, lectures and audio chapters all line up.

Install

uv tool install "slidestolectures[tts]"

or pip install "slidestolectures[tts]". Leave off [tts] if you don't need audio. Requires Python 3.11+.

• The vision and lecture steps call the Claude API: set ANTHROPIC_API_KEY.
• The tts step needs SPEECHIFY_API_KEY and ffmpeg on your PATH.

Quick start

slides-to-lectures toc --input slides       # out/pdfs/ and out/combined/
slides-to-lectures text --input slides      # out/text/   (or: vision, to transcribe slide images with Claude)
slides-to-lectures lecture                  # out/lectures/
slides-to-lectures tts                      # out/audio/

Every command takes --input DIR (the slideshow PDFs), --out DIR (default out), --plugin and --config. Source PDFs are never modified. Run slides-to-lectures <command> --help for each command's options:

toc, text and vision accept deck names to process only some decks; lecture and tts accept Markdown files.

Configuration

Put a slidestolectures.toml in the directory you run from (or pass --config), so you don't have to repeat options:

plugin = "my_plugin.py"   # optional, see below
input = "slides"
output = "out"

[output_dirs]             # optional: put individual outputs elsewhere
pdfs = "bookmarked"

[settings]                # plugin settings
course = "Introduction to Biology (BIO 101)"
audience = "a class of first-year undergraduates"
footer = "Example University"

Settings:

Plugins

When your slides need more than settings, such as particular filenames, deck titles, or fixes for slides whose title is an image, write a plugin: a subclass of slidestolectures.Plugin that overrides the hooks you need. Call super() to wrap the default behavior.

from slidestolectures import Plugin


class BiologyPlugin(Plugin):
    course = "Introduction to Biology (BIO 101)"

    def deck_title(self, path, doc):
        return path.stem.split(" - ", 1)[-1]  # "Week 3 - Cell Division" -> "Cell Division"

    def slide_title(self, deck, number, detected):
        if number == 42:
            return "The Krebs Cycle"  # this slide's title is an image
        return super().slide_title(deck, number, detected)

Use it with --plugin my_plugin.py, --plugin my_plugin.py:BiologyPlugin, --plugin package.module:BiologyPlugin, or plugin = ... in the config. See examples/example_plugin.py.

Development

uv sync --all-extras
uv run pytest
uv run ruff check .

With mise, mise run install, mise run test, mise run lint and mise run build do the same.

Releasing

Bump version in pyproject.toml, then publish a GitHub release tagged v<version>. The Release workflow builds the package and publishes it to PyPI with trusted publishing.

License

MIT