KO | EN

GitLite

Minimalist Open Source Repository Search Engine

gitlite — search

#dsh #dsh-plugin #developer-tools #ai-agent #claude-code #codex #typescript #ai-agents #deepseek-harness #mcp #cli #rust

mpv-shot-telegram

★ 2 Open GitHub ↗

Organised screenshots for mpv, with optional Telegram publishing. Fansub/scene release-name parsing, per-series folders, album batching.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# mpvshot

Organised screenshots for mpv, with optional Telegram publishing.

One keypress saves a screenshot into a per-series folder under a self-describing
name — and, if you switch it on, posts it to a Telegram forum supergroup: a
compressed photo in one topic, the pixel-exact PNG original in another.

It works for Jellyfin network streams (via
[jellyfin-mpv-shim](https://github.com/jellyfin/jellyfin-mpv-shim), fansub and
scene releases (`[SubsPlease] Show - 05 (1080p) [ABCD1234].mkv`,
`Show.Name.S01E05.1080p.WEB-DL.x264-GRP.mkv`), movies and OBS clips, degrading
to the filename when nothing better is known.

```
<screenshot_root>\
├── TV\Frieren_ Beyond Journey's End\Frieren_ Beyond Journey's End - S01E05 - 00.12.34.png
├── Movies\Spirited Away (2001)\Spirited Away - 01.23.45.png
├── Clips\2024-07\2024-07-15 12-52-05 - 00.00.42.png
└── Unsorted\Some Live Channel - 00.12.34.png
```

**Telegram is off by default.** With no configuration at all this is purely a
screenshot organiser: it loads, binds its keys, files your screenshots, uploads
nothing, and never errors out under plain mpv.

## Install

Download the zip from
[Releases](https://github.com/Bestfast/mpv-shot-telegram/releases) and unpack
it over your mpv config directory — it contains `scripts\mpvshot\` and
`script-opts\mpvshot.conf.example`, both already in the right place. Or copy
`mpvshot\` there yourself:

| Platform | mpv config directory |
|---|---|
| Windows (portable) | `<mpv folder>\portable_config\` |
| Windows | `%APPDATA%\mpv\` |
| Linux / macOS | `~/.config/mpv/` |

```
<mpv config>\
├── scripts\mpvshot\        ← the script (a whole directory, not one file)
└── script-opts\mpvshot.conf  ← optional, see Configuration
```

On Windows a directory junction works as well as a copy and keeps a checkout
and the installed script in sync — `mklink /J` needs no administrator rights.

If you use [jellyfin-mpv-shim](https://github.com/jellyfin/jellyfin-mpv-shim),
its config directory is often the same mpv config directory (or a link to it),
in which case one install serves plain mpv and the shim both.

Requires mpv with Lua enabled, and `curl` on `PATH` for uploading (Windows 10+
and most Linux/macOS installs already have it). No Python, no other runtime.

## Keys

| Key | Named binding | Does |
|---|---|---|
| `s` | `mpvshot/shot-subs` | screenshot **with** subtitles, save + upload |
| `S` | `mpvshot/shot-nosubs` | screenshot **without** subtitles, save + upload |
| `Ctrl+s` | `mpvshot/shot-local` | save locally only, never uploads |

Registered as script defaults, so they outrank mpv's builtins but yield to your
`input.conf`. To rebind:

```
F1 script-binding mpvshot/shot-nosubs
```

## Configuration

One file: `<mpv config>\script-opts\mpvshot.conf`. Copy
`script-opts\mpvshot.conf.example` there and edit it. Every key can also be set
per run with `--script-opts=mpvshot-key=value`.

```ini
telegram=yes
bot_token=123456:ABC...
chat_id=-1001234567890
topic_photos=2
topic_docs=3
```

Uploading happens only when `telegram=yes` **and** a token and chat id are
present. A missing or malformed config is never an error — the script falls
back to defaults and keeps saving locally.

> The bot token sits in plain text in your mpv config directory. Worth knowing
> if you sync or back that directory up, or if it's shared with another
> application. A bot token grants full control of that bot, so use a bot
> created for this and nothing else.

### Options

| Key | Default | Meaning |
|---|---|---|
| `telegram` | `no` | master switch; `no` means organiser only |
| `bot_token` | — | from [@BotFather](https://t.me/BotFather) |
| `chat_id` | — | forum supergroup id, with the `-100` prefix |
| `topic_photos`, `topic_docs` | — | topic ids; empty or `1` posts to General |
| `tag_tv`, `tag_movie`, `tag_clip`, `tag_other` | `TV`, `Movie`, `Clip`, `Stream` | category hashtag; empty to disable |
| `screenshot_root` | `<home>\Pictures\mpv` | archive root |
| `outbox_dir` | `%APPDATA%\mpvshot\outbox`, else `~/.local/state/mpvshot/outbox` | where failed uploads wait |
| `upload_photos` | `yes` | post the compressed photo |
| `upload_docs` | `yes` | post the original PNG as a document |
| `debounce` | `2.5` | seconds of quiet before posting; `0` posts at once |
| `jpeg_quality` | `95` | quality of the upload-only JPEG |
| `dry_run` | `no` | log captions and curl argv instead of posting |
| `screenshot_sw` | `no` | force software screenshots; `no` leaves mpv's own setting alone |

## Telegram setup

1. Create a **supergroup**, enable **Topics**, and in permissions disable *Send
   Messages* for members — it then reads like a channel but has topics. It must
   be a supergroup: only supergroups can be forums. An existing broadcast
   channel cannot be converted, so its history can't come along.
2. Create two topics, e.g. `Shots` and `Originals`.
3. Add your bot as an **administrator** with post rights.
4. Open a message in each topic → *Copy Message Link* →
   `https://t.me/c/<internal>/<topic_id>/<msg_id>`. Your `chat_id` is `-100` +
   `<internal>`; the middle number is the topic id.

**The General topic is a special case.** Its id is `1`, but the Bot API rejects
`message_thread_id=1` with *"message thread not found"* — posting to General
means omitting the parameter entirely. mpvshot treats `1`, `general` and empty
as the same thing and leaves it out, so `topic_photos=1` works as you'd expect.
Every other topic id is sent through as given.

## How it works

One keypress produces two files: the archive **PNG**, and — only when a photo
post is due — a **JPEG** in `%TEMP%\mpvshot\`, deleted after a successful post.
The JPEG exists because `sendPhoto` caps at 10 MB / 10000 px summed, which a 4K
PNG screenshot can breach. Both `screenshot-to-file` calls happen in one Lua
callback, so they capture the same frame.

Shots are queued and debounced, so rapid-fire screenshotting becomes one tidy
album per topic instead of eight separate posts (and stays well clear of
Telegram's ~20 messages/minute per chat). A single shot goes out as
`sendPhoto` + `sendDocument`; several become `sendMediaGroup`, ten per album,
with per-item captions.

Uploads run through `curl.exe` as an async subprocess: no playback stutter, no
console flash. A failed post is written as a job in `%APPDATA%\mpvshot\outbox\`
and retried when mpv next loads and after each successful flush. Quitting mpv
right after a screenshot triggers a synchronous flush, so nothing is lost.

### Classification

Ordered rules, first match wins. A trailing `" (Transcode)"` is stripped from
`media-title` first — the shim appends it while transcoding.

| # | Kind | Test | Goes to |
|---|---|---|---|
| 1 | Jellyfin episode | `media-title` is `Series - s1e05 - Episode` | `TV\<Series>\` |
| 2 | Jellyfin movie | network path, title is `Movie (2001)` | `Movies\<Movie (2001)>\` |
| 3 | Clip | filename is `YYYY-MM-DD HH-MM-SS` (OBS and videoclip default naming) | `Clips\<YYYY-MM>\` |
| 4 | Episode | the release name carries an episode marker | `TV\<Series>\` |
| 5 | Movie | the release name carries a year and no episode marker | `Movies\<Movie (Year)>\` |
| 6 | Unknown | anything else | `Unsorted\` |

Rule 3 keys off the filename pattern rather than the folder, because OBS
recordings and videoclip cuts often share both a folder and a naming scheme.

Rules 4 and 5 read the filename the way a release parser does: separators are
normalised (`_` always, `.` when the name has none of its own), bracketed
metadata is dropped — group tags, CRC hashes, `[1080p][Multi Sub]` — and the
title is cut at the first release tag (`1080p`, `WEB-DL`, `x265`, `10bit`,
`AAC`, `Multi`, …). What survives is the name.

| Filename | Becomes |
|---|---|
| `[SubsPlease] Frieren - 28 (1080p) [F1A2B3C4].mkv` | Frieren — S01E28 |
| `[SubsPlease] Mushoku Tensei S2 - 12 (1080p) [DEADBEEF].mkv` | Mushoku Tensei — S02E12 |
| `[Anime Time] Some Show - 07.5 (1080p) [x265][10bit].mkv` | Some Show — S01E07.5 |
| `[gg]_Old_Fansub_Show_-_05_[ABCD1234].mkv` | Old Fansub Show — S01E05 |
| `[Judas] Some Show - S01E05 [1080p][Multi-Subs].mkv` | Some Show — S01E05 |
| `Scene.Show.S02E07.1080p.WEB-DL.DDP5.1.H.264-GRP.mkv` | Scene Show — S02E07 |
| `Dated.Show.2023.S01E02.1080p.AMZN.WEB-DL.mkv` | Dated Show — S01E02 |
| `Blade.Runner.2049.2017.2160p.mkv` | Blade Runner 2049 (2017) |

Recognised episode markers, first match wins: `S01E05` (and `S01 E05`, `S1E5`),
`1x05`, ` - 05` (fansub absolute numbering, including `07.5` and a `v2`
suffix), `Episode 5`, `EP05`, `E05`. A season named in the title itself — `S2`,
`Season 2`, `2nd Season` — is folded into the episode code. Both rules refuse
to read a year as an episode number, so `The.Matrix.1999` is a movie while
`One Piece - 1100` is an episode; a movie keeps a year that is part of its name
(`Blade Runner 2049`) and uses the last one as the release year.

Captions are plain text — a title line and a hashtag line, no deep link:

```
Frieren: Beyond Journey's End — S01E05 — 12:34
#Frieren_Beyond_Journeys_End #TV
```

The second tag is the category, named by `tag_tv` / `tag_movie` / `tag_clip` /
`tag_other`. Hashtags strip to `[A-Za-z0-9_]` (apostrophes are dropped, not
converted). Telegram doesn't linkify a hashtag starting with a digit, so a
title that reduces to one — a date-named clip, say — falls back to its category
name, and the two collapse into a single `#Clip` rather than repeating.

Network streams whose URL carries no real filename (a Jellyfin
`/Items/<id>/Download?api_key=…`, for instance) are labelled `stream` rather
than parsed: the filename rules only run on a local path or a URL that actually
ends in a media extension. With jellyfin-mpv-shim running, `media-title` gives
the real name anyway and rule 1 wins.

Path components are sanitised for Windows (`<>:"/\|?*` → `_`, no trailing dots
or spaces, 120 characters max) and de-duplicated with a ` (2)` suffix.

## Development

`dry_run=yes` logs the exact captions and the curl argv without posting — with
the bot token redacted, and without needing one at all. The shim's metadata can
be simulated without Jellyfin, because `force-media-title` is the only property
it sets:

```bash
mpv --msg-level=mpvshot=debug --script-opts=mpvshot-telegram=yes,mpvshot-dry_run=yes --force-media-title="Frieren: Beyond Journey's End - s1e05 - Mimic" some-video.mkv
```

Classification and path tests run inside mpv's own Lua state:

```bash
mpv --no-config --idle=yes --script=tests/run.lua
```

## Known tradeoffs

- The bot token appears in the curl argv, so it is briefly visible in the
  process list. Fine on a single-user machine; if you'd rather it weren't,
  `curl -K -` can read the URL from stdin via the subprocess `stdin_data` field.
- **HDR is untested.** Screenshots of HDR sources can come out washed out
  depending on how mpv tone-maps them; that's `screenshot-sw` behaviour, not
  this script. The `screenshot_sw` option is there to try when you get to it.

## Credits & licensing

Portions are derived from **[Videoclip](https://github.com/Ajatt-Tools/videoclip)**,
Copyright (C) 2021 Ren Tatsumoto, GPL-3.0-or-later. Deriving from it means this
project ships under the same licence — that's the licence's requirement, not a
preference. Specifically:

| Taken from | Used in | What |
|---|---|---|
| `helpers.lua` `subprocess` | `telegram.lua` | the `mp.command_native{name="subprocess", playback_only=false, …}` table shape |
| `videoclip.lua` `upload_to_catbox` | `telegram.lua` | curl-over-subprocess structure, and its exit-code check: `status < 0 or status > 99` means curl itself failed or wasn't found, `status ~= 0` means curl ran and the request failed |
| `encoder.lua` `clean_filename` / `clean_forbidden_characters` | `paths.lua` | filename sanitising, adapted for this folder layout |
| `platform.lua` `curl_exe` | `telegram.lua` | `curl.exe` vs `curl` resolution |

Classification, captions, folder layout, queue/debounce, album batching and the
outbox are original.

Release-name parsing follows the approach used by
**[autobrr](https://github.com/autobrr/autobrr)** (through
[moistari/rls](https://github.com/moistari/rls)): normalise separators, drop
bracketed metadata, cut the title at the first release tag. No code is taken
from either — this is a much smaller tag list that only has to find where a
title ends, not describe the release.

mpv-shot-telegram

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README