Configuration Options

VoxKit uses YAML configuration files in the config folder to define workflows, pipelines, and app settings. Configuration can be modified post-build without requiring code changes, enabling researchers to adapt workflows to specific studies.

Configuration Architecture

VoxKit separates configuration into two files in the config folder:

• •app_info.yaml: Application metadata, version info, and introduction text
• •pipeline_definitions.yaml: Workflow steps, stacker classes, and UI settings

Application Configuration (app_info.yaml)

This file contains metadata about the application:

app_name: "VoxKit"
version: "0.1.0"
description: "AI/ML Research -> Clinical Applications (Speech Pathology)"
help_url: "http://localhost:3000/help"

introduction: |
  VoxKit is a comprehensive speech alignment and analysis toolkit designed for 
  clinical speech pathology applications. This version provides tools for training 
  acoustic models, generating forced alignments, and computing Goodness of 
  Pronunciation (GOP) scores for speech assessment.

release_date: "2026-01-14"
release_notes: |
  - Initial configurable release
  - Support for custom pipeline configurations

• •app_name: Display name shown in the application window
• •version: Semantic version number (e.g., 0.1.0)
• •description: Brief description of the application purpose
• •help_url: URL to documentation/help resources
• •introduction: Multi-line text shown to users on first launch
• •release_date: ISO date of the current release
• •release_notes: Multi-line changelog for this version

Pipeline Configuration (pipeline_definitions.yaml)

This file defines the workflow steps and their display configuration:

pipeline:
  - id: "training"
    label: "Ⓐ Train Aligners"
    stacker_class: "TrainingStacker"
    enabled: true
    collapsible_sections:
      "Step Instructions": "Train custom alignment models on your datasets"
      "Additional Info": "Training creates acoustic models that learn from your labeled audio data."
      "Requirements": "Ensure your dataset is properly formatted with aligned text transcriptions."

ui:
  menu_max_width: 500
  animation_duration: 300
  content_spacing: 20

Pipeline Step Configuration

Each step in the pipeline array supports these fields:

• •id: Unique identifier for the step (e.g., 'training', 'prediction')
• •label: Display text shown in navigation menu (supports Unicode symbols like Ⓐ Ⓑ Ⓒ)
• •stacker_class: Name of the Python class to instantiate (must be in STACKER_REGISTRY)
• •enabled: Boolean to show/hide this step (true/false)
• •collapsible_sections: Dictionary of expandable help sections (header: content)
• •markdown_content: Markdown text for MarkdownStacker (optional)

Collapsible Sections

Collapsible sections appear at the top of each stacker page as expandable help text:

collapsible_sections:
  "Step Instructions": "Brief guidance on what this step does"
  "Additional Info": "Detailed explanation or warnings"
  "Requirements": "Prerequisites or system requirements"
  "Misc": "Any other helpful information"

Users click the ▶ arrow to expand each section. The header text becomes ▼ when expanded.

Available Stacker Classes

• •TrainingStacker: Model training workflow (⑥ steps)
• •PredictionStacker: Alignment prediction workflow (④ steps)
• •PLLRStacker: GOP score extraction workflow (④ steps)
• •MarkdownStacker: Display formatted markdown content (requires markdown_content field)

MarkdownStacker Example

For introduction or documentation pages, use MarkdownStacker:

- id: "introduction"
  label: "Introduction"
  stacker_class: "MarkdownStacker"
  enabled: true
  markdown_content: |
    # Welcome to VoxKit
    
    ## Key Features:
    - Train custom alignment models
    - Generate forced alignments
    - Extract GOP scores
    
  collapsible_sections:
    "References": "For more info, visit the [Help Page](http://localhost:3000/help)"

UI Configuration

The ui section controls interface appearance:

• •menu_max_width: Maximum width in pixels for navigation menu (default: 500)
• •animation_duration: Slide transition time in milliseconds (default: 300)
• •content_spacing: Padding between content elements in pixels (default: 20)

Best Practices

• •Use Unicode symbols (Ⓐ Ⓑ Ⓒ or ①②③) in labels to create visual hierarchy
• •Keep collapsible section content concise (1-3 sentences per section)
• •Set enabled: false to temporarily hide steps without deleting configuration
• •Version control your YAML files to track workflow changes across studies
• •Test configuration changes in a development environment before distribution

Configuration Workflow

1. Developer creates Python stackers and registers them in STACKER_REGISTRY 2. Researcher edits pipeline_definitions.yaml to add/remove/reorder steps 3. Researcher customizes collapsible_sections for study-specific guidance 4. Application is bundled with updated configuration 5. No code changes required - just edit YAML and redistribute