repository·master·Indexed 22 days ago
https://github.com/xenova/chat-downloaderA tool for retrieving chat messages from livestreaming and video platforms including YouTube, Twitch, and Zoom. It is available as a standalone CLI tool and a Python library with a generator-based API. Features include message filtering by types or groups, timing controls, and support for site-specific arguments.
Chat Downloader currently supports retrieving chat from the following platforms:
chat_downloader.sites module provides specialized downloader classes for different streaming platforms. Instead of using a generic downloader, you can instantiate specific classes to target YouTube, Twitch, or Zoom. All site-specific downloaders inherit from BaseChatDownloader.When using ChatDownloader, options are categorized into two scopes:
ChatDownloader object. These settings are persistent and will be applied to every subsequent call to the get_chat method using that instance.get_chat method. These settings apply only to that specific call and do not affect other calls made with the same ChatDownloader instance.You can control which chat messages are included in a download by specifying how messages are filtered. Note that message types and message groups are mutually exclusive; you must choose one method per call.
Specify individual message_type values. This allows for granular control over exactly which message categories are captured.
Specify a message_group name. A group is a site-specific collection of multiple message types. Selecting a group automatically includes all message types associated with that group for the target site.
Example Logic:
If message_group_1 contains message_type_1 and message_type_2, specifying message_group_1 is functionally equivalent to specifying both message_type_1 and message_type_2 individually.
Every chat item retrieved by chat-downloader is represented as a dictionary.
Important: You should treat every field as optional. While most items include basic information like timestamp, message, or author, the presence of these fields cannot be guaranteed for every item.
Chat messages are parsed into JSON objects (dictionaries). Each item contains metadata about the message, the author, and timing information.
Key fields include:
message_id: Unique identifier for the message.message: The actual text content.message_type: The type of message (e.g., text_message).timestamp: The message timestamp.time_in_seconds: Time in seconds.time_text: Formatted time string (e.g., 20:34).author: An object containing id, name, images, and badges.Example structure:
{
"message_id": "xxxxxxxxxx",
"message": "actual message goes here",
"message_type": "text_message",
"timestamp": 1613761152565924,
"time_in_seconds": 1234.56,
"time_text": "20:34",
"author": {
"id": "UCxxxxxxxxxxxxxxxxxxxxxxx",
"name": "username_of_sender",
"images": [...],
"badges": [...]
}
}{
"message_id": "xxxxxxxxxx",
"message": "actual message goes here",
"message_type": "text_message",
"timestamp": 1613761152565924,
"time_in_seconds": 1234.56,
"time_text": "20:34",
"author": {
"id": "UCxxxxxxxxxxxxxxxxxxxxxxx",
"name": "username_of_sender",
"images": [...],
"badges": [...]
}
}To contribute to the project, fork the repository, clone it locally, and install the package in editable mode with developer dependencies using pip.
$ git clone git@github.com:YOUR_GITHUB_USERNAME/chat-downloader.git$ cd chat-downloader
$ git checkout -b name$ pip install -e .[dev]$ pip install -e .[dev]You can install chat-downloader using pip from PyPI, or by cloning the repository directly from GitHub.
To install via pip:
$ pip install chat-downloaderTo update to the latest version:
$ pip install chat-downloader --upgradeTo install from source using git:
$ git clone https://github.com/xenova/chat-downloader.git
$ cd chat-downloader
$ python setup.py install$ pip install chat-downloaderIf you are encountering issues with parsing or want to help identify undocumented endpoints, run the chat_downloader command with the --testing flag. This will print debugging messages and pause the execution when an unexpected item is encountered (e.g., an unknown item being parsed). This flag does not affect output written to files via --output.
$ chat_downloader https://www.youtube.com/watch?v=5qap5aO4i9A --testingYou can install chat-downloader via PyPI using pip or by cloning the repository from GitHub.
To install via pip:
$ pip install chat-downloaderTo update to the latest version:
$ pip install --upgrade chat-downloaderTo install from source via git:
$ git clone https://github.com/xenova/chat-downloader.git
$ cd chat-downloader
$ python setup.py installUse pytest to verify your changes. You can run the full suite, tests for all sites, or specific tests for a single site.
$ pytest -v$ pytest -v tests/test_chat_downloader.py::TestChatDownloader$ pytest -v tests/test_chat_downloader.py::TestChatDownloader::test_YourChatDownloader_TestNumber (e.g., test_YouTubeChatDownloader_1)$ pytest -v tests/test_chat_downloader.py::TestChatDownloader::test_YouTubeChatDownloader_1Ensure your code follows project conventions by running flake8. You can ignore specific warnings like E501, W503, and W504 if they are not critical to your changes.
$ flake8 path/to/code/to/check.py --ignore E501,W503,W504