..
    TODO
    - temp move ... move back to root
    - auto-generate using other rst files

***************
Chat Downloader
***************

.. image:: https://img.shields.io/pypi/pyversions/chat-downloader
   :target: https://pypi.org/project/chat-downloader
   :alt: Python

.. image:: https://img.shields.io/pypi/v/chat-downloader.svg
   :target: https://pypi.org/project/chat-downloader
   :alt: PyPI version

.. image:: https://pepy.tech/badge/chat-downloader/month
   :target: https://pypi.org/project/chat-downloader
   :alt: Downloads

.. image:: https://img.shields.io/github/license/xenova/chat-downloader
  :target: https://github.com/xenova/chat-downloader/blob/master/LICENSE
  :alt: License

.. image:: https://img.shields.io/endpoint?url=https%3A%2F%2Fraw.githubusercontent.com%2Fxenova%2Fchat-downloader%2Fmaster%2Fdocs%2F_dynamic%2Fcoverage.json
  :target: https://pypi.org/project/chat-downloader
  :alt: Coverage

..
    [![GitHub issues](https://img.shields.io/github/issues/xenova/chat-downloader)](https://badge.fury.io/py/chat-downloader)
    [![GitHub forks](https://img.shields.io/github/forks/xenova/chat-downloader)](https://badge.fury.io/py/chat-downloader)
    [![GitHub stars](https://img.shields.io/github/stars/xenova/chat-downloader)](https://badge.fury.io/py/chat-downloader)
    [![Downloads](https://img.shields.io/github/downloads/xenova/chat-downloader/total.svg)](https://github.com/xenova/chat-downloader/releases)

`Chat Downloader`_ is a simple tool used to retrieve chat messages from livestreams,
videos, clips and past broadcasts. No authentication needed!

.. _Chat Downloader: https://github.com/xenova/chat-downloader

############
Installation
############

This tool is distributed on PyPI_ and can be installed with ``pip``:

.. _PyPI: https://pypi.org/project/chat-downloader/

.. code:: console

   $ pip install chat-downloader

To update to the latest version, add the ``--upgrade`` flag to the above command.

Alternatively, the tool can be installed with ``git``:

.. code:: console

   $ git clone https://github.com/xenova/chat-downloader.git
   $ cd chat-downloader
   $ python setup.py install


#####
Usage
#####


Command line
------------

.. program-output:: cd .. && python -m chat_downloader -h | awk '{print} /url/ {exit}'
    :shell:

For example, to save messages from a livestream to a JSON file, you can use:

.. code:: console

   $ chat_downloader https://www.youtube.com/watch?v=jfKfPfyJRdk --output chat.json



For a description of these options, as well as advanced command line use-cases and examples, consult the :ref:`Command Line Usage` page.


Python
------

.. code:: python

   from chat_downloader import ChatDownloader

   url = 'https://www.youtube.com/watch?v=jfKfPfyJRdk'
   chat = ChatDownloader().get_chat(url)       # create a generator
   for message in chat:                        # iterate over messages
       chat.print_formatted(message)           # print the formatted message


For advanced python use-cases and examples, consult the :ref:`Python Documentation`.


##########
Chat Items
##########

Chat items/messages are parsed into JSON objects (a.k.a. dictionaries) and should follow a format similar to this:

.. code-block::

    {
        ...
        "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": [
                ...
            ]
        },
        ...
    }


For an extensive, documented list of included fields, consult the :ref:`Chat Item Fields` page.

##########################
Frequently Asked Questions
##########################

*Coming soon*

######
Issues
######

Found a bug or have a suggestion? File an issue `here`_. To assist the
developers in fixing the issue, please follow the issue template as
closely as possible.

.. _here: https://github.com/xenova/chat-downloader/issues/new/choose


############
Contributing
############

If you would like to help improve the tool, you'll find more
information on contributing in our :ref:`Contributing Guide`.


################
Supported sites:
################

-  YouTube.com - Livestreams, past broadcasts and premieres.
-  Twitch.tv - Livestreams, past broadcasts and clips.
-  Reddit.com - Livestreams, past broadcasts
-  Zoom.us - Past broadcasts
-  Facebook.com (currently in development) - Livestreams and past
   broadcasts.

.. _Chat Item Wiki: https://github.com/xenova/chat-downloader/wiki/Item-Template
.. _Command Line Wiki: https://github.com/xenova/chat-downloader/wiki/Command-Line-Usage
.. _Python Wiki: https://github.com/xenova/chat-downloader/wiki/Python-Documentation
