TiktokExplode.Infrastructure 1.1.1

TiktokExplode

<p align="center"> <img src="assets/icon.png" alt="TiktokExplode" width="140" /> </p>

TiktokExplode is a .NET library that lets you retrieve metadata and download videos from TikTok programmatically. It handles session management, cookie injection, and WAF/bot-detection bypassing behind a simple, clean API — so you can focus on using the data instead of fighting the platform.

The library follows Clean Architecture: the domain layer (TiktokExplode) has zero external dependencies and exposes immutable, strongly-typed models, while the infrastructure layer (TiktokExplode.Infrastructure) handles all HTTP and browser-based concerns.

Features

• Fetch full video metadata: author, stats, duration, language, location, bitrates, and more
• Download videos without watermark or with watermark
• Download the static cover image (JPEG) or the animated cover (WebP)
• Progress reporting during download via IProgress<double>
• Automatic WAF/bot-detection retry with configurable backoff
• Strategy pattern — choose between Playwright (reliable) or HTTP-only (lightweight) page fetching
• Clean Architecture — pure domain with zero external dependencies
• Targets net8.0 and net9.0

Installation

Recommended — install both packages in one command:

dotnet add package TiktokExplode.All

Or install individually:

dotnet add package TiktokExplode.Infrastructure

TiktokExplode.Infrastructure automatically brings in TiktokExplode (domain) as a transitive dependency.
Install TiktokExplode alone only if you need the domain models/interfaces without the infrastructure.

Using Microsoft.Extensions.DependencyInjection?

dotnet add package TiktokExplode.Extensions.DependencyInjection

Adds AddTiktokExplode() on IServiceCollection. See the Dependency Injection section.

Note: TiktokExplode.Infrastructure depends on Microsoft.Playwright. After installation, run the following once to download the browser binaries:

pwsh -c "playwright install chromium"

Quick Start

using TiktokExplode.Infrastructure.Clients;
using TiktokExplode.Infrastructure.Common;

await using var client = TiktokClient.CreateWithBrowser();

var video = await client.GetVideoAsync("https://www.tiktok.com/@user/video/1234567890");

Console.WriteLine($"ID:       {video.Id}");
Console.WriteLine($"Author:   {video.Author.Name} (@{video.Author.UniqueId})");
Console.WriteLine($"Duration: {video.Duration.Seconds}s");
Console.WriteLine($"Views:    {video.Stats.Views}");
Console.WriteLine($"Likes:    {video.Stats.Likes}");

// Download without watermark (stream + content length)
await using var streamInfo = await client.DownloadAsync(video);
await using var file = File.Create($"{video.Id}.mp4");
await streamInfo.Stream.CopyToAsync(file);

// Or use the extension to download directly to a file with progress
IProgress<double> progress = new Progress<double>(p => Console.Write($"\rProgress: {p:P0}"));
await client.DownloadAsync(video, $"{video.Id}.mp4", progress);

API Reference

TiktokClient

TiktokClient uses the Strategy pattern to decouple page fetching from downloading. Use the factory methods to choose a strategy:

// Playwright — uses a real browser to bypass WAF (recommended)
await using var client = TiktokClient.CreateWithBrowser();

// Playwright with custom options
await using var client = TiktokClient.CreateWithBrowser(
    new PlaywrightFetcherOptions { BrowserChannel = "msedge", Headless = true },
    new TikTokOptions { MaxWafRetries = 5 });

// HTTP-only — lightweight, may be blocked by WAF
await using var client = TiktokClient.CreateWithHttp();

// Inject your own IPageFetcher implementation
await using var client = new TiktokClient(myFetcher, new TikTokOptions());

Methods

TiktokClient implements IAsyncDisposable — always use await using.

Extension methods (via TiktokClientExtensions)

// Download to file path with optional progress
await client.DownloadAsync(video, "output.mp4", progress, cancellationToken);
await client.DownloadWatermarkedAsync(video, "output_wm.mp4", progress, cancellationToken);

// Download cover images
await client.DownloadImageAsync(video, "cover.jpg");
await client.DownloadAnimatedImageAsync(video, "cover.webp");

Note: Animated covers are served by TikTok as animated WebP files. Not all videos have an animated cover — if Cover.AnimatedUrl is empty, the video only has a static cover.

ContentLength is sourced from the CDN response headers — always accurate, no estimate from metadata.

StreamInfo

Returned by DownloadAsync and DownloadWatermarkedAsync. Implements IAsyncDisposable.

TikTokOptions

PlaywrightFetcherOptions

HttpFetcherOptions

Video model

Author model

Dependency Injection

TiktokExplode.Extensions.DependencyInjection provides a fluent AddTiktokExplode() extension method for registering all TiktokExplode services into the .NET DI container.

// Default — Playwright fetcher, all defaults
services.AddTiktokExplode();

// Custom — Playwright with visible browser window
services.AddTiktokExplode(b => b
    .UsePlaywrightFetcher(o => o.Headless = false));

// HTTP fetcher — lighter, no browser dependency
services.AddTiktokExplode(b => b
    .UseHttpFetcher(o => o.WarmupDelay = TimeSpan.Zero)
    .ConfigureTiktok(o => o.MaxWafRetries = 5));

Registered services:

// Consume in your services via constructor injection
public class MyService(IVideoClient client)
{
    public async Task<string> GetTitleAsync(string url)
    {
        var video = await client.GetVideoAsync(url);
        return video.Description;
    }
}

Error Handling

using TiktokExplode.Domain.Exceptions;

try
{
    var video = await client.GetVideoAsync(url);
}
catch (TiktokWafException ex)
{
    // Bot detection triggered after all retries exhausted
}
catch (VideoNotFoundException ex)
{
    // Video does not exist or is private
}
catch (TiktokParsingException ex)
{
    // Unexpected page structure (TikTok changed their HTML/JSON)
}
catch (TiktokException ex)
{
    // Base exception — catch-all for library errors
}

Project Structure

TiktokExplode/                # Domain — zero external dependencies
  Domain/
    Entities/                 # Video, Author
    ValueObjects/             # VideoInfo, StreamInfo, VideoStats, VideoDuration, etc.
    Abstractions/             # IVideoClient
    Exceptions/               # TiktokException hierarchy
    Utilities/                # URL validation

TiktokExplode.Infrastructure/ # HTTP + browser automation (Playwright + AngleSharp)
  Clients/                    # TiktokClient : IVideoClient
  Fetchers/                   # IPageFetcher, PlaywrightFetcher, HttpFetcher
  Http/                       # TikTokDownloadClient — CDN download management
  Browser/                    # TikTokBrowser — internal Playwright wrapper
  Parsers/                    # TikTokVideoParser — JSON extraction from hydration script
  Options/                    # TikTokOptions, PlaywrightFetcherOptions, HttpFetcherOptions
  Common/                     # StreamExtensions, TiktokClientExtensions

TiktokExplode.All/            # Meta-package — installs both packages above in one command

TiktokExplode.Extensions.DependencyInjection/  # AddTiktokExplode() for Microsoft.Extensions.DI

Acknowledgements

This library was heavily inspired by YoutubeExplode by Tyrrrz. His work showed me how a well-designed, clean .NET library for a media platform should look and feel. Without that reference, TiktokExplode would not exist. Thank you.

License

MIT — see LICENSE for details.