/cm-readit

name: cm-readit
description: Turn any website into an audio-enabled experience. Covers TTS reading mode (SpeechSynthesis API), pre-recorded MP3 audio player, and Voice CRO trigger system. Zero dependencies, works on any static or dynamic site. Use when adding read-aloud, audio player, or voice-based conversion features.
allowed-tools: Read, Write, Edit, Glob, Grep, Bash

CM ReadIt — Web Audio Experience Skill

> **Philosophy:** Reading is passive. Listening is intimate. Voice builds trust faster than any headline. > **Core Principle:** Zero dependencies. Progressive enhancement. Respect user's device and preferences.

---

🎯 Selective Reading Rule (MANDATORY)

| File | Status | When to Read | |------|--------|--------------| | [tts-engine.md](tts-engine.md) | 🔴 **REQUIRED** | Adding TTS / read-aloud to any page | | [audio-player.md](audio-player.md) | ⚪ Optional | Pre-recorded MP3 playback | | [voice-cro.md](voice-cro.md) | ⚪ Optional | Trigger-based voice sales / CRO | | [ui-patterns.md](ui-patterns.md) | ⚪ Optional | Player bar & bottom sheet design |

> 🔴 **tts-engine.md = ALWAYS READ when implementing TTS. Others = only if relevant.**

---

Quick Decision Tree

"I need audio on my website"
│
├─ Read article content aloud (text-to-speech)
│  └─ Use: TTS Engine → tts-engine.md
│     ├─ Blog / article pages → Content Reader pattern
│     ├─ Documentation → Section Reader pattern
│     └─ E-commerce → Product Description Reader pattern
│
├─ Play pre-recorded audio files (MP3/WAV)
│  └─ Use: Audio Player → audio-player.md
│     ├─ Podcasts / interviews → Playlist pattern
│     ├─ Sales pitch / welcome → Triggered playback
│     └─ Background ambient → Loop pattern
│
├─ Voice-based conversion optimization (CRO)
│  └─ Use: Voice CRO → voice-cro.md
│     ├─ Landing pages → Trigger-based bottom sheet
│     ├─ Service pages → Per-page audio scripts
│     └─ Course pages → Social proof audio
│
└─ Combination (TTS + CRO)
   └─ Read tts-engine.md + voice-cro.md
      └─ Ensure no conflict (TTS reader vs CRO player)

---

🧠 Core Principles (Internalize These)

1. The 3 Audio Engines

| Engine | API | Source | Best For | |--------|-----|--------|----------| | **TTS Reader** | `SpeechSynthesis` | Page text content | Blogs, articles, docs | | **Audio Player** | `HTMLAudioElement` | Pre-recorded MP3 | Sales, podcasts, guides | | **Voice CRO** | `Audio` + triggers | MP3 + behavior detection | Landing pages, sales |

2. Progressive Enhancement

Feature detection → Graceful degradation → Never break the page

if (!('speechSynthesis' in window)) return;  // TTS
if (!window.Audio) return;                    // Audio

**Rule:** Audio features are ENHANCEMENTS. The page must function 100% without them.

3. Content Extraction Principle

Clone → Strip → Clean → Split → Speak

DON'T read the raw DOM.
DO clone, remove noise, extract clean text.

**Strip list (always remove before speaking):**

• CTAs, promotions, ads
• Navigation, footer, sidebar
• Images, videos, iframes, SVGs
• Scripts, styles, hidden elements
• Tags, badges, metadata

4. The Chunking Problem

Browsers have a **hard limit** on utterance length (~3000-5000 chars depending on browser/OS). Long text must be split into chunks.

Split Strategy:
├─ Split on sentence boundaries (. ! ? \n)
├─ Max chunk: 2500 chars (safe across all browsers)
├─ Preserve sentence integrity (never split mid-sentence)
└─ Chain chunks via onend callback

5. Voice Selection Priority

Language voices:
1. Local service voice (faster, works offline)
2. Network voice (higher quality, needs internet)
3. Any voice matching language prefix
4. null (browser default)

6. Chrome Keep-Alive Bug

> ⚠️ **CRITICAL:** Chrome silently stops SpeechSynthesis after ~15 seconds of continuous speech. This is the #1 gotcha.

// Workaround: pause/resume every 10s
setInterval(() => {
    if (synth.speaking && !synth.paused) {
        synth.pause();
        synth.resume();
    }
}, 10000);

7. synth.cancel() Triggers onerror

> ⚠️ **GOTCHA:** Calling `synth.cancel()` fires the `onerror` event on any active utterance with error type `'canceled'` or `'interrupted'`.

**Solution:** Use a guard flag or check error type:

u.onerror = function(e) {
    if (e.error === 'canceled' || e.error === 'interrupted') return;
    stopReading();
};

---

🏗️ Architecture Pattern

Minimal TTS Reader (Copy-Paste Starting Point)

┌─────────────────────────────────────────┐
│                  IIFE                    │
│                                          │
│  ┌─ Feature Detection ─┐                │
│  │  speechSynthesis?    │                │
│  └──────────┬───────────┘                │
│             ▼                            │
│  ┌─ Content Extraction ─┐               │
│  │  Clone → Strip → Clean│              │
│  └──────────┬────────────┘               │
│             ▼                            │
│  ┌─ Chunking Engine ────┐               │
│  │  Split on sentences   │              │
│  │  Max 2500 chars       │              │
│  └──────────┬────────────┘               │
│             ▼                            │
│  ┌─ Utterance Builder ──┐               │
│  │  Set voice/rate/pitch │              │
│  │  Chain via onend      │              │
│  └──────────┬────────────┘               │
│             ▼                            │
│  ┌─ Player UI ──────────┐               │
│  │  Bar: play/pause/stop │              │
│  │  Progress indicator   │              │
│  │  Trigger button       │              │
│  └──────────┬────────────┘               │
│             ▼                            │
│  ┌─ Keep-Alive Timer ───┐               │
│  │  pause/resume @ 10s  │               │
│  └───────────────────────┘               │
└──────────────────────────────────────────┘

Lifecycle

Init → Detect → Inject Trigger Button
         │
   User clicks ▶
         │