{"id":28455413,"url":"https://github.com/theseraphim/scribe-forge-ai","last_synced_at":"2026-05-05T08:33:40.775Z","repository":{"id":297251233,"uuid":"991131031","full_name":"TheSeraphim/scribe-forge-ai","owner":"TheSeraphim","description":"🎵 Complete offline audio transcription system with speaker diarization using OpenAI Whisper and PyAnnote. Features automatic audio cleaning, precise timestamps, multiple output formats (JSON/TXT/Markdown), and support for 20+ audio formats. No external APIs required - works entirely offline.","archived":false,"fork":false,"pushed_at":"2025-06-16T13:08:56.000Z","size":2387,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-06-16T14:31:41.810Z","etag":null,"topics":["audio-analysis","audio-cleaning","audio-processing","audio-transcription","diarization","ffmpeg","huggingface","machine-learning","multi-speaker","nlp","offline-transcription","openai-whisper","pyannote","python","speaker-diarization","speech-recognition","speech-to-text","timestamps","transcription-tool","whisper"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/TheSeraphim.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-05-27T07:06:44.000Z","updated_at":"2025-06-16T13:52:38.000Z","dependencies_parsed_at":"2025-06-09T07:50:34.151Z","dependency_job_id":null,"html_url":"https://github.com/TheSeraphim/scribe-forge-ai","commit_stats":null,"previous_names":["theseraphim/scribe-forge-ai"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/TheSeraphim/scribe-forge-ai","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TheSeraphim%2Fscribe-forge-ai","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TheSeraphim%2Fscribe-forge-ai/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TheSeraphim%2Fscribe-forge-ai/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TheSeraphim%2Fscribe-forge-ai/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/TheSeraphim","download_url":"https://codeload.github.com/TheSeraphim/scribe-forge-ai/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TheSeraphim%2Fscribe-forge-ai/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":262460162,"owners_count":23314668,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["audio-analysis","audio-cleaning","audio-processing","audio-transcription","diarization","ffmpeg","huggingface","machine-learning","multi-speaker","nlp","offline-transcription","openai-whisper","pyannote","python","speaker-diarization","speech-recognition","speech-to-text","timestamps","transcription-tool","whisper"],"created_at":"2025-06-06T22:00:50.101Z","updated_at":"2026-05-05T08:33:40.744Z","avatar_url":"https://github.com/TheSeraphim.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"![](./scribe-forge.ai.png)\n\n## ☕ Support This Project\n\nSupport my work: [coff.ee/theseraphim](https://coff.ee/theseraphim)\n\n# Audio Transcription Tool\n\nComplete system for audio transcription with speaker diarization, using AI models that work entirely offline. Optimized for Windows with intelligent installation and automatic compatibility handling.\n\n## Features\n\n- **Accurate transcription** using OpenAI Whisper models\n- **Intelligent speaker diarization** with automatic method selection:\n  - Python 3.12+: Resemblyzer (no compilation issues, no tokens needed)\n  - Python 3.11-: pyannote.audio (traditional method)\n- **Precise timestamps** for every segment and word\n- **Automatic audio cleaning** to improve quality\n- **Support for multiple formats** (M4A, WAV, MP3, FLAC, etc.)\n- **Multiple output types** (JSON, TXT, Markdown)\n- **Offline operation** - no external APIs required\n- **Optimized GPU acceleration** with CUDA 12.4 support\n- **Local model caching** for offline usage\n- **Detailed logging** with precise timestamps\n- **Zero-config installation** for most scenarios\n\n## Installation (Windows)\n\n### 🚀 One-Click Installation (Recommended)\n\n**Run PowerShell as Administrator** and execute:\n\n```powershell\n# Full installation with all features\n.\\install.ps1\n\n# With model downloads for offline usage\n.\\install.ps1 -DownloadModels -DownloadDiarizationModels -HuggingFaceToken \"hf_your_token\"\n\n# CPU-only installation (no CUDA)\n.\\install.ps1 -NoGPU\n\n# Skip speaker diarization if not needed\n.\\install.ps1 -SkipDiarization\n```\n\n**The installation script automatically:**\n- ✅ Detects your Python version and chooses the best compatibility approach\n- ✅ Installs optimized PyTorch with CUDA 12.4 for maximum GPU performance\n- ✅ Handles all dependency conflicts and compilation issues\n- ✅ Sets up speaker diarization without HuggingFace token hassles (Python 3.12+)\n- ✅ Downloads models locally for offline usage (optional)\n- ✅ Creates a ready-to-use virtual environment\n\n### Installation Options\n\n```powershell\n# Installation script options\n.\\install.ps1 [OPTIONS]\n\nOptions:\n  -SkipDependencies         # Skip system tools (Python, FFmpeg, etc.)\n  -NoGPU                   # Force CPU-only PyTorch\n  -DownloadModels          # Download Whisper models\n  -DownloadDiarizationModels # Download speaker diarization models locally\n  -SkipDiarization         # Skip speaker diarization setup\n  -ForceNonAdmin           # Run without Administrator (limited functionality)\n  -HuggingFaceToken        # Specify HF token for pyannote models\n  -Help                    # Show detailed help\n```\n\n### System Requirements\n\n**Minimum:**\n- Windows 10/11\n- PowerShell 5.1+\n- Administrator privileges (for installation)\n- 4GB RAM\n- 2GB disk space\n\n**Recommended:**\n- Windows 11\n- 16GB RAM\n- NVIDIA GPU with 6GB+ VRAM (automatically detected)\n- 10GB free disk space\n\n### Manual Installation (Advanced Users)\n\nIf you prefer manual control:\n\n```powershell\n# 1. Create virtual environment\npython -m venv venv\nvenv\\Scripts\\Activate.ps1\n\n# 2. Install dependencies\npip install -r requirements.txt\n\n# 3. For GPU acceleration (optional)\npip install torch torchaudio --index-url https://download.pytorch.org/whl/cu124\n\n# 4. For speaker diarization (Python 3.12+)\npip install resemblyzer scikit-learn\n\n# 5. For speaker diarization (Python 3.11-)\npip install pyannote.audio\n```\n\n## Models Used\n\n### Whisper (Transcription)\nWhisper models are downloaded automatically on first use or with `-DownloadModels`:\n\n| Model | Size | VRAM | Speed | Quality |\n|-------|------|------|-------|---------|\n| tiny    | 39 MB  | ~1GB | ~32x | Basic |\n| base    | 74 MB  | ~1GB | ~16x | Good |\n| small   | 244 MB | ~2GB | ~6x  | Very good |\n| medium  | 769 MB | ~5GB | ~2x  | Excellent |\n| large-v3| 1550 MB| ~10GB| ~1x  | Best |\n\n### Speaker Diarization\n\n**Resemblyzer** (Python 3.12+, default):\n- **Advantages**: No compilation, no tokens needed, works immediately\n- **Size**: ~50MB\n- **Requirements**: None beyond installation script\n\n**PyAnnote** (Python 3.11-, optional):\n- **Model**: `pyannote/speaker-diarization-3.1`\n- **Size**: ~300MB\n- **Requirements**: HuggingFace token and model acceptance\n\n## Usage\n\n### Basic Examples\n\n```bash\n# Activate virtual environment first\nvenv\\Scripts\\Activate.ps1\n\n# Simple transcription\npython main.py input.m4a -o output --format txt\n\n# With speaker diarization\npython main.py input.m4a -o output --format md --diarize\n\n# High quality with GPU acceleration\npython main.py input.m4a -o output --format json --model-size large-v3 --clean-audio --diarize\n\n# Force CPU usage\npython main.py input.m4a -o output --format txt --device cpu\n```\n\n### Full Parameters\n\n```bash\npython main.py INPUT_FILE -o OUTPUT_PATH [OPTIONS]\n\nRequired arguments:\n  INPUT_FILE                Input audio file\n  -o, --output OUTPUT_PATH  Output path (without extension)\n\nOptions:\n  --format {json,txt,md}    Output format (default: txt)\n  --model-size {tiny,base,small,medium,large,large-v2,large-v3}\n                            Whisper model size (default: base)\n  --diarize                 Enable speaker diarization\n  --language LANG           Audio language (auto-detect if not specified)\n  --device {auto,cpu,cuda}  Processing device (default: auto)\n  --download-models         Download models before processing\n  --log-level {DEBUG,INFO,WARNING,ERROR}\n                            Logging level (default: INFO)\n  --clean-audio             Apply audio cleaning\n```\n\n### Practical Examples\n\n```bash\n# Italian meeting with multiple speakers\npython main.py meeting.m4a -o meeting_transcript \\\n  --format md --diarize --language it --clean-audio\n\n# English interview, JSON output for analysis\npython main.py interview.wav -o interview_data \\\n  --format json --model-size medium --diarize\n\n# Long podcast with best quality\npython main.py podcast.mp3 -o podcast_transcript \\\n  --format txt --model-size large-v3 --log-level DEBUG\n```\n\n## Output Structure\n\n### TXT Format\n```\nAudio Transcription\nGenerated: 2025-06-17 14:30:00\nLanguage: Italian\nSpeakers detected: 2\n\n==================================================\n\n[00:00:05] SPEAKER_00: Buongiorno e benvenuti alla nostra riunione.\n[00:00:12] SPEAKER_01: Grazie, sono felice di essere qui.\n[00:00:18] SPEAKER_00: Iniziamo con il primo punto all'ordine del giorno.\n```\n\n### JSON Format\n```json\n{\n  \"metadata\": {\n    \"created_at\": \"2025-06-17T14:30:00\",\n    \"language\": \"Italian\",\n    \"has_speakers\": true,\n    \"total_segments\": 45,\n    \"diarization_method\": \"Resemblyzer\"\n  },\n  \"transcription\": {\n    \"text\": \"Full transcription text...\",\n    \"language\": \"Italian\",\n    \"segments\": [\n      {\n        \"id\": 0,\n        \"start\": 5.2,\n        \"end\": 8.7,\n        \"text\": \"Buongiorno e benvenuti\",\n        \"speaker\": \"SPEAKER_00\",\n        \"words\": [\n          {\n            \"word\": \"Buongiorno\",\n            \"start\": 5.2,\n            \"end\": 5.8,\n            \"probability\": 0.95\n          }\n        ]\n      }\n    ]\n  }\n}\n```\n\n### Markdown Format\n```markdown\n# Audio Transcription\n\n**Generated:** 2025-06-17 14:30:00  \n**Language:** Italian  \n**Speakers:** 2  \n**Diarization:** Resemblyzer\n\n---\n\n## Transcription with Timestamps\n\n### SPEAKER_00\n\n**00:00:05**: Buongiorno e benvenuti alla nostra riunione.\n\n**00:00:18**: Iniziamo con il primo punto all'ordine del giorno.\n\n### SPEAKER_01\n\n**00:00:12**: Grazie, sono felice di essere qui.\n```\n\n## Smart Installation Features\n\n### Automatic Python Version Handling\nThe installation script detects your Python version and automatically chooses the best approach:\n\n**Python 3.13+**: Uses Resemblyzer for speaker diarization (recommended)\n- ✅ No compilation issues\n- ✅ No HuggingFace tokens needed\n- ✅ Works immediately after installation\n\n**Python 3.11-3.12**: Offers both Resemblyzer and pyannote.audio options\n- ✅ Fallback mechanisms for maximum compatibility\n- ✅ Handles compilation issues automatically\n\n### GPU Optimization\n- **Automatic CUDA detection** and driver compatibility check\n- **Optimized PyTorch** installation with CUDA 12.4 support\n- **Eliminates Triton warnings** and performance issues\n- **CPU fallback** for systems without compatible GPUs\n\n### Local Model Caching\n```powershell\n# Download models for offline usage\n.\\install.ps1 -DownloadDiarizationModels -HuggingFaceToken \"hf_your_token\"\n```\n- Downloads pyannote models to local cache\n- Enables completely offline operation\n- Bypasses HuggingFace authentication during transcription\n- Automatic cache setup and management\n\n## Troubleshooting\n\n### Installation Issues\n\n**1. \"Administrator privileges required\"**\n```\nERROR This script requires Administrator privileges!\n```\n**Solution**: Run PowerShell as Administrator or use:\n```powershell\n.\\install.ps1 -ForceNonAdmin -SkipDependencies\n```\n\n**2. Python version compatibility**\n```\nWARNING Python 3.13 detected - using Resemblyzer for speaker diarization\n```\n**Solution**: This is normal! The script automatically uses the best method for your Python version.\n\n**3. CUDA installation issues**\n```\nWARNING Failed to install CUDA toolkit\n```\n**Solution**: Use CPU-only mode:\n```powershell\n.\\install.ps1 -NoGPU\n```\n\n### Runtime Issues\n\n**1. Speaker diarization not working**\n```\nINFO No speaker diarization available\n```\n**Check**: Verify installation completed successfully:\n```bash\npython -c \"import resemblyzer; print('Resemblyzer available')\"\n```\n\n**2. GPU not detected**\n```\nINFO Using device: cpu\n```\n**Solution**: Check CUDA installation:\n```bash\npython -c \"import torch; print(torch.cuda.is_available())\"\n```\n\n**3. Model download issues**\n```\nWARNING Model download failed\n```\n**Solution**: Models download automatically on first use, or use:\n```powershell\n.\\install.ps1 -DownloadModels\n```\n\n### Performance Optimization\n\n**For long files (\u003e1 hour):**\n- Use `--model-size small` or `base`\n- Avoid `--clean-audio` if not needed\n- Consider using `--device cpu` for very long files\n\n**For best quality:**\n- Use `--model-size large-v3`\n- Enable `--clean-audio`\n- Ensure GPU acceleration: `--device cuda`\n\n**For maximum speed:**\n- Use `--model-size tiny`\n- Disable diarization or use Resemblyzer method\n- Skip audio cleaning\n\n## Logging\n\nThe system uses detailed logging with timestamps:\n\n```\n[20250617-143000] INFO - Starting audio transcription process\n[20250617-143001] INFO - Using device: cuda\n[20250617-143001] INFO - Resemblyzer available - speaker diarization enabled\n[20250617-143002] INFO - Processing audio file: meeting.m4a\n[20250617-143005] INFO - Loaded audio: 1547.2s, 16000Hz\n[20250617-143006] INFO - Loading Whisper model: large-v3\n[20250617-143008] INFO - Starting transcription...\n[20250617-143045] INFO - Detected language: Italian\n[20250617-143046] INFO - Performing speaker diarization...\n[20250617-143078] INFO - Diarization completed: 2 speakers detected\n[20250617-143079] INFO - Saving output in md format...\n[20250617-143080] INFO - ✅ Transcription completed with speaker diarization\n```\n\n## Supported Audio Formats\n\n- **Input**: M4A, WAV, MP3, FLAC, OGG, WMA, AAC\n- **Internal processing**: WAV 16kHz mono\n- **Maximum duration**: Limited only by available memory\n\n## Advanced Configuration\n\n### Environment Variables\n```powershell\n# For offline pyannote usage (if downloaded locally)\n$env:HF_HUB_OFFLINE = \"1\"\n\n# Force CPU usage\n$env:CUDA_VISIBLE_DEVICES = \"\"\n\n# Custom cache directory\n$env:TRANSFORMERS_CACHE = \"D:\\models\\cache\"\n```\n\n### Custom Diarization Settings\nThe system automatically chooses the best diarization method, but you can verify which is being used:\n\n```bash\npython -c \"\nimport sys\nsys.path.append('src')\nfrom diarizer import Diarizer\nprint('Diarizer using optimal method for your Python version')\n\"\n```\n\n## License\n\nThis project uses:\n- **Whisper**: MIT License (OpenAI)\n- **Resemblyzer**: Apache 2.0 License\n- **PyAnnote**: MIT License\n- **Other dependencies**: Various open source licenses\n\nSee the LICENSE files of the individual dependencies for full details.\n\n---\n\n**🎯 Ready to transcribe? Run `.\\install.ps1` as Administrator and you'll be set up in minutes!**\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftheseraphim%2Fscribe-forge-ai","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftheseraphim%2Fscribe-forge-ai","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftheseraphim%2Fscribe-forge-ai/lists"}