---
document_type: "reference_doc"
service: "MOMENTRY_CORE"
title: "ASR Configuration Unification"
date: "2026-04-25"
version: "V1.0"
status: "active"
owner: "Warren"
created_by: "OpenCode"
tags:
  - "configuration"
  - "unification"
ai_query_hints:
  - "查詢 ASR Configuration Unification 的內容"
  - "ASR Configuration Unification 的主要目的是什麼？"
  - "如何操作或實施 ASR Configuration Unification？"
---

# ASR Configuration Unification

## Overview
This document defines the unified configuration approach for the ASR (Automatic Speech Recognition) system in Momentry Core. The goal is to eliminate configuration fragmentation and establish a single source of truth for ASR settings.

## Current Configuration Fragmentation

| System | Configuration | Default Value | Purpose |
|--------|--------------|---------------|---------|
| Rust Core | `MOMENTRY_ASR_TIMEOUT` | 3600 seconds (1 hour) | Overall ASR process timeout |
| Python Script | `MOMENTRY_ASR_DIRECT_TIMEOUT` | 600 seconds (10 min) | Direct transcription timeout |
| Python Script | `MOMENTRY_ASR_CHUNK_TIMEOUT` | 300 seconds (5 min) | Per-chunk transcription timeout |
| Monitoring | `monitor_config.yaml` | Various | Health check timeouts |

## Unified Configuration Strategy

### 1. Centralized Configuration in Rust
All ASR configuration should be centralized in the Rust configuration system (`src/core/config.rs`).

### 2. Environment Variable Hierarchy
```
MOMENTRY_ASR_TIMEOUT (primary) → MOMENTRY_ASR_DIRECT_TIMEOUT → MOMENTRY_ASR_CHUNK_TIMEOUT
```

### 3. Configuration Propagation
Rust configuration should be passed to Python scripts via:
- Environment variables
- Command-line arguments
- Configuration files

## Unified Configuration Specification

### Core Timeout Settings

| Environment Variable | Default | Description | Contract Compliance |
|---------------------|---------|-------------|---------------------|
| `MOMENTRY_ASR_TIMEOUT` | 3600 | Overall ASR process timeout | Required |
| `MOMENTRY_ASR_PROCESS_TIMEOUT` | 1800 | ASR processing timeout (subset of overall) | Recommended |
| `MOMENTRY_ASR_CHUNK_TIMEOUT` | 300 | Per-chunk transcription timeout | Optional |

### Performance Settings

| Environment Variable | Default | Description |
|---------------------|---------|-------------|
| `MOMENTRY_ASR_MODEL_SIZE` | "medium" | Whisper model size (tiny, base, small, medium, large) |
| `MOMENTRY_ASR_DEVICE` | "cpu" | Processing device (cpu, cuda, mps) |
| `MOMENTRY_ASR_COMPUTE_TYPE` | "int8" | Compute type for quantization |
| `MOMENTRY_ASR_BATCH_SIZE` | 16 | Batch size for processing |

### Quality Settings

| Environment Variable | Default | Description |
|---------------------|---------|-------------|
| `MOMENTRY_ASR_LANGUAGE` | "auto" | Language code or "auto" for detection |
| `MOMENTRY_ASR_TASK` | "transcribe" | Task type (transcribe, translate) |
| `MOMENTRY_ASR_BEAM_SIZE` | 5 | Beam size for decoding |
| `MOMENTRY_ASR_BEST_OF` | 5 | Number of candidates for beam search |

## Implementation Plan

### Phase 1: Configuration Unification
1. **Update Rust Configuration** (`src/core/config.rs`)
   - Add comprehensive ASR configuration constants
   - Maintain backward compatibility with existing environment variables

2. **Update Python Scripts**
   - Modify `asr_processor_contract_v1.py` to use unified configuration
   - Add timeout handling compliant with AI-Driven Processor Contract
   - Remove hardcoded timeout values

3. **Update Monitoring Configuration**
   - Align `monitor_config.yaml` with unified timeout values

### Phase 2: Contract Compliance
1. **Add Timeout Handling to Contract-Compliant Version**
   - Implement signal-based timeout handling
   - Add progress reporting during long operations
   - Ensure graceful degradation on timeout

2. **Update AI-Driven Processor Contract**
   - Add timeout specification requirements
   - Define timeout handling best practices

### Phase 3: Validation and Testing
1. **Create Configuration Tests**
   - Test environment variable propagation
   - Verify timeout behavior
   - Validate backward compatibility

2. **Update Documentation**
   - Update AGENTS.md with new configuration variables
   - Create configuration reference guide

## Code Changes Required

### 1. Rust Configuration Update
```rust
// src/core/config.rs
pub mod asr {
    pub static TIMEOUT_SECS: Lazy<u64> = Lazy::new(|| {
        env::var("MOMENTRY_ASR_TIMEOUT")
            .unwrap_or_else(|_| "3600".to_string())
            .parse()
            .unwrap_or(3600)
    });
    
    pub static PROCESS_TIMEOUT_SECS: Lazy<u64> = Lazy::new(|| {
        env::var("MOMENTRY_ASR_PROCESS_TIMEOUT")
            .unwrap_or_else(|_| "1800".to_string())
            .parse()
            .unwrap_or(1800)
    });
    
    pub static CHUNK_TIMEOUT_SECS: Lazy<u64> = Lazy::new(|| {
        env::var("MOMENTRY_ASR_CHUNK_TIMEOUT")
            .unwrap_or_else(|_| "300".to_string())
            .parse()
            .unwrap_or(300)
    });
    
    // Additional configuration...
}
```

### 2. Python Configuration Handling
```python
# scripts/asr_processor_contract_v1.py
class ASRProcessor:
    def __init__(self):
        # Get unified configuration
        self.overall_timeout = int(os.environ.get("MOMENTRY_ASR_TIMEOUT", "3600"))
        self.process_timeout = int(os.environ.get("MOMENTRY_ASR_PROCESS_TIMEOUT", "1800"))
        self.chunk_timeout = int(os.environ.get("MOMENTRY_ASR_CHUNK_TIMEOUT", "300"))
        
    def process_with_timeout(self):
        # Implement timeout handling compliant with contract
        pass
```

## Migration Strategy

### Step 1: Backward Compatibility
- Keep existing environment variables functional
- Log deprecation warnings for old variables
- Provide migration guide

### Step 2: Gradual Migration
1. Update contract-compliant version first
2. Test with new configuration
3. Update other processors following same pattern

### Step 3: Full Migration
1. Remove old configuration variables
2. Update all documentation
3. Verify system-wide consistency

## Testing Requirements

### Unit Tests
- Configuration loading from environment variables
- Timeout behavior validation
- Backward compatibility verification

### Integration Tests
- End-to-end ASR processing with timeouts
- Configuration propagation from Rust to Python
- Signal handling and graceful degradation

### Performance Tests
- Timeout impact on processing performance
- Resource usage with different configurations
- Memory consumption with model caching

## Success Criteria

1. **Single Source of Truth**: All ASR configuration centralized in Rust
2. **Contract Compliance**: All processors follow AI-Driven Processor Contract
3. **Backward Compatibility**: Existing deployments continue to work
4. **Improved Maintainability**: Reduced configuration complexity
5. **Better Observability**: Consistent logging and monitoring

## Timeline

- **Week 1**: Design and specification
- **Week 2**: Implementation and testing  
- **Week 3**: Deployment and validation
- **Week 4**: Documentation and training

## Responsible Parties

- **Technical Lead**: Warren (design and implementation)
- **Quality Assurance**: Warren (testing and validation)
- **Documentation**: Warren (guides and references)

## Approval

| Role | Name | Date | Status |
|------|------|------|--------|
| Technical Reviewer | Warren | 2026-03-27 | Pending |
| Ops Responsible | Warren | 2026-03-27 | Pending |
| Final Approver | Warren | 2026-03-27 | Pending |

---

*Document Version: 1.0*  
*Last Updated: 2026-03-27*  
*Next Review: 2026-04-27*
