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

# ASR Improvement Plan

## Overview
This document outlines the plan to optimize the Automatic Speech Recognition (ASR) system in Momentry Core. The current implementation has several areas for improvement including performance bottlenecks, architectural complexity, and configuration fragmentation.

## Current State Analysis

### Architecture
1. **Rust → Python Subprocess**: Rust calls Python script via subprocess with 3600s timeout
2. **Complex Python Script**: `asr_processor.py` (953 lines) with monitoring, Redis publishing, chunking logic
3. **Configuration Fragmentation**: 
   - Rust: `ASR_TIMEOUT_SECS = 3600` (1 hour)
   - Python: Environment variables, hardcoded settings
   - Monitoring: Separate configuration

### Performance Issues
1. **Subprocess Overhead**: Rust → Python → Whisper pipeline adds latency
2. **Chunking Overhead**: Large files (>20 minutes) require complex chunking logic
3. **Memory Usage**: No model caching, reloads Whisper for each file
4. **No Concurrency**: Processes files sequentially

### Testing Coverage
- Multiple test scripts but no systematic performance monitoring
- No regression testing for optimization changes

## Improvement Goals

### Phase 1: Immediate Optimizations (Week 1)
1. **Simplify Python Script**: Remove unnecessary monitoring and Redis logic
2. **Unify Configuration**: Centralize ASR settings in Rust config
3. **Add Basic Caching**: Implement simple Whisper model caching

### Phase 2: Performance Enhancements (Week 2)
1. **PyO3 Integration**: Replace subprocess with direct Rust-Python calls
2. **Parallel Processing**: Enable concurrent ASR processing
3. **Smart Chunking**: Optimize chunk sizes based on file characteristics

### Phase 3: Advanced Features (Week 3)
1. **Performance Metrics**: Add detailed timing and resource usage tracking
2. **Adaptive Timeouts**: Dynamic timeout based on file size/duration
3. **Language Detection**: Improve language identification accuracy

## Detailed Implementation Plan

### Task 1: Simplify Python Script
**Current**: 953 lines with monitoring, Redis publishing, complex chunking
**Target**: ~300 lines focused on core ASR functionality

**Changes**:
1. Remove `ResourceMonitor` class and background monitoring
2. Remove Redis publishing dependencies
3. Simplify chunking logic with sensible defaults
4. Keep essential error handling and logging

### Task 2: Unify Configuration
**Current**: Settings spread across Rust config, Python env vars, monitoring config
**Target**: Single source of truth in Rust config

**Changes**:
1. Move all ASR settings to `src/core/config.rs`
2. Add environment variable overrides for key parameters:
   - `MOMENTRY_ASR_CHUNK_SIZE`: Chunk duration in seconds
   - `MOMENTRY_ASR_MODEL`: Whisper model name
   - `MOMENTRY_ASR_CACHE_ENABLED`: Enable model caching
3. Pass configuration from Rust to Python via command line arguments

### Task 3: Implement Model Caching
**Current**: Loads Whisper model for each file
**Target**: Cache model in memory across invocations

**Implementation**:
```python
# Simple singleton cache
_whisper_model_cache = {}

def get_whisper_model(model_name="base"):
    if model_name not in _whisper_model_cache:
        import whisper
        _whisper_model_cache[model_name] = whisper.load_model(model_name)
    return _whisper_model_cache[model_name]
```

### Task 4: Add Performance Metrics
**Current**: No systematic performance tracking
**Target**: Collect and log key metrics

**Metrics to Track**:
- Processing time per file
- Time per audio minute
- Memory usage
- CPU utilization
- Chunk count and sizes

### Task 5: Test Optimizations
**Test Strategy**:
1. **Unit Tests**: Verify simplified script functionality
2. **Performance Tests**: Compare before/after metrics
3. **Integration Tests**: Ensure Rust-Python integration works
4. **Regression Tests**: Verify existing functionality preserved

## Success Criteria

### Quantitative Metrics
1. **Processing Time**: Reduce by 20% for typical files
2. **Memory Usage**: Reduce peak memory by 30%
3. **Code Complexity**: Reduce Python script lines by 60%
4. **Configuration Points**: Reduce from 5+ to 2-3

### Qualitative Improvements
1. **Simpler Maintenance**: Easier to understand and modify
2. **Better Error Handling**: Clearer error messages and recovery
3. **Improved Monitoring**: Better visibility into ASR performance
4. **Enhanced Reliability**: More robust handling of edge cases

## Risks and Mitigations

### Risk 1: Breaking Existing Functionality
**Mitigation**: Comprehensive test suite, gradual rollout, backup of original scripts

### Risk 2: Performance Regression
**Mitigation**: Benchmark before/after, performance monitoring during rollout

### Risk 3: Increased Complexity
**Mitigation**: Keep changes focused, document thoroughly, peer review

## Timeline

### Week 1: Foundation
- Day 1-2: Simplify Python script
- Day 3-4: Unify configuration
- Day 5: Implement basic caching

### Week 2: Performance
- Day 1-2: Add performance metrics
- Day 3-4: Optimize chunking logic
- Day 5: Test and benchmark

### Week 3: Advanced Features
- Day 1-2: PyO3 integration research
- Day 3-4: Parallel processing implementation
- Day 5: Documentation and final testing

## Dependencies

1. **Whisper Model Availability**: Ensure required models are accessible
2. **FFmpeg/FFprobe**: Required for audio extraction
3. **Python Dependencies**: `openai-whisper`, `psutil` (optional)

## Team Responsibilities

- **Primary Developer**: Implement code changes
- **QA Engineer**: Test optimization results
- **DevOps**: Monitor production performance
- **Technical Lead**: Review architecture changes

## Next Steps

1. **Immediate**: Create simplified version of `asr_processor.py`
2. **Short-term**: Update Rust configuration to pass settings to Python
3. **Medium-term**: Implement performance metrics collection
4. **Long-term**: Evaluate PyO3 for direct Rust-Python integration

---

*Last Updated: 2026-03-27*
*Status: Planning Phase*
*Owner: Warren (Technical Lead)*
