Command Line Usage
Overview
A full list of command line arguments can be obtained by running the help command:
$ chat_analyzer -h
The output of which is as follows:
usage: chat_analyzer [-h] [--version] [--platform {youtube,twitch}]
[--mode {url,chatfile,reanalyze}]
[--save-chatfile-output SAVE_CHATFILE_OUTPUT]
[--interval INTERVAL] [--print-interval PRINT_INTERVAL]
[--highlight-percentile HIGHLIGHT_PERCENTILE]
[--highlight-metric {usersPSec,chatsPSec,activityPSec}]
[--description DESCRIPTION] [--output OUTPUT] [--nojson]
[--debug] [--break BREAK]
source
A tool used to process and analyze chat data from past live streams, providing
summarized information about chat activity over the stream's lifetime.
Required Arguments:
source
Raw chat data to process and analyze, or processed
sample data to re-analyze.
In mode=[1m'url'[0m, (default) source is a url to a
past stream/VOD.
We currently only support links from: www.youtube.com,
www.twitch.tv, youtu.be. The link must
be to the original stream/VOD with that attached chat
replay.
In mode=[1m'chatfile'[0m, source is a filepath to a
.json containing [3mraw chat data[0m,
produced by Xenonva's chat-downloader, or by this
program's `--save-chatfile-output` flag. NOTE: the
--platform argument is required
when using this mode.
In mode=[1m'reanalyze'[0m, source is a filepath to a
.json file previously produced by this program
which contains [3mexisting sample data to
reanalyze[0m.
(Highlights and spikes are regenerated, the existing
samples are not affected).
Optional Arguments:
-h, --help show this help message and exit
--version show program's version number and exit
--platform {youtube,twitch}
When reading from a chatfile, specify the platform the
chat was downloaded from. By default, Xenova's chat
downloader does not store this information with the
chat data so it must be manually specified. If the
incorrect platform is entered, site-specific data will
be innacurate but the program will still run and
analyze common attributes. (default: None)
Program Behavior (Mode):
--mode {url,chatfile,reanalyze}, -m {url,chatfile,reanalyze}
The program can be run in three modes:
[3mNOTE: All modes result in chat analytics output as
a .json file.[0m
[1m'url'[0m mode (default) downloads raw chat data
from an appropriate source url, processes the raw
chat data into samples, and then analyzes the
samples.
[1m'chatfile'[0m mode reads raw chat data from a
.json file, processes the raw chat data into
samples, and then analyzes the samples.
(We accept raw chat files produced by Xenonva's chat-
downloader, or by this program through '--save-
chatfile-output').
[1m'reanalyze'[0m mode reads existing sample data
from a .json file produced by this program in a
previous run, and recalculates ONLY the post-
processed data based on the existing samples.
(Highlights and spikes are regenerated, the existing
samples are not affected).
(default: url)
--save-chatfile-output SAVE_CHATFILE_OUTPUT, -sc SAVE_CHATFILE_OUTPUT
Filepath of the raw chat data to save. If downloading
chat data from a URL, save the raw chat data to the
provided filepath in addition to processing it, so
that the raw data can be [3mfully[0m reprocessed and
analyzed again quickly (using mode='chatfile'). NOTE:
Chatfiles are *much* larger in comparison to the
analytics file. NOTE: json file extension is enforced
because it affects the content that the chat
downloader writes to the file. (default: None)
Processing (Sampling):
--interval INTERVAL, -i INTERVAL
The time interval (in seconds) at which to compress
datapoints into samples. i.e. Duration of the samples.
The smaller the interval, the more granular the
analytics are. At interval=5, each sample contains 5
seconds of cumulative data. *(With the exception of
the last sample, which may be shorter than the
interval).* (default: 5)
--print-interval PRINT_INTERVAL
Number of messages between progress updates to the
console. If <= 0, progress is not printed. (default:
100)
Post Processing (Analyzing):
--highlight-percentile HIGHLIGHT_PERCENTILE, -ep HIGHLIGHT_PERCENTILE
A number between 0 and 100, representing the cutoff
percentile that a sample's attribute must meet to be
considered a 'highlight' of the chatlog. Samples in
the top HIGHLIGHT_PERCENTILE% of the selected
highlight metric will be considered high-engagement
samples and included within the constructed
highlights. The larger the percentile, the greater the
metric requirement before being reported. If
'highlight-percentile'=93.0, only samples in the 93rd
percentile (top 7.0%) of the selected metric will be
included in the highlights. (default: 93.0)
--highlight-metric {usersPSec,chatsPSec,activityPSec}, -em {usersPSec,chatsPSec,activityPSec}
The metric to use for engagement analysis when
constructing highlights. Samples in the top
HIGHLIGHT_PERCENTILE% of the selected metric will
be considered high-engagement samples and included
within the constructed highlights.
Each highlight metric choice corresponds to a
datapoint for each sample.
[1m'usersPSec'[0m compares samples based off of the
average number unique users that send a chat per
second of the sample.
[1m'chatsPSec'[0m compares samples based off of the
average number of chats per second of the sample
(not necessarily sent by unique users).
[1m'activityPSec'[0m compares samples based off of
the average number of any type of message that
appears in the chat per second of the sample.
(default: usersPSec)
Output:
--description DESCRIPTION, -d DESCRIPTION
A description included in the output file to help
distinguish it from other output files.
ex: -d "Ludwig product announcement, small intervals"
(default: None)
--output OUTPUT, -o OUTPUT
The filepath to write the output to. If not specified,
the output is written to '[MEDIA TITLE].json.' If the
provided file path does not end in '.json', the
'.json' file extension is appended automaticaly to the
filepath (disable with --nojson). (default: None)
--nojson Disable the automatic appending of the '.json' file
extension to the provided output filepath. (default:
False)
Debugging:
--debug, -db Enable debug mode (debug info is printed) (default:
False)
--break BREAK, -b BREAK
Stop processing messages after BREAK number of
messages have been processed. No effect if val < 0
(default: -1)
See Getting Started for examples and detailed use-cases.