# YouTube Chat Downloader
This tool provides a simple method for retrieving chat logs from both past (VOD) and ongoing YouTube live streams for data analysis.
Live stream chats contain valuable data for understanding audience sentiment, identifying trends, and measuring engagement.
This downloader makes that data accessible for your research.
A Python package to download YouTube live chat replays and regular comments from any YouTube video. Perfect for archiving live streams, analyzing chat interactions, or collecting comment data.
## Features
- 🔴 **Live Stream Support**: Continuous polling mode for active live streams
- 💬 **Chat Replay**: Download complete chat history from finished live streams
- 📝 **Regular Comments**: Fetch standard video comments
- 🎯 **Multiple Formats**: Support for text messages, super chats, and membership messages
- 📊 **Rich Metadata**: Includes user info, timestamps, badges, and more
- 💾 **Auto-saving**: Incremental JSON output (survives interruptions)
- ⌨️ **Graceful Interruption**: Press Ctrl+C to stop and save progress
## Installation
### From PyPI (when published)
```bash
pip install yt-chat-downloader
```
### From Source
```bash
git clone https://github.com/yourusername/yt-chat-downloader.git
cd yt-chat-downloader
pip install -e .
```
## Quick Start
### Command Line
Download both chat replay and comments:
```bash
yt-chat-downloader "https://www.youtube.com/watch?v=VIDEO_ID"
```
Download only live chat replay:
```bash
yt-chat-downloader VIDEO_ID --chat-type live
```
Download only regular comments:
```bash
yt-chat-downloader VIDEO_ID --chat-type comments
```
Specify output file:
```bash
yt-chat-downloader VIDEO_ID -o my_chat.json
```
Quiet mode (minimal output):
```bash
yt-chat-downloader VIDEO_ID --quiet
```
### Python API
```python
from yt_chat_downloader import YouTubeChatDownloader
# Initialize downloader
downloader = YouTubeChatDownloader()
# Download chat and comments
messages = downloader.download_chat(
video_url="https://www.youtube.com/watch?v=VIDEO_ID",
chat_type="both", # Options: "live", "comments", "both"
output_file="chat_data.json",
quiet=False
)
# Process messages
for msg in messages:
print(f"{msg['user_display_name']}: {msg['comment']}")
```
## Output Format
The downloader saves messages in JSON format with the following structure:
```json
[
{
"user_id": "UC...",
"user_display_name": "Dev maker",
"user_handle": "@devmaker",
"datetime": "2024-01-15T10:30:00",
"timestamp": "1:23:45",
"comment": "Great stream!",
"message_type": "text",
"badges": ["Verified", "Member (6 months)"],
"message_id": "...",
"purchase_amount": "",
"video_offset_ms": "5025000"
}
]
```
### Message Types
- `text`: Regular chat message
- `super_chat`: Super Chat (paid message)
- `membership`: Membership milestone/welcome message
- `comment`: Regular video comment
## Live Stream Mode
For active live streams, the downloader enters **continuous polling mode**:
1. Automatically detects live streams
2. Polls for new messages continuously
3. Saves progress incrementally
4. Handles API rate limiting
5. Retries on temporary failures
6. Runs until you press Ctrl+C
Example:
```bash
yt-chat-downloader "https://www.youtube.com/watch?v=LIVE_VIDEO_ID"
# 🔴 LIVE STREAM DETECTED - Continuous polling mode enabled
# ⌨️ Press Ctrl+C to stop downloading
# [downloading messages...]
# ^C
# ⚠️ Download interrupted by user
# 💾 Messages saved to: youtube_chat_LIVE_VIDEO_ID_1234567890.json
```
## Dependencies
- Python 3.7+
- `click` - Command-line interface
- `requests` - HTTP requests
- `yt-dlp` - YouTube metadata extraction
- `python-dateutil` - Date parsing
## Use Cases
- **Archive live streams**: Save chat before it's deleted
- **Research & Analysis**: Analyze viewer engagement and sentiment
- **Content Creation**: Create highlight reels with chat context
- **Moderation**: Review chat history for moderation purposes
- **Bot Development**: Collect training data for chatbots
## Limitations
- Requires video to have live chat enabled
- Some videos may have chat disabled or deleted
- Rate limiting applies (handled automatically)
- Very old videos may have incomplete chat data
## Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
1. Fork the repository
2. Create your feature branch (`git checkout -b feature/AmazingFeature`)
3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)
4. Push to the branch (`git push origin feature/AmazingFeature`)
5. Open a Pull Request
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## Disclaimer
This tool is for educational and archival purposes. Please respect YouTube's Terms of Service and the privacy of content creators and chat participants. Use responsibly.
## Acknowledgments
- Built with [yt-dlp](https://github.com/yt-dlp/yt-dlp) for video metadata
- Uses YouTube's internal InnerTube API for chat data
## Support
If you encounter any issues or have questions:
- Open an issue on [GitHub](https://github.com/yourusername/yt-chat-downloader/issues)
- Check existing issues for solutions
- Provide video ID and error messages when reporting bugs
---
Made with ❤️ for the YouTube archiving community
Raw data
{
"_id": null,
"home_page": "https://github.com/yourusername/yt-chat-downloader",
"name": "yt-chat-downloader",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": "youtube, chat, downloader, live-chat, comments, ranks, yt-dlp",
"author": "Dev Maker",
"author_email": "Dev Maker <dev.maker@example.com>",
"download_url": "https://files.pythonhosted.org/packages/22/a7/7d2c7d522035ead288d6918f44b9268660e0d5bda0c030be05430493538a/yt_chat_downloader-0.0.3.tar.gz",
"platform": null,
"description": "# YouTube Chat Downloader\n\nThis tool provides a simple method for retrieving chat logs from both past (VOD) and ongoing YouTube live streams for data analysis.\nLive stream chats contain valuable data for understanding audience sentiment, identifying trends, and measuring engagement. \nThis downloader makes that data accessible for your research.\n\nA Python package to download YouTube live chat replays and regular comments from any YouTube video. Perfect for archiving live streams, analyzing chat interactions, or collecting comment data.\n\n## Features\n\n- \ud83d\udd34 **Live Stream Support**: Continuous polling mode for active live streams\n- \ud83d\udcac **Chat Replay**: Download complete chat history from finished live streams\n- \ud83d\udcdd **Regular Comments**: Fetch standard video comments\n- \ud83c\udfaf **Multiple Formats**: Support for text messages, super chats, and membership messages\n- \ud83d\udcca **Rich Metadata**: Includes user info, timestamps, badges, and more\n- \ud83d\udcbe **Auto-saving**: Incremental JSON output (survives interruptions)\n- \u2328\ufe0f **Graceful Interruption**: Press Ctrl+C to stop and save progress\n\n## Installation\n\n### From PyPI (when published)\n\n```bash\npip install yt-chat-downloader\n```\n\n### From Source\n\n```bash\ngit clone https://github.com/yourusername/yt-chat-downloader.git\ncd yt-chat-downloader\npip install -e .\n```\n\n## Quick Start\n\n### Command Line\n\nDownload both chat replay and comments:\n\n```bash\nyt-chat-downloader \"https://www.youtube.com/watch?v=VIDEO_ID\"\n```\n\nDownload only live chat replay:\n\n```bash\nyt-chat-downloader VIDEO_ID --chat-type live\n```\n\nDownload only regular comments:\n\n```bash\nyt-chat-downloader VIDEO_ID --chat-type comments\n```\n\nSpecify output file:\n\n```bash\nyt-chat-downloader VIDEO_ID -o my_chat.json\n```\n\nQuiet mode (minimal output):\n\n```bash\nyt-chat-downloader VIDEO_ID --quiet\n```\n\n### Python API\n\n```python\nfrom yt_chat_downloader import YouTubeChatDownloader\n\n# Initialize downloader\ndownloader = YouTubeChatDownloader()\n\n# Download chat and comments\nmessages = downloader.download_chat(\n video_url=\"https://www.youtube.com/watch?v=VIDEO_ID\",\n chat_type=\"both\", # Options: \"live\", \"comments\", \"both\"\n output_file=\"chat_data.json\",\n quiet=False\n)\n\n# Process messages\nfor msg in messages:\n print(f\"{msg['user_display_name']}: {msg['comment']}\")\n```\n\n## Output Format\n\nThe downloader saves messages in JSON format with the following structure:\n\n```json\n[\n {\n \"user_id\": \"UC...\",\n \"user_display_name\": \"Dev maker\",\n \"user_handle\": \"@devmaker\",\n \"datetime\": \"2024-01-15T10:30:00\",\n \"timestamp\": \"1:23:45\",\n \"comment\": \"Great stream!\",\n \"message_type\": \"text\",\n \"badges\": [\"Verified\", \"Member (6 months)\"],\n \"message_id\": \"...\",\n \"purchase_amount\": \"\",\n \"video_offset_ms\": \"5025000\"\n }\n]\n```\n\n### Message Types\n\n- `text`: Regular chat message\n- `super_chat`: Super Chat (paid message)\n- `membership`: Membership milestone/welcome message\n- `comment`: Regular video comment\n\n## Live Stream Mode\n\nFor active live streams, the downloader enters **continuous polling mode**:\n\n1. Automatically detects live streams\n2. Polls for new messages continuously\n3. Saves progress incrementally\n4. Handles API rate limiting\n5. Retries on temporary failures\n6. Runs until you press Ctrl+C\n\nExample:\n\n```bash\nyt-chat-downloader \"https://www.youtube.com/watch?v=LIVE_VIDEO_ID\"\n# \ud83d\udd34 LIVE STREAM DETECTED - Continuous polling mode enabled\n# \u2328\ufe0f Press Ctrl+C to stop downloading\n# [downloading messages...]\n# ^C\n# \u26a0\ufe0f Download interrupted by user\n# \ud83d\udcbe Messages saved to: youtube_chat_LIVE_VIDEO_ID_1234567890.json\n```\n\n## Dependencies\n\n- Python 3.7+\n- `click` - Command-line interface\n- `requests` - HTTP requests\n- `yt-dlp` - YouTube metadata extraction\n- `python-dateutil` - Date parsing\n\n## Use Cases\n\n- **Archive live streams**: Save chat before it's deleted\n- **Research & Analysis**: Analyze viewer engagement and sentiment\n- **Content Creation**: Create highlight reels with chat context\n- **Moderation**: Review chat history for moderation purposes\n- **Bot Development**: Collect training data for chatbots\n\n## Limitations\n\n- Requires video to have live chat enabled\n- Some videos may have chat disabled or deleted\n- Rate limiting applies (handled automatically)\n- Very old videos may have incomplete chat data\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n1. Fork the repository\n2. Create your feature branch (`git checkout -b feature/AmazingFeature`)\n3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)\n4. Push to the branch (`git push origin feature/AmazingFeature`)\n5. Open a Pull Request\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Disclaimer\n\nThis tool is for educational and archival purposes. Please respect YouTube's Terms of Service and the privacy of content creators and chat participants. Use responsibly.\n\n## Acknowledgments\n\n- Built with [yt-dlp](https://github.com/yt-dlp/yt-dlp) for video metadata\n- Uses YouTube's internal InnerTube API for chat data\n\n## Support\n\nIf you encounter any issues or have questions:\n\n- Open an issue on [GitHub](https://github.com/yourusername/yt-chat-downloader/issues)\n- Check existing issues for solutions\n- Provide video ID and error messages when reporting bugs\n\n---\n\nMade with \u2764\ufe0f for the YouTube archiving community\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Download YouTube live chat replays and comments (Beta)",
"version": "0.0.3",
"project_urls": {
"Homepage": "https://github.com/yourusername/yt-chat-downloader",
"Issues": "https://github.com/yourusername/yt-chat-downloader/issues",
"Repository": "https://github.com/yourusername/yt-chat-downloader"
},
"split_keywords": [
"youtube",
" chat",
" downloader",
" live-chat",
" comments",
" ranks",
" yt-dlp"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "1b145f362a8aea6a5d9cdbdd340d2d71525bea00340ed179418020c299b0ea83",
"md5": "9cf0bcfb3f0e277217bf380415518460",
"sha256": "af3f8656d9ceaaa38435f9616807a15aaec0f2973efbfcb58a0f762ed46f833b"
},
"downloads": -1,
"filename": "yt_chat_downloader-0.0.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "9cf0bcfb3f0e277217bf380415518460",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 15057,
"upload_time": "2025-10-25T17:35:01",
"upload_time_iso_8601": "2025-10-25T17:35:01.756512Z",
"url": "https://files.pythonhosted.org/packages/1b/14/5f362a8aea6a5d9cdbdd340d2d71525bea00340ed179418020c299b0ea83/yt_chat_downloader-0.0.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "22a77d2c7d522035ead288d6918f44b9268660e0d5bda0c030be05430493538a",
"md5": "70c211eada751d3776e06c7aa9508ed6",
"sha256": "b27ce3bdc6d1c1180eae078aa82e783c30d8b532c68968a59c10da0ac5602278"
},
"downloads": -1,
"filename": "yt_chat_downloader-0.0.3.tar.gz",
"has_sig": false,
"md5_digest": "70c211eada751d3776e06c7aa9508ed6",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 17303,
"upload_time": "2025-10-25T17:35:04",
"upload_time_iso_8601": "2025-10-25T17:35:04.134638Z",
"url": "https://files.pythonhosted.org/packages/22/a7/7d2c7d522035ead288d6918f44b9268660e0d5bda0c030be05430493538a/yt_chat_downloader-0.0.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-25 17:35:04",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "yourusername",
"github_project": "yt-chat-downloader",
"github_not_found": true,
"lcname": "yt-chat-downloader"
}
JSON
