{"id":30364765,"url":"https://github.com/aathifzahir/whisprsplit","last_synced_at":"2025-08-19T20:19:56.723Z","repository":{"id":309748051,"uuid":"1037421790","full_name":"AathifZahir/WhisprSplit","owner":"AathifZahir","description":"A powerful, local speech-to-text transcription system that combines OpenAI's Whisper for accurate transcription with pyannote.audio for speaker diarization (identifying who spoke when). Perfect for meetings, interviews, podcasts, and any audio/video content that needs accurate transcription with speaker identification.","archived":false,"fork":false,"pushed_at":"2025-08-13T14:57:37.000Z","size":17,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-08-13T16:48:31.327Z","etag":null,"topics":["diarization","speaker-recognition","speech","speech-diarization","speech-recognition","speech-to-text","transcribe","transcript","transcription"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/AathifZahir.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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-08-13T14:47:10.000Z","updated_at":"2025-08-13T15:07:25.000Z","dependencies_parsed_at":"2025-08-13T16:48:33.564Z","dependency_job_id":"12e2a974-329e-433f-a035-5b6d7db0e4bb","html_url":"https://github.com/AathifZahir/WhisprSplit","commit_stats":null,"previous_names":["aathifzahir/whisprsplit"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/AathifZahir/WhisprSplit","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AathifZahir%2FWhisprSplit","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AathifZahir%2FWhisprSplit/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AathifZahir%2FWhisprSplit/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AathifZahir%2FWhisprSplit/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/AathifZahir","download_url":"https://codeload.github.com/AathifZahir/WhisprSplit/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AathifZahir%2FWhisprSplit/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":271215037,"owners_count":24720098,"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","status":"online","status_checked_at":"2025-08-19T02:00:09.176Z","response_time":63,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["diarization","speaker-recognition","speech","speech-diarization","speech-recognition","speech-to-text","transcribe","transcript","transcription"],"created_at":"2025-08-19T20:19:56.115Z","updated_at":"2025-08-19T20:19:56.705Z","avatar_url":"https://github.com/AathifZahir.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Whisper + pyannote.audio Transcription System\n\n[![Python](https://img.shields.io/badge/Python-3.8+-blue.svg)](https://www.python.org/)\n[![Whisper](https://img.shields.io/badge/OpenAI-Whisper-green.svg)](https://github.com/openai/whisper)\n[![PyTorch](https://img.shields.io/badge/PyTorch-CUDA-orange.svg)](https://pytorch.org/)\n[![Speaker Diarization](https://img.shields.io/badge/pyannote-Speaker%20Diarization-purple.svg)](https://github.com/pyannote/pyannote-audio)\n[![FFmpeg](https://img.shields.io/badge/FFmpeg-Audio%20Processing-red.svg)](https://ffmpeg.org/)\n[![Local Processing](https://img.shields.io/badge/Local-Processing%20Only-brightgreen.svg)](https://github.com/)\n[![Multi Format](https://img.shields.io/badge/Multi-Format%20Output-yellow.svg)](https://github.com/)\n[![GPU Optimized](https://img.shields.io/badge/GPU-Optimized-lightblue.svg)](https://github.com/)\n\nA powerful, local speech-to-text transcription system that combines OpenAI's Whisper for accurate transcription with pyannote.audio for speaker diarization (identifying who spoke when). Perfect for meetings, interviews, podcasts, and any audio/video content that needs accurate transcription with speaker identification.\n\n## 🚀 Features\n\n- **High-Quality Transcription**: Uses OpenAI's Whisper models (tiny to large) for accurate speech recognition\n- **Speaker Diarization**: Identifies different speakers by voice patterns using pyannote.audio\n- **Video Support**: Extract audio from video files and run complete video-to-text pipelines\n- **GPU Acceleration**: Optimized for CUDA-enabled GPUs (RTX series) with 5-10x speed improvement\n- **Multiple Output Formats**: JSON, TXT, SRT, VTT for different use cases\n- **Batch Processing**: Process multiple files at once for efficiency\n- **Multi-language Support**: Auto-detects language with excellent support for English and other languages\n- **Interactive Workflow**: User-friendly guided workflow for beginners\n- **Flexible Audio Formats**: Support for MP3, WAV, M4A, FLAC, OGG, WMA input/output\n\n## 📋 Prerequisites\n\n- Python 3.8 or higher\n- FFmpeg (for video processing)\n- CUDA-compatible GPU (optional, for acceleration)\n- HuggingFace account and token (for speaker diarization)\n\n## 🛠️ Installation\n\n### 1. Clone the Repository\n\n```bash\ngit clone \u003cyour-repo-url\u003e\ncd transcriptor\n```\n\n### 2. Install Dependencies\n\n```bash\npip install -r requirements.txt\n```\n\n**Note**: If you encounter issues with PyTorch, install it separately:\n\n```bash\n# For CUDA support (recommended)\npip install torch torchaudio --index-url https://download.pytorch.org/whl/cu121\n\n# For CPU only\npip install torch torchaudio\n```\n\n### 3. Install FFmpeg\n\n**Windows:**\n\n- Download from [ffmpeg.org](https://ffmpeg.org/download.html)\n- Add to PATH or place in project directory\n\n**macOS:**\n\n```bash\nbrew install ffmpeg\n```\n\n**Linux:**\n\n```bash\nsudo apt update \u0026\u0026 sudo apt install ffmpeg\n```\n\n### 4. Get HuggingFace Token (Required for Speaker Diarization)\n\n1. Go to [HuggingFace Settings](https://huggingface.co/settings/tokens)\n2. Create a new token\n3. Accept terms at [pyannote/speaker-diarization](https://huggingface.co/pyannote/speaker-diarization)\n4. Set environment variable using one of these methods:\n\n   **Method 1: Set environment variable directly**\n\n   ```bash\n   # Windows (Command Prompt)\n   set HF_TOKEN=your_token_here\n\n   # Windows (PowerShell)\n   $env:HF_TOKEN=\"your_token_here\"\n\n   # Linux/Mac\n   export HF_TOKEN=your_token_here\n   ```\n\n   **Method 2: Create .env file (Recommended)**\n\n   ```bash\n   # Create .env file in project root\n   echo HF_TOKEN=your_token_here \u003e .env\n\n   # Or manually create .env file with:\n   # HF_TOKEN=your_token_here\n   ```\n\n   **Note**: The .env file method is recommended as it persists across terminal sessions and is automatically loaded by the application.\n\n## 🚀 Quick Start\n\n### Recommended: Interactive Workflow\n\nThe easiest way to get started is using the interactive workflow:\n\n```bash\npython transcribe_workflow.py\n```\n\nThis will guide you through the entire process with prompts, helping you choose:\n\n- Input type (video or audio)\n- Processing options\n- Output preferences\n\n### Alternative: Direct Commands\n\n```bash\n# Basic transcription\npython transcribe.py \"path/to/audio.mp3\"\n\n# With speaker diarization\npython transcribe.py \"path/to/audio.mp3\" --model small --device cuda\n\n# Video to text (extracts audio first, then transcribes)\npython video_to_text.py \"path/to/video.mp4\"\n\n# Audio extraction only\npython extract_audio.py \"path/to/video.mp4\" --format wav --quality high\n```\n\n## 📖 Detailed Usage\n\n### 1. Audio Transcription (`transcribe.py`)\n\nThe core transcription script with speaker diarization:\n\n```bash\npython transcribe.py \"audio/meeting.wav\" --model small --device cuda --output results/\n```\n\n**Options:**\n\n- `--model`: Whisper model size (tiny, base, small, medium, large)\n- `--device`: Device to use (cpu, cuda, auto)\n- `--output`: Output directory (default: \"output\")\n\n**Model Selection Guide:**\n\n- `tiny`: Fastest, good for English (39M parameters)\n- `base`: Good balance of speed/accuracy (74M parameters)\n- `small`: Better accuracy, moderate speed (244M parameters)\n- `medium`: High accuracy, slower (769M parameters)\n- `large`: Best accuracy, slowest (1550M parameters)\n\n### 2. Video Processing (`video_to_text.py`)\n\nComplete pipeline from video to transcribed text:\n\n```bash\npython video_to_text.py \"video/presentation.mp4\" --whisper-model small --device cuda\n```\n\n**Options:**\n\n- `--audio-format`: Audio format (mp3, wav, m4a, flac, ogg)\n- `--audio-quality`: Quality (low, medium, high)\n- `--whisper-model`: Whisper model size\n- `--device`: Device to use\n- `--keep-audio`: Keep extracted audio file\n\n### 3. Audio Extraction (`extract_audio.py`)\n\nExtract audio from video files:\n\n```bash\npython extract_audio.py \"video.mp4\" --format wav --quality high --output audio/\n```\n\n**Options:**\n\n- `--format`: Output audio format\n- `--quality`: Audio quality (affects bitrate/sample rate)\n- `--output`: Output directory\n- `--batch`: Process all videos in directory\n\n### 4. Interactive Workflow (`transcribe_workflow.py`)\n\nUser-friendly interface for all transcription tasks:\n\n```bash\npython transcribe_workflow.py\n```\n\n**Features:**\n\n- Guided file selection\n- Interactive option configuration\n- Progress tracking\n- Error handling and suggestions\n\n## 📁 Output Formats\n\nThe system generates multiple output formats for different use cases:\n\n- **JSON**: Detailed transcription with timestamps, speaker info, and confidence scores\n- **TXT**: Plain text transcription for easy reading\n- **SRT**: Subtitle format with speaker labels for video players\n- **VTT**: Web video subtitle format for web applications\n\n**Example JSON Output:**\n\n```json\n{\n  \"segments\": [\n    {\n      \"start\": 0.0,\n      \"end\": 2.5,\n      \"speaker\": \"Speaker 1\",\n      \"text\": \"Hello, welcome to our meeting.\",\n      \"confidence\": 0.95\n    }\n  ]\n}\n```\n\n## 🎯 Supported Formats\n\n### Video Input\n\n- **Common**: MP4, AVI, MOV, MKV, WMV, FLV\n- **Web**: WebM, M4V\n- **Mobile**: 3GP\n\n### Audio Input/Output\n\n- **Lossy**: MP3, M4A, OGG, WMA\n- **Lossless**: WAV, FLAC\n\n## 🌍 Language Support\n\nWhisper automatically detects the language. For best results:\n\n- **English**: All models work excellently\n- **Other Languages**: Use `medium` or `large` models for better accuracy\n- **Mixed Language**: Large models handle code-switching well\n\n## ⚡ Performance Optimization\n\n### GPU Acceleration\n\n- **CUDA Users**: Use `--device cuda` for 5-10x faster processing\n- **Memory Management**: Close other GPU applications to avoid CUDA out of memory errors\n- **Model Selection**: Balance between speed and accuracy based on your needs\n\n### Processing Tips\n\n- **Short Files**: Use `tiny` or `base` models for quick results\n- **Long Files**: Use `small` or `medium` for better accuracy\n- **Batch Processing**: Process multiple files overnight for efficiency\n\n## 🔧 Configuration\n\n### Environment Variables\n\n- `HF_TOKEN`: HuggingFace authentication token for speaker diarization\n- `CUDA_VISIBLE_DEVICES`: Specify which GPU to use (if multiple)\n\n### Custom Settings\n\nEdit the Python files to customize:\n\n- Default model sizes\n- Output directory structure\n- Audio quality preferences\n- Speaker diarization parameters\n\n## 🚨 Troubleshooting\n\n### Common Issues\n\n#### 1. \"No module named 'torch'\"\n\n```bash\npip install torch torchaudio --index-url https://download.pytorch.org/whl/cu121\n```\n\n#### 2. Speaker diarization not working\n\n- Ensure you have a valid HuggingFace token\n- Accept the pyannote.audio model terms\n- Set `HF_TOKEN` environment variable correctly\n- Check token permissions\n\n#### 3. CUDA out of memory\n\n- Use smaller Whisper model (`tiny` or `base`)\n- Close other GPU applications\n- Process shorter audio segments\n- Use CPU if GPU memory is insufficient\n\n#### 4. Audio extraction fails\n\n- Install FFmpeg: `conda install ffmpeg` or download from [ffmpeg.org](https://ffmpeg.org/)\n- Check video file integrity\n- Ensure video has audio track\n\n#### 5. Poor transcription quality\n\n- Use larger models for better accuracy\n- Ensure clear audio input\n- Check audio format compatibility\n- Consider audio preprocessing for noisy files\n\n### Getting Help\n\n1. Check the output files for detailed error information\n2. Ensure all dependencies are installed correctly\n3. Verify your HuggingFace token is valid\n4. Check system requirements (Python version, FFmpeg, etc.)\n\n## 📚 Example Workflows\n\n### Meeting Transcription\n\n1. **Extract audio from meeting video:**\n\n   ```bash\n   python extract_audio.py \"meeting.mp4\" --format wav --quality high\n   ```\n\n2. **Transcribe with speaker identification:**\n\n   ```bash\n   python transcribe.py \"meeting_audio.wav\" --model small --device cuda\n   ```\n\n3. **View results:**\n   - Check `output/` folder for all formats\n   - Open SRT file in video player for subtitles\n   - Use JSON for detailed analysis\n\n### Podcast Processing\n\n1. **Batch process multiple episodes:**\n\n   ```bash\n   python extract_audio.py \"podcasts/\" --batch --format mp3 --quality high\n   ```\n\n2. **Transcribe all episodes:**\n   ```bash\n   for file in audio/*.mp3; do\n     python transcribe.py \"$file\" --model medium --device cuda\n   done\n   ```\n\n### Video Content Creation\n\n1. **Extract audio for editing:**\n\n   ```bash\n   python extract_audio.py \"content.mp4\" --format wav --quality high\n   ```\n\n2. **Generate subtitles:**\n   ```bash\n   python transcribe.py \"content_audio.wav\" --model small --device cuda\n   ```\n\n## 🤝 Contributing\n\nWe welcome contributions! Here's how you can help:\n\n1. **Report Issues**: Use GitHub issues for bug reports and feature requests\n2. **Submit PRs**: Fork the repository and submit pull requests\n3. **Improve Documentation**: Help make the setup and usage clearer\n4. **Add Features**: Implement new output formats or processing options\n\n### Development Setup\n\n```bash\ngit clone \u003cyour-fork-url\u003e\ncd transcriptor\npip install -r requirements.txt\npip install -e .  # Install in development mode\n```\n\n## 📄 License\n\nThis project is open source and available under the [MIT License](LICENSE).\n\n## 🙏 Acknowledgments\n\n- **OpenAI Whisper**: For the excellent speech recognition models\n- **pyannote.audio**: For speaker diarization capabilities\n- **MoviePy**: For video processing and audio extraction\n- **FFmpeg**: For multimedia processing\n\n---\n\n**Made with ❤️ for easy, local transcription**\n\n_Transform your audio and video content into searchable, accessible text with professional-grade accuracy._\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faathifzahir%2Fwhisprsplit","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faathifzahir%2Fwhisprsplit","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faathifzahir%2Fwhisprsplit/lists"}