Getting Started

Welcome to the getting started guide for Chat Analyzer! In this guide, we’ll cover the basics of how to use the software, some intermediate and advanced uses, and overall best practices when using the software.

Warning

This guide, the software itself, and the website visualization are still in the beta phase of development and not yet complete. Because Twitch Rivals started recently, I decided to make the software available because I believe it will be useful to some people even in its current state. If there are any questions/concerns, feel free to contact me at info@chatanalyze.com, or shoot me a DM on discord NaCl-y#1117.

Note

Even though this guide is not yet complete, the available arguments/flags are fully documented by running the --help flag, and can also be found on the Command Line Interface Specification page.

Basic Usage

In this section, we’ll cover the basic steps necessary to use the Chat Analyzer software.

Step 1 - Installation

If you haven’t already installed the software, you can easily install the software one of two ways:

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

pip install chat-analyzer

To update to the latest version, run:

pip install chat-analyzer --upgrade

Alternatively, the tool can be installed with git:

git clone https://github.com/David-Fryd/chat-analyzer.git
cd chat-analyzer
python setup.py install

Step 2 - Pick a Past Stream

By default, we will be downloading the chatlog data to analyze from a past stream’s url. Currently we support Twitch and YouTube streams/VODs. For a Twitch stream, simply copy the twitch.tv... link to use with the analyzer. For a YouTube stream, it is best to use the “share” button underneath the video player to get the youtu.be link, but the analyzer itself will still work with a standard YouTube link.

For example, a youtube/twitch link might look like:

https://youtu.be/d6JXhg1GBKs
https://www.twitch.tv/videos/1552248469

For help picking the right type of link, you can reference the rules & criteria under the url section.

Step 3 - Run the Chat Analyzer

Now that we have the link, all we have to do is run the analyzer and give it the link as an input. Open up a terminal/command prompt and run the following command:

chat_analyzer '<link>'

The program will produce an output file in the directory that the program was run in (the current directory). The output file/filepath can also be assigned using the -o flag:

chat_analyzer '<link>' -o '<output_filepath>'

After starting the program, the chatlog download will initiate and you should see output that looks something like this:

Getting chatlog using Xenonvas chat-downloader (https://github.com/xenova/chat-downloader)...
Successfully retrieved chat generator:
    Title: <video_title>
    Duration: ... (... seconds)
NOTICE: Downloading chats from a url is the largest rate-limiting factor.
            If you intend to sample the data differently multiple times, consider using chatfile mode, or saving the chat data with --save-chatfile.

Processing (Sampling) chat data...
  Completion   |   Processed Media Time    |   Messages Processed
    (...%)     |         ... / ...         |         ...

As messages are downloaded, you will see constant updates indicating the progress of the download.

Note

The downloading of chat data is the slowest part of the entire process. Twitch/YouTube limits the rate at which chat data can be downloaded. If you want to resample the chat multiple times, look into using chatfile mode

After the download has finished, you should see the following report:

Downloaded & Processed ... messages.
Post-processing (Analyzing)...
Post-processing (Analyzing) complete!
Successfully wrote chat analytics to `<output_filepath>`

The analyzed output file can now be found at <output_filepath>!

Final Step - Visualize the Chat Data

Now that we have generated the output file, we will use the visualizer found at chatanalyze.com/visualize to nicely visualize the analytical data. Once on the page, all you have to do is select the output file on the page and the visualization data will automatically appear on screen.

The two core features currently available are the graph representation of chat activity, and the highlights table. The graph provides a quick visual reference to the chat activity at any given point throughout the whole stream. The highlights table provides a useful way to examine the highest-activity portions of the video, and to quickly jump to those sections of the stream using the “Jump To” functionality.

Usage Modes & Source

In its simplest form, this software outputs information about a chatlog associated with a livestream. Regardless of the mode that is used, the output file format is the same (More details under Output Specification).

The three modes that can be used all refer to the type of input the program receieves.

url

The default mode, url accepts a link from a supported streaming site, downloads the raw chat data, processes the raw chat data into samples, and analyzes the samples.

Streaming services like Twitch & YouTube limit the rate at which we can download chat messages, The slowest part of the analytics process is downloading the chats themselves.

The link provided must:

Be a link to a past (finished) livestream.
Come from a supported streaming site.
Be the original video with the chatlog/replay. (It can’t be a reposted video.)

Note

If you want to analyze a YouTube stream, it is recommended you provide the youtu.be link generated through the “share” feature of the video.

Youtube Share Button found beneath YouTube videos

While the standard YouTube video link will work to download the chat and produce the data, the youtu.be short link works better with the visualizer at chatanalyze.com, enabling “Jump to” functionality (quickly jumping to highlighted points in the video).

chatfile

chatfile mode …

Warning

This section has not yet been written. Even though this guide is not yet complete, the available arguments/flags are fully documented by running the --help flag, and can also be found on the Command Line Interface Specification page.

reanalyze

reanalyze mode …

Warning

This section has not yet been written. Even though this guide is not yet complete, the available arguments/flags are fully documented by running the --help flag, and can also be found on the Command Line Interface Specification page.