Skip to content

README.md

Latest commit

 

History

History
322 lines (246 loc) · 10.8 KB

README.md

File metadata and controls

322 lines (246 loc) · 10.8 KB
Raw

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
  1. 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)