Scriptify

Transform lecture slides into comprehensive study materials using LLM-powered generation.

I personally prefer learning with a proper lecture script rather than just slides. After building talk-to-text, which transforms lecture recordings into websites, PDFs, and markdown files, the next logical step was to transform that content into structured lecture scripts. Scriptify takes either simple lecture slides or the JSON output from talk-to-text and generates flashcards, Quarkdown documents, or markdown lecture scripts — all enhanced with RAG (Retrieval-Augmented Generation) to incorporate your reference materials.

Features

• Multiple Output Formats

  • Quarkdown — Structured documents in Quarkdown format
  • Flashcards — Study cards for active recall learning
  • Markdown — Clean lecture scripts in markdown format

• Flexible Input Sources

  • JSON files from talk-to-text
  • Markdown lecture notes
  • PDF slide decks

• RAG-Enhanced Generation

  • Incorporate reference materials (PDFs, markdown) for richer content
  • Multi-language support with automatic language detection
  • Configurable source retrieval thresholds

• Multi-Provider LLM Integration

  • Support for OpenAI and Ollama providers
  • Compatible with OpenAI-compatible endpoints (OpenRouter, custom APIs)
  • ChromaDB vector store for efficient similarity search
  • Configurable embeddings (OpenAI or Ollama)

Installation

Prerequisites

• Python 3.11 or higher
• Poetry for dependency management

Setup

# Clone the repository
git clone https://github.com/AntonKluge/scriptify.git
cd scriptify

# Install dependencies
poetry install

# Configure environment variables
cp .env.example .env
# Edit .env with your API keys

Environment Variables

# Required when using --provider openai or --embedding-provider openai
OPENAI_API_KEY=your_openai_api_key

Note: When using the default Ollama provider locally, no API key is required. For OpenAI-compatible endpoints (like OpenRouter), set OPENAI_API_KEY to your provider's API key and use --api-base to specify the endpoint.

Usage

Basic Usage

# Generate Quarkdown document using local Ollama (default)
scriptify --tag "database-lecture" \
  --input lecture_01.json \
  --output lecture_01.qd \
  --format quarkdown

# Generate flashcards using OpenAI
scriptify --tag "ml-course" \
  --input notes.md \
  --output flashcards.md \
  --format flashcards \
  --provider openai

# Generate markdown script using a custom OpenAI-compatible endpoint
scriptify --tag "algorithms" \
  --input slides.pdf \
  --output script.md \
  --format markdown \
  --provider openai \
  --api-base "https://your-api-endpoint.com" \
  --model "your-model-name"

With Reference Materials

Enhance generated content by providing a directory of reference materials (PDFs, markdown files):

scriptify --tag "databases" \
  --input lecture_01.json \
  --output lecture_01.qd \
  --format quarkdown \
  --references ./references/databases \
  --max-sources 5 \
  --source-threshold 0.3

CLI Options

Option	Short	Description
--tag	-t	Tag to associate with the content (required)
--input	-i	Path to input file (required)
--output	-o	Path to output file (required)
--format	-f	Output format: quarkdown, flashcards, markdown (required)
--references	-r	Directory containing reference materials
--max-sources	-s	Maximum sources to retrieve (default: 5, min: 1)
--source-threshold	-st	Similarity threshold for sources (default: 0.3, range: 0.0-1.0)
--provider	-p	LLM provider: openai, ollama (default: ollama)
--api-base		Custom API base URL for the LLM
--model	-m	Model name (uses provider default if not set)
--embedding-provider		Provider for embeddings (defaults to --provider)
--embedding-model		Embedding model name
--embedding-api-base		Custom API base URL for embeddings
--debug	-d	Enable debug logging
--verbose	-v	Enable verbose output

Development

# Run the application
poetry run python -m scriptify --help

# Run tests with coverage
poetry run pytest

# Code quality checks
poetry run ruff check          # Linting
poetry run ruff format         # Formatting
poetry run pyright             # Type checking

# Run all pre-commit hooks
poetry run pre-commit run --all-files

# Security analysis
poetry run bandit -r src/
poetry run safety check

License

MIT License — see LICENSE for details.

Related Projects

• talk-to-text — Transform lecture recordings into structured content
• Quarkdown — Markdown-based document format