Party Validator Skill

Validate, create, and manage D&D party configuration files for accurate speaker mapping.

What This Skill Does

This skill helps manage party configurations to ensure accurate speaker-to-character mapping during session processing:

Validate Configurations: Check party config files for correct structure and data
Create New Configs: Generate party configuration files from templates
Update Configs: Modify existing configurations with new players or characters
Compare Configs: Diff multiple party configurations
Speaker Mapping: Preview how speakers will be mapped to characters
Troubleshoot Issues: Diagnose and fix common configuration problems

Why Party Configs Matter

Party configurations enable:

Accurate Speaker Mapping: Map SPEAKER_00, SPEAKER_01, etc. to actual players
Character Attribution: Link dialogue to D&D characters for IC content
Knowledge Extraction: Properly attribute actions and dialogue to characters
Consistent Naming: Maintain consistent player/character names across sessions

Configuration File Structure

Location

Party configs are stored in: data/party_<name>.json

Schema

json

{
  "party_name": "Main Campaign Party",
  "campaign": "Dragon Heist",
  "dm": {
    "name": "Alice",
    "voice_characteristics": "Female, low pitch, authoritative"
  },
  "players": [
    {
      "name": "Bob",
      "voice_characteristics": "Male, mid pitch, energetic",
      "characters": [
        {
          "name": "Thorin Ironfist",
          "class": "Fighter",
          "race": "Dwarf"
        }
      ]
    },
    {
      "name": "Charlie",
      "voice_characteristics": "Male, high pitch, dramatic",
      "characters": [
        {
          "name": "Elara Moonwhisper",
          "class": "Wizard",
          "race": "Elf"
        }
      ]
    }
  ]
}

Required Fields

Root Level:

party_name (string): Descriptive name for the party
dm (object): Dungeon Master information
players (array): List of player objects

DM Object:

name (string): DM's real name

Player Object:

name (string): Player's real name
characters (array): List of character objects (can be empty for new players)

Character Object:

name (string): Character's name in the game
class (string): D&D class (optional but recommended)
race (string): D&D race (optional but recommended)

Optional Fields

campaign (string): Campaign name or setting
voice_characteristics (string): Voice description to aid speaker mapping
session_range (array): e.g., [1, 50] - sessions this config applies to
notes (string): Additional information about the party
created_date (string): When configuration was created
last_updated (string): Last modification date

Usage

Validate Existing Config

User: "Validate the default party configuration" User: "Check if party_main.json is correct" User: "Is the party config valid?"

Validate All Configs

User: "Validate all party configurations" User: "Check all party config files"

Create New Config

User: "Create a new party config called 'oneshot' with 3 players" User: "Set up a party configuration for my new campaign"

Update Existing Config

User: "Add a new player named David to the main party config" User: "Update Bob's character to level 5 Paladin"

Troubleshoot Issues

User: "Why is speaker mapping wrong for session 12?" User: "The DM is being identified as a player. Help me fix the config."

Command Reference

bash

# Validate specific config
python cli.py validate-config --party default

# Validate all configs
python cli.py validate-config --all

# Create new config
python cli.py create-party-config --name oneshot --players Alice Bob Charlie

# Update config
python cli.py update-party-config --name default --add-player David

# Show config
python cli.py show-party-config --name default

# List all configs
python cli.py list-party-configs

MCP Tool Integration

Use mcp__videochunking-dev__validate_party_config to validate configurations.

Validate Specific Config

python

# Via MCP tool
validate_party_config(config_name="default")

Returns:

json

{
  "file": "party_default.json",
  "valid": true,
  "player_count": 4,
  "character_count": 4,
  "errors": [],
  "warnings": []
}

Validate All Configs

python

# Via MCP tool
validate_party_config()  # No config_name = validate all

Returns:

json

{
  "configs": [
    {
      "file": "party_default.json",
      "valid": true,
      "player_count": 4,
      "character_count": 4,
      "errors": [],
      "warnings": []
    },
    {
      "file": "party_oneshot.json",
      "valid": false,
      "errors": ["Missing 'dm' field"],
      "warnings": ["Player 0 has no characters"]
    }
  ],
  "total_validated": 2
}

Validation Rules

Critical Errors (Must Fix)

❌ Missing party_name field
❌ Missing dm object
❌ Missing players array
❌ Invalid JSON syntax
❌ DM missing name field
❌ Player missing name field
❌ Characters array is not a list
❌ Duplicate player names
❌ Character missing name field

Warnings (Should Review)

⚠️ Player has no characters (might be observer or new)
⚠️ Character missing class or race (less detailed extraction)
⚠️ No voice_characteristics (harder to map speakers)
⚠️ Very few players (<2) or many players (>8)
⚠️ No campaign specified
⚠️ Empty or very short character names

Recommendations

ℹ️ Add voice_characteristics for better speaker mapping
ℹ️ Include character class and race for richer knowledge extraction
ℹ️ Specify campaign name for organization
ℹ️ Add notes about campaign setting or party dynamics

Common Issues and Solutions

Issue: Missing Required Field

Error: Missing 'dm' field in party_custom.json

Solution:
Add DM information:
{
  "dm": {
    "name": "Your DM Name"
  }
}

Issue: Invalid JSON Syntax

Error: Invalid JSON in party_default.json - Unexpected token at line 15

Solution:
- Check for missing commas between fields
- Ensure all quotes are matched
- Verify no trailing commas
- Use JSON validator: jsonlint.com

Issue: Duplicate Player Names

Error: Duplicate player name 'Bob' found in party_main.json

Solution:
- Use unique player names
- If same person plays different characters across sessions,
  use disambiguating names: "Bob_Character1", "Bob_Character2"
- Or create separate configs per session range

Issue: Player Has No Characters

Warning: Player 'Charlie' has no characters defined

Solutions:
1. Add character to players array:
   "characters": [{"name": "CharName", "class": "Rogue", "race": "Human"}]
2. If player is observer/DM assistant, this is okay (can ignore warning)
3. If new campaign, add character after character creation session

Issue: Wrong Speaker Mapping

Problem: SPEAKER_00 is mapped to wrong player in output

Solutions:
1. Check if voice_characteristics are accurate and distinct
2. Verify player order matches typical speaking order
3. Review diarization settings (may need adjustment)
4. Consider manual speaker label correction post-processing
5. Ensure no players are missing from config

Issue: Character Name Mismatched

Problem: Character name in transcript doesn't match config

Solutions:
1. Update config with actual name used in game
2. Add name variations/aliases to character object
3. Use consistent character names during play
4. Manually correct extracted knowledge if needed

Creating New Party Configs

Template-Based Creation

Use provided template:

bash

cp data/party_template.json data/party_newcampaign.json
# Edit party_newcampaign.json with actual information
python cli.py validate-config --party newcampaign

Interactive Creation

Follow prompts:

bash

python cli.py create-party-config --interactive

Party name: Summer Oneshot
Campaign name (optional): Lost Mine of Phandelver
DM name: Alice

How many players? 4

Player 1 name: Bob
Player 1 voice: Male, deep voice
Player 1 character name: Thorin
Player 1 character class: Fighter
Player 1 character race: Dwarf

... (repeat for all players)

Config saved to: data/party_summer_oneshot.json
Validation: ✅ VALID

Programmatic Creation

python

from src.party_config import PartyConfig

config = PartyConfig.create(
    party_name="Test Party",
    campaign="Test Campaign",
    dm_name="Alice",
    players=[
        {
            "name": "Bob",
            "voice": "Male, mid pitch",
            "characters": [
                {"name": "Thorin", "class": "Fighter", "race": "Dwarf"}
            ]
        },
        {
            "name": "Charlie",
            "characters": [
                {"name": "Elara", "class": "Wizard", "race": "Elf"}
            ]
        }
    ]
)

config.save("data/party_test.json")
config.validate()  # Returns errors and warnings

Speaker Mapping Preview

Before processing, preview how speakers will be mapped:

bash

python cli.py preview-speaker-mapping --party default --session session_012

Expected Mapping (based on typical speaking order):
  SPEAKER_00 → Alice (DM)
  SPEAKER_01 → Bob (Thorin Ironfist)
  SPEAKER_02 → Charlie (Elara Moonwhisper)
  SPEAKER_03 → David (Grim Stonefist)
  SPEAKER_04 → Eve (Lyra Brightwood)

Notes:
  - Mapping is based on voice_characteristics and typical patterns
  - Actual mapping may vary based on who speaks first
  - Review output after processing for accuracy
  - Adjust voice_characteristics if mapping is incorrect

Configuration Management

Version Control

Commit party configs to git:

bash

git add data/party_*.json
git commit -m "Add main campaign party config"
git push

Backup Configs

Before making changes:

bash

cp data/party_default.json data/party_default.json.backup

Multiple Configs for Same Campaign

Use session ranges or naming:

party_main_sessions_1-10.json   # Original party
party_main_sessions_11-20.json  # New player joined
party_main_sessions_21-30.json  # Player left, character replaced

Or simply:

party_main_early.json
party_main_current.json

Specify during processing:

bash

python cli.py process video.mp4 --party main_current

Advanced Validation

Schema Validation

Use JSON Schema for strict validation:

bash

python cli.py validate-config --party default --strict

# Uses schema file: schemas/party_config_schema.json

Cross-Session Validation

Ensure config matches actual session data:

bash

python cli.py validate-config --party default --check-session session_012

Validation Results:
  ✅ All speakers in session_012 mapped to config players
  ⚠️ SPEAKER_04 in session but only 4 players in config (expected 5 speakers)

Recommendation:
  Check if new player joined for session_012
  Update config or verify diarization didn't over-segment

Historical Validation

Check if configs match historical usage:

bash

python cli.py validate-config --history

Party Config Usage:
  party_default.json:
    Used in: 25 sessions (session_001 to session_025)
    Speaker counts: 5 (consistent)
    Issues: None

  party_oneshot.json:
    Used in: 3 sessions (session_026, session_027, session_028)
    Speaker counts: 4, 4, 5 (inconsistent)
    Issues: Session_028 had extra speaker not in config

Recommendations:
  ⚠️ Review session_028 - possible new player or guest
  ℹ️ Consider creating party_oneshot_v2.json for future sessions

Integration with Other Skills

session-processor: Use validated configs for session processing
diagnostics-runner: Includes party config validation in health checks
campaign-analyzer: Use character names from configs for knowledge extraction
video-chunk: Validates party config before starting pipeline

Best Practices

Create Config Before First Session: Set up party config before processing
Include Voice Characteristics: Helps with speaker diarization accuracy
Keep Configs Updated: Add new players/characters as they join
Version Configs: Track changes in git for history
Validate After Changes: Always validate after editing configs
Use Descriptive Names: Name configs clearly (party_main, party_oneshot_winter)
Document Special Cases: Add notes for temporary players or guests
Backup Before Major Changes: Save backups before restructuring
Test with Sample Session: Process one session to verify mapping
Review First Output: Manually check speaker mapping is correct

Example Workflows

New Campaign Setup

User: "I'm starting a new campaign. Help me set up the party config."

Assistant uses party-validator:
1. Asks for party details (DM, players, characters)
2. Creates new config file: data/party_newcampaign.json
3. Validates structure
4. Previews speaker mapping
5. Confirms ready for session processing

Troubleshooting Bad Mapping

User: "Session 12 has wrong speaker assignments. The DM is labeled as a player."

Assistant uses party-validator:
1. Validates party config: check config is correct
2. Reviews session 12 output: check actual speaker assignments
3. Compares expected vs actual mapping
4. Identifies issue: Speaker order different than expected
5. Suggests: Update voice_characteristics or manually correct session

Config Migration

User: "We had a player change characters. Update the config."

Assistant uses party-validator:
1. Reads current config
2. Updates player's character information
3. Validates updated config
4. Creates backup of old config
5. Recommends: Specify session range for old vs new character

Future Enhancements

Potential features:

Automatic speaker-to-player mapping based on voice analysis
Config templates for common party sizes
Visual config editor (web UI)
Character progression tracking (levels, abilities)
Session attendance tracking
Voice sample collection for better diarization
Integration with D&D Beyond for character import
Multi-language support for international campaigns

Search AI Tools

Install this agent skill to your Project

SKILL.md

Party Validator Skill

What This Skill Does

Why Party Configs Matter

Configuration File Structure

Location

Schema

Required Fields

Optional Fields

Usage

Validate Existing Config

Validate All Configs

Create New Config

Update Existing Config

Troubleshoot Issues

Command Reference

MCP Tool Integration

Validate Specific Config

Validate All Configs

Validation Rules

Critical Errors (Must Fix)

Warnings (Should Review)

Recommendations

Common Issues and Solutions

Issue: Missing Required Field

Issue: Invalid JSON Syntax

Issue: Duplicate Player Names

Issue: Player Has No Characters

Issue: Wrong Speaker Mapping

Issue: Character Name Mismatched

Creating New Party Configs

Template-Based Creation

Interactive Creation

Programmatic Creation

Speaker Mapping Preview

Configuration Management

Version Control

Backup Configs

Multiple Configs for Same Campaign

Advanced Validation

Schema Validation

Cross-Session Validation

Historical Validation

Integration with Other Skills

Best Practices

Example Workflows

New Campaign Setup

Troubleshooting Bad Mapping

Config Migration

Future Enhancements