Twitch Chat Downloader

pip install tdh-tcd==2.4.3


Twitch Chat Downloader PyPI version

Neat python script to download chat messages from past broadcasts


Installation and usage

There are multiple ways to install this script.

# Install package with pip
pip3 install tdh-tcd
python3 -m tcd <video_id>
# Run pip3 as root to install `tcd` for all users (not recommended)
sudo pip3 install tdh-tcd
tcd <video_id>
# Start script directly from cloned repository
git clone
cd Twitch-Chat-Downloader
pip install -r requirements.txt

python -m tcd <video_id>
# or ...
python <video_id>


To override default options, run python -m tcd --generate-config and edit generated settings.json or just use console arguments listed below.

Option Type Argument Description
client_id str --client-id Twitch API Client-ID header.
cooldown int --cooldown Delay (in milliseconds) between API calls.
display_progress bool --[no-]progress Display animated progress bar in terminal.
formats str[] -f/--formats List of formats to download. See Formats table below.
directory str -t/--directory Name of directory to save all generated files.
filename_format str --filename-format Full format of generated filenames. Possible arguments: directory, video_id and format.
subtitle_duration int --subtitle-duration Duration (in seconds) of each line of subtitles.
dynamic_duration obj Convert Kappa Kappa Kappa to Kappa x3.
—.enabled bool --[no-]dynamic-duration Increase subtitle duration based on message length.
—.max int --dynamic-duration-max Maximum duration of subtitle message.
—.max_length int --dynamic-duration-max-length Maximum length of subtitle message.
group_repeating_emotes obj Convert Kappa Kappa Kappa to Kappa x3.
—.enabled bool --[no-]group Enable or disable this function.
—.threshold int --group-threshold Number of repeating emotes to trigger this function.
—.collocations int --group-collocations Maximum number of words in repeating collocations (default: 1, more is slower).
—.format str --group-format Customize format of replaced emotes.
video_types str --video-types Comma-separated list of VOD types to detect in Channel Mode. (see broadcast_type)


Format Description
ass or ssa Advanced SubStation Alpha
srt SubRip
irc IRC-style log


  • Empty messages means the user has been timed out. There's no known way to get these.
  • This script is using Twitch's API v5 that is deprecated.
  • Consider increasing the delay between API calls in settings.json to avoid a potential temporary block from Twitch for sending too many requests when downloading messages from very long streams.