#!/usr/bin/env python3 """ PPTX to SCORM 1.2 Converter, version 2.0 Turns a slide deck into a SCORM 1.2 package that any learning management system (LMS) can import: one image per slide, an HTML player, optional audio narration per slide, and optional multiple-choice quiz questions that are scored and reported to the LMS. Usage: python pptx_to_scorm.py path/to/course_folder [-o output.zip] [--dpi 200] Course folder: course_folder/ slides.pdf Your deck exported to PDF (preferred; any name works) slides.pptx Used only when there is no PDF; needs LibreOffice course.json Optional: title, passing score, quizzes, audio audio/ Optional: narration files referenced by course.json Requirements: Python 3.8+, Poppler (pdftoppm). LibreOffice only for .pptx input. Copyright (c) 2026 Virabelo, Inc. Released under the MIT License (see LICENSE). Shared by Loomforth: https://loomforth.ai/tools/pptx-to-scorm/ """ import argparse import html import json import os import re import shutil import subprocess import sys import tempfile import unicodedata import zipfile from pathlib import Path from xml.sax.saxutils import escape as xml_escape __version__ = "2.0.0" AUDIO_EXTENSIONS = (".mp3", ".wav", ".ogg", ".m4a") DEFAULT_TITLE = "Training Course" DEFAULT_ACCENT = "#e94560" class CourseError(Exception): """A problem with the course folder that the author needs to fix.""" # --------------------------------------------------------------------------- # Finding inputs and tools # --------------------------------------------------------------------------- def _visible_files(course_dir, pattern): return sorted( p for p in course_dir.glob(pattern) if p.is_file() and not p.name.startswith((".", "~$")) ) def find_slide_source(course_dir): """Return the deck to convert: the first PDF, otherwise the first PPTX.""" for pattern in ("*.pdf", "*.pptx"): found = _visible_files(course_dir, pattern) if found: if len(found) > 1: print(" WARNING: more than one %s file found; using %s" % (pattern[1:], found[0].name)) return found[0] raise CourseError( "No .pdf or .pptx file found in %s. Export your slides to PDF " "(File > Save As > PDF) and put the PDF in the course folder." % course_dir) def find_soffice(): """Locate LibreOffice's command-line program on Linux, macOS or Windows.""" for name in ("soffice", "libreoffice"): path = shutil.which(name) if path: return path candidates = [ "/Applications/LibreOffice.app/Contents/MacOS/soffice", r"C:\Program Files\LibreOffice\program\soffice.exe", r"C:\Program Files (x86)\LibreOffice\program\soffice.exe", ] for candidate in candidates: if os.path.exists(candidate): return candidate return None def require_pdftoppm(): path = shutil.which("pdftoppm") if not path: raise CourseError( "pdftoppm was not found. Install Poppler:\n" " macOS: brew install poppler\n" " Ubuntu/Debian: sudo apt install poppler-utils\n" " Windows: install a Poppler build and add its bin folder to PATH") return path # --------------------------------------------------------------------------- # Slide conversion # --------------------------------------------------------------------------- def pptx_to_pdf(pptx_path, work_dir): """Convert a .pptx to PDF with LibreOffice. Returns the PDF path.""" soffice = find_soffice() if not soffice: raise CourseError( "%s is a PowerPoint file and LibreOffice was not found. Either export " "the deck to PDF yourself (recommended; it also lets you check every " "slide) or install LibreOffice." % pptx_path.name) print(" Converting %s to PDF with LibreOffice..." % pptx_path.name) # A private profile lets the conversion run even if LibreOffice is open. profile = (work_dir / "lo_profile").resolve().as_uri() result = subprocess.run( [soffice, "-env:UserInstallation=" + profile, "--headless", "--convert-to", "pdf", "--outdir", str(work_dir), str(pptx_path)], capture_output=True, text=True) pdf_path = work_dir / (pptx_path.stem + ".pdf") if result.returncode != 0 or not pdf_path.exists(): detail = (result.stderr or result.stdout or "").strip() raise CourseError("LibreOffice could not convert %s.%s" % ( pptx_path.name, ("\n" + detail) if detail else "")) return pdf_path def pdf_to_images(pdf_path, slides_dir, dpi): """Render every PDF page to a JPEG. Returns file names in page order.""" pdftoppm = require_pdftoppm() print(" Rendering %s at %d DPI..." % (pdf_path.name, dpi)) result = subprocess.run( [pdftoppm, "-jpeg", "-jpegopt", "quality=88", "-r", str(dpi), str(pdf_path), str(slides_dir / "slide")], capture_output=True, text=True) if result.returncode != 0: raise CourseError("pdftoppm could not read %s.\n%s" % ( pdf_path.name, (result.stderr or "").strip())) def page_number(path): match = re.search(r"-(\d+)$", path.stem) return int(match.group(1)) if match else 0 images = sorted(slides_dir.glob("slide-*.jpg"), key=page_number) if not images: raise CourseError("No slide images were produced from %s." % pdf_path.name) print(" Rendered %d slides" % len(images)) return [p.name for p in images] # --------------------------------------------------------------------------- # course.json # --------------------------------------------------------------------------- def load_course_config(course_dir): config_path = course_dir / "course.json" if not config_path.exists(): print(" No course.json found; using defaults (no quizzes, no audio)") return {} try: with open(config_path, encoding="utf-8-sig") as handle: config = json.load(handle) except json.JSONDecodeError as exc: raise CourseError("course.json is not valid JSON: line %d, column %d: %s" % (exc.lineno, exc.colno, exc.msg)) if not isinstance(config, dict): raise CourseError("course.json must contain a JSON object ({ ... }).") print(' Loaded course.json: "%s"' % config.get("title", DEFAULT_TITLE)) return config def make_identifier(text): """A stable, XML-safe identifier, so re-uploads replace the same course.""" text = unicodedata.normalize("NFKD", str(text)).encode("ascii", "ignore").decode("ascii") ident = re.sub(r"[^A-Za-z0-9_.-]+", "_", text).strip("_.-").lower() if not ident or not (ident[0].isalpha() or ident[0] == "_"): ident = "course_" + ident return ident[:80] def validate_config(config, course_dir, slide_count): """Check course.json against the deck. Returns a cleaned configuration.""" errors, warnings = [], [] title = str(config.get("title") or DEFAULT_TITLE).strip() description = str(config.get("description") or "").strip() identifier = config.get("identifier") or make_identifier( config.get("title") or course_dir.name) identifier = str(identifier) if not re.match(r"^[A-Za-z_][A-Za-z0-9_.-]*$", identifier): errors.append('"identifier" may use only letters, digits, "_", "." and "-", ' "and must start with a letter.") passing = config.get("passing_score", 80) if isinstance(passing, bool) or not isinstance(passing, (int, float)) \ or not 0 <= passing <= 100: errors.append('"passing_score" must be a number from 0 to 100.') passing = 80 accent = str(config.get("accent_color") or DEFAULT_ACCENT) if not re.match(r"^#[0-9A-Fa-f]{6}$", accent): errors.append('"accent_color" must look like "#1f7a5c".') accent = DEFAULT_ACCENT slides_in = config.get("slides") or {} if not isinstance(slides_in, dict): errors.append('"slides" must be an object keyed by slide number, like {"1": {...}}.') slides_in = {} audio_files = {} # source path -> name inside the package used_names = set() slides = {} root = course_dir.resolve() for key, entry in slides_in.items(): where = 'slides["%s"]' % key try: number = int(key) except (TypeError, ValueError): errors.append("%s: slide keys must be numbers like \"1\"." % where) continue if not 1 <= number <= slide_count: warnings.append("%s refers to a slide that does not exist (the deck has %d)." % (where, slide_count)) continue if not isinstance(entry, dict): errors.append("%s must be an object." % where) continue clean = {} if entry.get("audio"): source = (course_dir / str(entry["audio"])).resolve() if root != source and root not in source.parents: errors.append("%s: audio must be inside the course folder." % where) elif not source.is_file(): errors.append("%s: audio file not found: %s" % (where, entry["audio"])) elif source.suffix.lower() not in AUDIO_EXTENSIONS: errors.append("%s: audio must be one of %s." % (where, ", ".join(AUDIO_EXTENSIONS))) else: if source not in audio_files: base = re.sub(r"[^A-Za-z0-9._-]+", "_", source.stem).strip("_") or "audio" name = base + source.suffix.lower() counter = 2 while name in used_names: name = "%s_%d%s" % (base, counter, source.suffix.lower()) counter += 1 used_names.add(name) audio_files[source] = name clean["audio"] = "audio/" + audio_files[source] quiz = entry.get("quiz") if quiz is not None: if not isinstance(quiz, dict): errors.append("%s.quiz must be an object." % where) else: question = str(quiz.get("question") or "").strip() choices = quiz.get("choices") correct = quiz.get("correct") if not question: errors.append("%s.quiz needs a \"question\"." % where) if not isinstance(choices, list) or len(choices) < 2 \ or not all(str(c).strip() for c in choices): errors.append("%s.quiz needs at least two non-empty \"choices\"." % where) choices = [] elif len(choices) > 6: warnings.append("%s.quiz has %d choices; 2 to 4 read best." % (where, len(choices))) if choices and (isinstance(correct, bool) or not isinstance(correct, int) or not 0 <= correct < len(choices)): errors.append("%s.quiz \"correct\" must be the zero-based index of the " "right choice (0 for the first)." % where) if question and choices and isinstance(correct, int) \ and not isinstance(correct, bool) and 0 <= correct < len(choices): clean["quiz"] = { "question": question, "choices": [str(c) for c in choices], "correct": correct, } if quiz.get("explanation"): clean["quiz"]["explanation"] = str(quiz["explanation"]) slides[number] = clean for message in warnings: print(" WARNING: " + message) if errors: raise CourseError("course.json has %d problem%s:\n - %s" % ( len(errors), "" if len(errors) == 1 else "s", "\n - ".join(errors))) return { "title": title, "description": description, "identifier": identifier, "passing_score": passing, "require_audio_completion": bool(config.get("require_audio_completion", False)), "accent_color": accent, "slides": slides, "audio_files": audio_files, } # --------------------------------------------------------------------------- # Player # --------------------------------------------------------------------------- PLAYER_TEMPLATE = r""" {{TITLE}}

{{TITLE}}

""" def script_safe_json(data): """JSON that is safe to place inside a