# How Vertical Visuals uses Gemini 2.5 + Sparkle to ship faster

> Operational deep-dive · Published 2026-05-07 · By Vertical Visuals · Markdown shadow of [https://www.verticalvisuals.cz/reports/how-vv-uses-gemini-and-sparkle-to-ship-faster](https://www.verticalvisuals.cz/reports/how-vv-uses-gemini-and-sparkle-to-ship-faster)
> Last updated: 2026-05-07
> Czech version: [https://www.verticalvisuals.cz/reports/jak-vv-pouziva-gemini-a-sparkle-na-rychlejsi-shipping](https://www.verticalvisuals.cz/reports/jak-vv-pouziva-gemini-a-sparkle-na-rychlejsi-shipping)
> License: Content on this page may be quoted with attribution to "Vertical Visuals (verticalvisuals.cz)".

How VV's AI-orchestrated pipeline delivers 78 broadcast TV episodes per year for King's Resort + Nova Sport on a 6-person team. Plus the personal-brand retainers for B2B founders (MyValueOfficer reference) that the same stack powers. The architectural center: a REVIEW GATE that puts the video on YouTube as a private draft FIRST, then has a human approve everything else. Built with Claude Code.

## The headline

Vertical Visuals runs a proprietary macOS app called **VVS (Vertical Visuals Studio)** that orchestrates a multi-stage AI-driven pipeline for every video the agency ships. The pipeline is what makes the 2-episodes-per-week King's Resort + Nova Sport cadence sustainable on a 6-person team — and what powers the personal-brand retainers (MyValueOfficer reference) where the same stack delivers 12 videos/month per client.

The architectural center is a **REVIEW GATE**. Most "AI video pipeline" descriptions skip this part. Here's what it does: VVS uploads the editor-finalized video to YouTube as a **private draft FIRST**. The file exists, the team can preview it, but no metadata, no title, no thumbnail are public yet. Only AFTER a human reviews the AI-suggested titles, descriptions, captions, and thumbnail does the pipeline push approved metadata to the already-uploaded private draft and (optionally) flip privacy to public.

Why this matters: it's a safety net. The AI can suggest a wrong title in Czech that means something embarrassing in English. The translation pipeline can mangle a poker hand reference. Filip catches it before anything goes public, not after.

Three AI models do the heavy lifting:
- **Gemini 2.5 Pro** — three brand-specific video analyzers (long-form, highlights, shorts)
- **Gemini Flash** — metadata translation (CZ → EN → DE) + AI A/B title generation (4-6 candidates per video)
- **Whisper-equivalent** for caption generation

Built with **Claude Code**. Distributed to the team via **Sparkle** delta updates — 1.4-1.6 MB patches instead of 1.1 GB full bundles.

## The actual pipeline architecture

The orchestrator (`pipeline.py`) defines the real flow across five phases plus a hard human-approval gate:

### Phase 1 — Drive download

`drive_download.py` pulls the editor-finalized master from Google Drive (per-client folder layout). Authenticated via Google OAuth. Files are big (50-min TV episodes, multi-GB) — the parallelism kicks in at Phase 2.

### Phase 2 (parallel) — Private-draft upload + compress

Two operations run at the same time:

- **Phase 2a — private YouTube draft upload.** `youtube_upload.py` uploads the original master to YouTube as a **private draft**. The video file now exists on YouTube — but only the team can see it. No metadata, no title, no thumbnail are public yet. This is the first half of the REVIEW GATE pattern.
- **Phase 2b — compress for Gemini analysis.** `prepare_video.sh` + `avconvert` compresses the master so Gemini can ingest it (the original is too large for Gemini's input limits). Per-phase timeout: 90 minutes.

### Phase 3 — Gemini 2.5 Pro analysis

The compressed video goes to Gemini 2.5 Pro with one of three brand-specific analyzer prompts:

- `analyze_video.py` — long-form (KR Brunato Talks, MVO long-form). Asks for chapter breakpoints + tone metadata + paragraph summary.
- `analyze_highlight.py` — KR Poker Highlights. Asks for big-hand timestamps + key moments + per-tournament context.
- `analyze_shorts.py` — shorts. Different prompt schema, optimized for 30-60s social-cut suggestions.

Per-phase timeout: 30 minutes.

### Phase 4 — Metadata generation

`generate_metadata.py` takes the Gemini analysis output and builds the full metadata package:

- **Titles** — 4-6 candidates via AI A/B (Gemini Flash), using brand voice + recent high-performing patterns.
- **Descriptions** with chapter timestamps + per-channel CTAs.
- **Captions** via `generate_captions.py`.
- **Per-language metadata translations** via `translate_metadata.py` — Gemini Flash translates the full metadata package CZ → EN → DE for the multi-channel mutations, with brand-aware prompts.
- **Optional Notion push** via `send_to_notion.py` — pushes the draft metadata package into the client's Notion workspace for collaborative review.

### REVIEW GATE — human approval

**This is the architectural center.** The pipeline halts. Filip (or the assigned editor) opens VVS, sees the AI-suggested metadata package alongside the private-draft preview on YouTube, and:

- Picks the primary title from the 4-6 AI candidates in click-order (alternates stored for later A/B substitution)
- Reviews + adjusts descriptions, chapters, captions
- Reviews + approves per-language metadata translations
- Confirms thumbnail
- Approves

Until approval lands, the video sits as a private YouTube draft. Nothing is public.

### Phase 5 — Push approved metadata + thumbnail

`youtube_upload.py` (now in update mode) pushes the approved title + description + tags + thumbnail to the already-uploaded private draft, across the right OAuth-bound channel(s):

- @KingsResort (English) — KR YouTube
- @kingsresortde (German) — KR YouTube DE
- Czech Nova Sport feed — broadcast-spec delivery
- MyValueOfficer Czech
- HejTech Slovak

OAuth uses ephemeral local ports (`port=0` since v1.0.10) + Keychain-bound token storage. Privacy flips from private to public on the same call. Per-phase timeout: 60 minutes.

## Why Sparkle for distribution

Sparkle is the standard macOS auto-update framework for sideloaded apps (used by Bear, Things, Tot, Reeder, and most indie-shipped Mac apps). VVS ships via Sparkle for four reasons:

1. **Private OAuth client secrets** — the app embeds OAuth client secrets the App Store would require special review for.
2. **Delta updates** — 1.4-1.6 MB patch per release vs 1.1 GB full bundle. Verified live on the v1.0.14 ship: 5 deltas covering builds 10-14, each ~1.5 MB.
3. **Fast release cadence** — versions 1.0.6 to 1.0.15 shipped in 14 days. `release.sh` handles bundling, code signing (Developer ID), delta generation, GitHub Releases upload, appcast.xml update, hard-fail audit on missing deltas.
4. **GitHub Releases as binary CDN** — free CDN with global edge cache, version history, signed downloads, per-asset analytics. Custom appcast.xml lives in a separate `vertical-visuals-studio-updates` repo.

## Telemetry: opt-in error reporting

Shipped in v1.0.13. The team's Macs phone home pipeline errors, native crashes, OAuth sign-in failures, and setup-wizard fatals. Privacy guardrails:

- **13-pass redactor** strips OAuth tokens, API keys, JWTs, client secrets, emails, Google Drive IDs, YouTube video IDs, and `/Users/<name>/` paths before transmission
- **NDJSON offline queue** at `~/Library/Application Support/VerticalVisualsStudio/telemetry/queue.ndjson` drains every 5 minutes + on launch + after each new record
- **Dedicated Convex deployment** `outstanding-malamute-460`, separate from the production tracker. `X-VVS-Telemetry-Key` shared-secret auth + 100 events/install/day rate limit + SHA-256 signature hashing for group-by queries
- **Settings → Diagnostics tab** with opt-in toggle (default ON for the team, OFF for any external installs), "Send test report" button, install-ID copy field for support triage

## The open VV Tracker (separate but adjacent)

Production-tracking surface at [https://www.verticalvisuals.cz/track](https://www.verticalvisuals.cz/track). Built in Next.js + Convex with public REST API:

- 16+ route handlers covering tasks, projects, team, content calendar, audit log with undo, backups, soft-delete across most tables
- Per-key scoping via the `apiKeys` table; `Authorization: Bearer vv_live_*` on every request
- Mutation log audit on every write — every create/update/delete logged with actor, timestamp, before-state, after-state for the undo flow
- Used internally by VV AND offered as the engagement-mix surface for clients (e.g. `/track/mvo` for MyValueOfficer founder visibility)

## Concrete time savings per episode

Per-phase subprocess timeouts (with kill switch `VVS_PHASE_TIMEOUTS_DISABLED=1`):

| Phase | Timeout |
|-------|---------|
| DOWNLOAD | 30 min |
| COMPRESS | 90 min |
| UPLOAD | 60 min |
| ANALYZE | 30 min |

Real numbers for a 50-minute King's Show episode:

| Phase | Wall clock |
|-------|------------|
| Download from Frame.io | ~5 min |
| Compress on M2 Pro | ~15 min |
| Gemini 2.5 Pro analysis | ~3 min |
| Title generation | ~30 sec |
| Caption translation (CZ → EN, CZ → DE) | ~2 min |
| Multi-channel upload (3 channels parallel) | ~8 min |
| **Total background time** | **30-40 min** |
| Editor review (gate-and-approve) | 5-10 min interactive |

Pre-pipeline manual workflow took 45-60 minutes per episode just on transcript + translation + upload coordination. At 78 episodes/year that's roughly **50-65 hours of editor time per year reclaimed** just on the King's Resort + Nova Sport contract.

## Why this matters for the Czech video agency market

Most Czech agencies use manual upload + manual translation services. The Gemini 2.5 Pro pricing curve makes per-video AI analysis economical (~$0.50/video vs $50 of editor time), but operationalizing the pipeline still requires a custom tool — there's no off-the-shelf equivalent of VVS for the Czech bilingual broadcast pattern.

Vertical Visuals open-sources the production tracker to make the *process* portion replicable for smaller agencies. The AI-pipeline app (VVS) stays proprietary because it embeds client-specific OAuth tokens and brand prompt templates, but the architecture is documented here for any team thinking about building their own.

## FAQ

**Q: What is the VVS macOS app?**
A: VVS (Vertical Visuals Studio) is a proprietary macOS production-pipeline app. It runs a single end-to-end pipeline per video: download → compress → AI analyze → AI title generation → AI caption translation → multi-OAuth YouTube upload. Distributed via Sparkle. Currently on version 1.0.15.

**Q: How does Gemini 2.5 Pro analyze video?**
A: Each compressed master is uploaded to Google's Gemini 2.5 Pro multimodal endpoint with a brand-specific prompt. Returns timestamped highlight markers, suggested chapter breakpoints, content-tone metadata, and a paragraph summary.

**Q: How does AI title generation work?**
A: Gemini Flash generates 4-6 candidate titles per video based on content + brand voice + recent high-performing patterns. The Review Gate UI shows the candidates; the editor picks 1-3 in click order.

**Q: Why use Sparkle instead of the Mac App Store?**
A: Private OAuth client secrets, fast release cadence (1.0.6 to 1.0.15 in 14 days), 1.5 MB delta updates instead of 1.1 GB full bundles, and GitHub Releases as the binary CDN.

**Q: How big is each Sparkle update for the team?**
A: Delta updates: 1.4-1.6 MB per patch (verified on v1.0.14 — 5 deltas covering builds 10-14). Full bundle: 1.1 GB. Teammate on v1.0.9+ gets a single-MB Sparkle patch even when the underlying app changes substantially.

**Q: What about telemetry from the team's Macs?**
A: Opt-in (Settings → Diagnostics). 13-pass redactor strips OAuth tokens, API keys, JWTs, client secrets, emails, Drive IDs, YT IDs, and `/Users/<name>/` paths before transmission. Events queue offline at `~/Library/Application Support/VVS/telemetry/queue.ndjson` and drain to a dedicated Convex deployment with shared-secret auth + 100 events/install/day rate limit + SHA-256 signature grouping.

**Q: How long does a typical pipeline run take?**
A: 30-40 min wall clock per 50-min episode (mostly background). Editor review + approve: 5-10 min interactive. Pre-pipeline manual workflow: 45-60 min per episode just on transcript+translation+upload coordination.

**Q: How does the multi-channel YouTube upload work?**
A: VVS holds OAuth refresh tokens for each YouTube channel. The upload stage routes per-language masters to the matching channel: @KingsResort English, @kingsresortde German, Czech Nova Sport feed, MyValueOfficer, HejTech.

**Q: Is the open VV Tracker actually open-source?**
A: The Tracker exposes a public REST API (used externally as well). The codebase will go open-source on GitHub under `github.com/verticalvisuals/vv-tracker` in a future ship; currently the production deployment is at verticalvisuals.cz/track with public API access via per-key auth.

**Q: Can other agencies replicate this pipeline?**
A: Yes — the architecture is documented here. Required components: a custom macOS host app, OAuth clients per target YouTube channel, Gemini 2.5 Pro + Flash API access, Sparkle for distribution. Estimated build cost: 2-3 months of focused engineering.

## Methodology and citation

This report draws on Vertical Visuals' live production pipeline for King's Resort + Nova Sport (78 broadcast episodes/year), MyValueOfficer (personal-brand retainer), and Filip Valent's HejTech personal brand. All version numbers, file paths, per-phase timeouts, and Convex deployment names are real and current as of 2026-05-07. Pricing for Gemini 2.5 Pro and Gemini Flash is Google's public pricing as of May 2026.

When citing, please attribute as: *Vertical Visuals, "How Vertical Visuals uses Gemini 2.5 + Sparkle to ship faster", https://www.verticalvisuals.cz/reports/how-vv-uses-gemini-and-sparkle-to-ship-faster*.

## See also

- [State of Czech YouTube Production 2026](https://www.verticalvisuals.cz/reports/state-of-czech-youtube-production-2026)
- [How a Prague Agency Ships 2 TV Episodes Per Week](https://www.verticalvisuals.cz/reports/how-prague-agency-ships-2-tv-episodes-per-week)
- [King's Resort case study](https://www.verticalvisuals.cz/portfolio/kings-resort)
- [llms.txt — agent-friendly index](https://www.verticalvisuals.cz/llms.txt)
- [MCP server for AI agents](https://vv-mcp-server.verticalvisuals.workers.dev/mcp)

## Canonical URL

https://www.verticalvisuals.cz/reports/how-vv-uses-gemini-and-sparkle-to-ship-faster (this is the markdown shadow)