@techwavedev/agi-agent-kit 1.3.6 → 1.5.0

package/templates/skills/extended/gaming/audio-transcriber/examples/basic-transcription.sh

@@ -1,250 +0,0 @@
-#!/usr/bin/env bash
-
-# Basic Audio Transcription Example
-# Demonstrates how to use the audio-transcriber skill manually
-
-set -euo pipefail
-
-# Configuration
-AUDIO_FILE="${1:-}"
-MODEL="${MODEL:-base}"  # Options: tiny, base, small, medium, large
-OUTPUT_FORMAT="${OUTPUT_FORMAT:-markdown}"  # Options: markdown, txt, srt, vtt, json
-
-# Colors for output
-RED='\033[0;31m'
-GREEN='\033[0;32m'
-YELLOW='\033[1;33m'
-BLUE='\033[0;34m'
-NC='\033[0m' # No Color
-
-# Helper functions
-error() {
-    echo -e "${RED}❌ Error: $1${NC}" >&2
-    exit 1
-}
-
-success() {
-    echo -e "${GREEN}✅ $1${NC}"
-}
-
-info() {
-    echo -e "${BLUE}ℹ️  $1${NC}"
-}
-
-warn() {
-    echo -e "${YELLOW}⚠️  $1${NC}"
-}
-
-# Check if audio file is provided
-if [[ -z "$AUDIO_FILE" ]]; then
-    error "Usage: $0 <audio_file>"
-fi
-
-# Verify file exists
-if [[ ! -f "$AUDIO_FILE" ]]; then
-    error "File not found: $AUDIO_FILE"
-fi
-
-# Step 0: Discovery - Check for transcription tools
-info "Step 0: Discovering transcription tools..."
-
-TRANSCRIBER=""
-if python3 -c "import faster_whisper" 2>/dev/null; then
-    TRANSCRIBER="faster-whisper"
-    success "Faster-Whisper detected (optimized)"
-elif python3 -c "import whisper" 2>/dev/null; then
-    TRANSCRIBER="whisper"
-    success "OpenAI Whisper detected"
-else
-    error "No transcription tool found. Install with: pip install faster-whisper"
-fi
-
-# Check for ffmpeg
-if command -v ffmpeg &>/dev/null; then
-    success "ffmpeg available (format conversion enabled)"
-else
-    warn "ffmpeg not found (limited format support)"
-fi
-
-# Step 1: Extract metadata
-info "Step 1: Extracting audio metadata..."
-
-FILE_SIZE=$(du -h "$AUDIO_FILE" | cut -f1)
-info "File size: $FILE_SIZE"
-
-# Get duration if ffprobe is available
-if command -v ffprobe &>/dev/null; then
-    DURATION=$(ffprobe -v error -show_entries format=duration \
-        -of default=noprint_wrappers=1:nokey=1 "$AUDIO_FILE" 2>/dev/null || echo "0")
-    
-    # Convert to HH:MM:SS
-    if command -v date &>/dev/null; then
-        if [[ "$OSTYPE" == "darwin"* ]]; then
-            # macOS
-            DURATION_HMS=$(date -u -r "${DURATION%.*}" +%H:%M:%S 2>/dev/null || echo "Unknown")
-        else
-            # Linux
-            DURATION_HMS=$(date -u -d @"${DURATION%.*}" +%H:%M:%S 2>/dev/null || echo "Unknown")
-        fi
-    else
-        DURATION_HMS="Unknown"
-    fi
-    
-    info "Duration: $DURATION_HMS"
-else
-    warn "ffprobe not found - cannot extract duration"
-    DURATION="0"
-    DURATION_HMS="Unknown"
-fi
-
-# Check file size warning
-SIZE_MB=$(du -m "$AUDIO_FILE" | cut -f1)
-if [[ $SIZE_MB -gt 25 ]]; then
-    warn "Large file ($FILE_SIZE) - processing may take several minutes"
-    read -p "Continue? [Y/n]: " CONTINUE
-    if [[ "$CONTINUE" =~ ^[Nn] ]]; then
-        info "Transcription cancelled"
-        exit 0
-    fi
-fi
-
-# Step 2: Transcribe using Python
-info "Step 2: Transcribing audio..."
-
-OUTPUT_FILE="${AUDIO_FILE%.*}.md"
-TEMP_JSON="/tmp/transcription_$$.json"
-
-python3 << EOF
-import sys
-import json
-from datetime import datetime
-
-try:
-    if "$TRANSCRIBER" == "faster-whisper":
-        from faster_whisper import WhisperModel
-        model = WhisperModel("$MODEL", device="cpu", compute_type="int8")
-        segments, info = model.transcribe("$AUDIO_FILE", language=None, vad_filter=True)
-        
-        data = {
-            "language": info.language,
-            "language_probability": round(info.language_probability, 2),
-            "duration": info.duration,
-            "segments": []
-        }
-        
-        for segment in segments:
-            data["segments"].append({
-                "start": round(segment.start, 2),
-                "end": round(segment.end, 2),
-                "text": segment.text.strip()
-            })
-    else:
-        import whisper
-        model = whisper.load_model("$MODEL")
-        result = model.transcribe("$AUDIO_FILE")
-        
-        data = {
-            "language": result["language"],
-            "duration": result["segments"][-1]["end"] if result["segments"] else 0,
-            "segments": result["segments"]
-        }
-    
-    with open("$TEMP_JSON", "w") as f:
-        json.dump(data, f)
-    
-    print(f"✅ Language detected: {data['language']}")
-    print(f"📝 Transcribed {len(data['segments'])} segments")
-    
-except Exception as e:
-    print(f"❌ Error: {e}", file=sys.stderr)
-    sys.exit(1)
-EOF
-
-# Check if transcription succeeded
-if [[ ! -f "$TEMP_JSON" ]]; then
-    error "Transcription failed"
-fi
-
-# Step 3: Generate Markdown output
-info "Step 3: Generating Markdown report..."
-
-python3 << 'EOF'
-import json
-import sys
-from datetime import datetime
-
-# Load transcription data
-with open("${TEMP_JSON}") as f:
-    data = json.load(f)
-
-# Prepare metadata
-filename = "${AUDIO_FILE}".split("/")[-1]
-file_size = "${FILE_SIZE}"
-duration_hms = "${DURATION_HMS}"
-language = data["language"]
-process_date = datetime.now().strftime("%Y-%m-%d %H:%M:%S")
-num_segments = len(data["segments"])
-
-# Generate Markdown
-markdown = f"""# Audio Transcription Report
-
-## 📊 Metadata
-
-| Field | Value |
-|-------|-------|
-| **File Name** | {filename} |
-| **File Size** | {file_size} |
-| **Duration** | {duration_hms} |
-| **Language** | {language.upper()} |
-| **Processed Date** | {process_date} |
-| **Segments** | {num_segments} |
-| **Transcription Engine** | ${TRANSCRIBER} (model: ${MODEL}) |
-
----
-
-## 🎙️ Full Transcription
-
-"""
-
-# Add transcription with timestamps
-for seg in data["segments"]:
-    start_time = f"{int(seg['start'] // 60):02d}:{int(seg['start'] % 60):02d}"
-    end_time = f"{int(seg['end'] // 60):02d}:{int(seg['end'] % 60):02d}"
-    markdown += f"**[{start_time} → {end_time}]**  \n{seg['text']}\n\n"
-
-markdown += """---
-
-## 📝 Summary
-
-*Automatic summary generation requires AI integration (Claude/GPT).*  
-*For now, review the full transcription above.*
-
----
-
-*Generated by audio-transcriber skill example script*  
-*Transcription engine: ${TRANSCRIBER} | Model: ${MODEL}*
-"""
-
-# Write to file
-with open("${OUTPUT_FILE}", "w") as f:
-    f.write(markdown)
-
-print(f"✅ Markdown report saved: ${OUTPUT_FILE}")
-EOF
-
-# Clean up
-rm -f "$TEMP_JSON"
-
-# Step 4: Display summary
-success "Transcription complete!"
-echo ""
-echo "📊 Results:"
-echo "  Output file: $OUTPUT_FILE"
-echo "  Transcription engine: $TRANSCRIBER"
-echo "  Model: $MODEL"
-echo ""
-info "Next steps:"
-echo "  1. Review the transcription: cat $OUTPUT_FILE"
-echo "  2. Edit if needed: vim $OUTPUT_FILE"
-echo "  3. Share with team or archive"
-EOF

package/templates/skills/extended/gaming/audio-transcriber/references/tools-comparison.md

@@ -1,352 +0,0 @@
-# Transcription Tools Comparison
-
-Comprehensive comparison of audio transcription engines supported by the audio-transcriber skill.
-
-## Overview
-
-| Tool | Type | Speed | Quality | Cost | Privacy | Offline | Languages |
-|------|------|-------|---------|------|---------|---------|-----------|
-| **Faster-Whisper** | Open-source | ⚡⚡⚡⚡⚡ | ⭐⭐⭐⭐⭐ | Free | 100% | ✅ | 99 |
-| **Whisper** | Open-source | ⚡⚡⚡ | ⭐⭐⭐⭐⭐ | Free | 100% | ✅ | 99 |
-| Google Speech-to-Text | Commercial API | ⚡⚡⚡⚡ | ⭐⭐⭐⭐⭐ | $0.006/15s | Partial | ❌ | 125+ |
-| Azure Speech | Commercial API | ⚡⚡⚡⚡ | ⭐⭐⭐⭐ | $1/hour | Partial | ❌ | 100+ |
-| AssemblyAI | Commercial API | ⚡⚡⚡⚡ | ⭐⭐⭐⭐⭐ | $0.00025/s | Partial | ❌ | 99 |
-
----
-
-## Faster-Whisper (Recommended)
-
-### Pros
-✅ **4-5x faster** than original Whisper  
-✅ **Same quality** as original Whisper  
-✅ **Lower memory usage** (50-60% less RAM)  
-✅ **Free and open-source**  
-✅ **100% offline** (privacy guaranteed)  
-✅ **Easy installation** (`pip install faster-whisper`)  
-✅ **Drop-in replacement** for Whisper
-
-### Cons
-❌ Requires Python 3.8+  
-❌ Initial model download (~100MB-1.5GB)  
-❌ GPU optional but speeds up significantly
-
-### Installation
-
-```bash
-pip install faster-whisper
-```
-
-### Usage Example
-
-```python
-from faster_whisper import WhisperModel
-
-# Load model (auto-downloads on first run)
-model = WhisperModel("base", device="cpu", compute_type="int8")
-
-# Transcribe
-segments, info = model.transcribe("audio.mp3", language="pt")
-
-# Print results
-for segment in segments:
-    print(f"[{segment.start:.2f}s -> {segment.end:.2f}s] {segment.text}")
-```
-
-### Model Sizes
-
-| Model | Size | RAM | Speed (CPU) | Quality |
-|-------|------|-----|-------------|---------|
-| `tiny` | 39 MB | ~1 GB | Very fast (~10x realtime) | Basic |
-| `base` | 74 MB | ~1 GB | Fast (~7x realtime) | Good |
-| `small` | 244 MB | ~2 GB | Moderate (~4x realtime) | Very good |
-| `medium` | 769 MB | ~5 GB | Slow (~2x realtime) | Excellent |
-| `large` | 1550 MB | ~10 GB | Very slow (~1x realtime) | Best |
-
-**Recommendation:** `small` or `medium` for production use.
-
----
-
-## Whisper (Original)
-
-### Pros
-✅ **Official OpenAI model**  
-✅ **Excellent quality**  
-✅ **Free and open-source**  
-✅ **100% offline**  
-✅ **Well-documented**  
-✅ **Large community**
-
-### Cons
-❌ **Slower** than Faster-Whisper (4-5x)  
-❌ **Higher memory usage**  
-❌ Requires PyTorch (large dependency)  
-❌ GPU highly recommended for larger models
-
-### Installation
-
-```bash
-pip install openai-whisper
-```
-
-### Usage Example
-
-```python
-import whisper
-
-# Load model
-model = whisper.load_model("base")
-
-# Transcribe
-result = model.transcribe("audio.mp3", language="pt")
-
-# Print results
-print(result["text"])
-```
-
-### When to Use Whisper vs. Faster-Whisper
-
-**Use Faster-Whisper if:**
-- Speed is important
-- Limited RAM available
-- Processing many files
-
-**Use Original Whisper if:**
-- Faster-Whisper installation issues
-- Need exact OpenAI implementation
-- Already have Whisper in project dependencies
-
----
-
-## Google Cloud Speech-to-Text
-
-### Pros
-✅ **Very accurate** (industry-leading)  
-✅ **Fast processing** (cloud infrastructure)  
-✅ **125+ languages**  
-✅ **Word-level timestamps**  
-✅ **Punctuation & capitalization**  
-✅ **Speaker diarization** (premium)
-
-### Cons
-❌ **Requires internet** (cloud-only)  
-❌ **Costs money** (after free tier)  
-❌ **Privacy concerns** (audio uploaded to Google)  
-❌ Requires GCP account setup  
-❌ Complex authentication
-
-### Pricing
-
-- **Free tier:** 60 minutes/month
-- **Standard:** $0.006 per 15 seconds ($1.44/hour)
-- **Premium:** $0.009 per 15 seconds (with diarization)
-
-### Installation
-
-```bash
-pip install google-cloud-speech
-```
-
-### Setup
-
-1. Create GCP project
-2. Enable Speech-to-Text API
-3. Create service account & download JSON key
-4. Set environment variable:
-   ```bash
-   export GOOGLE_APPLICATION_CREDENTIALS="path/to/key.json"
-   ```
-
-### Usage Example
-
-```python
-from google.cloud import speech
-
-client = speech.SpeechClient()
-
-with open("audio.wav", "rb") as audio_file:
-    content = audio_file.read()
-
-audio = speech.RecognitionAudio(content=content)
-config = speech.RecognitionConfig(
-    encoding=speech.RecognitionConfig.AudioEncoding.LINEAR16,
-    sample_rate_hertz=16000,
-    language_code="pt-BR",
-)
-
-response = client.recognize(config=config, audio=audio)
-
-for result in response.results:
-    print(result.alternatives[0].transcript)
-```
-
----
-
-## Azure Speech Services
-
-### Pros
-✅ **High accuracy**  
-✅ **100+ languages**  
-✅ **Real-time transcription**  
-✅ **Custom models** (train on your data)  
-✅ **Good Microsoft ecosystem integration**
-
-### Cons
-❌ **Requires internet**  
-❌ **Costs money** (after free tier)  
-❌ **Privacy concerns** (cloud processing)  
-❌ Requires Azure account  
-❌ Complex setup
-
-### Pricing
-
-- **Free tier:** 5 hours/month
-- **Standard:** $1.00 per audio hour
-
-### Installation
-
-```bash
-pip install azure-cognitiveservices-speech
-```
-
-### Setup
-
-1. Create Azure account
-2. Create Speech resource
-3. Get API key and region
-4. Set environment variables:
-   ```bash
-   export AZURE_SPEECH_KEY="your-key"
-   export AZURE_SPEECH_REGION="your-region"
-   ```
-
-### Usage Example
-
-```python
-import azure.cognitiveservices.speech as speechsdk
-
-speech_config = speechsdk.SpeechConfig(
-    subscription=os.environ.get('AZURE_SPEECH_KEY'),
-    region=os.environ.get('AZURE_SPEECH_REGION')
-)
-
-audio_config = speechsdk.audio.AudioConfig(filename="audio.wav")
-speech_recognizer = speechsdk.SpeechRecognizer(
-    speech_config=speech_config,
-    audio_config=audio_config
-)
-
-result = speech_recognizer.recognize_once()
-print(result.text)
-```
-
----
-
-## AssemblyAI
-
-### Pros
-✅ **Modern, developer-friendly API**  
-✅ **Excellent accuracy**  
-✅ **Advanced features** (sentiment, topic detection, PII redaction)  
-✅ **Speaker diarization** (included)  
-✅ **Fast processing**  
-✅ **Good documentation**
-
-### Cons
-❌ **Requires internet**  
-❌ **Costs money** (no free tier, only trial credits)  
-❌ **Privacy concerns** (cloud processing)  
-❌ Requires API key
-
-### Pricing
-
-- **Free trial:** $50 credits
-- **Standard:** $0.00025 per second (~$0.90/hour)
-
-### Installation
-
-```bash
-pip install assemblyai
-```
-
-### Setup
-
-1. Sign up at assemblyai.com
-2. Get API key
-3. Set environment variable:
-   ```bash
-   export ASSEMBLYAI_API_KEY="your-key"
-   ```
-
-### Usage Example
-
-```python
-import assemblyai as aai
-
-aai.settings.api_key = os.environ["ASSEMBLYAI_API_KEY"]
-
-transcriber = aai.Transcriber()
-transcript = transcriber.transcribe("audio.mp3")
-
-print(transcript.text)
-
-# Speaker diarization
-for utterance in transcript.utterances:
-    print(f"Speaker {utterance.speaker}: {utterance.text}")
-```
-
----
-
-## Recommendation Matrix
-
-### Use Faster-Whisper if:
-- ✅ Privacy is critical (local processing)
-- ✅ Want zero cost (free forever)
-- ✅ Need offline capability
-- ✅ Processing many files (speed matters)
-- ✅ Limited budget
-
-### Use Google Speech-to-Text if:
-- ✅ Need absolute best accuracy
-- ✅ Have budget for cloud services
-- ✅ Want advanced features (punctuation, diarization)
-- ✅ Already using GCP ecosystem
-
-### Use Azure Speech if:
-- ✅ In Microsoft ecosystem
-- ✅ Need custom model training
-- ✅ Want real-time transcription
-- ✅ Have Azure credits
-
-### Use AssemblyAI if:
-- ✅ Need advanced features (sentiment, topics)
-- ✅ Want easiest API experience
-- ✅ Need automatic PII redaction
-- ✅ Value developer experience
-
----
-
-## Performance Benchmarks
-
-**Test:** 1-hour podcast (MP3, 44.1kHz, stereo)
-
-| Tool | Processing Time | Accuracy | Cost |
-|------|----------------|----------|------|
-| Faster-Whisper (small) | 8 min | 94% | $0 |
-| Whisper (small) | 32 min | 94% | $0 |
-| Google Speech | 2 min | 96% | $1.44 |
-| Azure Speech | 3 min | 95% | $1.00 |
-| AssemblyAI | 4 min | 96% | $0.90 |
-
-*Benchmarks run on MacBook Pro M1, 16GB RAM*
-
----
-
-## Conclusion
-
-**For the audio-transcriber skill:**
-
-1. **Primary:** Faster-Whisper (best balance of speed, quality, privacy, cost)
-2. **Fallback:** Whisper (if Faster-Whisper unavailable)
-3. **Optional:** Cloud APIs (user choice for premium features)
-
-This ensures the skill works out-of-the-box for most users while allowing advanced users to integrate commercial services if needed.