Voice Mode

# Download Progress Indicator Specification ## Overview Standardize download progress indicators across VoiceMode CLI for consistent UX when downloading models, services, or other resources. ## Design Principles 1. **Informative**: Show progress, speed, time remaining 2. **Consistent**: Same style across all downloads 3. **Responsive**: Update smoothly without flickering 4. **Accessible**: Work in different terminal environments 5. **Graceful**: Handle unknown file sizes elegantly ## Progress Bar Options ### Option 1: Click Progress Bar (Recommended) Using Click's built-in ProgressBar - integrates well with our CLI framework. ``` Downloading ggml-large-v3.bin (3.1 GB) [████████████████████░░░░░░░░░░░░░░░░] 45% (1.4GB/3.1GB) • 12.5 MB/s • ETA: 02:16 ``` **Pros:** - Built into Click (no new dependencies) - Automatic terminal width detection - Handles ANSI colors well - Can customize format easily **Code example:** ```python import click with click.progressbar( length=total_size, label='Downloading ggml-large-v3.bin', show_eta=True, show_percent=True, show_pos=True, width=40, fill_char='█', empty_char='░' ) as bar: # Update during download bar.update(chunk_size) ``` ### Option 2: Rich Progress Bar Using the Rich library for beautiful terminal output. ``` Downloading Core ML model ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 100% 0:00:00 ggml-large-v3-encoder.mlmodelc.zip 1.2 GB / 1.2 GB • 15.3 MB/s • ✓ Complete ``` **Pros:** - Beautiful, modern appearance - Multiple progress bars simultaneously - Rich formatting options - Spinners for indeterminate progress **Cons:** - Adds Rich as dependency (~500KB) ### Option 3: Custom Minimal Progress Simple, dependency-free implementation. ``` Downloading: ggml-base.bin [=========== ] 55% | 78.1 MB / 142 MB | 8.2 MB/s | ~8s remaining ``` **Code example:** ```python def print_progress(downloaded, total, speed): percent = (downloaded / total) * 100 bar_length = 20 filled = int(bar_length * downloaded / total) bar = '=' * filled + ' ' * (bar_length - filled) print(f'\r[{bar}] {percent:.0f}% | {downloaded/1024/1024:.1f} MB / {total/1024/1024:.1f} MB | {speed/1024/1024:.1f} MB/s', end='', flush=True) ``` ### Option 4: Spinner for Unknown Size When Content-Length header is missing: ``` Downloading model ⠼ 45.2 MB downloaded (5.3 MB/s) ``` Spinner frames: `⠋ ⠙ ⠹ ⠸ ⠼ ⠴ ⠦ ⠧ ⠇ ⠏` ### Option 5: Block Progress Visual blocks that fill up (good for accessibility): ``` Downloading ggml-small.bin (466 MB) Progress: ▓▓▓▓▓▓▓▓▓▓▓▓▓▓░░░░░░░░░░░░░░░░ 45% Speed: 10.2 MB/s | Downloaded: 210 MB | Remaining: ~25s ``` ### Option 6: Verbose Mode (Debug/CI) For CI environments or debug mode: ``` [2024-10-01 13:45:23] Starting download: ggml-large-v3.bin [2024-10-01 13:45:24] Progress: 5% (155 MB / 3100 MB) - 12.3 MB/s [2024-10-01 13:45:25] Progress: 10% (310 MB / 3100 MB) - 13.1 MB/s [2024-10-01 13:45:26] Progress: 15% (465 MB / 3100 MB) - 12.8 MB/s ``` ## Implementation Strategy ### 1. Create Unified Download Function ```python # voice_mode/utils/download.py async def download_with_progress( url: str, destination: Path, description: str = None, style: str = "auto", # auto, bar, spinner, blocks, verbose quiet: bool = False ) -> bool: """ Download file with progress indicator. Args: url: URL to download from destination: Where to save the file description: Label for the progress bar style: Progress indicator style quiet: Suppress all output Returns: True if successful, False otherwise """ ``` ### 2. Environment Detection ```python def detect_progress_style(): """Auto-detect best progress style based on environment.""" if os.environ.get('CI'): return 'verbose' # CI environment if not sys.stdout.isatty(): return 'verbose' # Not a terminal if os.environ.get('VOICEMODE_PROGRESS_STYLE'): return os.environ['VOICEMODE_PROGRESS_STYLE'] return 'bar' # Default to progress bar ``` ### 3. Integration Points **Whisper Models:** ```python # voice_mode/utils/services/whisper_helpers.py async def download_whisper_model(...): await download_with_progress( url=model_url, destination=model_path, description=f"Downloading {model_name}" ) ``` **Core ML Models:** ```python # voice_mode/utils/services/whisper_helpers.py async def download_coreml_model(...): await download_with_progress( url=coreml_url, destination=coreml_zip, description=f"Downloading Core ML model for {model}" ) ``` **Service Installations:** ```python # When downloading Whisper.cpp releases, Kokoro, etc. ``` ## User Configuration ### Environment Variables ```bash # Progress bar style export VOICEMODE_PROGRESS_STYLE=bar # bar, spinner, blocks, verbose, quiet # Colors export VOICEMODE_PROGRESS_COLOR=true # Enable/disable colors # Update frequency export VOICEMODE_PROGRESS_RATE=10 # Updates per second ``` ### CLI Flags ```bash # Global flags voicemode --progress=verbose whisper model install large-v3 voicemode --quiet whisper model install base # Command-specific voicemode whisper model install large-v3 --no-progress voicemode whisper model install large-v3 --progress-style=blocks ``` ## Error Handling ### Network Interruption ``` Downloading ggml-large-v3.bin (3.1 GB) [████████████░░░░░░░░░░░░░░░░░░░░░░] 35% (1.1GB/3.1GB) ❌ Download interrupted: Connection reset by peer 💡 Resume with: voicemode whisper model install large-v3 --resume ``` ### Disk Space ``` Downloading ggml-large-v3.bin (3.1 GB) [██████░░░░░░░░░░░░░░░░░░░░░░░░░░░░] 18% (558MB/3.1GB) ❌ Insufficient disk space (need 3.1 GB, have 2.1 GB available) ``` ## Testing Considerations 1. **Terminal Widths**: Test with narrow (80 cols) and wide terminals 2. **Color Support**: Test with NO_COLOR environment variable 3. **CI Environment**: Test with CI=true 4. **Network Speeds**: Test progress updates with slow/fast connections 5. **File Sizes**: Test with small (KB), medium (MB), and large (GB) files ## Recommendation **Use Click's ProgressBar (Option 1)** because: - No new dependencies (already using Click) - Good terminal compatibility - Easy to customize - Consistent with CLI framework - Sufficient features for our needs Fallback to spinner (Option 4) when file size is unknown. ## Example Implementation ```python import click import urllib.request from pathlib import Path def download_with_click_progress(url: str, dest: Path, label: str = None): """Download with Click progress bar.""" response = urllib.request.urlopen(url) total_size = int(response.headers.get('Content-Length', 0)) if not label: label = f"Downloading {dest.name}" if total_size == 0: # Unknown size - use spinner with click.progressbar( label=label, length=None, show_percent=False, show_pos=True ) as bar: downloaded = 0 while chunk := response.read(8192): dest.write(chunk) downloaded += len(chunk) bar.update(len(chunk)) else: # Known size - use progress bar with click.progressbar( length=total_size, label=label, show_eta=True, show_percent=True, width=40, fill_char='█', empty_char='░' ) as bar: with open(dest, 'wb') as f: while chunk := response.read(8192): f.write(chunk) bar.update(len(chunk)) ``` ## Next Steps 1. Implement download_with_progress utility function 2. Update whisper_helpers.py to use new function 3. Update CLI to show progress 4. Add --quiet and --verbose flags 5. Test across different environments 6. Document in user guide