https://github.com/theelderemo/tg-media-browser
A desktop GUI for browsing your Telegram chats, listing the videos in any chat, and either streaming them in app or with any external player you have installed
https://github.com/theelderemo/tg-media-browser
gui python telegram telegram-client telegramapi video-player
Last synced: 6 days ago
JSON representation
A desktop GUI for browsing your Telegram chats, listing the videos in any chat, and either streaming them in app or with any external player you have installed
- Host: GitHub
- URL: https://github.com/theelderemo/tg-media-browser
- Owner: theelderemo
- License: apache-2.0
- Created: 2026-05-16T02:38:41.000Z (18 days ago)
- Default Branch: master
- Last Pushed: 2026-05-16T03:11:00.000Z (18 days ago)
- Last Synced: 2026-05-16T05:11:45.814Z (18 days ago)
- Topics: gui, python, telegram, telegram-client, telegramapi, video-player
- Language: Python
- Homepage:
- Size: 32.2 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Telegram Media Browser
A desktop GUI for browsing your Telegram chats, listing the **videos** in any chat, and either **streaming** them in app or with any external player you have installed (mpv, VLC, Totem, …) - or **downloading** them to a folder you pick.
Streaming uses a tiny localhost HTTP bridge that wraps Telegram's chunked MTProto downloads with full HTTP `Range` support, so any player that can open a URL works.
## Features
- Left-pane list of every dialog (users, bots, groups, channels), ordered by latest activity, with unread counts.
- Right-pane icon grid of every **video** in the selected chat (no animations or round messages), with thumbnails, duration, and metadata. Lazy-paginated 50 at a time as you scroll.
- Double-click to play in-app (Qt's `QMediaPlayer` / `QVideoWidget` uses the FFmpeg backend, plays everything Telegram sends).
- Right-click for the full menu: **Play in-app**, **Open with system default**, **Open with ▸** (submenu of every video-capable app detected via XDG `.desktop` files, with the system default flagged), **Download to default folder**, **Save as…**.
- Cancellable downloads with live progress.
- On-disk thumbnail cache keyed by Telegram's `file_unique_id`, so revisiting a chat is instant.
- Dark theme out of the box (Qt Fusion + a dark palette).
## Requirements
- **Python 3.14** (3.12 / 3.13 should also work; 3.14 is what's tested).
- A Telegram **API ID** and **API hash** - get them from [Telegram](https://my.telegram.org/apps) for free
- Linux desktop (I made this on Ubuntu). The "Open with…" picker uses XDG `.desktop` files, so it's Linux-only by design, but most other features should work on any platform.
## Setup
```bash
# From the project root:
python3.14 -m venv .venv
.venv/bin/pip install -r requirements.txt
# Export your Telegram credentials (add to ~/.bashrc to persist):
export TG_API_ID=123456
export TG_API_HASH=your_api_hash_here
```
## Run
```bash
.venv/bin/python main.py
```
On first run the status bar shows the streaming bridge URL and the
number of video players detected, e.g.
```text
Connected. Stream server on http://127.0.0.1:43217. 6 video player(s) detected. Loading chats…
```
## Build a standalone binary
`build.sh` bundles the app into a single self-contained executable with [PyInstaller](https://pyinstaller.org/) and installs it to `~/.local/bin/tgmedia` so you can launch it from anywhere:
```bash
./build.sh
```
After that, launch the app from any terminal with:
```bash
tgmedia
```
## Configuration
- **Default download folder** - `~/Videos/Telegram/` (created on first use). Override per-download with "Save as…". Persisted via `QSettings` at `~/.config/tg-media-browser/tg-media-browser.conf`.
- **Thumbnail cache** - `~/.cache/tg-media-browser/thumbs/` (override via `XDG_CACHE_HOME`). Safe to delete at any time; it'll repopulate.
## Privacy & security
- The app talks to Telegram directly. No third-party servers.
- The streaming bridge binds to **127.0.0.1 only**, on a random ephemeral port. URLs use short unguessable tokens that are valid only for the running app session.
## Stack
- [kurigram](https://github.com/KurimuzonAkuma/kurigram) - maintained Pyrogram fork. Pyrogram itself doesn't run on Python 3.13+ because of module-import-time `asyncio.get_event_loop()` calls.
- [pytgcrypto](https://pypi.org/project/pytgcrypto/) - TgCrypto fork with Python 3.14 wheels (fast AES-IGE / AES-CTR).
- [PySide6](https://doc.qt.io/qtforpython-6/) - Qt 6 bindings; the
FFmpeg multimedia backend ships by default on Linux.
- [qasync](https://github.com/CabbageDevelopment/qasync) - unified
asyncio + Qt event loop, so there's no thread juggling between the GUI and the Telegram client.
- [aiohttp](https://docs.aiohttp.org/) - localhost streaming server.
## Contributing
Contributions are welcome. Bug reports, feature ideas, and pull requests are all fair game.
A few ground rules:
- **Open an issue first** for anything non-trivial (new features, refactors, dependency swaps) so we can agree on the approach before you spend time on a PR.
- **One topic per PR.** Small, focused changes get reviewed and merged faster than sprawling ones.
- **Match the existing style.** Follow the patterns already in `tg_browser/` - async-first, type-annotated, and lean on `qasync` rather than threads. Keep GUI code in `tg_browser/gui/` and keep network/IO out of widget event handlers.
- **Don't commit secrets or session state.** `*.session`, `*.session-journal`, `.env`, `downloads/`, and `.cache/` are all in `.gitignore`; double-check `git status` before any commit.
- **Test against a real Telegram account** before opening a PR. There's no automated test suite yet - the bar is "run it locally, open a chat, stream a video, download a video, nothing regresses."
- **By submitting a contribution, you agree to license it under the project's Apache License 2.0** (see below). Per Section 5 of the license, contributions are submitted under those same terms unless you say otherwise.
## License
Licensed under the **Apache License, Version 2.0** (the "License"); you may not use this project except in compliance with the License. You may obtain a copy of the License in the [`LICENSE`](LICENSE) file at the root of this repository, or at .
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.