telegram-media-inspect

name	telegram-media-inspect
description	Use when the user asks to inspect, watch, listen to, transcribe, or understand Telegram voice notes, video notes, audio files, videos, or other message media.

Inspect Telegram media with the plugin's media tools plus the bundled one-shot inspection scripts in this skill.

Use this skill when the user cares about the contents of a voice note, video note, audio file, or video attachment, not just its metadata.

Primary workflow:

1. Resolve the target message first.

   • If the user gives a chat_ref and message_id, use them directly.
   • If the user only gives a chat and rough description like "that bubble", use get_dialog, get_history, get_message_context, or search_messages_in_chat to identify the right message before downloading anything.

2. Confirm the media type when needed.

   • Call get_media_info if you need to distinguish audio, voice note, video note, or another attachment before downloading.
   • Treat circular "Telegram bubbles" as either voice notes or video notes depending on the returned media metadata.

3. Prefer the thin MCP wrapper when available.

   • Call inspect_message_media(chat_ref, message_id, output_dir?).
   • It downloads the media, runs the one-shot inspector, and returns:
     • transcript_path
     • contact_sheet_path
     • frames_dir
     • downloaded_to
   • When output_dir is provided, results are still written into a per-media <media-basename>-inspect/ subdirectory so repeated inspections do not clobber each other.

4. Fall back to the script path when needed.

   • If you need to debug locally or the wrapper is unavailable, call download_media for the specific message_id, then run scripts/inspect_bubble.sh <downloaded_file> [output_dir].
   • inspect_bubble.sh prints one JSON object on stdout with the same path fields.
   • If you pass output_dir, the script writes into <output_dir>/<media-basename>-inspect/.
   • transcript_path is populated when the file has audio.
   • contact_sheet_path is populated when the file has video.

5. Read the outputs locally.

   • Read the transcript file when transcript_path is present.
   • Read the contact-sheet image when contact_sheet_path is present.
   • Use both when the user asks to "watch" a video bubble, since the speech and visuals often both matter.

6. Report results in two layers.

   • First give the literal content: transcript or best-effort quoted lines.
   • Then give the interpretation: what happened, what the speaker meant, what was shown visually, and any actionables or social context.

7. Be explicit about uncertainty.

   • If the transcript is partial, noisy, or cut off, say so.
   • If the contact sheet misses context between sampled frames, say so.
   • Distinguish between exact transcription and inference from the visual samples or surrounding chat context.

8. Do not send, forward, or delete the media unless the user explicitly asks.

What inspect_bubble.sh does:

• If the media has audio, it runs scripts/transcribe_media.sh.
• If the media has video, it runs scripts/extract_video_frames.sh and scripts/make_contact_sheet.sh.
• It defaults video sampling to evenly spaced frame-count mode so long clips do not explode into hundreds of JPGs.
• inspect_message_media is the MCP wrapper around this same shell workflow.

Advanced overrides:

• WHISPER_MODEL=tiny|base|small|medium|large
• WHISPER_LANGUAGE=English or another known language
• FRAME_MODE=interval|count|scenes
• FRAME_COUNT=8 for evenly spaced frame sampling
• FRAME_INTERVAL_SECONDS=8 for interval mode
• SHEET_COLUMNS=4
• SHEET_ROWS=<n> if you want to force a fixed grid; otherwise rows expand to fit all extracted frames. If you set it manually, it must be large enough for every extracted frame.

Bundled scripts:

• scripts/inspect_bubble.sh
  • One-shot wrapper that returns transcript and/or contact-sheet paths as JSON.
• scripts/transcribe_media.sh
  • Bootstraps Whisper in an isolated cache venv and writes a .txt transcript next to the media or into the provided output directory.
• scripts/extract_video_frames.sh
  • Extracts JPG frames from a Telegram video/video-note using interval, even-count, or scene-change sampling.
• scripts/make_contact_sheet.sh
  • Turns the extracted frame-*.jpg files into one tiled JPG for quick visual inspection.

Practical defaults:

• Start with inspect_message_media when the MCP wrapper is available.
• Use inspect_bubble.sh when debugging locally or when you want to bypass the MCP layer.
• For voice notes and audio files, the transcript is usually the whole answer.
• For video bubbles, read both the transcript and the contact sheet before summarizing.
• For short social clips, a concise summary plus 1-3 notable quoted lines is usually more useful than dumping the whole transcript.