synop 0.1.0__tar.gz

synop-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,34 @@
+name: Publish Package
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  id-token: write
+
+jobs:
+  build-and-publish:
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/thumby-cli
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Build distributions
+        run: uv build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

synop-0.1.0/.gitignore

@@ -0,0 +1,39 @@
+# Python
+__pycache__/
+*.py[cod]
+*.pyo
+*.pyd
+*.so
+
+# Packaging / build artifacts
+build/
+dist/
+*.egg-info/
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# Tooling caches
+.ruff_cache/
+.mypy_cache/
+.pytest_cache/
+
+# Editors / OS
+.vscode/
+.idea/
+.DS_Store
+Thumbs.db
+
+# Local media files (avoid accidental commits)
+*.ts
+*.mp4
+*.mkv
+*.mov
+*.avi
+*.flv
+*.webm
+
+# Temporary artifacts produced by app
+filelist.txt

synop-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

synop-0.1.0/PKG-INFO

@@ -0,0 +1,13 @@
+Metadata-Version: 2.4
+Name: synop
+Version: 0.1.0
+Summary: AI-powered CLI tool to generate structured video descriptions from sampled frames and metadata.
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: av>=9.0.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: jinja2>=3.1.0
+Requires-Dist: pillow>=9.2.0
+Requires-Dist: pymediainfo>=4.3
+Requires-Dist: rich>=13.0.0
+Requires-Dist: typer>=0.15.0

synop-0.1.0/README.md

@@ -0,0 +1,179 @@
+![Synop](logo.png)
+# synop
+
+**synop** is a uv-first CLI utility that generates structured video descriptions using OpenAI-compatible vision APIs (OpenRouter by default).
+
+It samples key frames across your video timeline, combines them with technical media metadata, and writes generated output as JSON, plaintext, or Jinja-rendered BBCode.
+
+![Python >=3.10](https://img.shields.io/badge/python-3.10%2B-blue)
+![OpenAI Compatible](https://img.shields.io/badge/provider-OpenAI%20compatible-green)
+
+## Features
+
+- Smart frame sampling based on runtime length (4/8/12 frames)
+- Metadata extraction (duration, resolution, codec)
+- OpenRouter by default, with configurable OpenAI-compatible API base URL
+- Persistent API key storage in user settings
+- Custom output templates with Jinja2
+
+## Installation
+
+```bash
+uv tool install synop-cli
+```
+
+## Quick Start
+
+1) Save your API key once:
+
+```bash
+synop config set-key
+```
+
+2) Generate a description:
+
+```bash
+synop "path/to/video.mp4"
+```
+
+This writes `video_name_desc.json` next to the source video.
+
+## Usage
+
+```bash
+synop "path/to/video.mp4" [OPTIONS]
+```
+
+Options:
+
+- `-m, --model` Model ID (default: `x-ai/grok-4.20-beta`)
+- `--api-base-url` OpenAI-compatible API base URL (default: `https://openrouter.ai/api/v1`)
+- `-f, --format` Output format: `json` (default), `plaintext`, `bbcode`
+- `-t, --template` Path to custom `.j2` or `.txt` template (only used with `--format bbcode`)
+- `-o, --output` Output path for generated description
+- `--thumb` Thumbnail URL/path to inject into `{{ video_thumb }}`
+- `--generate-thumbnail` Generate thumby-style thumbnail sheet image
+- `--thumbnail-output` Output path for generated thumbnail sheet
+- `--screens-dir` Directory to save thumby-grid extracted screen images
+- `--thumb-rows` Rows in thumbnail/screen grid (default: `9`)
+- `--thumb-cols` Columns in thumbnail/screen grid (default: `3`)
+- `--thumb-width` Grid tile width in pixels (default: `400`)
+- `--thumb-skip` Seconds to skip from start for grid extraction (default: `10.0`)
+- `--thumb-quality` JPEG quality for thumbnail/screens (default: `95`)
+
+## Output Formats
+
+By default, synop writes JSON output:
+
+```json
+{
+  "title": "...",
+  "short_summary": "...",
+  "generated_description": "...",
+  "duration": "01:42:33",
+  "full_resolution": "1920x1080",
+  "short_resolution": "1080p",
+  "codec": "H.264",
+  "video_thumb": ""
+}
+```
+
+Use `--format plaintext` to write plain text output.
+
+Use `--format bbcode` to render Jinja templates (defaults to bundled `example.j2` if `--template` is not set).
+
+When thumbnail/screens generation is enabled, JSON output also includes:
+
+- `thumbnail_path` (when `--generate-thumbnail` is used)
+- `screens_dir`, `screens_count`, `screens` (when `--screens-dir` is used)
+
+## Thumbnail and Screens
+
+Generate a thumby-style thumbnail sheet:
+
+```bash
+synop "path/to/video.mp4" --generate-thumbnail
+```
+
+Save thumby-grid extracted frames into a screens folder:
+
+```bash
+synop "path/to/video.mp4" --screens-dir "./screens"
+```
+
+Generate both thumbnail and screens with custom grid settings:
+
+```bash
+synop "path/to/video.mp4" --generate-thumbnail --screens-dir "./screens" --thumb-rows 6 --thumb-cols 4 --thumb-width 360
+```
+
+Notes:
+
+- `--screens-dir` always saves the thumby-grid frames (`rows * cols`) with ordered filenames.
+- By default, saved screens are resized to 50% of the original video dimensions.
+- When `--generate-thumbnail` is used and `--thumb` is not set, `video_thumb` is auto-filled with the generated thumbnail path.
+
+## API Key Resolution
+
+Synop resolves the key in this order:
+
+1. `SYNOP_API_KEY` environment variable
+2. Persisted settings file
+
+## API Provider
+
+By default, synop calls OpenRouter (`https://openrouter.ai/api/v1`).
+
+You can point synop to another OpenAI-compatible endpoint:
+
+```bash
+synop "path/to/video.mp4" --api-base-url "https://your-provider.example/v1" --model "your-vision-model"
+```
+
+Settings path:
+
+- Windows: `%APPDATA%\synop\settings.json`
+- Linux/macOS: `$XDG_CONFIG_HOME/synop/settings.json` or `~/.config/synop/settings.json`
+
+## Example BBCode Template
+
+The previous default BBCode output is now provided as an example Jinja template in `src/synop/templates/example.j2`:
+
+```text
+[cast]
+[font=Arial Black][size=4]{{ title }}[/size][/font]
+{{ short_summary }}
+
+[info]
+[b]Duration:[/b] {{ duration }}
+[b]Resolution:[/b] {{ full_resolution }} ({{ short_resolution }})
+[b]Codec:[/b] {{ codec }}
+
+[plot]
+{{ generated_description }}
+
+[screens]
+[img]{{ video_thumb }}[/img]
+```
+
+Use it directly:
+
+```bash
+synop "path/to/video.mp4" --format bbcode --template src/synop/templates/example.j2
+```
+
+Template variables available in Jinja context:
+
+- `title`
+- `short_summary`
+- `generated_description`
+- `duration`
+- `full_resolution`
+- `short_resolution`
+- `codec`
+- `video_thumb`
+
+## Requirements
+
+- Python 3.10+
+- FFmpeg runtime libraries (required by `av`)

synop-0.1.0/pyproject.toml

@@ -0,0 +1,24 @@
+[project]
+name = "synop"
+version = "0.1.0"
+description = "AI-powered CLI tool to generate structured video descriptions from sampled frames and metadata."
+requires-python = ">=3.10"
+dependencies = [
+    "typer>=0.15.0",
+    "av>=9.0.0",
+    "pymediainfo>=4.3",
+    "Pillow>=9.2.0",
+    "rich>=13.0.0",
+    "httpx>=0.27.0",
+    "jinja2>=3.1.0",
+]
+
+[project.scripts]
+synop = "synop.cli:run"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/synop"]

synop-0.1.0/src/synop/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

synop-0.1.0/src/synop/ai_client.py

@@ -0,0 +1,214 @@
+from __future__ import annotations
+
+import base64
+import json
+import re
+from dataclasses import dataclass
+from urllib.parse import urljoin
+
+import httpx
+
+OPENROUTER_BASE_URL = "https://openrouter.ai/api/v1"
+DEFAULT_MODEL = "x-ai/grok-4.20-beta"
+
+
+@dataclass(slots=True)
+class DescriptionResult:
+    title: str
+    short_summary: str
+    generated_description: str
+
+
+class OpenRouterError(RuntimeError):
+    pass
+
+
+class OpenRouterClient:
+    def __init__(
+        self,
+        api_key: str,
+        model: str = DEFAULT_MODEL,
+        timeout: float = 120.0,
+        api_base_url: str = OPENROUTER_BASE_URL,
+    ):
+        self.api_key = api_key
+        self.model = model
+        self.timeout = timeout
+        self.api_base_url = api_base_url.rstrip("/")
+
+    @property
+    def chat_completions_url(self) -> str:
+        if self.api_base_url.lower().endswith("/chat/completions"):
+            return self.api_base_url
+        return urljoin(f"{self.api_base_url}/", "chat/completions")
+
+    @property
+    def is_openrouter(self) -> bool:
+        return "openrouter.ai" in self.api_base_url.lower()
+
+    async def generate_description(self, frame_jpegs: list[bytes]) -> DescriptionResult:
+        if not frame_jpegs:
+            raise ValueError("No frame images were provided to the AI client")
+
+        content: list[dict[str, object]] = [
+            {
+                "type": "text",
+                "text": (
+                    "You are an expert film archiver. Analyze these sequential frames "
+                    "from a video and respond with valid JSON only. You are allowed to use explicit/adult language in case of NSFW context. "
+                    'Schema: {"title":"...", "short_summary":"...", "generated_description":"..."}. '
+                    "Requirements: title should be catchy and concise, short_summary must be exactly 2 sentences, "
+                    "generated_description must be 3 paragraphs with rich plot/detail context."
+                ),
+            }
+        ]
+
+        for frame in frame_jpegs:
+            encoded = base64.b64encode(frame).decode("ascii")
+            content.append(
+                {
+                    "type": "image_url",
+                    "image_url": {"url": f"data:image/jpeg;base64,{encoded}"},
+                }
+            )
+
+        payload = {
+            "model": self.model,
+            "messages": [{"role": "user", "content": content}],
+            "temperature": 0.4,
+        }
+
+        headers = {
+            "Authorization": f"Bearer {self.api_key}",
+            "Content-Type": "application/json",
+        }
+        if self.is_openrouter:
+            headers["HTTP-Referer"] = "https://github.com/h4nz4/synop"
+            headers["X-Title"] = "synop"
+
+        async with httpx.AsyncClient(timeout=self.timeout) as client:
+            response = await client.post(
+                self.chat_completions_url,
+                headers=headers,
+                json=payload,
+            )
+
+        if response.status_code >= 400:
+            self._raise_http_error(response)
+
+        data = response.json()
+        raw_content = _extract_assistant_content(data)
+        return _parse_description(raw_content)
+
+    def _raise_http_error(self, response: httpx.Response) -> None:
+        body_text = response.text
+        status = response.status_code
+        lowered = body_text.lower()
+
+        if status == 401:
+            provider = "OpenRouter" if self.is_openrouter else "API"
+            raise OpenRouterError(
+                f"{provider} authentication failed. Check SYNOP_API_KEY or saved key."
+            )
+        if status == 429:
+            provider = "OpenRouter" if self.is_openrouter else "API"
+            raise OpenRouterError(
+                f"{provider} rate limit reached. Retry later or use another model."
+            )
+        if (
+            status == 400
+            and "image" in lowered
+            and ("unsupported" in lowered or "not support" in lowered)
+        ):
+            raise OpenRouterError(
+                f"Model '{self.model}' does not appear to support vision input."
+            )
+
+        raise OpenRouterError(f"OpenRouter request failed ({status}): {body_text}")
+
+
+def _extract_assistant_content(payload: dict[str, object]) -> str:
+    choices = payload.get("choices")
+    if not isinstance(choices, list) or not choices:
+        raise OpenRouterError("OpenRouter response is missing choices")
+
+    first_choice = choices[0]
+    if not isinstance(first_choice, dict):
+        raise OpenRouterError("OpenRouter response has invalid choice format")
+
+    message = first_choice.get("message")
+    if not isinstance(message, dict):
+        raise OpenRouterError("OpenRouter response is missing message payload")
+
+    content = message.get("content")
+    if isinstance(content, str):
+        return content.strip()
+
+    if isinstance(content, list):
+        parts: list[str] = []
+        for item in content:
+            if isinstance(item, dict):
+                text = item.get("text")
+                if isinstance(text, str):
+                    parts.append(text)
+        if parts:
+            return "\n".join(parts).strip()
+
+    raise OpenRouterError("OpenRouter response did not include text content")
+
+
+def _parse_description(content: str) -> DescriptionResult:
+    data = _parse_json_maybe(content)
+    if data is not None:
+        title = str(data.get("title") or "Untitled")
+        short_summary = str(data.get("short_summary") or "No short summary provided.")
+        generated_description = str(
+            data.get("generated_description") or "No detailed description provided."
+        )
+        return DescriptionResult(
+            title=title.strip(),
+            short_summary=short_summary.strip(),
+            generated_description=generated_description.strip(),
+        )
+
+    plain = content.strip()
+    short_summary = plain[:220].strip()
+    if short_summary and not short_summary.endswith("."):
+        short_summary += "."
+    return DescriptionResult(
+        title="Generated Video Description",
+        short_summary=short_summary or "No short summary provided.",
+        generated_description=plain or "No detailed description provided.",
+    )
+
+
+def _parse_json_maybe(content: str) -> dict[str, object] | None:
+    stripped = content.strip()
+    try:
+        loaded = json.loads(stripped)
+        if isinstance(loaded, dict):
+            return loaded
+    except json.JSONDecodeError:
+        pass
+
+    fenced_match = re.search(r"```(?:json)?\s*(\{.*?\})\s*```", stripped, re.DOTALL)
+    if fenced_match:
+        candidate = fenced_match.group(1)
+        try:
+            loaded = json.loads(candidate)
+            if isinstance(loaded, dict):
+                return loaded
+        except json.JSONDecodeError:
+            pass
+
+    bracket_match = re.search(r"\{.*\}", stripped, re.DOTALL)
+    if bracket_match:
+        candidate = bracket_match.group(0)
+        try:
+            loaded = json.loads(candidate)
+            if isinstance(loaded, dict):
+                return loaded
+        except json.JSONDecodeError:
+            return None
+
+    return None