Welcome!

toc.yml Reference

This page is part of the advanced authoring path — a special case the Lupo team sets up on request. Most people don't need it.

TL;DR; toc.yml is the file that drives a hand-authored project: course settings at the top, then a chapters list, each with sections. Every key below is one you write yourself, so this page covers exactly what each key does — not what happens inside Lupo once you set it.

Before you start

See Authoring in Markdown for the project structure toc.yml sits inside.

Course-level keys

A missing required key stops the build. Keys marked "no" fall back to the default shown; a value out of range is reported as a warning and the build goes on.

Key Type Default Required What it does
name string — yes The course's display name — used in the completion email subject and elsewhere the course is referenced by name.
final bool — yes true for a final-quality run, false for a draft pass.
email string — yes Comma-separated address(es) the completion email goes to.
captions string — yes Comma-separated language codes to generate caption files for (e.g. es,fr). Empty string = none.
translate string — yes Comma-separated language codes to generate translated audio tracks for. Empty string = none.
transcript bool — yes true attaches a transcript to the completion email.
slides bool — yes true attaches slide images to the completion email.
chapters list — yes The ordered list of chapters — see below.
speaker string default voice no The default narration voice for the whole course (e.g. Aria). Leaving it out is reported as a warning and the default voice is used.
speed float 1.0 no Speaking speed, 0.5–2.0.
pitch float 1.0 no Speaking pitch, 0.5–1.5.
style string default no The narrator's speaking style — an emotion or tone, e.g. cheerful or newscast. This is unrelated to visual appearance; see Styling and themes for how the look of a slide is set.
leading_silence float 1 no Seconds of silence before narration starts, 0–2.
trailing_silence float 0 no Seconds of silence after narration ends, 0–2.
audio bool false no true attaches the audio files to the completion email.
resolution int 720 no Output video resolution — 720 (1280×720) or 1080 (1920×1080).
scorm bool false no true also produces a SCORM package alongside the video.
scorm-video string file no How video is embedded in the SCORM package: file (bundled) or url (linked).
zipOutput bool false no true attaches a zip of links to the finished videos and captions to the completion email — see Video bundle zip below. Only produced on a successful run.
per_slide bool false no true generates one narration request per slide instead of per section.
generateIfNoNotes bool unset no true generates video even for a slide with no speaker notes attached.

Chapter-level keys

Set inside each item of the course's chapters list. Any voice or timing key left out falls back to the course-level value.

Key Type Default What it does
name string — Chapter display name. The key must be present; an empty name is replaced by the chapter's number.
sections list — The ordered list of sections in this chapter — required; see below.
combine bool false true merges every section in this chapter into a single video file.
speaker string course Chapter-level voice override.
speed float course Chapter-level speed override.
pitch float course Chapter-level pitch override.
emotion string course Chapter-level style/emotion override.
leading_silence float course Chapter-level leading-silence override.
trailing_silence float course Chapter-level trailing-silence override.

Section-level keys

Set inside each item of a chapter's sections list. Voice and timing keys left out fall back to the chapter's value.

Key Type Default What it does
name string — Section display name. The key must be present; an empty name is replaced by the section's number.
href string — Path to the section's Markdown narration file, relative to the project. One of href or href-pptx is required; when both are present, href wins. A path or URL ending in .pptx is treated as href-pptx.
href-pptx string — Path or URL of a PPTX file, as an alternative to href. An https:// link — including a Google Slides link — is accepted.
generate bool true false skips this section.
speaker string chapter Section-level voice override.
speed float chapter Section-level speed override.
pitch float chapter Section-level pitch override.
emotion string chapter Section-level style/emotion override.
leading_silence float chapter Section-level leading-silence override.
trailing_silence float chapter Section-level trailing-silence override.
videoZip string — Path to an external zip of pre-made video files to use for this section instead of generating one.
embeddedVideos list auto-detected Embedded video file names found in the PPTX. You rarely set this yourself.
videoMapping dict auto-detected Which slide each embedded video maps to. You rarely set this yourself.
externalVideos list from videoZip External video paths, once videoZip has been extracted.
slides_folder string auto Overrides the folder slide images are extracted into.

Video bundle zip

With zipOutput: true, a successful run attaches a zip to the completion email containing:

  • playlist.html — a page listing every section with a link to its video and its available caption languages.
  • urls.txt — the same links as a plain-text list, grouped by chapter.

The zip contains links, not the video files themselves — recipients download each file individually from the links provided.

Minimal example

name: My Course
final: false
email: ops@example.com
captions: ""
translate: ""
transcript: false
slides: false
speaker: Aria
chapters:
  - name: Chapter 1
    sections:
      - name: Introduction
        href: chapter1/introduction.md

Full example, every optional key set

name: My Course
final: true
email: ops@example.com, manager@example.com
captions: es,fr
translate: de
transcript: true
slides: true
audio: false
resolution: 1080
scorm: false
scorm-video: url
zipOutput: true
per_slide: false
generateIfNoNotes: false
speaker: Aria
speed: 1.0
pitch: 1.0
style: cheerful
leading_silence: 0
trailing_silence: 1
chapters:
  - name: Chapter 1
    combine: false
    sections:
      - name: Section 1.1
        href: chapter1/section1.md
      - name: Section 1.2
        href-pptx: chapter1/section2.pptx
  - name: Chapter 2
    speaker: Guy
    sections:
      - name: Section 2.1
        href: chapter2/section1.md
        generate: false

Where to go next