media-to-text/DEVELOPMENT_RULES.md

Media to Text - Development Rules

CRITICAL RULE: Never Upload Full Video Files

Status: MANDATORY - NEVER VIOLATE

Rule Definition

• NEVER allow users to upload full video files (MP4, AVI, MOV, MKV, FLV, WMV, WEBM) to the server
• ALWAYS extract audio on the browser BEFORE uploading
• Only audio files (MP3, WAV, M4A, etc.) should be uploaded to the server

Why This Rule Exists

1. Bandwidth Efficiency: Video files are 10-100x larger than extracted audio
2. User Experience: Faster uploads = better UX
3. Server Resources: Reduces server storage and processing load
4. Cost: Minimizes data transfer costs

Implementation Requirements

• Browser-side audio extraction is MANDATORY for video files
• Use ffmpeg.wasm or equivalent WebAssembly solution
• If browser extraction fails, show error message - DO NOT fall back to uploading full video
• Server-side extraction is NOT acceptable as a workaround

Current Status

• ❌ Browser extraction via ffmpeg.wasm: BLOCKED (CORS/CORB issues)
• ⚠️ Temporary workaround: Guide users to extract audio locally using ffmpeg CLI
• 🔄 TODO: Find working ffmpeg.wasm CDN or alternative solution

Acceptable Solutions (In Priority Order)

1. ffmpeg.wasm from working CDN (no CORS/CORB issues)
2. Local ffmpeg.wasm with complete wasm binaries
3. Alternative WebAssembly video processing library
4. User-extracted audio files only (with clear instructions)

NOT Acceptable

• ❌ Uploading full video files to server
• ❌ Server-side extraction as primary solution
• ❌ Removing this rule without explicit approval

RULE: Show Model Download Progress

Status: MANDATORY

Rule Definition

• ALWAYS show download progress when loading Whisper models
• Display percentage and/or file size being downloaded
• Models can be 150MB-500MB+ and take significant time to download

Why This Rule Exists

1. User Experience: Users need to know the app isn't frozen
2. Transparency: Large downloads should be visible
3. Expectations: Users can estimate wait time

Implementation Requirements

• Use progress callback from transformers.js pipeline
• Display progress percentage in status element
• Show "Downloading model: X%" or similar message