botrun-horse 2.29.2 → 2.30.0

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

@@ -0,0 +1,115 @@
+---
+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

@@ -0,0 +1,499 @@
+#!/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()