Skip to content

README.md

Latest commit

 

History

History
237 lines (186 loc) · 8.47 KB

README.md

File metadata and controls

237 lines (186 loc) · 8.47 KB

Teghrim Campaign Management System

An AI-powered pipeline for transforming tabletop RPG session recordings into structured, searchable campaign knowledge. This system automates the journey from raw audio to a comprehensive campaign database synchronized with Kanka.io.

Overview

This is a Pathfinder 2e Remastered campaign set in the homebrew world of Septerra. The system processes game session audio through multiple AI-powered stages:

Processing Pipeline

  1. Audio Recording → Raw MP3 files (session-recordings/YYMMDD_####.mp3)
  2. Transcription → Timestamped transcripts (transcripts/YYYY-MM-DD.md)
  3. Digest Creation → Structured event logs (entities/notes/digest-YYYY-MM-DD.md)
  4. Entity Extraction → Update entity files from digest information
  5. Session Summaries → Narrative journals (entities/journals/session-summary-YYYY-MM-DD.md)
  6. Kanka Sync → Bidirectional synchronization with online campaign

Quick Start

Prerequisites

# Install Python dependencies
pip install -r scripts/requirements.txt

# Install system dependency (required for audio processing)
# Linux
apt-get install ffmpeg
# macOS
brew install ffmpeg

Required API Keys

Set these environment variables:

  • ELEVEN_API_KEY - For audio transcription and generation
  • OPENAI_API_KEY - For image generation
  • OPENAI_ORG_ID - OpenAI organization ID
  • KANKA_TOKEN - For campaign database sync
  • KANKA_CAMPAIGN_ID - Your Kanka campaign ID

Core Workflow Commands

# Get overview of all entities (with IDs for linking)
python scripts/get_entity_overview.py

# Process new audio files
python scripts/transcribe_audio.py

# Pull from Kanka and reconcile any conflicts
python scripts/pull_from_kanka.py
# For campaign reset scenarios, preserve local changes:
python scripts/pull_from_kanka.py --preserve-local

# Find what needs to be pushed
python scripts/find_local_changes.py

# Push changes to Kanka
python scripts/push_to_kanka.py entities/characters/moradin.md
# Or push all changes with confirmation
python scripts/push_to_kanka.py --all

Content Generation Commands

# Generate audiobook from narrative text
python scripts/generate_audiobook.py narrative.txt -o output.mp3 -c 15 -t "Chapter Title"

# Generate podcast from script (requires HOST: and GUEST: labels)
python scripts/generate_podcast.py script.txt -o output.mp3

# Generate image from prompt file
python scripts/generate_image.py prompt.txt -o output.png -t "Custom Title"

Slash Commands (in Claude)

For AI-assisted workflows, use these commands:

  • /project:process-audio - Transcribe audio files
  • /project:create-digests - Create digest from first unprocessed transcript
  • /project:update-entities - Extract entities from first unprocessed digest
  • /project:generate-session-summaries - Create journal entries for sessions
  • /project:pull-from-kanka - Pull and auto-reconcile conflicts
  • /project:push-to-kanka - Push all local changes
  • /project:add-entity-links - Add entity cross-references

Project Structure

teghrim/
├── session-recordings/ # Raw MP3 recordings (YYMMDD_####.mp3)
├── transcripts/        # Timestamped session transcripts (YYYY-MM-DD.md)
├── entities/           # Local entity database (syncs with Kanka)
│   ├── characters/     # PCs, NPCs, deities, dramatis personae
│   ├── locations/      # Places, regions, landmarks
│   ├── organizations/  # Factions, guilds, governments
│   ├── races/          # Ancestries and cultures
│   ├── creatures/      # Monsters and creature types
│   ├── quests/         # Missions and objectives
│   ├── notes/          # Including digests and GM notes
│   └── journals/       # Including session summaries
├── .claude/            
│   └── commands/       # Slash command implementations
├── references/         # Campaign setting PDFs
├── scripts/            # Python automation tools
└── docs/               # Process documentation

Entity Management

The system maintains a local markdown database that syncs bidirectionally with Kanka.io:

Entity File Structure

---
name: Moradin
entity_id: 123456    # Kanka ID (absent until first push)
type: Deity          # Specific type from metadata.json
tags: ["Greater Deity", "Dwarf Pantheon"]  # From controlled vocabulary
is_hidden: false     # true = GM only
created: '2024-12-30T10:00:00+00:00'
updated: '2024-12-31T15:30:00+00:00'
---

# Moradin

The Forge Father and chief deity of the dwarven pantheon, Moradin represents creation, smithing, and protection.

## Description
Moradin appears as a stern-faced dwarf with a magnificent beard...

## Notable History
- **The First Forging**: Created the dwarven race from precious metals
- **The Godswar**: Led dwarven pantheon in the ancient divine conflict

## Current Status
Actively worshipped across all dwarven settlements...

Entity Linking

Entities reference each other using Kanka's syntax:

  • [entity:123456] - Link with entity's name
  • [entity:123456|custom text] - Link with custom display text
  • Link first mention per paragraph for readability

Entity Posts

Additional notes attached to entities as separate files:

entities/characters/moradin/secret-of-eternal-flame.md

Sync Workflow

  1. Pull: pull_from_kanka.py fetches remote changes
    • Creates .local.md and .kanka.md files when conflicts exist
  2. Reconcile: AI-assisted merge preserving content from both versions
  3. Push: push_to_kanka.py uploads changes
    • Adds entity_id to new entities
    • Updates timestamps

Writing Guidelines

  • Style: Wikipedia-like, in-world perspective
  • Updates: Add to history, never delete
  • Overview: Keep current state description evergreen
  • Tags: Use controlled vocabulary from entities/metadata.json
  • Special Tags:
    • "Major Dramatis Personae" - Key story NPCs
    • "Minor Dramatis Personae" - Supporting NPCs

Scripts Reference

Audio Processing

  • transcribe_audio.py - Convert MP3 to text with speaker identification
    • Handles files >2 hours by auto-splitting
    • Groups multi-part sessions automatically

Content Generation

  • generate_audiobook.py - Text-to-speech audiobook creation
  • generate_podcast.py - Multi-voice podcast generation
  • generate_image.py - AI image generation from prompts

Entity Management

  • get_entity_overview.py - List all entities with IDs and player mappings
  • pull_from_kanka.py - Sync from Kanka to local (handles pagination)
    • --preserve-local - Keep local changes during campaign resets
  • push_to_kanka.py - Upload local changes to Kanka
    • --all - Push all pending changes
    • --force-repush - Get new IDs (for reset campaigns)
  • find_local_changes.py - Identify entities needing sync
  • clean_campaign.py - ⚠️ Delete all Kanka entities (use with caution)

Utilities

  • add_name_to_frontmatter.py - Bulk update entity metadata

Campaign Setting

The Teghrim campaign is a Pathfinder 2e Remastered game set in Septerra:

  • System: Pathfinder 2e with Remastered rules
  • Ancestries: 42 playable options, some reskinned PF2e ancestries
  • Pantheons: Multiple deity groups with complex relationships
  • Geography: Multiple continents including mysterious Astoria
  • Central Hub: Teghrim's Crossing - a massive bridge settlement
  • Organizations: From Dwarven Slayer Cults to Goblin Raiders

Workflows

See the docs/ directory for detailed workflows:

  • Audio transcription pipeline
  • Entity sync procedures
  • Campaign reset process
  • Image generation guidelines
  • MCP-Kanka operations

Technical Details

File Naming Conventions

  • Audio: YYMMDD_####.mp3 (e.g., 250530_0016.mp3)
  • Transcripts: YYYY-MM-DD.md (e.g., 2025-05-30.md)
  • Digests: entities/notes/digest-YYYY-MM-DD.md
  • Summaries: entities/journals/session-summary-YYYY-MM-DD.md
  • Entities: entities/[type]/[name-kebab-case].md
  • Posts: entities/[type]/[entity]/[post-title].md

API Constraints

  • Audio files must be <2 hours for ElevenLabs API
  • Speaker diarization supports up to 6 speakers
  • Kanka API paginates at ~45 entities per page
  • Images generated at 1536x1024 resolution

Important Notes

  • Entity IDs only exist after first Kanka push
  • Always update frontmatter after creating entities/posts
  • Conflicts create .local.md and .kanka.md files

License

This project is for the Teghrim campaign. The codebase structure and scripts may be adapted for other campaigns.