@colin4k1024/tsp 2.4.0

package/skills/videodb/reference/use-cases.md

@@ -0,0 +1,118 @@
+# Use Cases
+
+Common workflows and what VideoDB enables. For code details, see [api-reference.md](api-reference.md), [capture.md](capture.md), [editor.md](editor.md), and [search.md](search.md).
+
+---
+
+## Video Search & Highlights
+
+### Create Highlight Reels
+Upload a long video (conference talk, lecture, meeting recording), search for key moments by topic ("product announcement", "Q&A session", "demo"), and automatically compile matching segments into a shareable highlight reel.
+
+### Build Searchable Video Libraries
+Batch upload videos to a collection, index them for spoken word search, then query across the entire library. Find specific topics across hundreds of hours of content instantly.
+
+### Extract Specific Clips
+Search for moments matching a query ("budget discussion", "action items") and extract each matching segment as an individual clip with its own stream URL.
+
+---
+
+## Video Enhancement
+
+### Add Professional Polish
+Take raw footage and enhance it with:
+- Auto-generated subtitles from speech
+- Custom thumbnails at specific timestamps
+- Background music overlays
+- Intro/outro sequences with generated images
+
+### AI-Enhanced Content
+Combine existing video with generative AI:
+- Generate text summaries from transcript
+- Create background music matching video duration
+- Generate title cards and overlay images
+- Mix all elements into a polished final output
+
+---
+
+## Real-Time Capture (Desktop/Meeting)
+
+### Screen + Audio Recording with AI
+Capture screen, microphone, and system audio simultaneously. Get real-time:
+- **Live transcription** - Speech to text as it happens
+- **Audio summaries** - Periodic AI-generated summaries of discussions
+- **Visual indexing** - AI descriptions of screen activity
+
+### Meeting Capture with Summarization
+Record meetings with live transcription of all participants. Get periodic summaries with key discussion points, decisions, and action items delivered in real-time.
+
+### Screen Activity Tracking
+Track what's happening on screen with AI-generated descriptions:
+- "User is browsing a spreadsheet in Google Sheets"
+- "User switched to a code editor with a Python file"
+- "Video call with screen sharing enabled"
+
+### Post-Session Processing
+After capture ends, the recording is exported as a permanent video. Then:
+- Generate searchable transcript
+- Search for specific topics within the recording
+- Extract clips of important moments
+- Share via stream URL or player link
+
+---
+
+## Live Stream Intelligence (RTSP/RTMP)
+
+### Connect External Streams
+Ingest live video from RTSP/RTMP sources (security cameras, encoders, broadcasts). Process and index content in real-time.
+
+### Real-Time Event Detection
+Define events to detect in live streams:
+- "Person entering restricted area"
+- "Traffic violation at intersection"
+- "Product visible on shelf"
+
+Get alerts via WebSocket or webhook when events occur.
+
+### Live Stream Search
+Search across recorded live stream content. Find specific moments and generate clips from hours of continuous footage.
+
+---
+
+## Content Moderation & Safety
+
+### Automated Content Review
+Index video scenes with AI and search for problematic content. Flag videos containing violence, inappropriate content, or policy violations.
+
+### Profanity Detection
+Detect and locate profanity in audio. Optionally overlay beep sounds at detected timestamps.
+
+---
+
+## Platform Integration
+
+### Social Media Formatting
+Reframe videos for different platforms:
+- Vertical (9:16) for TikTok, Reels, Shorts
+- Square (1:1) for Instagram feed
+- Landscape (16:9) for YouTube
+
+### Transcode for Delivery
+Change resolution, bitrate, or quality for different delivery targets. Output optimized streams for web, mobile, or broadcast.
+
+### Generate Shareable Links
+Every operation produces playable stream URLs. Embed in web players, share directly, or integrate with existing platforms.
+
+---
+
+## Workflow Summary
+
+| Goal | VideoDB Approach |
+|------|------------------|
+| Find moments in video | Index spoken words/scenes → Search → Compile clips |
+| Create highlights | Search multiple topics → Build timeline → Generate stream |
+| Add subtitles | Index spoken words → Add subtitle overlay |
+| Record screen + AI | Start capture → Run AI pipelines → Export video |
+| Monitor live streams | Connect RTSP → Index scenes → Create alerts |
+| Reformat for social | Reframe to target aspect ratio |
+| Combine clips | Build timeline with multiple assets → Generate stream |

package/skills/videodb/scripts/ws_listener.py

@@ -0,0 +1,282 @@
+#!/usr/bin/env python3
+"""
+WebSocket event listener for VideoDB with auto-reconnect and graceful shutdown.
+
+Usage:
+  python scripts/ws_listener.py [OPTIONS] [output_dir]
+
+Arguments:
+  output_dir  Directory for output files (default: XDG_STATE_HOME/videodb or ~/.local/state/videodb)
+
+Options:
+  --clear     Clear the events file before starting (use when starting a new session)
+
+Output files:
+  <output_dir>/videodb_events.jsonl  - All WebSocket events (JSONL format)
+  <output_dir>/videodb_ws_id         - WebSocket connection ID
+  <output_dir>/videodb_ws_pid        - Process ID for easy termination
+
+Output (first line, for parsing):
+  WS_ID=<connection_id>
+
+Examples:
+  python scripts/ws_listener.py &                                 # Run in background
+  python scripts/ws_listener.py --clear                           # Clear events and start fresh
+  python scripts/ws_listener.py --clear /tmp/mydir                # Custom dir with clear
+  kill "$(cat ~/.local/state/videodb/videodb_ws_pid)"             # Stop the listener
+"""
+import os
+import sys
+import json
+import signal
+import asyncio
+import logging
+import contextlib
+from datetime import datetime, timezone
+from pathlib import Path
+
+from dotenv import load_dotenv
+load_dotenv()
+
+import videodb
+from videodb.exceptions import AuthenticationError
+
+# Retry config
+MAX_RETRIES = 10
+INITIAL_BACKOFF = 1  # seconds
+MAX_BACKOFF = 60     # seconds
+
+logging.basicConfig(
+    level=logging.INFO,
+    format="[%(asctime)s] %(message)s",
+    datefmt="%H:%M:%S",
+)
+LOGGER = logging.getLogger(__name__)
+
+# Parse arguments
+RETRYABLE_ERRORS = (ConnectionError, TimeoutError)
+
+
+def default_output_dir() -> Path:
+    """Return a private per-user state directory for listener artifacts."""
+    xdg_state_home = os.environ.get("XDG_STATE_HOME")
+    if xdg_state_home:
+        return Path(xdg_state_home) / "videodb"
+    return Path.home() / ".local" / "state" / "videodb"
+
+
+def ensure_private_dir(path: Path) -> Path:
+    """Create the listener state directory with private permissions."""
+    path.mkdir(parents=True, exist_ok=True, mode=0o700)
+    try:
+        path.chmod(0o700)
+    except OSError:
+        pass
+    return path
+
+
+def parse_args() -> tuple[bool, Path]:
+    clear = False
+    output_dir: str | None = None
+    
+    args = sys.argv[1:]
+    for arg in args:
+        if arg == "--clear":
+            clear = True
+        elif arg.startswith("-"):
+            raise SystemExit(f"Unknown flag: {arg}")
+        elif not arg.startswith("-"):
+            output_dir = arg
+    
+    if output_dir is None:
+        events_dir = os.environ.get("VIDEODB_EVENTS_DIR")
+        if events_dir:
+            return clear, ensure_private_dir(Path(events_dir))
+        return clear, ensure_private_dir(default_output_dir())
+
+    return clear, ensure_private_dir(Path(output_dir))
+
+CLEAR_EVENTS, OUTPUT_DIR = parse_args()
+EVENTS_FILE = OUTPUT_DIR / "videodb_events.jsonl"
+WS_ID_FILE = OUTPUT_DIR / "videodb_ws_id"
+PID_FILE = OUTPUT_DIR / "videodb_ws_pid"
+
+# Track if this is the first connection (for clearing events)
+_first_connection = True
+
+
+def log(msg: str):
+    """Log with timestamp."""
+    LOGGER.info("%s", msg)
+
+
+def append_event(event: dict):
+    """Append event to JSONL file with timestamps."""
+    now = datetime.now(timezone.utc)
+    event["ts"] = now.isoformat()
+    event["unix_ts"] = now.timestamp()
+    with EVENTS_FILE.open("a", encoding="utf-8") as f:
+        f.write(json.dumps(event) + "\n")
+
+
+def write_pid():
+    """Write PID file for easy process management."""
+    OUTPUT_DIR.mkdir(parents=True, exist_ok=True, mode=0o700)
+    PID_FILE.write_text(str(os.getpid()))
+
+
+def cleanup_pid():
+    """Remove PID file on exit."""
+    try:
+        PID_FILE.unlink(missing_ok=True)
+    except OSError as exc:
+        LOGGER.debug("Failed to remove PID file %s: %s", PID_FILE, exc)
+
+
+def is_fatal_error(exc: Exception) -> bool:
+    """Return True when retrying would hide a permanent configuration error."""
+    if isinstance(exc, (AuthenticationError, PermissionError)):
+        return True
+    status = getattr(exc, "status_code", None)
+    if status in {401, 403}:
+        return True
+    message = str(exc).lower()
+    return "401" in message or "403" in message or "auth" in message
+
+
+async def listen_with_retry():
+    """Main listen loop with auto-reconnect and exponential backoff."""
+    global _first_connection
+    
+    retry_count = 0
+    backoff = INITIAL_BACKOFF
+    
+    while retry_count < MAX_RETRIES:
+        try:
+            conn = videodb.connect()
+            ws_wrapper = conn.connect_websocket()
+            ws = await ws_wrapper.connect()
+            ws_id = ws.connection_id
+        except asyncio.CancelledError:
+            log("Shutdown requested")
+            raise
+        except Exception as e:
+            if is_fatal_error(e):
+                log(f"Fatal configuration error: {e}")
+                raise
+            if not isinstance(e, RETRYABLE_ERRORS):
+                raise
+            retry_count += 1
+            log(f"Connection error: {e}")
+            
+            if retry_count >= MAX_RETRIES:
+                log(f"Max retries ({MAX_RETRIES}) exceeded, exiting")
+                break
+            
+            log(f"Reconnecting in {backoff}s (attempt {retry_count}/{MAX_RETRIES})...")
+            await asyncio.sleep(backoff)
+            backoff = min(backoff * 2, MAX_BACKOFF)
+            continue
+
+        OUTPUT_DIR.mkdir(parents=True, exist_ok=True, mode=0o700)
+
+        if _first_connection and CLEAR_EVENTS:
+            EVENTS_FILE.unlink(missing_ok=True)
+            log("Cleared events file")
+        _first_connection = False
+
+        WS_ID_FILE.write_text(ws_id)
+
+        if retry_count == 0:
+            print(f"WS_ID={ws_id}", flush=True)
+        log(f"Connected (ws_id={ws_id})")
+
+        retry_count = 0
+        backoff = INITIAL_BACKOFF
+
+        receiver = ws.receive().__aiter__()
+        while True:
+            try:
+                msg = await anext(receiver)
+            except StopAsyncIteration:
+                log("Connection closed by server")
+                break
+            except asyncio.CancelledError:
+                log("Shutdown requested")
+                raise
+            except Exception as e:
+                if is_fatal_error(e):
+                    log(f"Fatal configuration error: {e}")
+                    raise
+                if not isinstance(e, RETRYABLE_ERRORS):
+                    raise
+                retry_count += 1
+                log(f"Connection error: {e}")
+
+                if retry_count >= MAX_RETRIES:
+                    log(f"Max retries ({MAX_RETRIES}) exceeded, exiting")
+                    return
+
+                log(f"Reconnecting in {backoff}s (attempt {retry_count}/{MAX_RETRIES})...")
+                await asyncio.sleep(backoff)
+                backoff = min(backoff * 2, MAX_BACKOFF)
+                break
+
+            append_event(msg)
+            channel = msg.get("channel", msg.get("event", "unknown"))
+            text = msg.get("data", {}).get("text", "")
+            if text:
+                print(f"[{channel}] {text[:80]}", flush=True)
+
+
+async def main_async():
+    """Async main with signal handling."""
+    loop = asyncio.get_running_loop()
+    shutdown_event = asyncio.Event()
+    
+    def handle_signal():
+        log("Received shutdown signal")
+        shutdown_event.set()
+    
+    # Register signal handlers
+    for sig in (signal.SIGINT, signal.SIGTERM):
+        with contextlib.suppress(NotImplementedError):
+            loop.add_signal_handler(sig, handle_signal)
+    
+    # Run listener with cancellation support
+    listen_task = asyncio.create_task(listen_with_retry())
+    shutdown_task = asyncio.create_task(shutdown_event.wait())
+    
+    _done, pending = await asyncio.wait(
+        [listen_task, shutdown_task],
+        return_when=asyncio.FIRST_COMPLETED,
+    )
+
+    if listen_task.done():
+        await listen_task
+    
+    # Cancel remaining tasks
+    for task in pending:
+        task.cancel()
+        try:
+            await task
+        except asyncio.CancelledError:
+            pass
+
+    for sig in (signal.SIGINT, signal.SIGTERM):
+        with contextlib.suppress(NotImplementedError):
+            loop.remove_signal_handler(sig)
+    
+    log("Shutdown complete")
+
+
+def main():
+    write_pid()
+    try:
+        asyncio.run(main_async())
+    finally:
+        cleanup_pid()
+
+
+if __name__ == "__main__":
+    main()

package/skills/visa-doc-translate/README.md

@@ -0,0 +1,86 @@
+# Visa Document Translator
+
+Automatically translate visa application documents from images to professional English PDFs.
+
+## Features
+
+- **Automatic OCR**: Tries multiple OCR methods (macOS Vision, EasyOCR, Tesseract)
+- **Bilingual PDF**: Original image + professional English translation
+- **Multi-language**: Supports Chinese, and other languages
+- **Professional Format**: Suitable for official visa applications
+- **Fully Automated**: No manual intervention required
+
+## Supported Documents
+
+- Bank deposit certificates (存款证明)
+- Employment certificates (在职证明)
+- Retirement certificates (退休证明)
+- Income certificates (收入证明)
+- Property certificates (房产证明)
+- Business licenses (营业执照)
+- ID cards and passports
+
+## Usage
+
+```bash
+/visa-doc-translate <image-file>
+```
+
+### Examples
+
+```bash
+/visa-doc-translate RetirementCertificate.PNG
+/visa-doc-translate BankStatement.HEIC
+/visa-doc-translate EmploymentLetter.jpg
+```
+
+## Output
+
+Creates `<filename>_Translated.pdf` with:
+- **Page 1**: Original document image (centered, A4 size)
+- **Page 2**: Professional English translation
+
+## Requirements
+
+### Python Libraries
+```bash
+pip install pillow reportlab
+```
+
+### OCR (one of the following)
+
+**macOS (recommended)**:
+```bash
+pip install pyobjc-framework-Vision pyobjc-framework-Quartz
+```
+
+**Cross-platform**:
+```bash
+pip install easyocr
+```
+
+**Tesseract**:
+```bash
+brew install tesseract tesseract-lang
+pip install pytesseract
+```
+
+## How It Works
+
+1. Converts HEIC to PNG if needed
+2. Checks and applies EXIF rotation
+3. Extracts text using available OCR method
+4. Translates to professional English
+5. Generates bilingual PDF
+
+## Perfect For
+
+- Australia visa applications
+- USA visa applications
+- Canada visa applications
+- UK visa applications
+- EU visa applications
+
+## License
+
+MIT

package/skills/visa-doc-translate/SKILL.md

@@ -0,0 +1,117 @@
+---
+name: visa-doc-translate
+description: Translate visa application documents (images) to English and create a bilingual PDF with original and translation
+---
+
+You are helping translate visa application documents for visa applications.
+
+## Instructions
+
+When the user provides an image file path, AUTOMATICALLY execute the following steps WITHOUT asking for confirmation:
+
+1. **Image Conversion**: If the file is HEIC, convert it to PNG using `sips -s format png <input> --out <output>`
+
+2. **Image Rotation**:
+   - Check EXIF orientation data
+   - Automatically rotate the image based on EXIF data
+   - If EXIF orientation is 6, rotate 90 degrees counterclockwise
+   - Apply additional rotation as needed (test 180 degrees if document appears upside down)
+
+3. **OCR Text Extraction**:
+   - Try multiple OCR methods automatically:
+     - macOS Vision framework (preferred for macOS)
+     - EasyOCR (cross-platform, no tesseract required)
+     - Tesseract OCR (if available)
+   - Extract all text information from the document
+   - Identify document type (deposit certificate, employment certificate, retirement certificate, etc.)
+
+4. **Translation**:
+   - Translate all text content to English professionally
+   - Maintain the original document structure and format
+   - Use professional terminology appropriate for visa applications
+   - Keep proper names in original language with English in parentheses
+   - For Chinese names, use pinyin format (e.g., WU Zhengye)
+   - Preserve all numbers, dates, and amounts accurately
+
+5. **PDF Generation**:
+   - Create a Python script using PIL and reportlab libraries
+   - Page 1: Display the rotated original image, centered and scaled to fit A4 page
+   - Page 2: Display the English translation with proper formatting:
+     - Title centered and bold
+     - Content left-aligned with appropriate spacing
+     - Professional layout suitable for official documents
+   - Add a note at the bottom: "This is a certified English translation of the original document"
+   - Execute the script to generate the PDF
+
+6. **Output**: Create a PDF file named `<original_filename>_Translated.pdf` in the same directory
+
+## Supported Documents
+
+- Bank deposit certificates (存款证明)
+- Income certificates (收入证明)
+- Employment certificates (在职证明)
+- Retirement certificates (退休证明)
+- Property certificates (房产证明)
+- Business licenses (营业执照)
+- ID cards and passports
+- Other official documents
+
+## Technical Implementation
+
+### OCR Methods (tried in order)
+
+1. **macOS Vision Framework** (macOS only):
+   ```python
+   import Vision
+   from Foundation import NSURL
+   ```
+
+2. **EasyOCR** (cross-platform):
+   ```bash
+   pip install easyocr
+   ```
+
+3. **Tesseract OCR** (if available):
+   ```bash
+   brew install tesseract tesseract-lang
+   pip install pytesseract
+   ```
+
+### Required Python Libraries
+
+```bash
+pip install pillow reportlab
+```
+
+For macOS Vision framework:
+```bash
+pip install pyobjc-framework-Vision pyobjc-framework-Quartz
+```
+
+## Important Guidelines
+
+- DO NOT ask for user confirmation at each step
+- Automatically determine the best rotation angle
+- Try multiple OCR methods if one fails
+- Ensure all numbers, dates, and amounts are accurately translated
+- Use clean, professional formatting
+- Complete the entire process and report the final PDF location
+
+## Example Usage
+
+```bash
+/visa-doc-translate RetirementCertificate.PNG
+/visa-doc-translate BankStatement.HEIC
+/visa-doc-translate EmploymentLetter.jpg
+```
+
+## Output Example
+
+The skill will:
+1. Extract text using available OCR method
+2. Translate to professional English
+3. Generate `<filename>_Translated.pdf` with:
+   - Page 1: Original document image
+   - Page 2: Professional English translation
+
+Perfect for visa applications to Australia, USA, Canada, UK, and other countries requiring translated documents.

package/skills/wave-execution/SKILL.md

@@ -0,0 +1,106 @@
+---
+name: wave-execution
+description: >
+  基于依赖关系的波次并行执行策略，融合 GSD wave-execution 模式。
+  将任务按依赖图分组为有序波次，同一波次内的任务可安全并行，
+  增强现有 parallel-execution 技能的任务编排能力。
+---
+
+# Wave Execution
+
+## 用途
+
+- 把"按列表顺序逐个执行"改成"按依赖图分波次并行执行"。
+- 适合 `/team-plan` 拆解出多个独立任务、且部分任务间存在依赖关系的场景。
+- 与 `parallel-execution`（Git worktree 并行）互补：wave-execution 负责"什么可以并行"，parallel-execution 负责"如何物理并行"。
+
+## 核心概念
+
+### 波次（Wave）
+
+将所有任务按依赖关系分组：
+- **Wave 0**：没有前置依赖的任务，可以最先执行
+- **Wave 1**：仅依赖 Wave 0 产出的任务
+- **Wave N**：仅依赖 Wave 0 ~ N-1 产出的任务
+
+同一波次内的任务之间**没有依赖关系**，可以安全并行执行。
+
+### 依赖图构建规则
+
+1. **显式依赖**：任务 A 的输入来自任务 B 的输出（接口契约、数据模型、共享模块）。
+2. **文件依赖**：任务 A 和任务 B 修改同一文件或同一模块。
+3. **测试依赖**：任务 A 的测试需要任务 B 的 mock 或 fixture。
+4. **部署依赖**：任务 A 的部署要求任务 B 先上线。
+
+## 默认做法
+
+### 1. 解析任务列表
+
+从 `/team-plan` 的 delivery plan 中提取任务列表，每个任务需包含：
+- 任务 ID
+- 影响的文件/模块
+- 输入依赖（其他任务的产出）
+- 预计工作量
+
+### 2. 构建依赖图
+
+```
+任务 A (API 契约定义)
+  ↓
+任务 B (后端实现)    任务 C (前端骨架)
+  ↓                    ↓
+任务 D (联调)  ←←←←←←←┘
+  ↓
+任务 E (E2E 测试)
+```
+
+### 3. 分配波次
+
+- Wave 0: [A]
+- Wave 1: [B, C]（B 和 C 无互相依赖，可并行）
+- Wave 2: [D]（依赖 B 和 C）
+- Wave 3: [E]（依赖 D）
+
+### 4. 执行波次
+
+每个波次遵循：
+1. **启动**：并行触发本波次所有任务
+2. **监控**：跟踪每个任务的完成状态
+3. **门禁**：本波次所有任务完成且通过 Pre-flight Gate 后，才启动下一波次
+4. **异常处理**：
+   - 某任务失败但不阻塞其他任务 → 标记失败，继续其他任务
+   - 某任务失败且下游依赖它 → 暂停下游波次中依赖该任务的子集
+   - 关键路径任务失败 → 触发 Escalation Gate
+
+### 5. 产出
+
+波次执行完成后输出：
+```
+## 波次执行报告
+- 总波次数：{N}
+- 并行度峰值：Wave {X} = {Y} 个并行任务
+- 关键路径：{任务序列}
+- 完成状态：{成功/部分成功/失败}
+- 失败任务：{列表}
+```
+
+## 与现有能力的关系
+
+| 能力 | 职责 |
+|------|------|
+| `wave-execution` | 确定"什么可以并行"（逻辑编排层） |
+| `parallel-execution` | 确定"如何物理并行"（Git worktree / tmux 层） |
+| `/team-plan` | 产出任务列表和依赖关系 |
+| `/team-execute` | 消费波次计划，按波次驱动执行 |
+
+## 触发信号
+
+- `/team-plan` 产出超过 5 个任务且存在可并行子集。
+- 用户要求"加快交付节奏"或"并行推进"。
+- 多个前后端任务可以在接口契约锁定后同时启动。
+
+## 配套约束
+
+1. **依赖必须显式**：不允许"应该没有依赖"的默认假设，必须逐任务确认。
+2. **冲突检测**：同一波次内的任务如果修改同一文件，自动升级为顺序执行或拆分更细粒度。
+3. **回退到顺序**：当并行执行引入额外协调成本（频繁 merge conflict、上下文切换过多）时，主动建议回退到顺序执行。