botrun-horse 2.30.0 → 2.34.0

package/botrun-c/.claude/skills/gemini-transcribe/SKILL.md

@@ -1,115 +0,0 @@
----
-name: gemini-transcribe
-description: 使用 Google Gemini API 進行語音轉文字，支援長音訊自動分段並行處理，含時間戳記
-allowed-tools: Bash
----
-
-# Gemini 語音轉錄工具
-
-使用 Google Gemini API 進行語音轉文字。支援長音訊自動分段、並行處理、時間戳記。
-
-## 處理流程
-
-```
-音訊檔案
-    │
-    ▼
-┌─────────────────────────────┐
-│ 1. ffmpeg 切片              │  ← 預設每段 5 分鐘
-│    M4A 48kbps mono 16kHz    │
-└─────────────────────────────┘
-    │
-    ▼
-┌─────────────────────────────┐
-│ 2. Gemini API 並行轉錄      │  ← 預設 10 並行
-│    含自動重試（最多 3 次）   │
-│    每段 4 分鐘超時保護       │
-└─────────────────────────────┘
-    │
-    ▼
-┌─────────────────────────────┐
-│ 3. 合併結果                 │  ← 保留時間戳記
-│    輸出 Markdown 格式        │
-└─────────────────────────────┘
-```
-
-## 使用方式
-
-```bash
-uv run $OFFICIAL_SKILLS_DIR/gemini-transcribe/scripts/transcribe.py \
-  --input <AUDIO_FILE> \
-  [--output <OUTPUT_FILE>] \
-  [--chunk-minutes <MINUTES>] \
-  [--max-workers <N>] \
-  [--json]
-```
-
-### 參數說明
-
-| 參數 | 縮寫 | 必填 | 說明 |
-|------|------|------|------|
-| `--input` | `-i` | 是 | 輸入音訊檔案路徑 |
-| `--output` | `-o` | 否 | 輸出文字檔案路徑（預設輸出到 stdout） |
-| `--chunk-minutes` | `-c` | 否 | 切片時長（分鐘），預設 5 |
-| `--max-workers` | `-w` | 否 | 最大並行數，預設 10 |
-| `--json` | | 否 | 輸出 JSON 格式（含 metadata） |
-
-### 範例
-
-**基本轉錄（輸出到 stdout）：**
-```bash
-uv run $OFFICIAL_SKILLS_DIR/gemini-transcribe/scripts/transcribe.py \
-  -i recording.m4a
-```
-
-**轉錄並儲存到檔案：**
-```bash
-uv run $OFFICIAL_SKILLS_DIR/gemini-transcribe/scripts/transcribe.py \
-  -i meeting.mp3 \
-  -o output/transcript.md
-```
-
-**長音訊 + 高並行：**
-```bash
-uv run $OFFICIAL_SKILLS_DIR/gemini-transcribe/scripts/transcribe.py \
-  -i long_audio.wav \
-  -o output/transcript.md \
-  --chunk-minutes 3 \
-  --max-workers 15
-```
-
-## 支援的音訊格式
-
-所有 ffmpeg 支援的格式皆可使用，包括：
-- WebM, MP3, MP4, M4A, WAV, OGG, AAC, FLAC 等
-
-## 輸出格式
-
-Markdown 格式，每段以分隔線和時間範圍標記：
-
-```markdown
------
-[00:00-05:00]
-[00:00] 歡迎收聽...
-[00:15] 今天我們要討論的是...
-
------
-[05:00-10:00]
-[05:02] 接下來...
-```
-
-## 環境需求
-
-- Python 3.10+
-- ffmpeg（音訊切片用）
-- 網路連線（需存取 Gemini API）
-- 使用 `uv run` 執行（自動安裝依賴）
-
-## 依賴套件
-
-腳本使用 PEP 723 inline script metadata，`uv run` 會自動安裝：
-- `google-genai>=1.0.0`
-
----
-
-*Version: 1.0.0*

package/botrun-c/.claude/skills/gemini-transcribe/scripts/transcribe.py

@@ -1,499 +0,0 @@
-#!/usr/bin/env python3
-# /// script
-# requires-python = ">=3.10"
-# dependencies = [
-#     "google-genai>=1.0.0",
-#     "python-dotenv>=1.0.0",
-# ]
-# ///
-"""
-Gemini 語音轉錄工具
-使用 Google Gemini API 進行語音轉文字，支援長音訊自動分段並行處理。
-
-使用方式：
-uv run .claude/skills/gemini-transcribe/scripts/transcribe.py --input <AUDIO_FILE> [--output <OUTPUT_FILE>]
-"""
-
-import argparse
-import json
-import os
-import re
-import shutil
-import subprocess
-import sys
-import tempfile
-import threading
-import time
-from concurrent.futures import ThreadPoolExecutor, as_completed
-from dataclasses import dataclass
-from datetime import datetime
-from pathlib import Path
-from typing import Optional
-
-from dotenv import load_dotenv
-import google.genai as genai
-
-# 載入專案根目錄的 .env（往上搜尋）
-load_dotenv()
-
-# ============================================================
-# 設定（從環境變數讀取）
-# ============================================================
-
-GEMINI_API_KEY = os.environ.get("GEMINI_API_KEY", "")
-GEMINI_MODEL = "gemini-3-pro-preview"
-
-DEFAULT_CHUNK_DURATION_MINUTES = 5
-DEFAULT_MAX_WORKERS = 10
-MAX_RETRIES = 2
-CHUNK_TIMEOUT = 240  # 4 分鐘
-
-
-def log(message: str) -> None:
-    timestamp = datetime.now().strftime("%H:%M:%S")
-    print(f"[{timestamp}] {message}", file=sys.stderr)
-
-
-# ============================================================
-# 資料結構
-# ============================================================
-
-@dataclass
-class AudioChunk:
-    file_path: str
-    index: int
-    start_time: float
-    duration: float
-
-
-@dataclass
-class TranscriptionResult:
-    chunk_index: int
-    start_offset: float
-    raw_text: str
-    processed_text: str = ""
-    error: Optional[str] = None
-    processing_time: float = 0
-
-
-# ============================================================
-# 音訊時長偵測
-# ============================================================
-
-def get_audio_duration(audio_path: str) -> float:
-    """取得音訊時長（秒），優先用 ffprobe，備用 ffmpeg 解碼"""
-    # 方法 1: ffprobe stream duration
-    try:
-        result = subprocess.run(
-            ['ffprobe', '-v', 'error', '-select_streams', 'a:0',
-             '-show_entries', 'stream=duration', '-of', 'csv=p=0', audio_path],
-            capture_output=True, text=True, check=True, timeout=30,
-        )
-        val = result.stdout.strip()
-        if val and val != 'N/A':
-            return float(val)
-    except Exception:
-        pass
-
-    # 方法 2: ffprobe format duration
-    try:
-        result = subprocess.run(
-            ['ffprobe', '-v', 'error', '-show_entries', 'format=duration',
-             '-of', 'csv=p=0', audio_path],
-            capture_output=True, text=True, check=True, timeout=30,
-        )
-        return float(result.stdout.strip())
-    except Exception:
-        pass
-
-    # 方法 3: ffmpeg 解碼
-    try:
-        result = subprocess.run(
-            ['ffmpeg', '-i', audio_path, '-f', 'null', '-'],
-            stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True, timeout=300,
-        )
-        output = result.stdout + result.stderr
-        m = re.findall(r'time=(\d{2}):(\d{2}):(\d{2}\.\d+)', output)
-        if m:
-            h, mi, s = m[-1]
-            return int(h) * 3600 + int(mi) * 60 + float(s)
-        dm = re.search(r'Duration:\s*(\d{2}):(\d{2}):(\d{2}\.\d+)', output)
-        if dm:
-            h, mi, s = dm.groups()
-            return int(h) * 3600 + int(mi) * 60 + float(s)
-    except Exception:
-        pass
-
-    # 方法 4: 粗估（1MB ≈ 1 分鐘）
-    size = Path(audio_path).stat().st_size
-    return (size / (1024 * 1024)) * 60
-
-
-# ============================================================
-# 音訊切片
-# ============================================================
-
-def split_audio(audio_path: str, chunk_duration: int, temp_dir: str) -> list[AudioChunk]:
-    """將音訊切割為多段，回傳 AudioChunk 列表"""
-    total_duration = get_audio_duration(audio_path)
-    log(f"音訊時長: {total_duration:.1f}s ({total_duration/60:.1f} 分鐘)")
-
-    if total_duration <= chunk_duration:
-        return [AudioChunk(file_path=audio_path, index=0, start_time=0, duration=total_duration)]
-
-    input_format = Path(audio_path).suffix.lower().lstrip('.')
-    num_chunks = int((total_duration + chunk_duration - 1) // chunk_duration)
-    ts = datetime.now().strftime("%Y%m%d%H%M%S")
-
-    chunks: list[AudioChunk] = []
-    for i in range(num_chunks):
-        start = i * chunk_duration
-        if start >= total_duration:
-            break
-        dur = min(chunk_duration, total_duration - start)
-        sm, ss = int(start // 60), int(start % 60)
-
-        out_path = Path(temp_dir) / f"chunk_{i:03d}_[{sm:02d}_{ss:02d}]_{ts}.m4a"
-
-        if not out_path.exists():
-            cmd = [
-                'ffmpeg', '-i', audio_path,
-                '-ss', str(start), '-t', str(dur),
-                '-c:a', 'aac', '-b:a', '48k', '-ac', '1', '-ar', '16000',
-                '-y', str(out_path),
-            ]
-            subprocess.run(cmd, capture_output=True, check=True)
-
-        chunks.append(AudioChunk(file_path=str(out_path), index=i, start_time=start, duration=dur))
-
-    # 合併過短的最後一段（< 10s）到倒數第二段
-    if len(chunks) >= 2 and chunks[-1].duration < 10:
-        last = chunks[-1]
-        prev = chunks[-2]
-        merged_dur = prev.duration + last.duration
-
-        Path(last.file_path).unlink(missing_ok=True)
-        Path(prev.file_path).unlink(missing_ok=True)
-
-        sm, ss = int(prev.start_time // 60), int(prev.start_time % 60)
-        merged_path = Path(temp_dir) / f"chunk_{prev.index:03d}_[{sm:02d}_{ss:02d}]_{ts}.m4a"
-        cmd = [
-            'ffmpeg', '-i', audio_path,
-            '-ss', str(prev.start_time), '-t', str(merged_dur),
-            '-c:a', 'aac', '-b:a', '48k', '-ac', '1', '-ar', '16000',
-            '-y', str(merged_path),
-        ]
-        subprocess.run(cmd, capture_output=True, check=True)
-
-        chunks[-2] = AudioChunk(file_path=str(merged_path), index=prev.index, start_time=prev.start_time, duration=merged_dur)
-        chunks.pop()
-
-    log(f"切割完成: {len(chunks)} 段")
-    return chunks
-
-
-# ============================================================
-# Gemini 轉錄
-# ============================================================
-
-def build_prompt(chunk: AudioChunk) -> str:
-    sm = int(chunk.start_time // 60)
-    ss = int(chunk.start_time % 60)
-    return f"""請將此音頻檔案完整轉錄為文字，並包含詳細的時間戳記。請注意以下要求：
-
-1. 語言識別：音頻內容可能包含繁體中文(Traditional Chinese)或台語(Taiwanese/Hokkien)
-2. 時間戳記：為每個句子或語音段落提供精確的時間戳記（格式：[MM:SS] 或 [HH:MM:SS]）
-3. 轉錄格式：
-   - 對於繁體中文：使用標準繁體中文字符
-   - 對於台語：盡可能用繁體中文字符表達
-4. 標點符號：正確使用中文標點符號
-5. 語音特徵：如有明顯的停頓、語調變化或重複，請適當標註
-
-注意：這是音頻片段 {chunk.index + 1}，時間戳記應從 {sm:02d}:{ss:02d} 開始計算。
-
-輸出格式範例：
-[{sm:02d}:{ss:02d}] 歡迎收聽...
-[{sm:02d}:{ss+15:02d}] 今天我們要討論的是...
-
-請完整轉錄整個音頻片段內容，如果整個檔案都沒有人講話的聲音請回傳 [靜音...]。""".strip()
-
-
-def transcribe_chunk(client: genai.Client, chunk: AudioChunk) -> TranscriptionResult:
-    """轉錄單段音訊，含重試邏輯"""
-    for attempt in range(MAX_RETRIES + 1):
-        start = time.time()
-        myfile = None
-        try:
-            if attempt > 0:
-                wait = 2 ** attempt
-                log(f"[chunk {chunk.index}] 重試 {attempt}，等待 {wait}s...")
-                time.sleep(wait)
-
-            myfile = client.files.upload(file=chunk.file_path)
-
-            # 等待檔案處理完成
-            wait_time = 0
-            while myfile.state == "PROCESSING":
-                if time.time() - start > CHUNK_TIMEOUT:
-                    raise TimeoutError(f"處理超時（>{CHUNK_TIMEOUT}s）")
-                time.sleep(0.5)
-                wait_time += 0.5
-                myfile = client.files.get(name=myfile.name)
-
-            if myfile.state != "ACTIVE":
-                raise RuntimeError(f"檔案處理失敗，狀態: {myfile.state}")
-
-            if time.time() - start > CHUNK_TIMEOUT:
-                raise TimeoutError(f"處理超時（>{CHUNK_TIMEOUT}s）")
-
-            response = client.models.generate_content(
-                model=GEMINI_MODEL,
-                contents=[build_prompt(chunk), myfile],
-            )
-
-            client.files.delete(name=myfile.name)
-            elapsed = time.time() - start
-            log(f"[chunk {chunk.index}] 完成 ({elapsed:.1f}s)")
-
-            return TranscriptionResult(
-                chunk_index=chunk.index,
-                start_offset=chunk.start_time,
-                raw_text=response.text,
-                processing_time=elapsed,
-            )
-
-        except TimeoutError:
-            try:
-                if myfile:
-                    client.files.delete(name=myfile.name)
-            except Exception:
-                pass
-            if attempt == MAX_RETRIES:
-                elapsed = time.time() - start
-                log(f"[chunk {chunk.index}] 超時失敗: {elapsed:.1f}s")
-                return TranscriptionResult(
-                    chunk_index=chunk.index, start_offset=chunk.start_time,
-                    raw_text="", processing_time=elapsed, error=f"超時 ({elapsed:.1f}s)",
-                )
-
-        except Exception as e:
-            log(f"[chunk {chunk.index}] 錯誤: {e}")
-            try:
-                if myfile:
-                    client.files.delete(name=myfile.name)
-            except Exception:
-                pass
-            if attempt == MAX_RETRIES:
-                elapsed = time.time() - start
-                return TranscriptionResult(
-                    chunk_index=chunk.index, start_offset=chunk.start_time,
-                    raw_text="", processing_time=elapsed, error=str(e),
-                )
-
-    # Should not reach here
-    return TranscriptionResult(chunk_index=chunk.index, start_offset=chunk.start_time, raw_text="", error="unknown")
-
-
-def transcribe_parallel(client: genai.Client, chunks: list[AudioChunk], max_workers: int) -> list[TranscriptionResult]:
-    """並行轉錄所有片段"""
-    log(f"開始並行轉錄 {len(chunks)} 段（max_workers={max_workers}）")
-
-    completed = 0
-    failed = 0
-    total = len(chunks)
-    lock = threading.Lock()
-
-    def on_done(success: bool):
-        nonlocal completed, failed
-        with lock:
-            if success:
-                completed += 1
-            else:
-                failed += 1
-            log(f"[進度] {completed + failed}/{total} ({completed} 成功, {failed} 失敗)")
-
-    results: list[TranscriptionResult] = []
-    with ThreadPoolExecutor(max_workers=max_workers) as executor:
-        futures = {executor.submit(transcribe_chunk, client, c): c for c in chunks}
-        for future in as_completed(futures):
-            result = future.result()
-            results.append(result)
-            on_done(result.error is None)
-
-    results.sort(key=lambda r: r.chunk_index)
-    return results
-
-
-# ============================================================
-# 結果合併
-# ============================================================
-
-def merge_results(results: list[TranscriptionResult], chunk_duration: int) -> str:
-    """合併轉錄結果，保留時間戳"""
-    ok = [r for r in results if r.error is None and r.raw_text.strip()]
-    if not ok:
-        raise RuntimeError("沒有成功的轉錄結果")
-
-    lines: list[str] = []
-    for i, result in enumerate(ok):
-        if i < len(ok) - 1:
-            actual_dur = ok[i + 1].start_offset - result.start_offset
-        else:
-            actual_dur = chunk_duration
-
-        sm = int(result.start_offset // 60)
-        ss = int(result.start_offset % 60)
-        et = result.start_offset + actual_dur
-        em = int(et // 60)
-        es = int(et % 60)
-        time_range = f"[{sm:02d}:{ss:02d}-{em:02d}:{es:02d}]"
-
-        section_lines = ["-----", time_range]
-        found_first_ts = False
-
-        for line in result.raw_text.strip().split('\n'):
-            line = line.strip()
-            if not line:
-                continue
-            ts_match = re.match(r'^\[(\d{1,2}):(\d{2})\](.*)$', line)
-            if ts_match:
-                found_first_ts = True
-            elif not found_first_ts:
-                continue
-            section_lines.append(line)
-
-        lines.extend(section_lines)
-
-    return '\n'.join(lines)
-
-
-# ============================================================
-# 主流程
-# ============================================================
-
-def transcribe_audio(
-    audio_path: str,
-    output_path: Optional[str] = None,
-    max_workers: int = DEFAULT_MAX_WORKERS,
-    chunk_duration_minutes: int = DEFAULT_CHUNK_DURATION_MINUTES,
-) -> str:
-    """完整轉錄流程：切片 → 並行轉錄 → 合併"""
-    audio_file = Path(audio_path)
-    if not audio_file.exists():
-        raise FileNotFoundError(f"檔案不存在: {audio_path}")
-
-    chunk_duration_seconds = chunk_duration_minutes * 60
-
-    client = genai.Client(api_key=GEMINI_API_KEY)
-
-    temp_dir = tempfile.mkdtemp(prefix="gemini_transcribe_")
-    log(f"暫存目錄: {temp_dir}")
-
-    try:
-        # 1. 切片
-        chunks = split_audio(audio_path, chunk_duration_seconds, temp_dir)
-
-        # 2. 並行轉錄
-        results = transcribe_parallel(client, chunks, max_workers)
-
-        # 3. 合併
-        final_text = merge_results(results, chunk_duration_seconds)
-
-        # 4. 輸出
-        if output_path:
-            out = Path(output_path)
-            out.parent.mkdir(parents=True, exist_ok=True)
-            with open(out, 'w', encoding='utf-8') as f:
-                f.write(final_text)
-            log(f"已儲存: {output_path}")
-
-        return final_text
-
-    finally:
-        shutil.rmtree(temp_dir, ignore_errors=True)
-        log("已清理暫存目錄")
-
-
-def main():
-    parser = argparse.ArgumentParser(
-        description="Gemini 語音轉錄工具（支援長音訊分段並行處理）"
-    )
-    parser.add_argument(
-        "--input", "-i", type=Path, required=True,
-        help="輸入音訊檔案路徑",
-    )
-    parser.add_argument(
-        "--output", "-o", type=Path, default=None,
-        help="輸出文字檔案路徑（預設輸出到 stdout）",
-    )
-    parser.add_argument(
-        "--chunk-minutes", "-c", type=int, default=DEFAULT_CHUNK_DURATION_MINUTES,
-        help=f"切片時長（分鐘），預設 {DEFAULT_CHUNK_DURATION_MINUTES}",
-    )
-    parser.add_argument(
-        "--max-workers", "-w", type=int, default=DEFAULT_MAX_WORKERS,
-        help=f"最大並行數，預設 {DEFAULT_MAX_WORKERS}",
-    )
-    parser.add_argument(
-        "--json", action="store_true",
-        help="輸出 JSON 格式（含 metadata）",
-    )
-
-    args = parser.parse_args()
-
-    if not args.input.exists():
-        print(f"錯誤：檔案不存在 '{args.input}'", file=sys.stderr)
-        sys.exit(1)
-
-    file_size = args.input.stat().st_size
-    print("=" * 60, file=sys.stderr)
-    print("Gemini Transcription Tool", file=sys.stderr)
-    print("=" * 60, file=sys.stderr)
-    log(f"Input: {args.input}")
-    log(f"Size: {file_size / 1024 / 1024:.2f} MB")
-    log(f"Model: {GEMINI_MODEL}")
-    log(f"Chunk: {args.chunk_minutes} min, Workers: {args.max_workers}")
-    print("-" * 60, file=sys.stderr)
-
-    start_time = time.time()
-
-    try:
-        text = transcribe_audio(
-            audio_path=str(args.input),
-            output_path=str(args.output) if args.output else None,
-            max_workers=args.max_workers,
-            chunk_duration_minutes=args.chunk_minutes,
-        )
-
-        elapsed = time.time() - start_time
-        print("-" * 60, file=sys.stderr)
-        log(f"完成！耗時 {elapsed:.1f}s ({elapsed/60:.1f} 分鐘)")
-        log(f"文字長度: {len(text)} 字元")
-        print("=" * 60, file=sys.stderr)
-
-        if args.json:
-            result = {
-                "success": True,
-                "text": text,
-                "model": GEMINI_MODEL,
-                "file": str(args.input),
-                "file_size": file_size,
-                "elapsed_seconds": round(elapsed, 2),
-                "processed_at": datetime.now().isoformat(),
-            }
-            output_text = json.dumps(result, ensure_ascii=False, indent=2)
-        else:
-            output_text = text
-
-        if not args.output:
-            print(output_text)
-
-    except Exception as e:
-        elapsed = time.time() - start_time
-        print(f"\n錯誤：{e}", file=sys.stderr)
-        log(f"失敗，耗時 {elapsed:.1f}s")
-        sys.exit(1)
-
-
-if __name__ == "__main__":
-    main()