@thierrynakoa/fire-flow 12.2.2 → 13.0.1

package/skills-library/integrations/realtimestt-openwakeword-cuda-windows.md

@@ -0,0 +1,229 @@
+---
+name: realtimestt-openwakeword-cuda-windows
+category: integrations
+version: 1.0.0
+contributed: 2026-02-22
+contributor: voice-bridge-v3
+last_updated: 2026-02-22
+tags: [realtimestt, openwakeword, whisper, cuda, wake-word, speech-to-text, windows, pyaudio, torch-multiprocessing, pyqt6]
+difficulty: hard
+usage_count: 0
+success_rate: 100
+---
+
+# RealtimeSTT + OpenWakeWord + CUDA on Windows
+
+## Problem
+
+Integrating OpenWakeWord wake word detection via RealtimeSTT's native `wakeword_backend` parameter on Windows with CUDA GPU hits 7 non-obvious failures that each appear as unrelated errors. The combination of RealtimeSTT's `torch.multiprocessing` child processes, OpenWakeWord's ONNX model loading, CUDA's float16 compute, MKL memory allocation, and PyQt6's global state creates a minefield of ordering and configuration gotchas.
+
+**Symptoms you'll see (in order of appearance):**
+1. `Wakeword engine oww unknown/unsupported or wake_words not specified`
+2. `mkl_malloc: failed to allocate memory`
+3. `ValueError: Requested float16 compute type, but the target device or backend do not support efficient float16 computation`
+4. `BrokenPipeError` in torch.multiprocessing child process
+5. `MemoryError` in openwakeword `_streaming_melspectrogram`
+6. Wake word fires 5+ times per single utterance (no debounce)
+7. Transcription returns garbage ("Bit.") after fragmented audio
+
+## Solution Pattern
+
+Each error has a specific fix. Apply ALL of them — they're independent failure modes.
+
+### 1. Backend Name + wake_words Parameter (BOTH required)
+
+RealtimeSTT checks: `elif wake_words and self.wakeword_backend in {'oww', 'openwakeword', 'openwakewords'}`
+
+Both conditions must be true. If `wake_words` is empty/missing, the entire wake word system silently skips.
+
+```python
+# WRONG — wake_words defaults to empty, silently disables wake word
+AudioToTextRecorder(wakeword_backend="openwakeword")
+
+# RIGHT — both backend AND wake_words must be set
+AudioToTextRecorder(
+    wakeword_backend="openwakeword",
+    wake_words="hey_jarvis",  # REQUIRED — comma-separated built-in model names
+    wake_words_sensitivity=0.35,
+)
+```
+
+Built-in models: `alexa`, `hey_jarvis`, `hey_mycroft`, `hey_rhasspy`, `timer`, `weather`.
+
+### 2. MKL Thread Memory (High-Core CPUs)
+
+On CPUs with 16+ threads (i9-12900H has 20), MKL allocates buffers for ALL threads simultaneously while loading OpenWakeWord + Whisper models. Must be set BEFORE any imports.
+
+```python
+# MUST be at the very top of your entry point, before ANY imports
+import os
+os.environ.setdefault("MKL_NUM_THREADS", "4")
+os.environ.setdefault("OMP_NUM_THREADS", "4")
+```
+
+### 3. CUDA float16 in torch.multiprocessing Context
+
+CTranslate2 CUDA float16 works perfectly in direct tests but fails inside RealtimeSTT's `mp.Process` child processes on Windows. The child processes re-import everything and the CUDA state gets confused.
+
+```python
+# WRONG — fails inside RealtimeSTT's multiprocessing context
+AudioToTextRecorder(compute_type="float16")
+
+# RIGHT — let CTranslate2 choose the best available type
+AudioToTextRecorder(compute_type="auto")
+```
+
+### 4. PyQt6 Import Order (Windows only)
+
+PyQt6 creates global state that breaks `torch.multiprocessing` child processes when `enable_realtime_transcription=True`. Initialize STT FGTAT, then import PyQt6.
+
+```python
+# WRONG — PyQt6 imported before STT causes BrokenPipeError
+from PyQt6.QtWidgets import QApplication
+from RealtimeSTT import AudioToTextRecorder
+recorder = AudioToTextRecorder(enable_realtime_transcription=True)  # CRASH
+
+# RIGHT — initialize STT before any PyQt6 imports
+from RealtimeSTT import AudioToTextRecorder
+recorder = AudioToTextRecorder(enable_realtime_transcription=True)
+recorder_ready = True  # models loaded, child processes spawned
+
+# NOW safe to import PyQt6
+from PyQt6.QtWidgets import QApplication
+app = QApplication(sys.argv)
+```
+
+### 5. First-Launch Audio Queue Overflow
+
+First run downloads OpenWakeWord models from HuggingFace (~30s). Audio queues up during download. When wake word processing starts, the backlog causes `MemoryError` in `_streaming_melspectrogram`.
+
+**Fix:** Kill and restart. Models are cached after first download, startup drops to ~8s with no backlog. This is a one-time issue.
+
+**Better fix (if building a product):** Flush the audio queue after recorder initialization:
+```python
+recorder = AudioToTextRecorder(**params)
+# Flush any audio that queued during model download
+while not recorder.audio_queue.empty():
+    try:
+        recorder.audio_queue.get_nowait()
+    except:
+        break
+```
+
+### 6. Wake Word Callback Debounce
+
+RealtimeSTT fires `on_wakeword_detected` on every overlapping audio chunk that scores above threshold. A single "Hey Jarvis" produces 5+ callbacks in 127ms, fragmenting the audio buffer.
+
+```python
+import time
+
+class STTEngine:
+    def __init__(self):
+        self._wakeword_debounce_sec = 2.0
+        self._last_wakeword_time = 0.0
+
+    def _handle_wakeword_detected(self):
+        now = time.time()
+        if now - self._last_wakeword_time < self._wakeword_debounce_sec:
+            return  # duplicate within debounce window
+        self._last_wakeword_time = now
+
+        # Process the actual detection
+        self.on_wakeword_detected()
+```
+
+### 7. Config File Deep-Merge Staleness
+
+If your app creates a config file on first run with wrong defaults, `_deep_merge` preserves old values on subsequent runs. After fixing defaults in code, **delete the on-disk config** to regenerate.
+
+```bash
+# If wake word doesn't work after code fix, check the on-disk config
+del %USERPROFILE%\.claude\voice-bridge-v3\config.yaml
+# Restart app — regenerates with correct defaults
+```
+
+## Implementation Steps
+
+1. Set `MKL_NUM_THREADS=4` and `OMP_NUM_THREADS=4` at the very top of entry point
+2. Initialize `AudioToTextRecorder` with `compute_type="auto"`, `wakeword_backend="openwakeword"`, `wake_words="hey_jarvis"`
+3. THEN import PyQt6/PySide6 (after recorder is initialized)
+4. Add 2-second debounce to `on_wakeword_detected` callback
+5. On first launch, expect model downloads — kill and restart if MemoryError occurs
+6. Delete stale config files after changing defaults
+
+## When to Use
+
+- Building a voice-to-text application with wake word activation on Windows
+- Using RealtimeSTT with OpenWakeWord backend and CUDA GPU
+- Combining speech-to-text with a Qt-based GUI on Windows
+- Any project using `torch.multiprocessing` alongside CUDA and audio processing
+
+## When NOT to Use
+
+- Linux/macOS — torch.multiprocessing uses fork() not spawn(), different behavior
+- CPU-only inference — float16 issue doesn't apply
+- Porcupine wake word backend — different engine, different issues
+- No GUI framework — PyQt6 import order issue doesn't apply
+
+## Common Mistakes
+
+- Setting `wakeword_backend` without `wake_words` — silently disables wake word
+- Using `compute_type="float16"` — works in tests, fails in production
+- Importing PyQt6 at module top level — breaks multiprocessing child processes
+- Not debouncing wake word callbacks — causes fragmented audio transcription
+- Forgetting to delete stale config after fixing code defaults
+- Setting MKL_NUM_THREADS after importing numpy/scipy — too late, already allocated
+
+## Diagnostic Script
+
+Use this standalone test to verify wake word detection works independently of RealtimeSTT:
+
+```python
+"""test_wakeword.py — Tests OpenWakeWord directly with microphone"""
+import numpy as np
+import pyaudio
+from openwakeword.model import Model
+import openwakeword
+
+SAMPLE_RATE = 16000
+CHUNK_SIZE = 1280  # 80ms at 16kHz
+THRESHOLD = 0.35
+
+openwakeword.utils.download_models()
+model = Model(inference_framework="onnx")
+print(f"Models: {list(model.models.keys())}")
+
+pa = pyaudio.PyAudio()
+stream = pa.open(format=pyaudio.paInt16, channels=1,
+                 rate=SAMPLE_RATE, input=True,
+                 frames_per_buffer=CHUNK_SIZE)
+try:
+    while True:
+        audio = stream.read(CHUNK_SIZE, exception_on_overflow=False)
+        pcm = np.frombuffer(audio, dtype=np.int16)
+        model.predict(pcm)
+        for name in model.prediction_buffer:
+            score = list(model.prediction_buffer[name])[-1]
+            if score >= THRESHOLD:
+                print(f"DETECTED: {name} (score={score:.4f})")
+            elif score > 0.05:
+                print(f"  heard: {name} (score={score:.4f})")
+except KeyboardInterrupt:
+    pass
+finally:
+    stream.close()
+    pa.terminate()
+```
+
+## Related Skills
+
+- [stripe-payment-integration-complete](../integrations/stripe-payment-integration-complete.md) - Third-party API integration patterns
+- [cloudflare-turnstile-debugging](../integrations/cloudflare-turnstile-debugging.md) - Debugging third-party library integration
+
+## References
+
+- RealtimeSTT: https://github.com/KoljaB/RealtimeSTT
+- OpenWakeWord: https://github.com/dscripka/openWakeWord
+- OpenWakeWord custom model training: https://openwakeword.com/
+- CTranslate2 CUDA: https://github.com/OpenNMT/CTranslate2
+- Contributed from: voice-bridge-v3 (C:\path\to\repos\voice-bridge-v3)

package/skills-library/integrations/rss-podcast-integration.md

@@ -0,0 +1,300 @@
+# Skill: RSS Podcast Integration (Castos/Generic)
+
+**Category:** Integrations
+**Complexity:** Medium
+**Technologies:** Node.js, Express, React, rss-parser, react-h5-audio-player
+
+---
+
+## Overview
+
+Integrate RSS podcast feeds into a web application with support for:
+- Public and private (authenticated) feeds
+- Membership-based access control
+- Episode search and pagination
+- Audio playback with speed control
+- In-memory or Redis caching
+
+---
+
+## When to Use This Skill
+
+- Adding podcast functionality to an LMS or content platform
+- Integrating Castos, Libsyn, Buzzsprout, or any RSS-based podcast service
+- Implementing tiered access (free vs premium content)
+- Building a podcast aggregator
+
+---
+
+## Implementation Pattern
+
+### 1. Backend Service (Node.js/Express)
+
+```javascript
+// server/services/podcastService.js
+import Parser from 'rss-parser';
+
+const parser = new Parser({
+  customFields: {
+    item: [
+      ['itunes:duration', 'duration'],
+      ['itunes:image', 'image'],
+      ['enclosure', 'enclosure']
+    ]
+  }
+});
+
+// Feed configuration
+const PODCAST_FEEDS = {
+  public: {
+    'feed-id': {
+      id: 'feed-id',
+      name: 'Display Name',
+      url: 'https://feeds.castos.com/xxxxx',
+      accessLevel: 'member'
+    }
+  },
+  private: {
+    'private-feed': {
+      id: 'private-feed',
+      name: 'Premium Content',
+      url: 'https://feeds.castos.com/xxxxx?uuid=AUTH_TOKEN',
+      accessLevel: 'partner'
+    }
+  }
+};
+
+// Simple cache
+const cache = new Map();
+const CACHE_TTL = {
+  public: 6 * 60 * 60 * 1000,  // 6 hours
+  private: 2 * 60 * 60 * 1000   // 2 hours
+};
+
+class PodcastService {
+  static async fetchFeed(feedId, user, options = {}) {
+    const feed = this.getFeedConfig(feedId);
+    if (!feed) throw new Error('Feed not found');
+
+    // Check access
+    if (feed.category === 'private' && !this.hasAccess(user)) {
+      throw new Error('Access denied');
+    }
+
+    // Check cache
+    const cached = cache.get(feedId);
+    if (cached && Date.now() - cached.timestamp < CACHE_TTL[feed.category]) {
+      return cached.data;
+    }
+
+    // Fetch fresh
+    const data = await parser.parseURL(feed.url);
+    cache.set(feedId, { data, timestamp: Date.now() });
+    return data;
+  }
+
+  static hasAccess(user) {
+    if (!user) return false;
+    if (user.role === 'admin') return true;
+    const partnerTiers = ['partner', 'premium', 'lifetime'];
+    return partnerTiers.includes(user.membershipTier?.toLowerCase());
+  }
+}
+```
+
+### 2. API Routes
+
+```javascript
+// server/routes/podcastRoutes.js
+import express from 'express';
+import { protect } from '../middleware/auth.js';
+import PodcastService from '../services/podcastService.js';
+
+const router = express.Router();
+
+// List available feeds
+router.get('/', protect, async (req, res) => {
+  const feeds = PodcastService.getAvailableFeeds(req.user);
+  res.json({ success: true, data: feeds });
+});
+
+// Get feed with episodes
+router.get('/:feedId', protect, async (req, res) => {
+  const { limit = 20, offset = 0 } = req.query;
+  const podcast = await PodcastService.fetchFeed(
+    req.params.feedId,
+    req.user,
+    { limit: +limit, offset: +offset }
+  );
+  res.json({ success: true, data: podcast });
+});
+
+// Search episodes
+router.get('/search/episodes', protect, async (req, res) => {
+  const results = await PodcastService.searchEpisodes(
+    req.query.q,
+    req.user
+  );
+  res.json({ success: true, data: results });
+});
+
+export default router;
+```
+
+### 3. Frontend Audio Player
+
+```jsx
+// client/src/components/PodcastPlayer.jsx
+import AudioPlayer from 'react-h5-audio-player';
+import 'react-h5-audio-player/lib/styles.css';
+
+const PodcastPlayer = ({ episode, onPlay, onEnded }) => {
+  const [playbackRate, setPlaybackRate] = useState(1);
+  const playerRef = useRef(null);
+
+  useEffect(() => {
+    if (playerRef.current?.audio?.current) {
+      playerRef.current.audio.current.playbackRate = playbackRate;
+    }
+  }, [playbackRate]);
+
+  return (
+    <div className="podcast-player">
+      <div className="episode-info">
+        <img src={episode.image} alt="" />
+        <h3>{episode.title}</h3>
+        <span>{formatDuration(episode.duration)}</span>
+      </div>
+
+      <AudioPlayer
+        ref={playerRef}
+        src={episode.audioUrl}
+        showJumpControls={true}
+        progressJumpSteps={{ backward: 15000, forward: 30000 }}
+        customAdditionalControls={[
+          <select
+            value={playbackRate}
+            onChange={(e) => setPlaybackRate(+e.target.value)}
+          >
+            {[0.5, 0.75, 1, 1.25, 1.5, 2].map(s => (
+              <option key={s} value={s}>{s}x</option>
+            ))}
+          </select>
+        ]}
+        onPlay={() => onPlay?.(episode)}
+        onEnded={() => onEnded?.(episode)}
+      />
+    </div>
+  );
+};
+```
+
+### 4. Frontend API Service
+
+```javascript
+// client/src/services/podcastService.js
+import api from './api';
+
+export const getAvailableFeeds = () => api.get('/podcasts');
+export const getFeed = (id, { limit, offset }) =>
+  api.get(`/podcasts/${id}`, { params: { limit, offset } });
+export const searchEpisodes = (q) =>
+  api.get('/podcasts/search/episodes', { params: { q } });
+```
+
+---
+
+## NPM Dependencies
+
+```bash
+# Backend
+npm install rss-parser
+
+# Frontend
+npm install react-h5-audio-player
+```
+
+---
+
+## Key Patterns
+
+### Private Feed Authentication (Castos)
+
+Castos private feeds use UUID tokens in the URL:
+```
+https://feeds.castos.com/xxxxx?uuid=YOUR_PRIVATE_UUID
+```
+
+The UUID acts as authentication - store it in your backend config, never expose to client.
+
+### Caching Strategy
+
+| Feed Type | Cache TTL | Reason |
+|-----------|-----------|--------|
+| Public | 6 hours | Content rarely changes |
+| Private | 2 hours | May have more frequent updates |
+
+For production, consider Redis:
+```javascript
+import Redis from 'ioredis';
+const redis = new Redis(process.env.REDIS_URL);
+
+// Cache with TTL
+await redis.setex(`podcast:${feedId}`, CACHE_TTL, JSON.stringify(data));
+```
+
+### Membership-Based Access
+
+```javascript
+// Check user's membership level from database
+const membership = await sql`
+  SELECT ml.slug, ml.access_rank
+  FROM user_memberships um
+  JOIN membership_levels ml ON um.membership_level_id = ml.id
+  WHERE um.user_id = ${userId}
+    AND um.status = 'active'
+`;
+
+// Compare access ranks
+const userRank = membership?.access_rank || 0;
+const requiredRank = feedConfig.accessLevel === 'partner' ? 2 : 1;
+return userRank >= requiredRank;
+```
+
+---
+
+## Common Issues & Solutions
+
+| Issue | Solution |
+|-------|----------|
+| CORS errors fetching RSS | Fetch from backend, not client |
+| Duration parsing | Handle both "HH:MM:SS" and seconds formats |
+| Missing episode images | Fallback to podcast image or default |
+| Audio not playing | Check audio URL, may need proxy for HTTPS |
+
+---
+
+## Testing Checklist
+
+- [ ] Public feeds load for all authenticated users
+- [ ] Private feeds blocked for non-partners
+- [ ] Admin can access all feeds
+- [ ] Search returns results from accessible feeds only
+- [ ] Audio plays correctly
+- [ ] Playback speed control works
+- [ ] Cache invalidates after TTL
+- [ ] Pagination works correctly
+
+---
+
+## Related Skills
+
+- `video-media/audio-player-integration.md`
+- `api-patterns/membership-access-control.md`
+- `deployment-security/caching-strategies.md`
+
+---
+
+**Last Updated:** January 5, 2026
+**Author:** Claude Opus 4.5
+**Project Reference:** my-other-project

package/skills-library/integrations/wordpress/WORDPRESS_LEARNDASH_DATA_RECOVERY.md

@@ -0,0 +1,53 @@
+# WordPress LMS Course Data Recovery - Extraction & Migration
+
+## The Problem
+
+You have WordPress LMS course data exported as JSON files, and need to extract course structure, find embedded media URLs, and recreate the course in a new LMS system.
+
+### Why It Was Hard
+
+- LMS exports are spread across multiple JSON files (courses, lessons, topics)
+- Media URLs are embedded in HTML content fields
+- Course iterations create duplicate entries with slug suffixes like `-2-2-2-3`
+
+---
+
+## The Solution
+
+### LMS Export Structure
+
+| File | Post Type | Contains |
+|------|-----------|----------|
+| `wordpress-courses.json` | `sfwd-courses` | Course metadata |
+| `wordpress-lessons.json` | `sfwd-lessons` | Lesson titles, ordering |
+| `wordpress-topics.json` | `sfwd-topic` | Sub-lessons with actual content/media |
+
+### Extract Media URLs
+
+```bash
+# Find all Castos audio URLs
+grep -oE "https://[^\"']*castos[^\"']*\.mp3" wordpress-topics.json | sort -u
+```
+
+### Generate Embed HTML
+
+```html
+<audio controls style="width:100%">
+  <source src="https://episodes.castos.com/.../file.mp3" type="audio/mpeg">
+</audio>
+```
+
+---
+
+## Key Insight
+
+LMS spreads content across three post types. Lessons often just have titles - the actual content with media is in **Topics**. Always search all three JSON files.
+
+## Difficulty Level
+
+⭐⭐⭐ (3/5)
+
+---
+
+**Author Notes:**
+"Activation completed during a live session" means no audio exists - it was conducted live.