web2labs-studio

Edit my recording, turn a long video into shorts, generate captions and thumbnails, estimate cost before processing. Upload local files or YouTube/Twitch URLs and get back edited jump-cut videos, vertical shorts, subtitles, and thumbnail variants.

# Web2Labs Studio

AI-powered video editor for creators. Process recordings into jump-cut videos,
automatic subtitles, and shorts.

## Available Tools

- `studio_setup`: Send magic link, complete setup, or save an existing API key.
- `studio_upload`: Upload local file or supported URL for processing.
  - supports optional `webhook_url` + `webhook_secret` for `project.completed` callbacks.
- `studio_status`: Check current project status.
- `studio_poll`: Wait for completion with real-time WebSocket progress (falls back to HTTP polling).
- `studio_results`: Get output URLs and metadata.
- `studio_download`: Download outputs to local filesystem.
- `studio_credits`: Check API/subscription balances.
- `studio_pricing`: Get current pricing metadata for API and Creator Credit features.
- `studio_estimate`: Estimate API and Creator Credit cost before upload.
- `studio_thumbnails`: Generate A/B/C thumbnail variants for a completed project.
- `studio_rerender`: Re-render a completed project with configuration overrides. First re-render per project is free; subsequent re-renders cost 15 Creator Credits.
- `studio_analytics`: Get usage and value analytics.
- `studio_brand`: Get or update brand kit settings (colors, identity, fonts, defaults).
- `studio_brand_import`: Import brand colors and identity from a YouTube/Twitch profile URL.
- `studio_assets`: Upload/list/delete reusable intro/outro/watermark assets.
- `studio_projects`: List recent projects.
- `studio_delete`: Delete a project.
- `studio_feedback`: Report bugs/suggestions/questions.
- `studio_referral`: Get or apply referral codes for bonus credits.
- `studio_watch`: Watch a YouTube or Twitch channel for new videos and auto-process them.

## Presets

- `quick`: Fast cleanup, no extras.
- `youtube`: Subtitles + shorts + music.
- `shorts-only`: Generate only vertical shorts.
- `podcast`: Soft cuts, subtitles, no zoom.
- `gaming`: Dynamic zoom and gaming-style pacing.
- `tutorial`: Gentle edits for educational content.
- `vlog`: Balanced vlog workflow.
- `cinematic`: High-production settings.

## Standard Workflow

1. If auth is missing, run `studio_setup`.
2. Run `studio_credits` first.
3. If the workflow may use premium features, run `studio_estimate`.
4. Run `studio_upload` with a preset.
5. If no webhook is configured, run `studio_poll` for progress until completion.
6. Run `studio_results` and optionally `studio_thumbnails`.
7. Use `studio_rerender` if the user wants output changes without re-uploading.
8. Run `studio_download` to save outputs.
9. Use `studio_brand` when the user asks for brand color/font consistency across future outputs.
10. Use `studio_brand_import` when the user provides a YouTube/Twitch profile URL for one-click brand setup.
11. Use `studio_assets` when the user wants reusable intro/outro/watermark media.

## Cost-Aware Workflow

- Use `studio_pricing` when the user asks "how much will this cost?" or wants bundle guidance.
- Use `studio_estimate` before upload when configuration enables thumbnails/B-roll/audio polish.
- Use `studio_rerender` for post-processing adjustments when analysis is already complete.
- If estimate is non-trivial, confirm expected cost with the user before upload.
- If the user asks for urgent/rush processing, set `priority: "rush"` and confirm the 2x API-credit cost before upload.
- Paid tools support `confirm_spend: true` for explicit approval when required by spend policy.

## Spend Policy

Spend policy is controlled by env var `WEB2LABS_SPEND_POLICY`:
- `auto` (default): proceed without prompt unless auto-spend caps are exceeded. Best for most users who want a frictionless workflow.
- `smart`: confirm higher-risk or higher-cost spends (rush uploads, low balance, large creator credit spend).
- `explicit`: confirm every credit-spending action. Use for strict budget control.

Auto mode caps (all tunable via env vars):
- `WEB2LABS_AUTO_SPEND_MAX_API_PER_ACTION` (default: 2)
- `WEB2LABS_AUTO_SPEND_MAX_CREATOR_PER_ACTION` (default: 40)
- `WEB2LABS_AUTO_SPEND_MAX_API_PER_MONTH` (default: 80)
- `WEB2LABS_AUTO_SPEND_MAX_CREATOR_PER_MONTH` (default: 400)

When a tool returns `spend_confirmation_required`, ask the user and re-run with `confirm_spend: true`.

## URL Input

If `file_path` is a URL, use local yt-dlp download first.
If yt-dlp is missing, provide install help:
- macOS: `brew install yt-dlp`
- Linux: `pip install yt-dlp`
- Windows: `winget install yt-dlp`

Only process content the user has rights to edit.

## Webhooks

- `studio_upload` accepts `webhook_url` and optional `webhook_secret`.
- If provided, Studio sends `project.completed` to the callback URL when rendering finishes.
- Signed callbacks include:
  - `X-Web2Labs-Webhook-Timestamp`
  - `X-Web2Labs-Webhook-Signature` (`sha256=<hmac(timestamp + "." + payload)>`)
- With webhook enabled, polling is optional and can be skipped for fire-and-forget automation.

## Batch Workflow

Before batch processing, confirm total credit cost:
"This will process N videos and consume N credits. Proceed?"

## Guardrails

1. Always call `studio_credits` before upload.
2. Never expose API keys in logs or messages.
3. Respect spend policy and confirmation requirements before spending credits.
4. Remind users about retention after download.
5. Suggest presets when users do not provide settings.
6. For URLs, verify yt-dlp availability before proceeding.
7. Respect user rights and content ownership.
8. For `priority: "rush"`, explicitly confirm "2 API credits instead of 1" before proceeding.
9. For watch mode, only monitor channels the user owns or has permission to process.

## Upsell Moments

- After successful processing: suggest thumbnails if missing.
- When API credits are low (`<=2`): use `studio_pricing` and provide purchase links.
- When subscription monthly usage is above 80%: suggest API credit bundles.
- After first project: suggest thumbnails, cinematic preset, and brand consistency features.
- After first project: mention referral program — "Share your referral link to earn 5 free credits per signup!"

## Brand Kit Workflow

- If user asks to set brand colors, fonts, or identity, call `studio_brand` with `action: "update"`.
- Use snake_case fields for convenience (`primary_color`, `secondary_color`, `channel_name`) or `updates` object.
- Confirm that changes apply to future thumbnail/subtitle outputs.
- If user shares a YouTube/Twitch profile URL, offer `studio_brand_import` first, then review/apply suggestions.

## Assets Workflow

- Use `studio_assets` with:
  - `action: "list"` to inspect available intro/outro/watermark assets.
  - `action: "upload"` + `asset_type` + `file_path` to add reusable media.
  - `action: "delete"` + `asset_type` to remove old assets.
- If user says "use this intro/outro on future videos", upload via `studio_assets` first, then ensure brand defaults are configured with `studio_brand`.

## Watch Mode

Watch mode monitors YouTube or Twitch channels for new videos and auto-processes them through Studio.

### Setting up a watcher

1. Run `studio_watch` with `action: "add"` and the channel `url` (e.g. `https://youtube.com/@username`).
2. Optionally set `preset`, `max_duration_minutes`, `max_daily_uploads`, and `poll_interval_minutes`.
3. The watcher is saved and ready. Run `studio_watch` with `action: "check"` to poll for new videos.

Only channel/user URLs are accepted, not individual video URLs.

### How check works

`action: "check"` does a single poll cycle:
- Lists recent videos from each enabled watcher's channel via yt-dlp.
- Filters out already-processed videos (tracked by video ID).
- Filters out videos exceeding `max_duration_minutes`.
- Respects the `max_daily_uploads` cap per watcher.
- Downloads and uploads each new video to Studio with the watcher's preset.
- Returns a summary of what was processed.

Pass `id` to check a specific watcher, or omit to check all enabled watchers.

### Managing watchers

- `action: "list"` — show all watchers and their status.
- `action: