TikLocal 0.8.9

A local media server that combines the features of TikTok and Pinterest

TikLocal

TikLocal is a mobile and tablet web application built on Flask. It allows you to browse and manage your local videos and images in a way similar to TikTok and Pinterest.

中文

Introduction

TikLocal's main features include:

• A TikTok-like swipe-up browsing experience with a mixed feed of local videos and images.
• A file manager-like directory browsing feature that allows you to easily find and manage local video files.
• A Pinterest-like grid layout feature that allows you to enjoy local images.
• Support for light and dark modes to suit your personal preferences.

Use cases

TikLocal is suitable for the following use cases:

• You don't trust TikTok's teen mode and want to provide your child with completely controllable video content.
• You want to browse and manage your local videos and images locally, but don't want to use third-party cloud services.
• You want to use a TikTok-style mixed media browsing experience on your phone or tablet.
• You want to use a Pinterest-style image browsing experience on your phone or tablet.

How to use

Installation

TikLocal is a Python application that you can install using the following command:

pip install tiklocal

Usage

Starting TikLocal is very simple, just run the following command:

tiklocal ~/Videos/

You can specify any media folder.

To close, press Ctrl + C.

CLI Commands

TikLocal provides several CLI commands:

Start the server:

tiklocal /path/to/media           # Start with media directory
tiklocal --port 9000              # Use custom port

Generate video thumbnails:

tiklocal thumbs /path/to/media    # Generate thumbnails
tiklocal thumbs /path --overwrite # Regenerate existing thumbnails

Find and remove duplicate files:

tiklocal dedupe /path/to/media              # Find duplicates (dry-run mode)
tiklocal dedupe /path --type video          # Check video files only
tiklocal dedupe /path --execute             # Execute deletion
tiklocal dedupe /path --keep newest         # Keep newest files

Options for dedupe:

• --type: File type (video, image, all)
• --algorithm: Hash algorithm (sha256, md5)
• --keep: Keep strategy (oldest, newest, shortest_path)
• --dry-run: Preview mode (default)
• --execute: Execute actual deletion
• --auto-confirm: Skip confirmation prompt

URL Download (Web)

TikLocal includes a /download page where you can paste a media URL and enqueue a background download job.

Requirements:

• yt-dlp (required)
• gallery-dl (recommended for image/gallery posts)
• ffmpeg (recommended for format merge)

Download engine:

• yt-dlp: video-oriented sites and links
• gallery-dl: image posts/albums (Instagram/X/Pinterest, etc.)
• Download form allows manual engine selection per task (default: yt-dlp)

Cookie for login-only content (optional):

• Put exported cookie files in ~/.tiklocal/cookies
• Filename should include domain, e.g. x.com.txt, youtube.com.cookies
• The download page supports Auto match or manual file selection per task
• The download page also supports cookie file upload/replace, history delete/clear, and retry for failed tasks

Example installs:

# macOS (Homebrew)
brew install yt-dlp gallery-dl ffmpeg

# Ubuntu / Debian
sudo apt install yt-dlp gallery-dl ffmpeg

Home Mixed Feed

The home page (/) now uses a mixed immersive feed:

• Videos and images are mixed in one swipe flow (video-first density, randomized order)
• Image cards support in-feed AI caption/tags panel
• Image cards support circular magnifier (2.5x / 5x)
• Image cards do not auto-advance; swipe manually to move next/previous

Configuration

TikLocal provides some configuration options that you can adjust to your needs.

• Light and dark modes: You can choose to use light or dark mode.
• Video playback speed: You can adjust the video playback speed.

Documentation

• Docs index: docs/README.md
• Flow interaction unification: docs/flow-interaction-unification.md
• Release notes: docs/release_notes.md

TODO

• Add search
• Add more management operations, such as moving files and creating folders
• Add basic login control
• Add a bookmarking feature
• Add a Docker image
• Add a tagging feature
• Use recommendation algorithms

Contribution

TikLocal is an open source project that you can contribute to in the following ways:

• Submit code or documentation improvements.
• Report bugs.
• Suggest new features.

Contact us

If you have any questions or suggestions, you can contact us in the following ways:

• GitHub project page: https://github.com/ChanMo/TikLocal/
• Email: [[e-mail]]