Skip to content

Latest commit

 

History

History
423 lines (351 loc) · 25.7 KB

README_EN.md

File metadata and controls

423 lines (351 loc) · 25.7 KB
TikTokDownloader

TikTokDownloader

简体中文 | English

JoeanAmier%2FTikTokDownloader | Trendshift
GitHub GitHub forks GitHub Repo stars GitHub code size in bytes
Static Badge GitHub release (with filter) GitHub all releases

🔥 TikTok Posts/Liked/Mix/Live/Video/Image/Music; DouYin Posts/Liked/Favorites/Collections/Video/Image/LivePhoto/Live/Music/Mix/Comments/Account/Search/Hot Board Data Acquisition Tools: Fully open-source, free data collection and file download tool based on HTTPX module implementation; batch download of DouYin account posts works, liked works, favorites works and collections works; batch download of TikTok account posts works and liked works; download of DouYin linked or TikTok linked works; obtain DouYin live stream addresses; download DouYin live stream video; obtain TikTok live stream addresses; download TikTok live stream video; collect DouYin works comments data; batch download of DouYin Mix works; batch download of TikTok Mix works; collect detailed data of DouYin accounts; collect DouYin user/works/live search results; collect DouYin Hot Board data.

⭐ This project is completely free and open-source, with no paid features. Please do not be deceived!

⭐ Due to the author's limited energy, I was unable to update the English document in a timely manner, and the content may have become outdated, partial translation is machine translation, the translation result may be incorrect, Suggest referring to Chinese documentation. If you want to contribute to translation, we warmly welcome you.

📝 Project Features

  • ✅ Download DouYin video/image without watermarks
  • ✅ Download DouYin live photo without watermarks
  • ✅ Download the highest quality video file
  • ✅ Download TikTok video/image without watermarks
  • ✅ Download of DouYin account posts/liked/favorites works
  • ✅ Download of TikTok account posts/liked works
  • ✅ Collect detailed data from DouYin/TikTok
  • ✅ Batch download of linked works
  • ✅ Batch download of works from multiple accounts
  • ✅ Automatically skip already downloaded files
  • ✅ Persistently save collected data
  • ✅ Support CSV/XLSX/SQLite format for saving data
  • ✅ Download dynamic/static cover images
  • ✅ Obtain DouYin live stream addresses
  • ✅ Obtain TikTok live stream addresses
  • ✅ Use ffmpeg to download live video
  • ✅ Web UI interaction interface
  • ✅ Collect comments data from DouYin works
  • ✅ Batch download of DouYin Mix works
  • ✅ Batch download of TikTok Mix works
  • ✅ Record statistics such as likes and favorites
  • ✅ Filter works based on publication time
  • ✅ Support incremental downloading of account works
  • ✅ Support data Collections using proxies
  • ✅ Support remote access via LAN
  • ✅ Collect detailed data from DouYin accounts
  • ✅ Update statistics of works
  • ✅ Support custom account/mix mark
  • ✅ Automatically update account nickname/mark
  • ✅ Deploy to private servers
  • ✅ Deploy to public servers
  • ✅ Collect DouYin search data
  • ✅ Collect DouYin hot board data
  • ✅ Record IDs of already downloaded works
  • ☑️ Scan QR code to log in and obtain Cookies
  • ✅ Obtain Cookies from browsers
  • ✅ Support Web API calls
  • ✅ Support multithreaded downloading of works
  • ✅ File integrity processing mechanism
  • ✅ Custom rules for filtering works
  • ✅ Archive and save works files by folder
  • ✅ Customize file size limit
  • ✅ Support resume downloading of files from breakpoints

💻 Program Screenshot

Terminal interaction mode：

🎥 Click on the image to watch the demonstration video. It is recommended to manage accounts through configuration files. For more information, please refer to the documentation

终端模式截图

终端模式截图

终端模式截图

Web UI interaction mode：

WebUI模式截图

WebUI模式截图

WebUI模式截图

Web API mode：

WebAPI模式截图

📈 Project Status

  • 🟢 After testing, the source code published on Releases has been verified and all functions are normal.
  • 🟡 For the development plans and progress of TikTokDownloader, please visit Projects.
  • 🔴 Note that the latest source code (Beta version) may have some unstable bugs.
  • 🔴 If you find any program bugs during use, please inform the author promptly for repairs.

📋 Project Instructions

Quick Start

⭐ Mac OS and Windows 10 and above users can go to Releases to download the compiled program, ready to use!

⭐ This project includes GitHub Actions for manually building executable files. Users can use GitHub Actions to build the latest source code into executable files at any time!

Note: The executable file main on Mac OS may need to be started from the terminal command line. Due to device limitations, the executable file on the Mac OS platform has not been tested, and its usability cannot be guaranteed!

  1. Run the executable file or configure the environment to run
      Run the executable file
    1. Download the executable file compressed file built by Releases or Actions.
    2. After extracting, open the program folder and double-click to run main.
      Configure the environment to run
    1. Install Python interpreter version 3.12
    2. Download the latest source code or the source code published on Releases to your local machine.
    3. Run the command python -m venv venv to create a virtual environment (optional).
    4. Run the command .\venv\Scripts\activate.ps1 or venv\Scripts\activate to activate the virtual environment (optional).
    5. Run the command pip install -r requirements.txt to install the required modules for the program.
    6. Run the command python .\main.py or python main.py to start TikTokDownloader.
  2. Read the disclaimer of TikTokDownloader and enter content according to the prompt.
  3. Write Cookie information into the configuration file
      Manually copy and paste Cookie (recommended)
    1. Refer to Cookie Extraction Tutorial, copy the required Cookie to the clipboard.
    2. Select the option to copy and paste to write Cookie, and follow the prompts to write the Cookie into the configuration file.
      Get Cookie from Browser (recommended)
    1. Select the option Get Cookie from Browser and follow the prompts to choose the browser type.
      Scan code login to get Cookie (deprecated)
    1. Select the option Scan code login to get Cookie, and the program will display a login QR code image and open the image with the default application.
    2. Use the DouYin APP to scan the QR code and log into your account.
    3. Follow the prompts to write the Cookie into the configuration file.
  4. Return to the program interface, sequentially select Terminal interactive mode -> Batch download link works (general) -> Manually enter the link of the works to be collected.
  5. Input the DouYin works link to download the works file (the TikTok platform requires more initial setup, please refer to the documentation for details).
  6. For more detailed instructions, please see Project Documentation.

⭐ It is recommended to use Windows Terminal (the default terminal that comes with Windows 11).

Docker Container

  1. Get the image
    • Method 1: Build the image using the Dockerfile.
    • Method 2: Pull the image using the command docker pull joeanamier/tiktok-downloader.
  2. Create the container: docker run -it joeanamier/tiktok-downloader.
  3. Run the container
    • Start the container: docker start -i container name/container ID.
    • Restart the container: docker restart -i container name/container ID.

Docker containers cannot directly access the host machine's file system, and some features may be unavailable, for example: Get Cookie from Browser; if there are any other issues, please report!

About Cookie

Click to view Cookie tutorial

Program Function Login Required
Download Account Posts Works ⭕ Recommended to Login
Download Account Liked Works ⭕ Recommended to Login
Download Linked Works ❌ No Login Required
Obtain Live Stream Address ❌ No Login Required
Download Live Video ❌ No Login Required
Obtain Works Comment Data ❌ No Login Required
Download Mix Works ❌ No Login Required
Obtain Account Data ❌ No Login Required
Collect Search Results ❌ No Login Required
Collect Hot Board Data ❌ No Login Required
Download Favorites Works ✔️ Login Required
Download Collections Works ✔️ Login Required
Obtain Collections Mix ✔️ Login Required
Obtain Collections Music ✔️ Login Required
Obtain Collections Series ✔️ Login Required

  • Cookie only needs to be re-written to the configuration file after it expires, and not every time the program is run.

  • The Cookie can affect the resolution of the video files downloaded from the DouYin platform. If you are unable to download high-resolution video files, please try updating the Cookie!

  • When the program fails to obtain data, you can try updating the Cookie or using a Cookie that is already logged in!

Other Instructions

  • When the program prompts the user for input, pressing Enter directly will return to the previous menu, and inputting Q or q will end the program's execution.
  • Since fetching data for liked and favorites works of an account only returns the publication dates of those works, not the dates of the actions (liking or favouring), the program needs to retrieve all liked and favorites works data before performing date filtering. If there are a large number of works, this may take a considerable amount of time. The number of requests can be controlled via the max_pages parameter.
  • To obtain data for posts made by a private account, a logged-in Cookie is required, and the logged-in account must follow the private account.
  • When batch downloading account posts works or mix works, if the corresponding nickname or mark parameter changes, the program will automatically update the nickname and mark parameter in the file names of the downloaded works.
  • When downloading files, the program first downloads them to a temporary folder and then moves them to the storage folder upon completion. The temporary folder will be emptied when the program ends.
  • The Batch Download Favorites Works Mode currently only supports downloading favorited works for the account corresponding to the currently logged-in Cookie and does not support multiple accounts.
  • If you want the program to use a proxy to request data, you must set the proxy parameter in settings.json; otherwise, the program will not use a proxy.
  • To exit the program, please end it in a normal way or by pressing Ctrl + C. Do not directly close the terminal window, as this may result in data loss.
  • If your computer does not have a suitable program for editing JSON files, we recommend using the JSON Online Tool to edit the configuration file content.
  • When the program prompts the user to input content or links, please be careful to avoid including newline characters, as this may cause unexpected issues.
  • This project does not support downloading paid works. Please do not report any issues related to downloading paid works.
  • On Windows systems, the program needs to be run as an administrator to read Cookies from Chromium, Chrome, and Edge browsers.
  • This project has not been optimized for running multiple instances of the program. If you need to run multiple instances, please copy the entire project folder to avoid unexpected issues.

Program Update

Option 1: Download and unzip the files, then copy the old version of the TikTokDownloader.db file and the settings.json file into the _internal folder.

Option 2: Download and unzip the files (without running the program), then copy all the files and directly overwrite the old version files.

Build of Executable File Guide

This guide will walk you through forking this repository and executing GitHub Actions to automatically build and package the program based on the latest source code!

Steps to Use

1. Fork the Repository

  1. Click the Fork button at the top right of the project repository to fork it to your personal GitHub account
  2. Your forked repository address will look like this: https://github.com/your-username/this-repo

2. Enable GitHub Actions

  1. Go to the page of your forked repository
  2. Click the Settings tab at the top
  3. Click the Actions tab on the right
  4. Click the General option
  5. Under Actions permissions, select Allow all actions and reusable workflows and click the Save button

3. Manually Trigger the Build Process

  1. In your forked repository, click the Actions tab at the top
  2. Find the workflow named Manual Build of Executable File
  3. Click the Run workflow button on the right:
    • Select the master or develop branch
    • Click Run workflow

4. Check the Build Progress

  1. On the Actions page, you can see the execution records of the triggered workflow
  2. Click on the run record to view detailed logs to check the build progress and status

5. Download the Build Result

  1. Once the build is complete, go to the corresponding run record page
  2. In the Artifacts section at the bottom of the page, you will see the built result file
  3. Click to download and save it to your local machine to get the built program

Notes

  1. Resource Usage:

    • GitHub provides free build environments for Actions, with a monthly usage limit (2000 minutes) for free-tier users

  2. Code Modifications:

    • You are free to modify the code in your forked repository to customize the build process
    • After making changes, you can trigger the build process again to get your customized version

  3. Stay in Sync with the Main Repository:

    • If the main repository is updated with new code or workflows, it is recommended that you periodically sync your forked repository to get the latest features and fixes

Frequently Asked Questions

Q1: Why can't I trigger the workflow?

A: Please ensure that you have followed the steps to Enable Actions. Otherwise, GitHub will prevent the workflow from running

Q2: What should I do if the build process fails?

A:

  • Check the run logs to understand the cause of the failure
  • Ensure there are no syntax errors or dependency issues in the code
  • If the problem persists, please open an issue on the Issues page

Q3: Can I directly use the Actions from the main repository?

A: Due to permission restrictions, you cannot directly trigger Actions from the main repository. Please use the forked repository to execute the build process

⚠️ Disclaimer

  • Users decide on their own how to use this project and bear the risks themselves. The author is not responsible for any losses, liabilities, or risks incurred by users in the use of this project
  • The code and functionalities provided by the author of this project are developed based on existing knowledge and technology. The author strives to ensure the correctness and security of the code but does not guarantee that the code is completely error-free or defect-free.
  • Users must strictly adhere to the provisions in GNU General Public License v3.0 , and appropriately mention the use of code adhering GNU General Public License v3.0.
  • Under no circumstances shall users associate the author of this project, contributors, or other related parties with the user's usage behavior, or demand that they be held responsible for any losses or damages incurred by the user's use of this project.
  • Users must independently study relevant laws and regulations when using the code and functionalities of this project and ensure that their usage is legal and compliant. Users are solely responsible for any legal liability and risks resulting from violations of laws and regulations.
  • The author of this project will not provide a paid version of the TikTokDownloader project, nor will they offer any commercial services related to the TikTokDownloader project.
  • Any secondary development, modification, or Collections of the program based on this project is unrelated to the original author. The original author is not responsible for any consequences related to secondary development or its results. Users should take full responsibility for any situations that may arise from secondary development on their own.
Before using the code and functionalities of this project, please carefully consider and accept the above disclaimer. If you have any questions or disagree with the statement, please do not use the code and functionalities of this project. If you use the code and functionalities of this project, it is considered that you fully understand and accept the above disclaimer, and willingly assume all risks and consequences associated with the use of this project.

🌟 Contribution Guidelines

Welcome to contributing to this project! To keep the codebase clean, efficient, and easy to maintain, please read the following guidelines carefully to ensure that your contributions can be accepted and integrated smoothly.

  • Before starting development, please pull the latest code from the develop branch as the basis for your modifications; this helps avoid merge conflicts and ensures your changes are based on the latest state of the project.
  • If your changes involve multiple unrelated features or issues, please split them into several independent commits or pull requests.
  • Each pull request should focus on a single feature or fix as much as possible, to facilitate code review and testing.
  • Follow the existing coding style; make sure your code is consistent with the style already present in the project.
  • Write code that is easy to read; add appropriate annotation to help others understand your intentions.
  • Each commit should include a clear and concise commit message describing the changes made. The commit message should follow this format: <type>: <short description>
  • When you are ready to submit a pull request, please prioritize submitting them to the develop branch; this provides maintainers with a buffer zone for additional testing and review before final merging into the master branch.

Reference materials:

✉️ Contact the Author

✨ The author's other open-source projects:

♥️ Support the Project

If TikTokDownloader has been helpful to you, please consider giving it a Star ⭐. Your support is greatly appreciated!

微信(WeChat) 支付宝(Alipay)
微信赞助二维码 支付宝赞助二维码

If you're willing, consider making a contribution to provide additional support for TikTokDownloader!

💰 Project Sponsorship

JetBrains Tools

PyCharm logo

JetBrains support active projects recognized within the global open-source community with complimentary licenses for non-commercial development.

TikHub

TikHub

TikHub is a leading data interface service provider, specializing in offering high-quality data interfaces for multiple popular platforms, including DouYin, TikTok, Xiaohongshu, Instagram, Twitter, and Kuaishou.

TikHub also provides customized services such as live streaming room monitoring, post monitoring, and influencer monitoring to meet the needs of different business scenarios.

Through daily sign-ins, users can obtain a certain quota of usage for free. You can use my referral link：https://user.tikhub.io/users/signup?referral_code=ZrdH8McC or Referral Code：ZrdH8McC，Register and recharge to receive $2 limit！

TikHub Provide the following services:

💡 Project References