telegram-video-repurpose-bot 0.1.1

Telegram bot for repurposing & uniquing videos

Telegram Video Repurpose & Uniquing Bot

Introduction

Telegram bot based on pyrotgfork (a maintained fork of the pyrogram library).

This bot was originally developed as a commissioned project for social media content management. While the original project is no longer active, this version has been updated and streamlined for public use.

Project Purpose

The core concept of the bot is video uniquing.

The bot processes an input video and applies subtle FFmpeg filters to generate technically unique versions of the same file. This allows users to post the same content multiple times across different social media accounts (such as TikTok or Instagram) while minimizing the risk of duplicate content flags or automated bans.

How It Works

Instead of applying static filters, the bot uses a system of controlled randomization:

• The user defines a range (minimum/maximum) for each supported FFmpeg parameter.

  While the bot currently supports a small subset of filters selected for content uniquing, the codebase is structured to be modular, making it easy to add new filters as needed.

• Every time a video is processed, the bot generates a random value within that specified range for each filter.

• Consequently, every output video is technically unique, even when starting from the same source file.

Key Features

• User-Friendly Interface: Designed with non-technical users in mind, the bot is fully managed via a button-based GUI.
• Direct Processing: In this version, videos are sent directly to the bot within the Telegram chat (automatic downloading from TikTok/Instagram URLs has been removed to ensure easier maintenance).
• Role-Based Access Control:
  • Administrators: Can manage user permissions (i.e. add/remove creators) and modify the audio/video parameters.
  • Creators: Can only process videos using the pre-configured settings.

Video Example

Setup

Create Telegram app

In order to use the bot, you need a Telegram bot token, an API ID, and an API hash.

To obtain them, create an app on the following website: https://my.telegram.org/apps.

Installation

This package requires Python >= 3.7.

1. Install FFmpeg: The bot requires FFmpeg to be installed and available in the system (i.e. added to the system PATH).

   Please refer to the official download page for installation instructions.

   To verify the installation, open a terminal and run: ffmpeg -version

   If the command returns version information, FFmpeg is correctly set up. Example output (truncated):

ffmpeg version 4.4.2-0ubuntu0.22.04.1 Copyright (c) 2000-2021 the FFmpeg developers

2. Set up a virtual environment (optional but recommended):

python -m venv venv
source venv/bin/activate    # On Windows use: venv\Scripts\activate

3. Install the bot:

pip install telegram_video_repurpose_bot

IMPORTANT NOTE: This bot uses pyrotgfork. If you are not using a virtual environment, ensure that the standard pyrogram library (or forks) is not installed in your Python environment. Since both libraries use the same package name, having both installed will cause conflicts and the bot will not function correctly.

4. Set up the bot: Copy the app folder from the repository to your device. Edit the configuration file by specifying your API ID, API hash, bot token, and other parameters according to your needs (see the "Configuration" chapter).
5. Run the bot: Inside the app folder, launch the bot_start.py script to start the bot:

python bot_start.py

---

Custom Configuration

When run without parameters, the bot uses conf/config.ini as the default configuration file. To specify a different configuration file, use:

python bot_start.py -c another_conf.ini

or:

python bot_start.py --config another_conf.ini

This allows you to manage different bots easily, each one with its own configuration file.

Code analysis

To run code analysis:

mypy .
ruff check .

Configuration

Bot Configuration

An example of bot configuration file is provided in the app folder: app/conf/config.ini.

The full list of configurable fields is documented below.

Name	Description
[pyrogram]	Configuration for pyrogram
session_name	Path of the file used to store the session.
api_id	API ID from https://my.telegram.org/apps.
api_hash	API hash from https://my.telegram.org/apps.
bot_token	Bot token from BotFather.
[app]	Configuration for app
app_support	Username of the user to contact for support in case of bot errors.
app_admin_users	List of usernames of admin users (see "User Roles").
app_auth_users	List of usernames of authorized users (see "User Roles").
app_lang_file	Path of custom language file in XML format (default: English).
[video]	Configuration for videos
video_max_processes	Maximum number of FFmpeg processes that can be active at the same time.
video_download_folder	Path of the folder where downloaded videos are stored (default: video/download/). Path must be existent, an error will be triggered if not existent.
video_download_delete_file	True to delete downloaded video, false otherwise (default: true)
video_process_folder	Path of the folder where processed videos are stored (default: video/proc/). Path must be existent, an error will be triggered if not existent.
video_process_delete_file	True to delete processed video, false otherwise (default: true)
video_ffmpeg_params_file	Path of the ffmpeg configuration file (default: conf/ffmpeg_params.ini).
video_ffmpeg_filters_doc_url	URL with FFmpeg filter documentation (default: https://ffmpeg.org/ffmpeg-filters.html)
[logging]	Configuration for logging
log_level	Log level, same as python logging (DEBUG, INFO, WARNING, ERROR, CRITICAL). Default: INFO.
log_console_enabled	True to enable logging to console, false otherwise (default: true)
log_file_enabled	True to enable logging to file, false otherwise (default: false). If false, the following fields will be ignored.
log_file_name	Log file name
log_file_use_rotating	True to use a rotating log file, false otherwise
log_file_max_bytes	Maximum size in bytes for a log file. When reached, a new log file is created up to log_file_backup_cnt. Only valid if log_file_use_rotating is true.
log_file_backup_cnt	Maximum number of log files. Only valid if log_file_use_rotating is true.
log_file_append	True to append to the log file, false to start fresh each time. Only valid if log_file_use_rotating is false.

FFmpeg Configuration

The file app/conf/ffmpeg_params.ini serves as the baseline for FFmpeg configuration. It contains the default enable flags and ranges (min/max values) for all supported filters.

NOTE: Since FFmpeg parameters can be updated directly via bot GUI, manual editing of this file is generally unnecessary.

The full list of configurable fields is documented below.

Parameter	Description
[ffmpeg_audio]	Audio
ffmpeg_abitrate_enabled	Enable/disable audio bitrate control.
ffmpeg_abitrate_min / max	Target audio bitrate range (in bits/s).
ffmpeg_acontrast_enabled	Enable/disable the audio contrast filter.
ffmpeg_acontrast_min / max	Range for audio contrast expansion/compression.
ffmpeg_aecho_enabled	Enable/disable the audio echo effect.
ffmpeg_aecho_in_gain_min / max	Range for input signal volume (gain).
ffmpeg_aecho_out_gain_min / max	Range for output signal volume (gain).
ffmpeg_aecho_delays_min / max	Range for echo delay in milliseconds.
ffmpeg_aecho_decays_min / max	Range for echo decay factors.
[ffmpeg_common]	Common
ffmpeg_verbosity	Verbosity level for FFmpeg (default: error), same of FFmpeg -loglevel.
ffmpeg_tempo_enabled	Enable/disable playback speed adjustment (without pitch shift).
ffmpeg_tempo_min / max	Speed multiplier range (e.g., 0.96x to 1.04x).
[ffmpeg_video]	Video
ffmpeg_colorbalance_enabled	Enable/disable color balance adjustments.
ffmpeg_colorbalance_rgbs_min / max	Range for Red, Green, and Blue shadows.
ffmpeg_colorbalance_rgbm_min / max	Range for Red, Green, and Blue midtones.
ffmpeg_colorbalance_rgbh_min / max	Range for Red, Green, and Blue highlights.
ffmpeg_colorcorrect_enabled	Enable/disable the color correction filter.
ffmpeg_colorcorrect_rbl_min / max	Range for red/blue components in lowlights.
ffmpeg_colorcorrect_rbh_min / max	Range for red/blue components in highlights.
ffmpeg_crop_enabled	Enable/disable video cropping.
ffmpeg_crop_h_min / max	Range for height pixels to be cropped.
ffmpeg_crop_w_min / max	Range for width pixels to be cropped.
ffmpeg_eq_enabled	Enable/disable the equalizer (Brightness, Contrast, Saturation, Gamma).
ffmpeg_eq_contrast_min / max	Range for video contrast adjustment.
ffmpeg_eq_brightness_min / max	Range for video brightness adjustment.
ffmpeg_eq_saturation_min / max	Range for color saturation intensity.
ffmpeg_eq_gamma_min / max	Range for gamma correction.
ffmpeg_fps_enabled	Enable/disable forced output frame rate (FPS).
ffmpeg_fps_min / max	Range for target frames per second.
ffmpeg_hflip_enabled	Enable/disable horizontal flip (mirror effect).
ffmpeg_noise_enabled	Enable/disable artificial video noise.
ffmpeg_noise_allf	Noise flags (e.g., a+p+u for all planes/uniform noise).
ffmpeg_noise_alls_min / max	Range for noise seed/intensity.
ffmpeg_output_format	Defines the output video codec (possible values: h264, libx265, h264_nvenc, hevc_nvenc).
ffmpeg_scale_enabled	Enable/disable video resizing.
ffmpeg_scale_algo	Scaling algorithm used (possible values: fast_bilinear, bilinear, bicubic, neighbor, area, bicublin, gauss, spline).
ffmpeg_scale_w / h	Target output resolution (Width x Height).
ffmpeg_smartblur_enabled	Enable/disable the smart blur filter.
ffmpeg_smartblur_lr_min / max	Range for luma radius.
ffmpeg_smartblur_ls_min / max	Range for luma strength.
ffmpeg_smartblur_lt_min / max	Range for luma threshold.
ffmpeg_vbitrate_enabled	Enable/disable video bitrate control.
ffmpeg_vbitrate_min / max	Target video bitrate range (in bits/s).

User Roles

As previously described, the bot implements a simple RBAC (Role-Based Access Control) system to manage usage:

Feature	Admin Users	Authorized Users
Process Videos	✅	✅
Change FFmpeg Parameters	✅	❌
Add/Remove Authorized Users	✅	❌

Role Details:

• Admin Users: Have total control over the bot instance. They are responsible for configuring the processing engine and managing the access list.
• Authorized Users: Can utilize the bot's core functionality (video processing) but cannot alter global settings or manage other users.

Bot GUI

The bot GUI is intuitive and straightforward. The main menu consists of three primary options:

• Process Video: Start processing a video file.
• Configure Bot: Access bot configuration (restricted to administrators).
• Info Bot: Display general information about the bot (i.e. author, version).

The configuration menu allows administrators to manage authorized users and adjust FFmpeg parameters:

• Bot Access: Add, remove, or view authorized users.

• Audio Parameters / Video Parameters: Enable, disable, or modify specific FFmpeg filters.

  Both menus share a similar interface, varying only in the available filter list.

• Parameters Management: Save, load, or view FFmpeg configurations.

  • Concept: Changes made via the GUI are applied in-memory and will be lost if the bot restarts. To make changes permanent, they must be saved to file. Similarly, users can load from file to revert unsaved in-memory changes.

• Filters Documentation: Opens the official FFmpeg documentation for detailed filter descriptions.

Run the Bot

The bot is designed for use in private chats. There is no need to add it to a group.

To ensure the bot remains online and responsive, it is highly recommended to host it on a VPS for 24/7 operation.

Note: While FFmpeg is known for being resource-intensive, this bot is specifically intended to process short video clips (1 to 2 minutes). Therefore, even a low-spec VPS should be sufficient to handle the processing tasks effectively.

Docker

Docker files are provided to run the bot in a container. You can specify the configuration file via the CONFIG_FILE variable:

CONFIG_FILE=conf/config.ini docker compose up -d --build

Translation

Bot messages can be translated using a custom XML file specified in the app_lang_file field. An Italian example is provided in app/lang.

License

This software is available under the MIT license.