usage - Scoofszlo/tk3u8 GitHub Wiki

There are two ways to use this program. For the easiest and straightforward approach, you can use the program through your terminal. Advanced users may choose to use the program within a script, however, the steps will not be included in this guide as I have yet to publish an official package for this project (I hope you can wait!).

The simplest way to use this program is through your terminal (e.g., Command Prompt on Windows). After following the installation steps, you can now use several commands to perform basic stuff like downloading a live stream. Refer to the following steps below on each command usage.

To download a live stream from a user, simply run:

uv run -m tk3u8 username  # Replace 'username` with actual username of choice

If the user is not live, the program will raise an error:

tk3u8.exceptions.UserNotLiveError: User @username is not live.

If the user is live, the program will show the following output:

Starting download:
Username: @username
Quality: original
Stream Link: https://pull-hls-f16-va01.tiktokcdn.com/... # Stream link may vary

After this appears, you will see many messages popping up, which is from ffmpeg. If this kinda overwhelms you, you don't have to worry about these messages. It is just the library that logs its activity as it is processing and capturing the live stream data.

To stop recording and save the live stream, just hit Ctrl+C on your keyboard and wait for yt-dlp to finish and cleanup everything. The stream will be saved in <project_directory>/user_data/downloads/username folder with a filename, for example,username-20251225-original.mp4

By default, the program will download the highest quality stream. If you want to specify the quality to download, simply choose either original, uhd_60, uhd, hd_60, hd, ld, or sd.

uv run -m tk3u8 username -q uhd

You can also use a proxy by specifying the IP_ADDRESS:PORT in --proxy arg:

# Replace with your actual proxy address
uv run -m tk3u8 username --proxy 127.0.0.1:80

Or you can supply it too in the config file located in user_data/config.toml:

[config]
proxy = "127.0.0.1:80" # Replace with your actual proxy address

If there are both proxy address supplied in the command-line arg and in the config file, the former will be used instead.

For most cases, you don't really need to supply proxy and you can just skip this one instead.

• Installation Guide
• Usage Guide
• Configuration Guide
• Issues
• API Reference