User guide¶

The reference for installing, configuring and running SlideStream. For step-by-step recipes see Use cases; for every voice, picture, LLM, presenter and design option see Providers.

Install¶

pip install "slide-stream[all]"

Python 3.10 or newer. FFmpeg comes with the package (through moviepy), so a system install is optional; SlideStream uses one on your PATH if present.

[all] is everything. Smaller installs:

Extra	Adds
(none)	Markdown and PowerPoint input, text-card slides, gTTS voice, `.mp4` and `.pptx` output
`local-tts`	Kokoro, the offline voice
`serve`	The web UI (`slide-stream serve`); includes PDF and Word import
`import`	PDF and Word input for `draft`
`presenton`	Designed slides: Presenton, `--preserve-style`, `--slides-pdf`
`openai`, `claude`, `gemini`, `groq`, `elevenlabs`	That provider's SDK
`all-ai`	Every cloud provider SDK, without the offline voice or web UI (for lean servers)

Quote the package name ("slide-stream[all]") so your shell doesn't expand the brackets. slide-stream doctor <deck> names any extra a configured provider still needs.

Other ways to run it:

Desktop app for macOS, Windows and Linux: a window around the web UI that installs and updates the engine itself. See the releases page.
Docker for hosting the web UI for others: see deploy/README.md.

Configuration¶

Settings come from YAML files, merged in layers; later layers win (ADR-0002):

Built-in defaults.
~/.slidestream.yaml (or .yml): personal settings shared by every project, such as server URLs and key references.
./slidestream.yaml (or .yml) in the current folder, or the file given with --config: settings for this deck.
Command-line flags, for one run.

slide-stream init           # a minimal file that works with no keys
slide-stream init --full    # every provider and setting, commented

The full reference is also in slidestream.example.yaml.

Secrets stay out of the files. A value written as "${VAR}" is read from the environment variable VAR, and SlideStream warns if it is unset. Providers also read their standard variables directly (OPENAI_API_KEY, ANTHROPIC_API_KEY, GEMINI_API_KEY, GROQ_API_KEY, ELEVENLABS_API_KEY, PEXELS_API_KEY, UNSPLASH_ACCESS_KEY, DID_API_KEY, PRESENTON_API_KEY). The command line does not read .env files.

Settings¶

providers: chooses engines (Providers). settings: controls the output:

Setting	Default	Meaning
`video.resolution`	`[1920, 1080]`	Frame size
`video.fps`	`24`	Frames per second
`video.transition_seconds`	`0`	Crossfade between slides (`--transition`)
`video.slide_duration_padding`	`1.0`	Seconds added after each slide's narration
`video.default_slide_duration`	`5.0`	Length of a slide with no narration
`video.bullets_overlay`	`true`	Show bullets beside generated pictures
`image.bg_color`, `image.font_color`	`black`, `white`	Colours of text-card slides
`image.title_font_size`, `image.content_font_size`	`100`, `60`	Text sizes on text cards
`narration.target_seconds`	none	Aim for this many seconds of speech per slide (`--narration-seconds`)
`narration.wpm`	`150`	Speaking rate used for that estimate
`avatar.position`	`bottom-right`	Presenter corner
`avatar.size`	`0.28`	Presenter circle, as a share of the frame height
`avatar.slides`	`all`	Which slides show the presenter (`--avatar-slides`)
`avatar.reuse_clip`	`false`	Render one presenter clip and loop it (`--reuse-avatar`)
`voice_floor`	`auto`	Local fallback voice: `auto`, `kokoro` or `gtts`
`strict`	`false`	Fail instead of falling back when a chosen provider fails (`--strict`)
`temp_dir`, `cleanup`	`temp_files`, `true`	Working folder, and whether to delete it afterwards

Decks¶

Markdown¶

Each # heading starts a slide. Everything under it until the next # heading belongs to that slide.

---
title: optional front matter, ignored
---

# Hash Tables

- Find a value without searching
- **Week 6**, Data Structures

# A Hash Function

```python
def bucket_for(key: str, n: int) -> int:
    return hash(key) % n
```

## Notes on this slide

| Operation | List | Hash table |
|---|---|---|
| Look up | O(n) | O(1) |

Bullets, paragraphs, quotes and ## sub-headings all become slide content, in order.
Fenced code blocks keep their indentation and are drawn in a monospace font with syntax colouring; give the language after the fence. A # inside a code block never starts a slide.
Tables are drawn one row per line.
Pictures: a line such as ![](images/slide_1.png) becomes the slide's picture instead of narrated text (this is what enrich writes).
Separator style: a deck can instead separate slides with lines of --- (Marp style), one heading per slide.

Markdown slides have no speaker notes. Provide narration with an LLM, or with a --script file.

PowerPoint¶

slide-stream create slides.pptx talk.mp4 reads each slide's title, text and pictures, and its speaker notes, which become the narration source. By default the video uses SlideStream's own slide layout; add --preserve-style to keep the deck's look (needs LibreOffice).

Notes are used when they read as narration. Placeholders ("Click to add notes") and presenter cues ("Discuss the plan") are ignored, and bracketed stage directions such as [pause] are removed before speaking.

Narration¶

Per slide, SlideStream uses the first of these that applies:

A block from --script FILE: one block per slide, separated by lines of ---, spoken exactly as written.
Speaker notes, spoken exactly as written, with --verbatim-notes.
With an LLM configured: notes cleaned and fitted to the target length; else the slide content turned into what a presenter would say; else a picture-only slide described by a vision model; else a short introduction of the title.
With no LLM: the title, content and usable notes, read as written.

--narration-seconds 30 aims for about 30 seconds per slide.

Commands¶

Every command has --help.

`create IN OUT`¶

Renders a deck. The output's extension picks the mode:

.mp4: the full pipeline (narration, voice, pictures, presenter, video).
.pptx: an editable PowerPoint with the pictures and the narration in the speaker notes. No voice, presenter or video work.

Option	Does
`-c, --config FILE`	Use this config file as the project layer
`--llm-provider`, `--llm-model`	Narration writer for this run
`--narration-seconds N`	Target speech per slide
`--script FILE`	Narration from a script, one block per slide
`--verbatim-notes`	Speak speaker notes as written
`--tts-provider`, `--tts-base-url`, `--voice`	Voice for this run
`--voice-sample FILE`	Clone this recording for this run
`--avatar / --no-avatar`	Show the presenter
`--avatar-slides SPEC`	`all`, `none`, `first`, `last`, `first,last`, `1,3,5`, `every:3`
`--reuse-avatar`	One presenter clip looped across the deck
`--transition SECONDS`	Crossfade between slides
`--strict`	Fail instead of falling back
`--dry-run`, `--fail-on-warn`	Report only, as `doctor` does
`--preserve-style`	Keep a `.pptx` input's own design in the video
`--slides-pdf FILE`	Use a PDF's pages as the video frames
`--template NAME`	Designed slides from Presenton (experimental)
`--presenton-url`, `--presenton-api-key`, `--save-deck`	Presenton connection and where to save its deck

`doctor IN`¶

A preflight that renders nothing. It reports the slide count, slides without notes, stage directions that would be spoken, voice-sample length, picture resolution, presenter and engine mismatches, missing packages or keys, and estimates video length, cost and render time. --fail-on-warn exits non-zero on any warning, for CI. create --dry-run gives the same report using create's options.

`draft DOC [OUT.md]`¶

Turns a .txt, .md, .pdf, .docx or .pptx file into a Markdown deck with an LLM. --slides N sets the count. It never renders; edit the deck, then run create. PDF and Word need the import extra (in [all]).

`enrich IN OUT_DIR`¶

Adds a picture to every slide and writes a new deck: Markdown plus an images/ folder, and a .pptx with --pptx. --notes all writes AI speaker notes for every slide, --notes fill only where notes are missing; existing notes are kept otherwise. The result round-trips: create OUT_DIR/deck.pptx narrates from those notes.

`scan DIR`¶

Renames a folder of pictures to descriptive names with a vision model, so the local picture provider can match them to slides. It previews by default; --apply renames.

`presenton IN OUT`¶

Designs a deck with a running Presenton (experimental) and writes a .pptx or .pdf with the narration in the speaker notes, plus a fidelity report. See Use cases.

`serve`¶

The web UI: upload a deck, an optional voice sample and photo, render and download. Locally it binds to 127.0.0.1 and opens a browser. For a server, see deploy/README.md. Uploaded voice samples and photos are deleted after the render.

Others¶

init [FILE] [--full]: write a config file.
providers: list providers and whether each is usable.
voices: list voices on the configured voice server.
avatars: list the built-in mascots.

Troubleshooting¶

Start with slide-stream doctor deck.md. It names missing packages, keys and server URLs, with the fix.

A provider "is not available". Its package, key or base_url is missing. Without --strict SlideStream falls back and says so; check slide-stream providers.
The wrong voice. A voice server failed and the voice floor took over; the end-of-run summary counts such slides. Use --strict when the exact voice matters.
The first Kokoro run is slow. It downloads its model (about 340 MB) once, to ~/.cache/slide-stream/kokoro/.
"No FFmpeg found". The bundled copy is missing, which means a broken install; reinstall slide-stream, or install FFmpeg yourself.
A slide count mismatch with designed slides. The designed deck or PDF must have the same number of slides as the source, or narration would drift; SlideStream stops instead.
--preserve-style fails. It needs LibreOffice (soffice) on your PATH, or export the PDF yourself and use --slides-pdf.