Command Line Usage


A full list of command line arguments can be obtained by running the help command:

$ chat_downloader -h

The output of which is as follows:

usage: chat_downloader [-h] [--version] [--start_time START_TIME]
                       [--end_time END_TIME]
                       [--message_types MESSAGE_TYPES | --message_groups MESSAGE_GROUPS]
                       [--max_attempts MAX_ATTEMPTS]
                       [--retry_timeout RETRY_TIMEOUT]
                       [--interruptible_retry [INTERRUPTIBLE_RETRY]]
                       [--max_messages MAX_MESSAGES]
                       [--inactivity_timeout INACTIVITY_TIMEOUT]
                       [--timeout TIMEOUT] [--format FORMAT]
                       [--format_file FORMAT_FILE] [--chat_type {live,top}]
                       [--ignore IGNORE]
                       [--message_receive_timeout MESSAGE_RECEIVE_TIMEOUT]
                       [--buffer_size BUFFER_SIZE] [--output OUTPUT]
                       [--overwrite [OVERWRITE]] [--sort_keys [SORT_KEYS]]
                       [--indent INDENT] [--pause_on_debug | --exit_on_debug]
                       [--logging {none,debug,info,warning,error,critical} | --testing | --verbose | --quiet]
                       [--cookies COOKIES] [--proxy PROXY]

A simple tool used to retrieve chat messages from livestreams, videos, clips
and past broadcasts. No authentication needed!

Mandatory Arguments:
  url                   The URL of the livestream, video, clip or past
                        broadcast, defaults to None

General Arguments:
  -h, --help            show this help message and exit
  --version             show program's version number and exit

Timing Arguments:
  --start_time START_TIME, -s START_TIME
                        Start time in seconds or hh:mm:ss, defaults to None
                        (as early as possible)
  --end_time END_TIME, -e END_TIME
                        End time in seconds or hh:mm:ss, defaults to None
                        (until the end)

Message Type Arguments:
  --message_types MESSAGE_TYPES
                        List of messages types to include, defaults to None
  --message_groups MESSAGE_GROUPS
                        List of messages groups (a predefined, site-specific
                        collection of message types) to include

Retry Arguments:
  --max_attempts MAX_ATTEMPTS
                        Maximum number of attempts to retrieve chat messages,
                        defaults to 15
  --retry_timeout RETRY_TIMEOUT
                        Number of seconds to wait before retrying. Setting
                        this to a negative number will wait for user input.
                        Default is None (use exponential backoff, i.e.
                        immediate, 1s, 2s, 4s, 8s, ...)
  --interruptible_retry [INTERRUPTIBLE_RETRY]
                        Have the option to skip waiting and immediately retry.
                        Defaults to True

Termination Arguments:
  --max_messages MAX_MESSAGES
                        Maximum number of messages to retrieve, defaults to
                        None (unlimited)
  --inactivity_timeout INACTIVITY_TIMEOUT
                        Stop getting messages after not receiving anything for
                        a certain duration (in seconds), defaults to None
  --timeout TIMEOUT     Stop retrieving chat after a certain duration (in
                        seconds), defaults to None

Format Arguments:
  --format FORMAT       Specify how messages should be formatted for printing,
                        defaults to the site's default value
  --format_file FORMAT_FILE
                        Specify the path of the format file to choose formats
                        from, defaults to None

[Site Specific] YouTube Arguments:
  --chat_type {live,top}
                        Specify chat type, defaults to 'live'
  --ignore IGNORE       Ignore a list of video ids, defaults to None

[Site Specific] Twitch Arguments:
  --message_receive_timeout MESSAGE_RECEIVE_TIMEOUT
                        Time before requesting for new messages, defaults to
  --buffer_size BUFFER_SIZE
                        Specify a buffer size for retrieving messages,
                        defaults to 4096

Output Arguments:
  --output OUTPUT, -o OUTPUT
                        Path of the output file, defaults to None (print to
                        standard output)
  --overwrite [OVERWRITE]
                        If True, overwrite output file. Otherwise, append to
                        the end of the file. Defaults to True. In both cases,
                        the file (and directories) is created if it does not
  --sort_keys [SORT_KEYS]
                        Sort keys when outputting to a file, defaults to True
  --indent INDENT       Number of spaces to indent JSON objects by. If
                        nonnumerical input is provided, this will be used to
                        indent the objects. Defaults to 4

Debugging/Testing Arguments:
  --pause_on_debug      Pause on certain debug messages, defaults to False
  --exit_on_debug       Exit when something unexpected happens, defaults to
  --logging {none,debug,info,warning,error,critical}
                        Level of logging to display, defaults to info
  --testing             Enable testing mode. This is equivalent to setting
                        logging to debug and enabling pause_on_debug. Defaults
                        to False
  --verbose, -v         Print various debugging information. This is
                        equivalent to setting logging to debug. Defaults to
  --quiet, -q           Activate quiet mode (hide all output), defaults to

Initialisation Arguments:
  --cookies COOKIES, -c COOKIES
                        Path of cookies file, defaults to None
  --proxy PROXY, -p PROXY
                        Use the specified HTTP/HTTPS/SOCKS proxy. To enable
                        SOCKS proxy, specify a proper scheme. For example
                        socks5:// Pass in an empty string
                        (--proxy "") for direct connection. Defaults to None


  1. Message groups and types

    Options are specified by a space- or comma-separated list. If you specify more than one item, enclose the argument in quotation marks.

    • Using message groups:

    $ chat_downloader --message_groups "messages superchat"
    • Using message types:

    $ chat_downloader --message_types membership_item
  2. Output to file

$ chat_downloader --output chat.json