Configuration Options

VoxKit uses (YAML or JSON) configuration files in the apps config folder to define information about the app and pipeline. Configuration can be modified post-build without requiring code changes, enabling researchers to adapt workflows to specific studies.

Application Configuration (app_info.yaml)

Located in the apps config folder. Defines application metadata, version info, introduction text. Anything related to the app as a whole:

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: Version number; often linked to a tag on github (e.g., 0.1.0)
• •description: Brief description of the applications purpose in context
• •help_url: URL to documentation/help resources, flexible to support custom documentation sites
• •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)

Also located in the apps config folder. Workflow steps, stacker classes, UI settings. Anything related to the workflow and user interface:

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