tiktok-live-recorder: archiving TikTok live sessions from the command line

Three recording modes decide how much you record

tiktok-live-recorder is described as a tool for recording live streaming TikTok, capturing and saving live sessions with both audio and video. The stated users are creators, researchers, and anyone who wants to capture memorable moments from live streams.

The tool is built around three modes, and the choice between them is the first decision a user makes.

Manual is the default and records immediately if the user is currently live. There is no polling and no schedule; you start it and it captures whatever is happening now.

Automatic polls at regular intervals and records whenever the user goes live. The polling interval is set with a flag given in minutes, and the documentation notes the interval applies to automatic mode only.

Followers records live streams from all followed users automatically. This is the mode that turns the tool into a background archiver rather than a one-shot capture.

The distinction between manual and automatic is easy to miss and matters a lot in practice. Manual is for the case where you already know a stream is running. Automatic is for a fixed set of creators whose schedule you do not know, and it is the mode that needs a persistent process. Followers is broader still and depends on the account you are running as.

The targets are configurable in three ways. A username flag records one or more named users, with multiple values separated by commas. A URL flag records from a TikTok live URL, and a room ID flag records from a room identifier. The project links a separate guide page explaining how to obtain a room_id.

Options that shape the output rather than the target

Beyond the target and the mode, the option table is mostly about where files go and what they look like.

The output flag names the directory where recordings are saved, and the duration flag stops recording after a given number of seconds, which is how you cap a long stream without watching it.

A bitrate flag sets the output bitrate for post-processing, with values written the way ffmpeg expects them, for example 1M or 1000k. That word post-processing is doing work in the sentence, because it distinguishes the recorded stream from the file that ends up on disk, and the tool re-encodes rather than simply remuxing when you set it.

Two flags change behaviour in ways that could surprise you. The Telegram flag uploads the recording to Telegram once it is finished, and it requires a telegram.json configuration file that the guide explains how to set up. The update check flag skips the automatic update check on startup, which is what you want on a machine that runs unattended and does not want a network call at launch.

A proxy flag takes an HTTP proxy URL and is described as a way to bypass regional restrictions. That is the honest reason many people reach for this tool, and it is also the reason the tool needs a proxy at all: the platform applies regional availability rules to live content, and the endpoint used to read stream metadata is not reachable from every network.

Taken together the option surface is small and readable. There is no configuration file for the main behaviour, everything lives on the command line, and the guide pages cover the three situations where extra setup is needed: cookies, room IDs and Telegram.

Cookies are the authentication mechanism, and the guide explains how

The dependency list explains how the tool reaches TikTok: curl_cffi at 0.12.0 or newer, requests at 2.32.0 or newer, telethon at 1.42.0 or newer for the Telegram side, ffmpeg-python for the media handling and distro for platform detection.

curl_cffi is a client that impersonates the TLS fingerprint of a browser. That is what makes it usable against an endpoint that is not an open API, and it is the reason the tool works where a plain requests call might not.

Authentication comes from a cookies.json file in the project directory, and the project links a documentation page titled How to set cookies in cookies.json. This is the account access requirement, and it works the way you would expect: you supply your own session, the tool acts as you. The distinction matters for anyone evaluating the tool, because a session cookie is a credential, and the tool's usefulness for archiving is proportional to the access your account already has.

The Telegram dependency, telethon, is a separate client library for the Telegram client API. It is only needed for the Telegram upload path, and it has its own configuration in telegram.json with its own guide section.

The project also states its legal position plainly: the code is in no way affiliated with, authorized, maintained, sponsored or endorsed by TikTok or any of its affiliates or subsidiaries, and it should be used at your own risk. That is a disclaimer, not a permission, and it is worth reading as the honest signal it is. Recording a stream that the platform's terms restrict is a decision for the account holder to make, and this project neither grants nor removes that decision.

Installing on Linux, macOS, Windows and Termux

The prerequisites are Git, Python 3.11 or newer, and FFmpeg. The install path on every platform uses uv to create the environment and sync the dependencies, and then runs the entry point.

On Linux the sequence is short.

curl -LsSf https://astral.sh/uv/install.sh | sh
git clone https://github.com/Michele0303/tiktok-live-recorder
cd tiktok-live-recorder
uv venv
uv sync
uv run python src/main.py -h

The Windows variant installs uv through a PowerShell one-liner and then follows the same clone and sync steps. macOS adds one line before the clone, because FFmpeg comes from Homebrew rather than from the system.

brew install ffmpeg

The Termux instructions are the most involved, and they carry a specific warning: install Termux from F-Droid rather than the Play Store version. The package steps update the package list, install git, ffmpeg, uv and tur-repo, uninstall the existing python, and install python3.11 explicitly.

pkg update && pkg upgrade
pkg install git ffmpeg uv tur-repo
pkg uninstall python
pkg install python3.11

Running the tool itself is the same everywhere, and the -h flag prints the help.

uv run python src/main.py [options]

The project also publishes a console script entry point, tiktok-live-recorder, mapped to main:main, and the package metadata sets py-modules to main and check_updates with the package directory at src. That second module name is a hint about how the tool behaves on startup.

The Docker image splits build from runtime and installs FFmpeg

The Docker route exists and is a two stage build, which is a sensible choice for a tool whose runtime needs differ from its build needs.

The builder stage starts from python:3.13-slim and copies the uv binary from the ghcr.io/astral-sh/uv:latest image. It installs gcc, g++ and libffi-dev as build dependencies, copies pyproject.toml and uv.lock, and runs uv sync with the frozen flag, no dev extras and no project install, so the dependency layer caches independently of the source. Then it copies src/ into place.

The runtime stage is another python:3.13-slim image with ffmpeg installed from apt, with the apt lists cleaned afterwards. It sets PATH to put the virtualenv first, copies the built virtualenv and application from the builder, makes the entrypoint executable and runs it.

The image is used with a volume for the output directory and the target user passed as a flag.

sudo docker run \
  -v ./output:/output \
  michele0303/tiktok-live-recorder:latest \
  -output /output \
  -user <username>

Two details are worth noting for anyone running this on a NAS or a small server. The volume mount is how recordings leave the container, and the username argument is passed to the program rather than to docker, which means it selects what is recorded, not who runs it. The Docker Hub repository is published under michele0303/tiktok-live-recorder.

The Python version in the image, 3.13, is newer than the 3.11 floor in the package metadata, so the container runs a version the project also supports locally on Termux.

Version numbering, update checks and what the project does not promise

The project is on version 7.7.1, with 7.7.0 and 7.6.0 in the recent release list. That the minor version moves often and the patch versions move with it is a signal about the pace of change: this is a tool that is still being adjusted rather than a settled utility.

Release numbering is automated. The pyproject configures bump-my-version with commit and tag enabled and a tag name of v{new_version}, and it lists the files it rewrites, pyproject.toml and src/utils/enums.py, replacing the version string in each. So the version reported at runtime comes from an enum in the source tree rather than from package metadata, which is why both files are listed.

The version is also checked at startup, since check_updates is one of the two modules packaged, and there is a command line flag to skip that check. That combination is reasonable for a tool people run unattended, and the flag is the escape hatch when the check itself is the problem.

Development tooling is conventional: ruff for linting with a line length of 88, pytest with importlib import mode, pre-commit, and a dev extra group. There is a Code of Conduct, a Contributing guide and a .codacy.yml configuration for static analysis.

The licence field on the repository says MIT, and the licence is referenced from the package metadata as a file. That is a permissive licence covering the code, and it does not extend to the content being recorded.

The last push was on 2026-08-12, so the tree is being worked on, but the newest tagged release in the list is 7.7.1 from 2026-07-15. The project also carries a Telegram channel badge, which is where release announcements and support requests are likely to be handled, given the GitHub issues route is open to contributors.

Editorial conclusion

tiktok-live-recorder suits a creator, researcher or archivist who wants their own live streams, or a set of followed accounts' streams, captured as files rather than left to expire on the platform, and the Docker route makes it easy to run on a small always-on host. It does not suit anyone who needs to record streams they have no account access to, since the cookie configuration in cookies.json is what authenticates the requests, and the project is explicit that it is not affiliated with TikTok and is used at your own risk. Before adopting it, check the recording mode against what you actually want, since followers mode records every followed user and manual mode records only a user who is live at the moment you start, and confirm that FFmpeg is on the path before you blame the tool for an empty output directory.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. Michele0303/tiktok-live-recorder on GitHub
4. README
5. Releases