Scrible Wise

A comprehensive audio transcription tool powered by Whisper models that converts audio/video files into Chinese transcripts. Features include WebM video conversion, robust error handling, and an intuitive CLI interface.

Features

Core Features

• 🎵 Multi-format Support: WebM, MP4, MKV, AVI, MP3, WAV, FLAC, OGG, AAC, M4A
• 🧠 Multi-Model AI: Support for 6 different transcription models (local & cloud)
  • MediaTek Breeze-ASR-25 (默認中文模型)
  • OpenAI Whisper (Base/Small/Medium/Large 本地模型)
  • OpenAI Whisper API (雲端服務)
• ⚡ Smart Processing: Automatic chunking for long audio files (30-second segments)
• 🔧 Error Recovery: Comprehensive error handling with retry mechanisms and recovery suggestions
• 💻 Cross-platform: Apple Silicon (MPS), CPU support with automatic fallback
• 📝 Complete Workflow: Video → Audio → Transcription with validation at each step
• 💰 Cost Control: API usage tracking and cost estimation for cloud services

Advanced CLI Interface

• 🚀 Easy to Use: Simple command-line interface with automatic output path generation
• ✅ User-friendly: Clear success/error messages with recovery suggestions
• 🔍 Format Detection: Automatic file type detection and processing
• 📊 Progress Tracking: Real-time processing feedback and status reporting
• 🎯 Model Selection: Choose from 6 different AI models with --model parameter
• 📋 Model Management: List models (--list-models) and view details (--model-info)

System Requirements

• Python 3.13+
• FFmpeg (for video to audio conversion)
• macOS (Apple Silicon recommended for better performance)
• Sufficient memory to load Whisper models

Installation

Install FFmpeg

First, install FFmpeg for video conversion:

macOS:

brew install ffmpeg

Ubuntu/Debian:

sudo apt update
sudo apt install ffmpeg

Windows: Download from https://ffmpeg.org/download.html

Install Python Dependencies

Install dependencies using uv:

uv sync

For development with linting tools:

uv sync --extra dev

Quick Start

🚀 Simple Usage (Recommended)

The advanced CLI interface makes transcription incredibly easy:

# Basic transcription - automatic output file generation
uv run python -m cli.main input.webm
# Custom output file
uv run python -m cli.main input.webm my_transcription.txt
# Works with any supported format
uv run python -m cli.main meeting.mp3
uv run python -m cli.main video.mp4
uv run python -m cli.main audio.wav

🎯 Model Selection

Choose from 6 different AI models for optimal results:

# Use specific model
uv run python -m cli.main audio.mp3 --model local_whisper_base
# List all available models
uv run python -m cli.main --list-models
# Get detailed model information
uv run python -m cli.main --model-info local_breeze
# Use OpenAI API (requires OPENAI_API_KEY environment variable)export OPENAI_API_KEY="your-api-key"
uv run python -m cli.main audio.mp3 --model openai_api

📋 Available Models

Model ID	Type	Description	Best For
local_breeze	本地	MediaTek Breeze-ASR-25	中文語音識別 (默認)
local_whisper_base	本地	OpenAI Whisper Base	輕量級多語言轉錄
local_whisper_small	本地	OpenAI Whisper Small	平衡性能與準確度
local_whisper_medium	本地	OpenAI Whisper Medium	高品質轉錄
local_whisper_large	本地	OpenAI Whisper Large	最高準確度
openai_api	雲端	OpenAI Whisper API	免安裝，按使用付費

📋 CLI Options

# Show help and all available options
uv run python -m cli.main --help
# Show version information
uv run python -m cli.main --version
# Show supported input formats
uv run python -m cli.main --formats
# Show system diagnostics
uv run python -m cli.main --diagnostics
# Model management commands
uv run python -m cli.main --list-models # List all models
uv run python -m cli.main --model-info <model_id># Model details

🔄 Legacy Usage (Still Supported)

For backward compatibility, the original interface works with MP3 files:

# Place your audio file as 'meeting.mp3' in the project root
uv run python main.py

💡 Example Output

$ uv run python -m cli.main presentation.webm --model local_whisper_base
✅ Transcription completed successfully
Input: presentation.webm
Output: presentation_transcription.txt
Model: OpenAI Whisper Base (local)

Development

Code Quality Tools

The project includes several linting and formatting tools:

# Run linter
uv run ruff check main.py
# Auto-fix linting issues
uv run ruff check --fix main.py
# Format code
uv run black main.py
# Sort imports
uv run isort main.py
# Type checking
uv run mypy main.py

Pre-commit Hooks

Pre-commit hooks automatically run linting and formatting before each commit:

# Install pre-commit hooks (one-time setup)
uv run pre-commit install
# Run hooks manually on all files
uv run pre-commit run --all-files
# Run hooks on specific files
uv run pre-commit run --files main.py

The hooks will automatically:

• Remove trailing whitespace
• Fix end-of-file issues
• Check YAML syntax
• Run Ruff linter with auto-fix
• Format code with Ruff formatter
• Format code with Black
• Sort imports with isort

3. The program will:
   • Automatically detect audio file duration
   • Process long audio files in segments
   • Display processing progress
   • Save complete transcription results to transcription.txt

Program Flow

1. Load Audio: Supports MP3 format, automatically converts sample rate to 16kHz
2. Audio Preprocessing: Mono conversion and normalization
3. Model Loading: Uses MediaTek Breeze-ASR-25 Whisper model
4. Segmented Processing: Splits long audio into 30-second chunks for processing
5. Transcription Merging: Combines all segment results into complete transcript
6. Result Output: Saves to text file

Technical Architecture

• Audio Processing: torchaudio + soundfile
• Video Conversion: FFmpeg via ffmpeg-python
• Speech Recognition: Multi-model support (Hugging Face Transformers + OpenAI API)
• Hardware Acceleration: Apple MPS (Metal Performance Shaders)
• Package Management: uv
• Testing: pytest with asyncio support (115+ test cases)
• Code Quality: ruff, black, isort, mypy
• Model Management: Dynamic model loading/unloading with service abstraction

Module Structure

scrible-wise/
├── main.py # Legacy transcription program
├── cli/ # New CLI interface
│ ├── main.py # Main CLI entry point
│ └── integration.py # CLI integration layer
├── transcription/ # Core transcription workflow
│ └── workflow.py # Complete processing workflow
├── converters/ # Media conversion modules
│ └── media_converter.py # WebM to MP3 converter
├── validators/ # Audio validation modules
│ └── audio_validator.py # Audio file validator
├── utils/ # Utility modules
│ ├── ffmpeg_checker.py # FFmpeg dependency checker
│ ├── file_detector.py # File type detection
│ └── error_recovery.py # Error handling and retry logic
├── config/ # Configuration management
│ └── model_config.py # Model configuration and management
├── services/ # Transcription service abstraction
│ ├── base.py # Base transcription service interface
│ ├── local_breeze.py # MediaTek Breeze service
│ ├── local_whisper.py # Local Whisper service
│ └── openai_service.py # OpenAI API service
├── exceptions/ # Custom exception hierarchy
│ ├── base.py # Base exception classes
│ ├── conversion.py # Conversion-related exceptions
│ ├── validation.py # Validation-related exceptions
│ └── transcription.py # Transcription-related exceptions
└── tests/ # Comprehensive test suites (115+ tests)
├── test_*.py # Unit tests for all modules
└── test_workflow_error_integration.py # Integration tests

Error Handling & Recovery

Scrible Wise includes comprehensive error handling with automatic recovery suggestions:

$ uv run python -m cli.main broken_video.webm
❌ Error: FFmpeg not found. FFmpeg is required for media conversion.
Install it using: brew install ffmpeg (macOS) or sudo apt install ffmpeg (Ubuntu/Debian)

The system automatically:

• ✅ Detects Issues: Identifies missing dependencies, corrupted files, and format problems
• 🔄 Retries Operations: Automatic retry with exponential backoff for temporary failures
• 💡 Provides Solutions: Clear recovery suggestions for common problems
• 🧹 Cleans Up: Automatic cleanup of temporary files on errors

Notes

• First run will download Whisper model, internet connection required
• Processing time depends on audio length and hardware performance
• Recommended to run on Apple Silicon Mac for optimal performance
• Supports Chinese speech recognition, limited effectiveness for other languages

Testing

The project includes comprehensive test coverage with 115+ test cases covering all modules:

# Run all tests
uv run pytest -v
# Run specific test module
uv run pytest tests/test_workflow_error_integration.py -v
# Test specific model integration
uv run pytest tests/test_workflow_model_integration.py -v
# Test CLI model selection
uv run pytest tests/test_cli_model_selection.py -v
# Run with coverage
uv run pytest --cov=. --cov-report=html

Troubleshooting

Common Issues

Issue	Solution
FFmpeg not found	Install FFmpeg: brew install ffmpeg (macOS)
Audio loading failed	Install audio libraries: uv add soundfile librosa
CUDA errors	Program auto-switches to MPS/CPU - no action needed
Model download fails	Check internet connection, model downloads on first run
Memory errors	Try shorter audio files or use lighter models (base/small)
OpenAI API errors	Set OPENAI_API_KEY environment variable
Unknown model	Use --list-models to see available models

Getting Help

1. Check the error message for recovery suggestions
2. Verify FFmpeg installation: ffmpeg -version
3. Test with a smaller audio file
4. Check available disk space (models need ~2GB)