tflix

A Telegram CLI interface for media downloading and streaming, built on top of Telethon.

Description

tflix streamlines the process of discovering, downloading and streaming media files from Telegram bots. It provides an interactive command-line interface that handles bot navigation, automatic channel joining, and media file streaming and downloads with minimal user intervention.

Features

• Interactive CLI - Navigate bot menus and send messages directly from the terminal
• Auto-Join Support - Automatically joins groups via invite links when required
• Button Navigation - Click numbered options from bot menus instantly
• Media Filtering - Lists only media files
• Downloading and Streaming - Can download or stream media files directly
• Movie/Series Search - Use Tab to search and autocomplete movies or series titles

Requirements

• Python 3.8+
• Telegram API Credentials

Installation

From PyPI

pip install tflix

From Source

git clone https://github.com/voidsnax/tflix.git
cd tflix
pip install -e .

Usage

Setup Guide

Creating the .env File

1. Locate the config folder:

   • Windows: C:\Users\<User>\tflix\
   • Linux/Mac: ~/.config/tflix/

2. Create a new file named .env in the config folder

3. Get your Telegram API credentials:

   • Visit https://my.telegram.org
   • Log in with your Telegram account
   • Go to "API development tools"
   • Create a new application
   • Copy your api_id and api_hash

4. Add your credentials to .env:

   TGRAM_API_ID=your_api_id_here
   TGRAM_API_HASH=your_api_hash_here
   

5. Optional: Add movie database API keys for title suggestions

   Note: TMDB is recommended for vast movie and series collections, while OMDB is recommended for quicker response times.

   • TMDB

     1. Create an account at https://www.themoviedb.org/
     2. Go to Settings > API and apply for an API key
     3. Add TMDB_API_KEY=your_tmdb_api_key to .env

   • OMDB

     1. Visit http://www.omdbapi.com/apikey.aspx
     2. Request a free API key
     3. Add OMDB_API_KEY=your_omdb_api_key to .env

   Example:

   TGRAM_API_ID=your_api_id_here
   TGRAM_API_HASH=your_api_hash_here
   TMDB_API_KEY=your_tmdb_api_key_here
   OMDB_API_KEY=your_omdb_api_key_here
   

6. Save the file

Configuration File

tflix also supports a config file for advanced settings. The default location is:

• Linux/Mac: ~/.config/tflix/tflix.conf
• Windows: C:\Users\<User>\tflix\tflix.conf

A sample config file looks like:

[chat]
auto_join_buttons = join updates channel, join channel, me joined, request to my updates channel
buttons_to_skip = search movies here, search on google

[log]
# channel =

[server]
host = http://localhost
port = 8080

[stream]
auto_stream = True
copy_links = False

[download]
connection_count = 4

Options:

• auto_join_buttons: comma-separated button labels to auto-click for joining channels/groups
• buttons_to_skip: comma-separated button labels to ignore
• channel: log channel ID for forwading streaming files (needed if u want to start or use streaming services also u can connect to log channel and access files by just mentioning log channel name, e.g, tflix streamlogs -s)
• host: streaming server host
• port: streaming server port
• auto_stream: automatically generate stream links for files
• copy_links: copy streaming links to clipboard
• connection_count: number of download connections (1-20) (higher values can cause instability or flood wait)

If the config file does not exist, it is created automatically with default values.

Basic Command

tflix CHAT [OPTIONS]

Options

CHAT                         Chat username, ID, or link
-o, --output PATH            Output directory for downloads (default: current dir)
-l, --list [LIMIT/STRING]    List recent N bot media messages (default: 1) or searches across the chat for the file if a string is provided
-d, --download [INDEX]       Download recent N bot media messages (default: 1)
-s, --stream                 Starts streaming server

Interactive Commands

h                     → Print help table
<text>                → Send message to bot
<number>              → Click button # from the list
ls [LIMIT/STRING]     → List files to a limit or based on string
stream [INDEX]        → Stream files
dl [INDEX]            → Download files (e.g., indices '1', '1,2,3', '1:3', '1-3')
exit/ctrl-c           → Quit

Examples

Connect to a bot and list 5 recent files:

tflix @mybot -l 5

Connect to a bot with server running:

tflix @mybot -s

Connect to a bot and set output folder:

tflix @mybot -o C:\Downloads

Then interact :)

Notes

• API Credentials - Create .env in config folder with TGRAM_API_ID and TGRAM_API_HASH
• Session Changes - Overwrites existing session when .env file attributes changes
• Private groups - need invite link to connect
• Input Delay - Allow 10-15 seconds for input to process if responses or input prompt arrow seem delayed
• Faster downloads - Install cryptg or telethon-tgcrypto for faster download speeds (pip install cryptg OR pip install telethon-tgcrypto).
• Video listing filter - Only video files with size greater than 15 MB are listed by default.
• Copying streaming links - Depends on platform:
  • Windows/Mac: install pyperclip (pip install pyperclip) to enable clipboard copying.
  • Linux: wl-copy from the wl-clipboard package is used (e.g. on Debian/Ubuntu: sudo apt install wl-clipboard).
  • Termux: requires the Termux:API add-on and termux-api package (install Termux:API from F‑Droid/GitHub repo, the original source you have used to install termux and run pkg install termux-api).
• Streamable links - Use the generated streamable links in a media player like mpv for a better streaming experience.You can also use the links in a download managers when server is active.

License

MIT License