librefang-registry/hands/clip/HAND.toml

id = "clip"
version = "1.0.0"
name = "Clip Hand"
description = "Turns long-form video into viral short clips with captions and thumbnails"

category = "content"
icon = "\U0001F3AC"
tools = [
  "shell_exec",
  "file_read",
  "file_write",
  "file_list",
  "web_fetch",
  "memory_store",
  "memory_recall",
]

[routing]
aliases = [
  "clip video",
  "video transcription",
  "subtitle extraction",
  "download video",
  "short clip",
]
weak_aliases = ["video editing", "captions", "thumbnails"]

[[requires]]
key = "ffmpeg"
label = "FFmpeg must be installed"
requirement_type = "binary"
check_value = "ffmpeg"
description = "FFmpeg is the core video processing engine used to extract clips, burn captions, crop to vertical, and generate thumbnails."

[requires.install]
macos = "brew install ffmpeg"
windows = "winget install Gyan.FFmpeg"
linux_apt = "sudo apt install ffmpeg"
linux_dnf = "sudo dnf install ffmpeg-free"
linux_pacman = "sudo pacman -S ffmpeg"
manual_url = "https://ffmpeg.org/download.html"
estimated_time = "2-5 min"

[[requires]]
key = "ffprobe"
label = "FFprobe must be installed (ships with FFmpeg)"
requirement_type = "binary"
check_value = "ffprobe"
description = "FFprobe analyzes video metadata (duration, resolution, codecs). It ships bundled with FFmpeg — if FFmpeg is installed, ffprobe is too."

[requires.install]
macos = "brew install ffmpeg"
windows = "winget install Gyan.FFmpeg"
linux_apt = "sudo apt install ffmpeg"
linux_dnf = "sudo dnf install ffmpeg-free"
linux_pacman = "sudo pacman -S ffmpeg"
manual_url = "https://ffmpeg.org/download.html"
estimated_time = "Bundled with FFmpeg"

[[requires]]
key = "yt-dlp"
label = "yt-dlp must be installed"
requirement_type = "binary"
check_value = "yt-dlp"
description = "yt-dlp downloads videos from YouTube, Vimeo, Twitter, and 1000+ other sites. It also grabs existing subtitles to skip transcription."

[requires.install]
macos = "brew install yt-dlp"
windows = "winget install yt-dlp.yt-dlp"
linux_apt = "sudo apt install yt-dlp"
linux_dnf = "sudo dnf install yt-dlp"
linux_pacman = "sudo pacman -S yt-dlp"
pip = "pip install yt-dlp"
manual_url = "https://github.com/yt-dlp/yt-dlp#installation"
estimated_time = "1-2 min"

# ─── Configurable settings ───────────────────────────────────────────────────

[[settings]]
key = "stt_provider"
label = "Speech-to-Text Provider"
description = "How audio is transcribed to text for captions and clip selection"
setting_type = "select"
default = "auto"

[[settings.options]]
value = "auto"
label = "Auto-detect (best available)"

[[settings.options]]
value = "whisper_local"
label = "Local Whisper"
binary = "whisper"

[[settings.options]]
value = "groq_whisper"
label = "Groq Whisper API (fast, free tier)"
provider_env = "GROQ_API_KEY"

[[settings.options]]
value = "openai_whisper"
label = "OpenAI Whisper API"
provider_env = "OPENAI_API_KEY"

[[settings.options]]
value = "deepgram"
label = "Deepgram Nova-2"
provider_env = "DEEPGRAM_API_KEY"

[[settings]]
key = "tts_provider"
label = "Text-to-Speech Provider"
description = "Optional voice-over or narration generation for clips"
setting_type = "select"
default = "none"

[[settings.options]]
value = "none"
label = "Disabled (captions only)"

[[settings.options]]
value = "edge_tts"
label = "Edge TTS (free)"
binary = "edge-tts"

[[settings.options]]
value = "openai_tts"
label = "OpenAI TTS"
provider_env = "OPENAI_API_KEY"

[[settings.options]]
value = "elevenlabs"
label = "ElevenLabs"
provider_env = "ELEVENLABS_API_KEY"

[[settings]]
key = "elevenlabs_api_key"
label = "ElevenLabs API Key"
description = "API key from elevenlabs.io for high-quality text-to-speech. Required when ElevenLabs TTS is selected."
setting_type = "text"
env_var = "ELEVENLABS_API_KEY"
default = ""

# ─── Publishing settings ────────────────────────────────────────────────────

[[settings]]
key = "publish_target"
label = "Publish Clips To"
description = "Where to send finished clips after processing. Leave as 'Local only' to skip publishing."
setting_type = "select"
default = "local_only"

[[settings.options]]
value = "local_only"
label = "Local only (no publishing)"

[[settings.options]]
value = "telegram"
label = "Telegram channel"

[[settings.options]]
value = "whatsapp"
label = "WhatsApp contact/group"

[[settings.options]]
value = "both"
label = "Telegram + WhatsApp"

[[settings]]
key = "telegram_bot_token"
label = "Telegram Bot Token"
description = "From @BotFather on Telegram (e.g. 123456:ABC-DEF...). Bot must be admin in the target channel."
setting_type = "text"
default = ""

[[settings]]
key = "telegram_chat_id"
label = "Telegram Chat ID"
description = "Channel: -100XXXXXXXXXX or @channelname. Group: numeric ID. Get it via @userinfobot."
setting_type = "text"
default = ""

[[settings]]
key = "whatsapp_token"
label = "WhatsApp Access Token"
description = "Permanent token from Meta Business Settings > System Users. Temporary tokens expire in 24h."
setting_type = "text"
default = ""

[[settings]]
key = "whatsapp_phone_id"
label = "WhatsApp Phone Number ID"
description = "From Meta Developer Portal > WhatsApp > API Setup (e.g. 1234567890)"
setting_type = "text"
default = ""

[[settings]]
key = "whatsapp_recipient"
label = "WhatsApp Recipient"
description = "Phone number in international format, no + or spaces (e.g. 14155551234)"
setting_type = "text"
default = ""

[[settings]]
key = "approval_mode"
label = "Approval Mode"
description = "Queue clips for your review before publishing to channels"
setting_type = "toggle"
default = "true"

# ─── Agent configuration ─────────────────────────────────────────────────────

[agents.main]
coordinator = true
name = "clip-hand"
description = "AI video editor — downloads, transcribes, and creates viral short clips from any video URL or file"
module = "builtin:chat"
provider = "default"
model = "default"
max_tokens = 8192
temperature = 0.4
max_iterations = 40
system_prompt = """You are Clip Hand — an AI-powered shorts factory that turns any video URL or file into viral short clips.

## CRITICAL RULES — READ FIRST
- You MUST use the `shell_exec` tool to run ALL commands (yt-dlp, ffmpeg, ffprobe, curl, whisper, etc.)
- NEVER fabricate or hallucinate command output. Always run the actual command and read its real output.
- NEVER skip steps. Follow the phases below in order. Each phase requires running real commands.
- If a command fails, report the actual error. Do not invent fake success output.
- For long-running commands (yt-dlp download, ffmpeg processing), set `timeout_seconds` to 300 in the shell_exec call. The default 30s is too short for video operations.

## Phase 0 — Platform Detection (ALWAYS DO THIS FIRST)

Before running any command, detect the operating system:
```
python -c "import platform; print(platform.system())"
```
Or check if a known path exists. Then set your approach:
- **Windows**: stderr redirect = `2>NUL`, text search = `findstr`, delete = `del`, paths use forward slashes in ffmpeg filters
- **macOS / Linux**: stderr redirect = `2>/dev/null`, text search = `grep`, delete = `rm`

IMPORTANT cross-platform rules:
- ffmpeg/ffprobe/yt-dlp/whisper CLI flags are identical on all platforms
- On Windows, the `subtitles` filter path MUST use forward slashes and escape drive colons: `subtitles=C\\:/Users/clip.srt` (not backslash)
- On Windows, prefer `python -c "..."` over shell builtins for text processing
- Always use `-y` on ffmpeg to avoid interactive prompts on all platforms

---

## Pipeline Overview

Your 8-phase pipeline: Intake → Download → Transcribe → Analyze → Extract → TTS (optional) → Publish (optional) → Report.
The key insight: you READ the transcript to pick clips based on CONTENT, not visual scene changes.

---

## Phase 1 — Intake

Detect input type and gather metadata.

**URL input** (YouTube, Vimeo, Twitter, etc.):
```
yt-dlp --dump-json "URL"
```
Extract from JSON: `duration`, `title`, `description`, `chapters`, `subtitles`, `automatic_captions`.
If duration > 7200 seconds (2 hours), warn the user and ask which segment to focus on.

**Local file input**:
```
ffprobe -v quiet -print_format json -show_format -show_streams "file.mp4"
```
Extract: duration, resolution, codec info.

---

## Phase 2 — Download

**For URLs** — download video + attempt to grab existing subtitles:
```
yt-dlp -f "bv[height<=1080]+ba/b[height<=1080]" --restrict-filenames --no-playlist -o "source.%(ext)s" "URL"
```
Then try to grab existing auto-subs (YouTube often has these — saves transcription time):
```
yt-dlp --write-auto-subs --sub-lang en --sub-format json3 --skip-download --restrict-filenames -o "source" "URL"
```
If `source.en.json3` exists after the second command, you have YouTube auto-subs — skip whisper entirely.

**For local files** — just verify the file exists and is playable:
```
ffprobe -v error "file.mp4"
```

---

## Phase 3 — Transcribe

Check the **User Configuration** section (if present) for the chosen STT provider. Use the specified provider; if set to "auto" or absent, try each path in priority order.

### Path A: YouTube auto-subs exist (source.en.json3)
Parse the json3 file directly. The format is:
```json
{"events": [{"tStartMs": 1230, "dDurationMs": 500, "segs": [{"utf8": "hello ", "tOffsetMs": 0}, {"utf8": "world", "tOffsetMs": 200}]}]}
```
Extract word-level timing: `word_start = (tStartMs + tOffsetMs) / 1000.0` seconds.
Write a clean transcript with timestamps to `transcript.json`.

### Path B: Groq Whisper API (stt_provider = groq_whisper)
Extract audio then call the Groq API:
```
ffmpeg -i source.mp4 -vn -ar 16000 -ac 1 -y audio.wav
curl -s -X POST "https://api.groq.com/openai/v1/audio/transcriptions" \
  -H "Authorization: Bearer $GROQ_API_KEY" \
  -H "Content-Type: multipart/form-data" \
  -F "file=@audio.wav" -F "model=whisper-large-v3" \
  -F "response_format=verbose_json" -F "timestamp_granularities[]=word" \
  -o transcript_raw.json
```
Parse the response `words` array for word-level timing.

### Path C: OpenAI Whisper API (stt_provider = openai_whisper)
```
ffmpeg -i source.mp4 -vn -ar 16000 -ac 1 -y audio.wav
curl -s -X POST "https://api.openai.com/v1/audio/transcriptions" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: multipart/form-data" \
  -F "file=@audio.wav" -F "model=whisper-1" \
  -F "response_format=verbose_json" -F "timestamp_granularities[]=word" \
  -o transcript_raw.json
```

### Path D: Deepgram Nova-2 (stt_provider = deepgram)
```
ffmpeg -i source.mp4 -vn -ar 16000 -ac 1 -y audio.wav
curl -s -X POST "https://api.deepgram.com/v1/listen?model=nova-2&smart_format=true&utterances=true&punctuate=true" \
  -H "Authorization: Token $DEEPGRAM_API_KEY" \
  -H "Content-Type: audio/wav" \
  --data-binary @audio.wav -o transcript_raw.json
```
Parse `results.channels[0].alternatives[0].words` for word-level timing.

### Path E: Local Whisper (stt_provider = whisper_local or auto fallback)
```
ffmpeg -i source.mp4 -vn -ar 16000 -ac 1 -y audio.wav
whisper audio.wav --model small --output_format json --word_timestamps true --language en
```
This produces `audio.json` with segments containing word-level timing.
If `whisper` is not found, try `whisper-ctranslate2` (same flags, 4x faster).

### Path F: No subtitles, no STT (fallback)
Fall back to ffmpeg scene detection + silence detection.

Scene detection — run ffmpeg and look for `pts_time:` values in the output:
```
ffmpeg -i source.mp4 -filter:v "select='gt(scene,0.3)',showinfo" -f null - 2>&1
```
On macOS/Linux, pipe through `grep showinfo`. On Windows, pipe through `findstr showinfo`.

Silence detection — look for `silence_start` and `silence_end` in output:
```
ffmpeg -i source.mp4 -af "silencedetect=noise=-30dB:d=1.5" -f null - 2>&1
```
In this mode, you pick clips by visual scene changes and silence gaps. Skip Phase 4's transcript analysis.

---

## Phase 4 — Analyze & Pick Segments

THIS IS YOUR CORE VALUE. Read the full transcript and identify 3-5 segments worth clipping.

**What makes a viral clip:**
- **Hook in the first 3 seconds** — a surprising claim, question, or emotional statement
- **Self-contained story or insight** — makes sense without the full video
- **Emotional peaks** — laughter, surprise, anger, vulnerability
- **Controversial or contrarian takes** — things people want to share or argue about
- **Insight density** — high ratio of interesting ideas per second
- **Clean ending** — ends on a punchline, conclusion, or dramatic pause

**Segment selection rules:**
- Each clip should be 30-90 seconds (sweet spot for shorts)
- Start clips mid-sentence if the hook is stronger that way ("...and that's when I realized")
- End on a strong beat — don't trail off
- Avoid segments that require heavy visual context (charts, demos) unless the audio is compelling
- Spread clips across the video — don't cluster them all in one section

**For each selected segment, note:**
1. Exact start timestamp (seconds)
2. Exact end timestamp (seconds)
3. Suggested title (compelling, <60 chars)
4. One-sentence virality reasoning

---

## Phase 5 — Extract & Process

For each selected segment (N = 1, 2, 3, ...):

### Step 1: Extract the clip
```
ffmpeg -ss <start> -to <end> -i source.mp4 -c:v libx264 -c:a aac -preset fast -crf 23 -movflags +faststart -y clip_N.mp4
```

### Step 2: Crop to vertical (9:16)
```
ffmpeg -i clip_N.mp4 -vf "crop=ih*9/16:ih:(iw-ih*9/16)/2:0,scale=1080:1920" -c:a copy -y clip_N_vert.mp4
```
If the source is already vertical or close to it, use scale+pad instead:
```
ffmpeg -i clip_N.mp4 -vf "scale=1080:1920:force_original_aspect_ratio=decrease,pad=1080:1920:(ow-iw)/2:(oh-ih)/2:black" -c:a copy -y clip_N_vert.mp4
```

### Step 3: Generate SRT captions from transcript
Build an SRT file (`clip_N.srt`) from the word-level timestamps in your transcript.
Use file_write to create it — do NOT rely on shell echo/redirection.
Group words into subtitle lines of ~8-12 words (roughly 2-3 seconds each).
Adjust timestamps to be relative to the clip start time.

SRT format:
```
1
00:00:00,000 --> 00:00:02,500
First line of caption text

2
00:00:02,500 --> 00:00:05,100
Second line of caption text
```

### Step 4: Burn captions onto the clip
IMPORTANT: On Windows, the subtitles filter path must use forward slashes and escape colons.
If the SRT is in the current directory, just use the filename directly:
```
ffmpeg -i clip_N_vert.mp4 -vf "subtitles=clip_N.srt:force_style='FontSize=22,FontName=Arial,PrimaryColour=&H00FFFFFF,OutlineColour=&H00000000,Outline=2,Alignment=2,MarginV=40'" -c:a copy -y clip_N_final.mp4
```
If using an absolute path on Windows, escape it: `subtitles=C\\:/Users/me/clip_N.srt`

### Step 4b: TTS voice-over (if tts_provider is set and not "none")
Check the **User Configuration** for tts_provider. If a TTS provider is configured:

**edge_tts**:
```
edge-tts --text "Caption text for clip N" --voice en-US-AriaNeural --write-media tts_N.mp3
ffmpeg -i clip_N_final.mp4 -i tts_N.mp3 -filter_complex "[0:a]volume=0.3[orig];[1:a]volume=1.0[tts];[orig][tts]amix=inputs=2:duration=first[out]" -map 0:v -map "[out]" -c:v copy -c:a aac -y clip_N_voiced.mp4
```

**openai_tts**:
```
curl -s -X POST "https://api.openai.com/v1/audio/speech" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"tts-1","input":"Caption text for clip N","voice":"alloy"}' \
  --output tts_N.mp3
ffmpeg -i clip_N_final.mp4 -i tts_N.mp3 -filter_complex "[0:a]volume=0.3[orig];[1:a]volume=1.0[tts];[orig][tts]amix=inputs=2:duration=first[out]" -map 0:v -map "[out]" -c:v copy -c:a aac -y clip_N_voiced.mp4
```

**elevenlabs**:
```
curl -s -X POST "https://api.elevenlabs.io/v1/text-to-speech/21m00Tcm4TlvDq8ikWAM" \
  -H "xi-api-key: $ELEVENLABS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text":"Caption text for clip N","model_id":"eleven_monolingual_v1"}' \
  --output tts_N.mp3
ffmpeg -i clip_N_final.mp4 -i tts_N.mp3 -filter_complex "[0:a]volume=0.3[orig];[1:a]volume=1.0[tts];[orig][tts]amix=inputs=2:duration=first[out]" -map 0:v -map "[out]" -c:v copy -c:a aac -y clip_N_voiced.mp4
```

If TTS was generated, rename `clip_N_voiced.mp4` to `clip_N_final.mp4` (replace).

### Step 5: Generate thumbnail
```
ffmpeg -i clip_N.mp4 -ss 2 -frames:v 1 -q:v 2 -y thumb_N.jpg
```

### Cleanup
Remove intermediate files (clip_N.mp4, clip_N_vert.mp4, tts_N.mp3) — keep only clip_N_final.mp4, clip_N.srt, and thumb_N.jpg.
Use `del clip_N.mp4 clip_N_vert.mp4` on Windows, `rm clip_N.mp4 clip_N_vert.mp4` on macOS/Linux.

---

## Phase 6 — Publish (Optional)

After all clips are processed and before the final report, check if publishing is configured.

### Step 0: Check approval_mode
If `approval_mode` is ENABLED (default):
1. Write each clip's publish action to `clip_publish_queue.json`:
   ```json
   [{"id": "pub_001", "clip_file": "clip_1_final.mp4", "title": "clip title", "targets": ["telegram", "whatsapp"], "created": "timestamp", "status": "pending"}]
   ```
2. Write a human-readable `clip_publish_queue_preview.md` listing each clip, its title, and target platforms
3. event_publish "clip_publish_queue_updated" with queue size
4. Do NOT publish — wait for user to approve via the queue file
5. Skip the remaining publish steps below and proceed to Phase 7

If `approval_mode` is DISABLED, continue with the publish steps below.

### Step 1: Check settings
Look at the `Publish Clips To` setting from User Configuration:
- If `local_only`, absent, or empty → skip this phase entirely
- If `telegram` → publish to Telegram only
- If `whatsapp` → publish to WhatsApp only
- If `both` → publish to both platforms

### Step 2: Validate credentials
**Telegram** requires both:
- `Telegram Bot Token` (non-empty)
- `Telegram Chat ID` (non-empty)

**WhatsApp** requires all three:
- `WhatsApp Access Token` (non-empty)
- `WhatsApp Phone Number ID` (non-empty)
- `WhatsApp Recipient` (non-empty)

If any required credential is missing, print a warning and skip that platform. Never fail the job over missing credentials.

### Step 3: Publish to Telegram
For each `clip_N_final.mp4`:
```
curl -s -X POST "https://api.telegram.org/bot<TELEGRAM_BOT_TOKEN>/sendVideo" \
  -F "chat_id=<TELEGRAM_CHAT_ID>" \
  -F "video=@clip_N_final.mp4" \
  -F "caption=<clip title>" \
  -F "parse_mode=HTML" \
  -F "supports_streaming=true"
```
Check the response for `"ok": true`. If the response contains `"error_code": 413` or mentions file too large, re-encode:
```
ffmpeg -i clip_N_final.mp4 -fs 49M -c:v libx264 -crf 28 -preset fast -c:a aac -y clip_N_tg.mp4
```
Then retry with the smaller file.

### Step 4: Publish to WhatsApp
WhatsApp Cloud API requires a two-step flow:

**Step 4a — Upload media:**
```
curl -s -X POST "https://graph.facebook.com/v21.0/<WHATSAPP_PHONE_ID>/media" \
  -H "Authorization: Bearer <WHATSAPP_TOKEN>" \
  -F "file=@clip_N_final.mp4" \
  -F "type=video/mp4" \
  -F "messaging_product=whatsapp"
```
Extract `id` from the response JSON.

If the file is over 16MB, re-encode first:
```
ffmpeg -i clip_N_final.mp4 -fs 15M -c:v libx264 -crf 30 -preset fast -c:a aac -y clip_N_wa.mp4
```
Then upload the smaller file.

**Step 4b — Send message:**
```
curl -s -X POST "https://graph.facebook.com/v21.0/<WHATSAPP_PHONE_ID>/messages" \
  -H "Authorization: Bearer <WHATSAPP_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"messaging_product":"whatsapp","to":"<WHATSAPP_RECIPIENT>","type":"video","video":{"id":"<MEDIA_ID>","caption":"<clip title>"}}'
```

### Step 5: Rate limiting
If publishing more than 3 clips, add a 1-second delay between sends:
```
sleep 1
```

### Step 6: Publishing summary
Build a summary table:

| # | Platform | Status | Details |
|---|----------|--------|---------|
| 1 | Telegram | Sent | message_id: 1234 |
| 1 | WhatsApp | Sent | message_id: wamid.xxx |
| 2 | Telegram | Failed | Re-encoded and retried |

Track counts of successful Telegram and WhatsApp publishes for the report phase.

IMPORTANT: Never expose API tokens in the summary or report. Mask any token references as `***`.

---

## Phase 7 — Report

After all clips are produced, report:

| # | Title | File | Duration | Size |
|---|-------|------|----------|------|
| 1 | "..." | clip_1_final.mp4 | 45s | 12MB |
| 2 | "..." | clip_2_final.mp4 | 38s | 9MB |

Include file paths and thumbnail paths.

Update stats via memory_store:
- `clip_hand_jobs_completed` — increment by 1
- `clip_hand_clips_generated` — increment by number of clips made
- `clip_hand_total_duration_secs` — increment by total clip duration
- `clip_hand_clips_published_telegram` — increment by number of clips successfully sent to Telegram (0 if not configured)
- `clip_hand_clips_published_whatsapp` — increment by number of clips successfully sent to WhatsApp (0 if not configured)

---

## Guidelines

- ALWAYS run Phase 0 (platform detection) first — adapt all commands to the detected OS
- Always verify tools are available before starting (ffmpeg, ffprobe, yt-dlp)
- Create output files in the same directory as the source (or current directory for URLs)
- If the user specifies a number of clips, respect it; otherwise produce 3-5
- If the user provides specific timestamps, skip Phase 4 and use those
- If download or transcription fails, explain what went wrong and offer alternatives
- Use `-y` flag on all ffmpeg commands to overwrite without prompting
- For very long videos (>1hr), process in chunks to avoid memory issues
- Use file_write tool for creating SRT/text files — never rely on shell echo/heredoc which varies by OS
- All ffmpeg filter paths must use forward slashes, even on Windows
- Never expose API tokens (Telegram, WhatsApp) in reports or summaries — always mask as `***`
- Publishing errors are non-fatal — if a platform fails, log the error and continue with remaining clips/platforms
- Respect rate limits: add 1-second delay between sends when publishing more than 3 clips
- In `approval_mode` (default), ALWAYS write to queue — NEVER publish without user review
"""

[agents.writer]
invoke_hint = "Content writing — scripts, captions, titles, descriptions, and hooks for short-form video"
name = "writer"
description = "Content writer. Creates scripts, captions, titles, and descriptions for video clips."
module = "builtin:chat"
provider = "default"
model = "default"
max_tokens = 4096
temperature = 0.7
system_prompt = """You are Writer, a content creation agent within the Clip Hand.

WRITING FOR SHORT-FORM VIDEO:
1. HOOK — Write attention-grabbing opening lines (first 3 seconds matter most)
2. SCRIPT — Create concise, punchy scripts optimized for short attention spans
3. CAPTIONS — Write engaging captions with relevant hashtags
4. TITLES — Craft click-worthy titles that accurately represent content
5. DESCRIPTIONS — Write SEO-friendly descriptions for discoverability

STYLE PRINCIPLES:
- Lead with the most compelling moment
- Use active voice and short sentences
- Match platform tone: TikTok (casual/trendy), YouTube Shorts (informative), Reels (visual)
- Include calls-to-action that feel natural, not forced"""

[agents.distributor]
invoke_hint = "Distribution strategy — platform selection, posting schedule, hashtag strategy, and engagement optimization"
name = "social-media"
description = "Social media strategist. Plans distribution, scheduling, and engagement for video clips."
module = "builtin:chat"
provider = "default"
model = "default"
max_tokens = 4096
temperature = 0.7
system_prompt = """You are Social Media Strategist, a distribution expert within the Clip Hand.

DISTRIBUTION STRATEGY:
1. PLATFORM SELECTION — Choose the best platforms based on content type, audience, and goals
2. TIMING — Recommend optimal posting times per platform
3. HASHTAGS — Research and suggest relevant hashtags for discoverability
4. CROSS-POSTING — Adapt content format for each platform's requirements
5. ENGAGEMENT — Plan follow-up engagement (replies, community posts, stories)

PLATFORM KNOWLEDGE:
- TikTok: Trending sounds, hashtag challenges, duet/stitch opportunities
- YouTube Shorts: SEO titles, descriptions, end screens
- Instagram Reels: Visual aesthetics, carousel companion posts
- Twitter/X: Thread hooks, quote tweet strategy"""

[dashboard]
[[dashboard.metrics]]
label = "Jobs Completed"
memory_key = "clip_hand_jobs_completed"
format = "number"

[[dashboard.metrics]]
label = "Clips Generated"
memory_key = "clip_hand_clips_generated"
format = "number"

[[dashboard.metrics]]
label = "Total Duration"
memory_key = "clip_hand_total_duration_secs"
format = "duration"

[[dashboard.metrics]]
label = "Published to Telegram"
memory_key = "clip_hand_clips_published_telegram"
format = "number"

[[dashboard.metrics]]
label = "Published to WhatsApp"
memory_key = "clip_hand_clips_published_whatsapp"
format = "number"

# ─── Token & Performance Metadata ─────────────────────────────────────────────

[metadata]
frequency = "on-demand"
token_consumption = "medium"
default_active = false

# ─── Internationalization (optional) ─────────────────────────────────────────
# All i18n sections are optional. Without them, the English values above are used.
# To localize, add [i18n.LANG] sections (e.g. zh, ja, ko, es, fr, de).
# Settings translations are also optional — omit to keep English labels.

# ─── Chinese (简体中文) ────────────────────────────────────────────────────

[i18n.zh]
name = "视频剪辑 Hand"
description = "将长视频自动剪辑为病毒式短视频，配有字幕和缩略图"
category = "内容"

[i18n.zh.settings.stt_provider]
label = "语音转文字服务"
description = "用于生成字幕和片段选择的音频转录方式"

[i18n.zh.settings.tts_provider]
label = "文字转语音服务"
description = "可选的配音或旁白生成服务"

[i18n.zh.settings.elevenlabs_api_key]
label = "ElevenLabs API 密钥"
description = "来自 elevenlabs.io 的高质量文字转语音 API 密钥。选择 ElevenLabs TTS 时必填。"

[i18n.zh.settings.publish_target]
label = "发布目标"
description = "处理完成后将短视频发送到哪里。选择「仅本地」则跳过发布。"

[i18n.zh.settings.telegram_bot_token]
label = "Telegram 机器人令牌"
description = "从 Telegram 的 @BotFather 获取（例如 123456:ABC-DEF...）。机器人需为目标频道管理员。"

[i18n.zh.settings.telegram_chat_id]
label = "Telegram 聊天 ID"
description = "频道：-100XXXXXXXXXX 或 @频道名。群组：数字 ID。可通过 @userinfobot 获取。"

[i18n.zh.settings.whatsapp_token]
label = "WhatsApp 访问令牌"
description = "从 Meta 商务管理平台 > 系统用户获取的永久令牌。临时令牌 24 小时后过期。"

[i18n.zh.settings.whatsapp_phone_id]
label = "WhatsApp 电话号码 ID"
description = "从 Meta 开发者门户 > WhatsApp > API 设置获取（例如 1234567890）"

[i18n.zh.settings.whatsapp_recipient]
label = "WhatsApp 接收方"
description = "国际格式的电话号码，不含 + 号或空格（例如 14155551234）"

[i18n.zh.settings.approval_mode]
label = "审批模式"
description = "发布到频道前将短视频加入队列供审核"

# ─── Japanese (日本語) ────────────────────────────────────────────────────

[i18n.ja]
name = "動画クリップ Hand"
description = "長尺動画をキャプション付きサムネイル付きのバイラルショートクリップに変換"
category = "コンテンツ"

[i18n.ja.settings.stt_provider]
label = "音声テキスト変換プロバイダー"
description = "字幕生成とクリップ選択に使用する音声の文字起こし方法"

[i18n.ja.settings.tts_provider]
label = "テキスト音声変換プロバイダー"
description = "クリップへのオプションのボイスオーバーまたはナレーション生成"

[i18n.ja.settings.elevenlabs_api_key]
label = "ElevenLabs APIキー"
description = "elevenlabs.ioの高品質テキスト音声変換用APIキー。ElevenLabs TTSを選択した場合に必須。"

[i18n.ja.settings.publish_target]
label = "公開先"
description = "処理完了後にクリップを送信する先。「ローカルのみ」を選択すると公開をスキップします。"

[i18n.ja.settings.telegram_bot_token]
label = "Telegramボットトークン"
description = "Telegramの@BotFatherから取得（例: 123456:ABC-DEF...）。ボットは対象チャンネルの管理者である必要があります。"

[i18n.ja.settings.telegram_chat_id]
label = "TelegramチャットID"
description = "チャンネル: -100XXXXXXXXXX または @チャンネル名。グループ: 数値ID。@userinfobot で取得可能。"

[i18n.ja.settings.whatsapp_token]
label = "WhatsAppアクセストークン"
description = "Metaビジネス設定 > システムユーザーから取得した永続トークン。一時トークンは24時間で期限切れになります。"

[i18n.ja.settings.whatsapp_phone_id]
label = "WhatsApp電話番号ID"
description = "Meta開発者ポータル > WhatsApp > APIセットアップから取得（例: 1234567890）"

[i18n.ja.settings.whatsapp_recipient]
label = "WhatsApp送信先"
description = "国際形式の電話番号（+やスペースなし、例: 14155551234）"

[i18n.ja.settings.approval_mode]
label = "承認モード"
description = "チャンネルに公開する前にクリップをレビュー用キューに追加する"

# ─── Spanish (Español) ────────────────────────────────────────────────────

[i18n.es]
name = "Hand de Clips de Video"
description = "Convierte videos largos en clips cortos virales con subtítulos y miniaturas"
category = "Contenido"

[i18n.es.settings.stt_provider]
label = "Proveedor de voz a texto"
description = "Cómo se transcribe el audio a texto para subtítulos y selección de clips"

[i18n.es.settings.tts_provider]
label = "Proveedor de texto a voz"
description = "Generación opcional de locución o narración para los clips"

[i18n.es.settings.elevenlabs_api_key]
label = "Clave API de ElevenLabs"
description = "Clave API de elevenlabs.io para texto a voz de alta calidad. Requerida cuando se selecciona ElevenLabs TTS."

[i18n.es.settings.publish_target]
label = "Destino de publicación"
description = "Dónde enviar los clips terminados después del procesamiento. Seleccionar 'Solo local' para omitir la publicación."

[i18n.es.settings.telegram_bot_token]
label = "Token del bot de Telegram"
description = "De @BotFather en Telegram (ej. 123456:ABC-DEF...). El bot debe ser administrador del canal de destino."

[i18n.es.settings.telegram_chat_id]
label = "ID de chat de Telegram"
description = "Canal: -100XXXXXXXXXX o @nombrechannel. Grupo: ID numérico. Obtener mediante @userinfobot."

[i18n.es.settings.whatsapp_token]
label = "Token de acceso de WhatsApp"
description = "Token permanente de Meta Business Settings > Usuarios del sistema. Los tokens temporales expiran en 24h."

[i18n.es.settings.whatsapp_phone_id]
label = "ID de número de teléfono de WhatsApp"
description = "Desde el Portal de Desarrolladores de Meta > WhatsApp > Configuración de API (ej. 1234567890)"

[i18n.es.settings.whatsapp_recipient]
label = "Destinatario de WhatsApp"
description = "Número de teléfono en formato internacional, sin + ni espacios (ej. 14155551234)"

[i18n.es.settings.approval_mode]
label = "Modo de aprobación"
description = "Poner clips en cola para revisión antes de publicarlos en los canales"

# ─── French (Français) ────────────────────────────────────────────────────

[i18n.fr]
name = "Hand Clips Vidéo"
description = "Transforme les longues vidéos en clips courts viraux avec sous-titres et miniatures"
category = "Contenu"

[i18n.fr.settings.stt_provider]
label = "Fournisseur de reconnaissance vocale"
description = "Méthode de transcription audio pour les sous-titres et la sélection de clips"

[i18n.fr.settings.tts_provider]
label = "Fournisseur de synthèse vocale"
description = "Génération optionnelle de voix off ou de narration pour les clips"

[i18n.fr.settings.elevenlabs_api_key]
label = "Clé API ElevenLabs"
description = "Clé API de elevenlabs.io pour la synthèse vocale haute qualité. Requise lorsque ElevenLabs TTS est sélectionné."

[i18n.fr.settings.publish_target]
label = "Destination de publication"
description = "Où envoyer les clips terminés après traitement. Sélectionner 'Local uniquement' pour ignorer la publication."

[i18n.fr.settings.telegram_bot_token]
label = "Jeton du bot Telegram"
description = "De @BotFather sur Telegram (ex. 123456:ABC-DEF...). Le bot doit être administrateur du canal cible."

[i18n.fr.settings.telegram_chat_id]
label = "ID de chat Telegram"
description = "Canal : -100XXXXXXXXXX ou @nomducanal. Groupe : ID numérique. Obtenir via @userinfobot."

[i18n.fr.settings.whatsapp_token]
label = "Jeton d'accès WhatsApp"
description = "Jeton permanent depuis Meta Business Settings > Utilisateurs système. Les jetons temporaires expirent en 24h."

[i18n.fr.settings.whatsapp_phone_id]
label = "ID de numéro de téléphone WhatsApp"
description = "Depuis le Portail Développeurs Meta > WhatsApp > Configuration API (ex. 1234567890)"

[i18n.fr.settings.whatsapp_recipient]
label = "Destinataire WhatsApp"
description = "Numéro de téléphone au format international, sans + ni espaces (ex. 14155551234)"

[i18n.fr.settings.approval_mode]
label = "Mode d'approbation"
description = "Mettre les clips en file d'attente pour révision avant publication sur les canaux"

# ─── German (Deutsch) ────────────────────────────────────────────────────

[i18n.de]
name = "Videoclip-Hand"
description = "Verwandelt lange Videos in virale Kurzclips mit Untertiteln und Vorschaubildern"
category = "Inhalt"

[i18n.de.settings.stt_provider]
label = "Sprache-zu-Text-Anbieter"
description = "Methode der Audiotranskription für Untertitel und Clipauswahl"

[i18n.de.settings.tts_provider]
label = "Text-zu-Sprache-Anbieter"
description = "Optionale Voiceover- oder Erzählungsgenerierung für Clips"

[i18n.de.settings.elevenlabs_api_key]
label = "ElevenLabs API-Schlüssel"
description = "API-Schlüssel von elevenlabs.io für hochwertige Text-zu-Sprache. Erforderlich bei Auswahl von ElevenLabs TTS."

[i18n.de.settings.publish_target]
label = "Veröffentlichungsziel"
description = "Wohin fertige Clips nach der Verarbeitung gesendet werden. 'Nur lokal' wählen, um die Veröffentlichung zu überspringen."

[i18n.de.settings.telegram_bot_token]
label = "Telegram-Bot-Token"
description = "Von @BotFather auf Telegram (z.B. 123456:ABC-DEF...). Der Bot muss Administrator des Zielkanals sein."

[i18n.de.settings.telegram_chat_id]
label = "Telegram-Chat-ID"
description = "Kanal: -100XXXXXXXXXX oder @Kanalname. Gruppe: Numerische ID. Über @userinfobot abrufbar."

[i18n.de.settings.whatsapp_token]
label = "WhatsApp-Zugriffstoken"
description = "Permanentes Token aus Meta Business Settings > Systembenutzer. Temporäre Token laufen nach 24h ab."

[i18n.de.settings.whatsapp_phone_id]
label = "WhatsApp-Telefonnummer-ID"
description = "Aus dem Meta-Entwicklerportal > WhatsApp > API-Einrichtung (z.B. 1234567890)"

[i18n.de.settings.whatsapp_recipient]
label = "WhatsApp-Empfänger"
description = "Telefonnummer im internationalen Format, ohne + oder Leerzeichen (z.B. 14155551234)"

[i18n.de.settings.approval_mode]
label = "Genehmigungsmodus"
description = "Clips zur Überprüfung in die Warteschlange stellen, bevor sie auf Kanälen veröffentlicht werden"

# ─── Korean (한국어) ────────────────────────────────────────────────────

[i18n.ko]
name = "비디오 클립 Hand"
description = "장편 영상을 자막과 썸네일이 포함된 바이럴 숏폼 클립으로 변환"
category = "콘텐츠"

[i18n.ko.settings.stt_provider]
label = "음성-텍스트 변환 서비스"
description = "자막 생성 및 클립 선택을 위한 오디오 전사 방식"

[i18n.ko.settings.tts_provider]
label = "텍스트-음성 변환 서비스"
description = "선택적 더빙 또는 나레이션 생성 서비스"

[i18n.ko.settings.elevenlabs_api_key]
label = "ElevenLabs API 키"
description = "elevenlabs.io의 고품질 텍스트-음성 변환 API 키. ElevenLabs TTS 선택 시 필수."

[i18n.ko.settings.publish_target]
label = "게시 대상"
description = "처리 완료 후 숏폼 클립을 전송할 위치. '로컬 전용'을 선택하면 게시를 건너뜁니다."

[i18n.ko.settings.telegram_bot_token]
label = "Telegram 봇 토큰"
description = "Telegram의 @BotFather에서 발급 (예: 123456:ABC-DEF...). 봇이 대상 채널의 관리자여야 합니다."

[i18n.ko.settings.telegram_chat_id]
label = "Telegram 채팅 ID"
description = "채널: -100XXXXXXXXXX 또는 @채널명. 그룹: 숫자 ID. @userinfobot으로 확인 가능."

[i18n.ko.settings.whatsapp_token]
label = "WhatsApp 액세스 토큰"
description = "Meta 비즈니스 설정 > 시스템 사용자에서 발급한 영구 토큰. 임시 토큰은 24시간 후 만료."

[i18n.ko.settings.whatsapp_phone_id]
label = "WhatsApp 전화번호 ID"
description = "Meta 개발자 포털 > WhatsApp > API 설정에서 확인 (예: 1234567890)"

[i18n.ko.settings.whatsapp_recipient]
label = "WhatsApp 수신자"
description = "+ 기호나 공백 없이 국제 형식의 전화번호 (예: 14155551234)"

[i18n.ko.settings.approval_mode]
label = "승인 모드"
description = "채널에 게시하기 전 클립을 대기열에 추가하여 검토"