# SubPlz - Subtitle Pipeline for Everyone
**Automatically download YouTube videos and burn clean, professional subtitles into them!**
[](https://badge.fury.io/py/subtitle-for-everyone)
[](https://www.python.org/downloads/)
[](https://opensource.org/licenses/MIT)
## Features
- **One-command processing** - Just provide a YouTube URL or local video
- **Clean burned-in subtitles** - Professional white text with black outline
- **AI-powered transcription** - Uses OpenAI Whisper for accurate subtitles
- **Multiple formats** - Supports YouTube URLs and local video files
- **Smart dependency handling** - Guides you through installing missing dependencies
- **Automatic cleanup** - Removes temporary files after processing
## Installation
```bash
pip install subtitle-for-everyone
```
## System Requirements
### Required Dependencies
- **Python 3.8+**
- **FFmpeg** - For video processing
- Windows: Download from [ffmpeg.org](https://ffmpeg.org/download.html)
- macOS: `brew install ffmpeg`
- Linux: `sudo apt install ffmpeg`
### Python Dependencies (Installed Automatically)
- `yt-dlp` - YouTube video downloading
- `openai-whisper` - AI subtitle generation
- `torch` - Machine learning backend
- `ffmpeg-python` - Video processing
- `tqdm` - Progress bars
## Quick Start
### Process YouTube Videos
```bash
# Single YouTube video
subplz https://www.youtube.com/watch?v=VIDEO_ID
# The command will:
# 1. Download the video
# 2. Generate subtitles using AI
# 3. Burn clean white subtitles into the video
# 4. Save to 'processed_videos' folder
```
### Process Local Videos
```bash
# Local video file
subplz /path/to/your/video.mp4
subplz "C:\\Users\\Name\\Videos\\myvideo.mp4"
```
### Custom Output Directory
```bash
subplz https://www.youtube.com/watch?v=VIDEO_ID -o my_output_folder
```
## Clean Professional Subtitles
SubPlz creates clean, readable subtitles that look professional:
- **White text** (#FFFFFF) for maximum visibility
- **Black outline** for contrast on any background
- **No background box** - clean appearance
- **Arial Bold font** at size 24
- **Bottom center positioning** with proper margins
- **Perfect readability** on any video content
## Output
- Processed videos are saved with `_with_subtitles` suffix
- Original video quality is preserved
- Subtitles are permanently burned into the video
- Temporary files are automatically cleaned up
## Dependency Troubleshooting
If you get dependency errors, SubPlz will guide you:
### Missing FFmpeg
```
Missing dependencies: ffmpeg
Installation Instructions:
To install FFmpeg:
Windows: Download from https://ffmpeg.org/download.html
macOS: brew install ffmpeg
Linux: sudo apt install ffmpeg
Then add FFmpeg to your system PATH
```
### Missing yt-dlp
```
Missing dependencies: yt-dlp
Installation Instructions:
To install yt-dlp:
pip install yt-dlp
```
## Advanced Configuration
SubPlz uses sensible defaults, but you can customize behavior by modifying the config:
```python
# In your Python code
from subplz.config import NETFLIX_SUBTITLE_STYLE
# Customize subtitle appearance
NETFLIX_SUBTITLE_STYLE['fontsize'] = 28 # Bigger text
NETFLIX_SUBTITLE_STYLE['primary_colour'] = "&Hffffff" # White text (default)
NETFLIX_SUBTITLE_STYLE['outline'] = 3 # Thicker outline
```
## Examples
### Basic Usage
```bash
# Download and add subtitles to a YouTube video
subplz "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
```
### Batch Processing Script
```python
import subprocess
urls = [
"https://www.youtube.com/watch?v=VIDEO1",
"https://www.youtube.com/watch?v=VIDEO2",
"https://www.youtube.com/watch?v=VIDEO3"
]
for url in urls:
subprocess.run(["subplz", url])
```
### Local Video Processing
```bash
# Add subtitles to local videos
subplz "/Users/name/Movies/lecture.mp4"
subplz "C:\\Downloads\\presentation.mp4"
```
## Troubleshooting
### Common Issues
1. **"Command not found: subplz"**
```bash
pip install --upgrade subtitle-for-everyone
# Or try: python -m subplz
```
2. **"FFmpeg not found"**
- Install FFmpeg and add to system PATH
- Restart terminal after installation
3. **Out of memory errors**
- Use smaller Whisper model: modify `WHISPER_MODEL = "tiny"` in config
4. **Video download failures**
- Some videos may be region-blocked or private
- Try different video URLs
## License
MIT License - see [LICENSE](LICENSE) file for details.
## Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
## Support
- **GitHub Issues**: [github.com/guider23/subplz/issues](https://github.com/guider23/subplz/issues)
- **Email**: sofiyasenthilkumar@gmail.com
## Acknowledgments
- [OpenAI Whisper](https://github.com/openai/whisper) - AI transcription
- [yt-dlp](https://github.com/yt-dlp/yt-dlp) - YouTube downloading
- [FFmpeg](https://ffmpeg.org/) - Video processing
---
**Made with care by Sid & Kan**
Raw data
{
"_id": null,
"home_page": null,
"name": "subtitle-for-everyone",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "youtube, subtitles, video, netflix, whisper, ffmpeg",
"author": null,
"author_email": "Sid & Kan <sofiyasenthilkumar@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/b9/39/ace815fd70de7eeb7017159db1e22121933cb5953491bc5e0002173dcec6/subtitle_for_everyone-1.0.3.tar.gz",
"platform": null,
"description": "# SubPlz - Subtitle Pipeline for Everyone\r\n\r\n**Automatically download YouTube videos and burn clean, professional subtitles into them!**\r\n\r\n[](https://badge.fury.io/py/subtitle-for-everyone)\r\n[](https://www.python.org/downloads/)\r\n[](https://opensource.org/licenses/MIT)\r\n\r\n## Features\r\n\r\n- **One-command processing** - Just provide a YouTube URL or local video\r\n- **Clean burned-in subtitles** - Professional white text with black outline\r\n- **AI-powered transcription** - Uses OpenAI Whisper for accurate subtitles\r\n- **Multiple formats** - Supports YouTube URLs and local video files\r\n- **Smart dependency handling** - Guides you through installing missing dependencies\r\n- **Automatic cleanup** - Removes temporary files after processing\r\n\r\n## Installation\r\n\r\n```bash\r\npip install subtitle-for-everyone\r\n```\r\n\r\n## System Requirements\r\n\r\n### Required Dependencies\r\n- **Python 3.8+**\r\n- **FFmpeg** - For video processing\r\n - Windows: Download from [ffmpeg.org](https://ffmpeg.org/download.html)\r\n - macOS: `brew install ffmpeg`\r\n - Linux: `sudo apt install ffmpeg`\r\n\r\n### Python Dependencies (Installed Automatically)\r\n- `yt-dlp` - YouTube video downloading\r\n- `openai-whisper` - AI subtitle generation\r\n- `torch` - Machine learning backend\r\n- `ffmpeg-python` - Video processing\r\n- `tqdm` - Progress bars\r\n\r\n## Quick Start\r\n\r\n### Process YouTube Videos\r\n\r\n```bash\r\n# Single YouTube video\r\nsubplz https://www.youtube.com/watch?v=VIDEO_ID\r\n\r\n# The command will:\r\n# 1. Download the video\r\n# 2. Generate subtitles using AI\r\n# 3. Burn clean white subtitles into the video\r\n# 4. Save to 'processed_videos' folder\r\n```\r\n\r\n### Process Local Videos\r\n\r\n```bash\r\n# Local video file\r\nsubplz /path/to/your/video.mp4\r\nsubplz \"C:\\\\Users\\\\Name\\\\Videos\\\\myvideo.mp4\"\r\n```\r\n\r\n### Custom Output Directory\r\n\r\n```bash\r\nsubplz https://www.youtube.com/watch?v=VIDEO_ID -o my_output_folder\r\n```\r\n\r\n## Clean Professional Subtitles\r\n\r\nSubPlz creates clean, readable subtitles that look professional:\r\n\r\n- **White text** (#FFFFFF) for maximum visibility\r\n- **Black outline** for contrast on any background\r\n- **No background box** - clean appearance\r\n- **Arial Bold font** at size 24\r\n- **Bottom center positioning** with proper margins\r\n- **Perfect readability** on any video content\r\n\r\n## Output\r\n\r\n- Processed videos are saved with `_with_subtitles` suffix\r\n- Original video quality is preserved\r\n- Subtitles are permanently burned into the video\r\n- Temporary files are automatically cleaned up\r\n\r\n## Dependency Troubleshooting\r\n\r\nIf you get dependency errors, SubPlz will guide you:\r\n\r\n### Missing FFmpeg\r\n```\r\nMissing dependencies: ffmpeg\r\n\r\nInstallation Instructions:\r\nTo install FFmpeg:\r\n Windows: Download from https://ffmpeg.org/download.html\r\n macOS: brew install ffmpeg \r\n Linux: sudo apt install ffmpeg\r\n Then add FFmpeg to your system PATH\r\n```\r\n\r\n### Missing yt-dlp\r\n```\r\nMissing dependencies: yt-dlp\r\n\r\nInstallation Instructions: \r\nTo install yt-dlp:\r\n pip install yt-dlp\r\n```\r\n\r\n## Advanced Configuration\r\n\r\nSubPlz uses sensible defaults, but you can customize behavior by modifying the config:\r\n\r\n```python\r\n# In your Python code\r\nfrom subplz.config import NETFLIX_SUBTITLE_STYLE\r\n\r\n# Customize subtitle appearance\r\nNETFLIX_SUBTITLE_STYLE['fontsize'] = 28 # Bigger text\r\nNETFLIX_SUBTITLE_STYLE['primary_colour'] = \"&Hffffff\" # White text (default)\r\nNETFLIX_SUBTITLE_STYLE['outline'] = 3 # Thicker outline\r\n```\r\n\r\n## Examples\r\n\r\n### Basic Usage\r\n```bash\r\n# Download and add subtitles to a YouTube video\r\nsubplz \"https://www.youtube.com/watch?v=dQw4w9WgXcQ\"\r\n```\r\n\r\n### Batch Processing Script\r\n```python\r\nimport subprocess\r\n\r\nurls = [\r\n \"https://www.youtube.com/watch?v=VIDEO1\",\r\n \"https://www.youtube.com/watch?v=VIDEO2\", \r\n \"https://www.youtube.com/watch?v=VIDEO3\"\r\n]\r\n\r\nfor url in urls:\r\n subprocess.run([\"subplz\", url])\r\n```\r\n\r\n### Local Video Processing\r\n```bash\r\n# Add subtitles to local videos\r\nsubplz \"/Users/name/Movies/lecture.mp4\"\r\nsubplz \"C:\\\\Downloads\\\\presentation.mp4\" \r\n```\r\n\r\n## Troubleshooting\r\n\r\n### Common Issues\r\n\r\n1. **\"Command not found: subplz\"**\r\n ```bash\r\n pip install --upgrade subtitle-for-everyone\r\n # Or try: python -m subplz\r\n ```\r\n\r\n2. **\"FFmpeg not found\"**\r\n - Install FFmpeg and add to system PATH\r\n - Restart terminal after installation\r\n\r\n3. **Out of memory errors**\r\n - Use smaller Whisper model: modify `WHISPER_MODEL = \"tiny\"` in config\r\n\r\n4. **Video download failures**\r\n - Some videos may be region-blocked or private\r\n - Try different video URLs\r\n\r\n## License\r\n\r\nMIT License - see [LICENSE](LICENSE) file for details.\r\n\r\n## Contributing\r\n\r\nContributions are welcome! Please feel free to submit a Pull Request.\r\n\r\n## Support\r\n\r\n- **GitHub Issues**: [github.com/guider23/subplz/issues](https://github.com/guider23/subplz/issues)\r\n- **Email**: sofiyasenthilkumar@gmail.com\r\n\r\n## Acknowledgments\r\n\r\n- [OpenAI Whisper](https://github.com/openai/whisper) - AI transcription\r\n- [yt-dlp](https://github.com/yt-dlp/yt-dlp) - YouTube downloading\r\n- [FFmpeg](https://ffmpeg.org/) - Video processing\r\n\r\n---\r\n\r\n**Made with care by Sid & Kan**\r\n",
"bugtrack_url": null,
"license": null,
"summary": "Download YouTube videos and burn Netflix-style subtitles automatically",
"version": "1.0.3",
"project_urls": {
"Bug Reports": "https://github.com/guider23/subplz/issues",
"Homepage": "https://github.com/guider23/subplz",
"Source": "https://github.com/guider23/subplz"
},
"split_keywords": [
"youtube",
" subtitles",
" video",
" netflix",
" whisper",
" ffmpeg"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "0fb964623b9eec09ba5de397a1f4284c34de901c6fa8388826c3e7a3350a6d3c",
"md5": "6f86d97ecd7d65e92cfa38e4ac7c63dd",
"sha256": "533e2bb29b1de6e9d62f54443115a2e92d6823d29165e063e58acecaf67a5315"
},
"downloads": -1,
"filename": "subtitle_for_everyone-1.0.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "6f86d97ecd7d65e92cfa38e4ac7c63dd",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 10371,
"upload_time": "2025-08-28T17:34:04",
"upload_time_iso_8601": "2025-08-28T17:34:04.126593Z",
"url": "https://files.pythonhosted.org/packages/0f/b9/64623b9eec09ba5de397a1f4284c34de901c6fa8388826c3e7a3350a6d3c/subtitle_for_everyone-1.0.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "b939ace815fd70de7eeb7017159db1e22121933cb5953491bc5e0002173dcec6",
"md5": "45b160f4b39eb9d00a688974b188c46b",
"sha256": "7f89b8c5bad700f1a981b47630ed3d752cab13140e74e9fd0b8a0a269a3a7a97"
},
"downloads": -1,
"filename": "subtitle_for_everyone-1.0.3.tar.gz",
"has_sig": false,
"md5_digest": "45b160f4b39eb9d00a688974b188c46b",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 11728,
"upload_time": "2025-08-28T17:34:05",
"upload_time_iso_8601": "2025-08-28T17:34:05.576694Z",
"url": "https://files.pythonhosted.org/packages/b9/39/ace815fd70de7eeb7017159db1e22121933cb5953491bc5e0002173dcec6/subtitle_for_everyone-1.0.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-28 17:34:05",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "guider23",
"github_project": "subplz",
"github_not_found": true,
"lcname": "subtitle-for-everyone"
}
JSON
