Agent skill

cinema-voice-architect

Expert architect for Cinema Mode, Discipleship Cinema, and audio/voice systems in Raamattu Nyt. Use when: (1) Building or modifying Cinema Mode full-screen verse presentation (2) Implementing audio playback with verse-level synchronization (3) Integrating ElevenLabs TTS voice generation (4) Creating auto-scroll functionality with or without audio (5) Managing audio cues and timing synchronization (6) Working with background music and visual effects (Ken Burns) (7) Implementing dual-track audio (Bible + music) controls (8) Building or modifying Discipleship Cinema Mode (task selector, inline task, verse bar, transition overlay, pomodoro) (9) Working with DiscipleshipVerseBar, DiscipleshipInlineTask, DiscipleshipTaskSelector, DiscipleshipTransitionOverlay, DiscipleshipPomodoroButton (10) Integrating practice/prayer tasks into Cinema full-screen flow (11) Working with Nyt Kooste (daily verse summary collection) in cinema (12) Implementing verse memory quizzes (VerseMemoryQuiz, reading plan memory, smart verse selection) (13) Working with TanaanPage sections (TodayTaskList, TomorrowTasks, PermanentTasks, RecurringTasks) (14) Working with DiscipleshipLandingPage (/opetuslapseus) (15) Working with useDiscipleshipTasks, useNytSummary, useReadingPlanQuiz, useSmartVerseSelection hooks (16) Configuring autoStart reading plan cinema mode vs full discipleship cinema Triggers: "cinema mode", "voice playback", "audio sync", "verse scrolling", "ElevenLabs", "TTS", "audio cues", "auto-advance", "full screen reader", "background music", "Ken Burns", "verse timing", "discipleship cinema", "discipleship-tila", "DiscipleshipVerseBar", "DiscipleshipInlineTask", "DiscipleshipTaskSelector", "pomodoro break", "inline task", "task selector", "transition overlay", "useTodayTasks", "UnifiedTodayTask", "Nyt Kooste", "nyt summary", "verse memory quiz", "VerseMemoryQuiz", "reading plan memory", "useReadingPlanQuiz", "useSmartVerseSelection", "useDiscipleshipTasks", "useNytSummary", "TanaanPage", "tanaan", "opetuslapseus", "discipleship landing", "TodayTaskList", "TomorrowTasksSection", "PermanentTasksSection", "RecurringTasksSection", "initialTask", "nytKoosteRefs", "reading_plan_memory", "verse_memory", "read_memory", "autoStart", "reading plan cinema", "marked_refs"

Stars 0
Forks 0

Install this agent skill to your Project

npx add-skill https://github.com/Spectaculous-Code/raamattu-nyt/tree/main/.claude/skills/cinema-voice-architect

SKILL.md

Cinema Voice Architect

Expert skill for Cinema Mode and audio/voice implementation.

Quick Reference

Component Location
Cinema Screen src/features/cinema/CinemaReaderScreen.tsx
Cinema Background src/components/cinema/CinemaBackground.tsx
Audio Service src/lib/audioService.ts
ElevenLabs Voices src/lib/elevenLabsVoices.ts
Cinema Audio Hook src/hooks/useCinemaAudio.ts
Bible Audio Hook src/hooks/useBibleAudio.ts
Auto-Advance Hook src/hooks/useAutoAdvance.ts
Audio Generation supabase/functions/generate-audio/index.ts
Cinema Preferences Hook src/hooks/useCinemaPreferences.ts
Cinema Fullscreen Hook src/hooks/useCinemaFullscreen.ts
Chapter Bundle Hook src/hooks/useChapterBundle.tsx
Audio Sync src/lib/cinemaAudioSync.ts
Audio Estimation src/lib/audioEstimation.ts
Cinema Types src/types/cinema.ts
Reel Types src/types/reel.ts
Background Music Picker src/components/cinema/BackgroundMusicPicker.tsx
Background Visual Picker src/components/cinema/BackgroundVisualPicker.tsx
Discipleship TaskSelector src/components/cinema/DiscipleshipTaskSelector.tsx
Discipleship InlineTask src/components/cinema/DiscipleshipInlineTask.tsx
Discipleship VerseBar src/components/cinema/DiscipleshipVerseBar.tsx
Discipleship Pomodoro src/components/cinema/DiscipleshipPomodoroButton.tsx
Discipleship Transition src/components/cinema/DiscipleshipTransitionOverlay.tsx
Verse Memory Quiz src/components/practice/VerseMemoryQuiz.tsx
Unified Tasks Hook packages/shared-practices/src/hooks/useTodayTasks.ts
Discipleship Tasks Hook src/hooks/useDiscipleshipTasks.ts
Nyt Summary Hook src/hooks/useNytSummary.ts
Reading Plan Quiz Hook src/hooks/useReadingPlanQuiz.ts
Smart Verse Selection src/hooks/useSmartVerseSelection.ts
Tanaan Page src/pages/TanaanPage.tsx
Discipleship Landing src/pages/DiscipleshipLandingPage.tsx
Today Task List src/components/today/TodayTaskList.tsx
Tomorrow Tasks src/components/today/TomorrowTasksSection.tsx
Permanent Tasks src/components/today/PermanentTasksSection.tsx
Recurring Tasks src/components/today/RecurringTasksSection.tsx
Daily Reading View src/components/reading-plans/DailyReadingView.tsx

Architecture Overview

┌─────────────────────────────────────────────────────────┐
│                   CinemaReaderScreen                     │
│  (Orchestrator: state, audio, visuals, preferences)     │
│  mode: "chapter" | "verseList" | "summaryItems"         │
├─────────────────────────────────────────────────────────┤
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐  │
│  │ useCinema-   │  │ useAuto-     │  │ useCinema-   │  │
│  │ Audio        │  │ Advance      │  │ Preferences  │  │
│  │ (dual-track) │  │ (WPM-based)  │  │ (persist)    │  │
│  └──────────────┘  └──────────────┘  └──────────────┘  │
├─────────────────────────────────────────────────────────┤
│  ┌──────────────────────┐  ┌─────────────────────────┐  │
│  │ CinemaBackground     │  │ @raamattu-nyt/          │  │
│  │ (Ken Burns, video)   │  │ cinema-reader (pkg)     │  │
│  └──────────────────────┘  └─────────────────────────┘  │
├─────────────────────────────────────────────────────────┤
│  Discipleship Mode (mode="verseList"):                   │
│  ┌────────────────┐ ┌────────────────┐ ┌─────────────┐  │
│  │ TaskSelector   │ │ InlineTask     │ │ Transition  │  │
│  │ (pick tasks)   │ │ (prayer/quiz)  │ │ Overlay     │  │
│  └────────────────┘ └────────────────┘ └─────────────┘  │
│  ┌────────────────┐ ┌────────────────┐ ┌─────────────┐  │
│  │ VerseBar       │ │ PomodoroButton │ │ NytKooste   │  │
│  │ (note/share)   │ │ (break timer)  │ │ (summary)   │  │
│  └────────────────┘ └────────────────┘ └─────────────┘  │
│  ┌────────────────┐ ┌────────────────┐                   │
│  │ VerseMemory    │ │ ReadingPlan    │                   │
│  │ Quiz           │ │ Memory Quiz    │                   │
│  └────────────────┘ └────────────────┘                   │
└─────────────────────────────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────┐
│                    Audio Pipeline                        │
├─────────────────────────────────────────────────────────┤
│  generate-audio Edge Function                            │
│  └─→ ElevenLabs API (with timestamps)                   │
│      └─→ audio_assets table (hash-cached)               │
│          └─→ audio_cues table (verse timing)            │
└─────────────────────────────────────────────────────────┘

Cinema Mode Components

CinemaReaderScreen

Main orchestrator at src/features/cinema/CinemaReaderScreen.tsx:

typescript
// Key responsibilities:
// 1. Map BundleVerse → CinemaVerse for cinema-reader package
// 2. Manage dual audio tracks (Bible narration + background music)
// 3. Handle verse navigation (index state)
// 4. Persist preferences to Supabase
// 5. Coordinate background visuals
// 6. Orchestrate discipleship task flow (queue, transitions, quizzes)

Animation Modes

Five animation modes in src/types/cinema.ts: slide, zoom, stack, loopH, loopV

Ken Burns Effect

CinemaBackground.tsx: Random transform over 25s (scale 1.0-1.15, translate ±5%)

Audio System

ElevenLabs Integration

Voices in src/lib/elevenLabsVoices.ts: Venla (female, T5qAFgaL2uYxoUtojUzQ), Urho (male, 1WVCONUwYGulVaKg4oTr)

Audio Generation Flow

Client → Edge Function → check hash cache → ElevenLabs API (with timestamps)
→ parse timestamps → verse cues → store MP3 → save metadata + cues → return

For detailed API reference, see references/elevenlabs-api.md

Audio Cue Format

See references/audio-cue-format.md for full specification.

Auto-Advance (Without Audio)

useAutoAdvance: WPM-based timing (default 150, adjustable 50-400). Min 1.5s per verse. Priority: audio cues > auto-advance timer.

Dual-Track Audio

useCinemaAudio: Bible + background music tracks with independent volume (0-1).

Database Schema

See existing tables: audio_assets, audio_cues, cinema_preferences, background_tracks, background_visuals in bible_schema.

Discipleship Cinema Mode

Immersive full-screen task flow launched from Tanaan page. Guides users through daily reading plans, prayers, practices, and memory quizzes sequentially.

For full details: See references/discipleship-cinema.md

Key Concepts

  • Launched via "Discipleship-tila" button on /tanaanCinemaReaderScreen(mode="verseList")
  • useTodayTasks normalizes practices + plans + prayers → UnifiedTodayTask[]
  • useDiscipleshipTasks convenience hook composes all data sources
  • Task routing: reading_plan → verse reader, prayer/practiceDiscipleshipInlineTask
  • Quiz content types: verse_memory, read_memory, reading_plan_memoryVerseMemoryQuiz
  • Between tasks: DiscipleshipTransitionOverlay with progress bar + free navigation
  • DiscipleshipVerseBar on pause: Add to Nyt Kooste, Note, Share, Pomodoro Break
  • Nyt Kooste: Auto-created daily verse collection, appended as final task
  • Reading Plan Memory Quiz: Auto-inserted after each reading plan day completion (discipleship mode only, NOT autoStart)
  • initialTask prop: Start specific task immediately, bypass selector
  • autoStart prop: Skip task selector, auto-queue all uncompleted tasks, auto-skip transitions
  • Break duration from app_config.discipleship_break_minutes (default 5 min)

Two Cinema Launch Modes from Tanaan

Mode Button Props Behavior
Reading Plan Cinema Blue Play button discipleshipTasks={readingPlanCinemaTasks} autoStart Auto-plays reading plans only. No task selector, no discipleship UI toggle, no memory quizzes, no transition overlays.
Discipleship Cinema Amber Clapperboard button discipleshipTasks={allTasks} Full discipleship flow: task selector → reading + prayer + practice → quizzes → kooste.

autoStart behavior:

  • Queues all uncompleted tasks, starts first immediately (line ~1071-1092)
  • Hides discipleship toggle/next button in CinemaReader (discipleshipMode={false}, no onDiscipleshipToggle)
  • Skips reading plan memory quizzes (!props.autoStart guard on quiz insertion)
  • Auto-skips transition overlays between tasks (useEffect at line ~1285-1290)
  • When all tasks done: calls onAllTasksCompleted and closes

Reading Plan Completion

handleComplete calls mark_reading_day_complete RPC when a reading plan finishes. Key details:

  • Completion-type plans: RPC advances current_day immediately (e.g. 5→6)
  • Dashboard fix: get_today_dashboard checks completed_at::date = CURRENT_DATE for completion-type plans (not current_day which already advanced)
  • Client-side fix: useTodayTasks checks completed_days.includes(current_day - 1) for completion-type plans as fallback
  • Query invalidation: Must invalidate ["today-dashboard"], ["reading-plan-streaks"], AND ["user-reading-plans"]

Reading Plan Memory Quiz

useReadingPlanQuiz generates a 3-verse quiz after reading plan completion:

  • Picks 2 plan verses + 1 decoy (from user highlights or well-known verses)
  • Marked verse priority: Verses user marked via DiscipleshipVerseBar (marked_refs in quiz task metadata) are selected first
  • Priority: marked refs in plan → preferred books (NT, Psalms, Proverbs) → any plan verse
  • Quiz task metadata includes marked_refs: string[] populated from nytKoosteRefsRef.current

Tanaan Page Sections

Section Component Content
Päivän tehtävät TodayTaskList Uncompleted + completed tasks with quick complete
Huomisen tehtävät TomorrowTasksSection Next day preview (collapsible)
Pysyvät tehtävät PermanentTasksSection Prayers with priority_level='always'
Toistuvat tehtävät RecurringTasksSection Active plans + subscribed prayer calendars
Tilaa harjoitus PracticeActivationCard Available templates to subscribe

DiscipleshipLandingPage

Marketing page at /opetuslapseus (fi) / /en/discipleship (en). Four pillars: Read, Pray, Reflect, Practice. JSON-LD SEO (WebPage + FAQPage).

Discipleship Files

src/components/cinema/
├── DiscipleshipTaskSelector.tsx    # Task picker before cinema
├── DiscipleshipInlineTask.tsx      # Full-screen prayer/practice/quiz view
├── DiscipleshipVerseBar.tsx        # Verse action bar (note, share, break, add to kooste)
├── DiscipleshipPomodoroButton.tsx  # Break timer
└── DiscipleshipTransitionOverlay.tsx # Between-task progress + free navigation

src/components/practice/
└── VerseMemoryQuiz.tsx             # Quiz for verse/reading plan memory

src/components/today/
├── TodayTaskList.tsx               # Päivän tehtävät section
├── TomorrowTasksSection.tsx        # Tomorrow preview
├── PermanentTasksSection.tsx       # Always-priority prayers
└── RecurringTasksSection.tsx       # Active plans + prayer calendars

src/hooks/
├── useDiscipleshipTasks.ts         # Convenience wrapper for all task sources
├── useNytSummary.ts                # Daily verse summary collection
├── useReadingPlanQuiz.ts           # Generate quiz from reading plan day
└── useSmartVerseSelection.ts       # Priority-based verse picking for quizzes

Common Tasks

Add New Voice

  1. Get voice ID from ElevenLabs → add to elevenLabsVoices.ts → add to admin UI → use elevenlabs:{voiceId} format

Debug Audio Sync

Add interval logging in useCinemaAudio to trace findCurrentCue() output.

File Structure

src/
├── features/cinema/
│   └── CinemaReaderScreen.tsx    # Main orchestrator
├── components/cinema/
│   ├── CinemaBackground.tsx      # Video/image + Ken Burns
│   ├── BackgroundMusicPicker.tsx  # Music selection UI
│   ├── BackgroundVisualPicker.tsx # Visual selection UI
│   ├── DiscipleshipTaskSelector.tsx
│   ├── DiscipleshipInlineTask.tsx
│   ├── DiscipleshipVerseBar.tsx
│   ├── DiscipleshipPomodoroButton.tsx
│   └── DiscipleshipTransitionOverlay.tsx
├── components/today/
│   ├── TodayTaskList.tsx
│   ├── TomorrowTasksSection.tsx
│   ├── PermanentTasksSection.tsx
│   └── RecurringTasksSection.tsx
├── components/practice/
│   └── VerseMemoryQuiz.tsx
├── hooks/
│   ├── useCinemaAudio.ts         # Dual-track audio
│   ├── useBibleAudio.ts          # Single-track audio
│   ├── useAutoAdvance.ts         # WPM-based scrolling
│   ├── useCinemaPreferences.ts   # Preferences persistence
│   ├── useCinemaFullscreen.ts    # Fullscreen API
│   ├── useChapterBundle.tsx      # Bundle with audio data
│   ├── useDiscipleshipTasks.ts
│   ├── useNytSummary.ts
│   ├── useReadingPlanQuiz.ts
│   └── useSmartVerseSelection.ts
├── lib/
│   ├── audioService.ts           # Audio generation client
│   ├── elevenLabsVoices.ts       # Voice configurations
│   ├── cinemaAudioSync.ts        # Cue-to-verse mapping
│   └── audioEstimation.ts        # Word count timing
├── types/
│   ├── cinema.ts                 # Cinema types & defaults
│   └── reel.ts                   # Reel rendering types
├── pages/
│   ├── TanaanPage.tsx
│   └── DiscipleshipLandingPage.tsx
supabase/functions/
└── generate-audio/
    └── index.ts                  # ElevenLabs Edge Function
packages/shared-practices/src/hooks/
└── useTodayTasks.ts              # Unified task normalization

References

  • references/audio-cue-format.md - Detailed cue timing specification
  • references/elevenlabs-api.md - ElevenLabs API reference
  • references/discipleship-cinema.md - Full discipleship cinema mode documentation (components, hooks, flows, gotchas)
  • references/reading-plan-transition.md - State flow for "Next Day" in reading plan cinema mode
  • references/learnings.md - Bug patterns and fixes

Cross-cutting learnings: See .claude/LEARNINGS.md → "CSS/Layout" section for framer-motion patterns and animation gotchas.

Expand your agent's capabilities with these related and highly-rated skills.

Spectaculous-Code/raamattu-nyt

docs-updater

Expert assistant for keeping documentation synchronized with code changes in the KR92 Bible Voice project. Use when updating API docs, maintaining architecture diagrams, syncing README, updating CLAUDE.MD, or generating documentation from code.

0 0
Explore
Spectaculous-Code/raamattu-nyt

ai-prompt-manager

Expert assistant for managing AI prompts, features, and configuration in the KR92 Bible Voice AI system. Use when creating AI prompts, configuring AI features, managing prompt versions, setting up AI bindings, or working with AI pricing and models.

0 0
Explore
Spectaculous-Code/raamattu-nyt

performance-auditor

Expert assistant for monitoring and optimizing performance in the KR92 Bible Voice project. Use when analyzing query performance, optimizing database indexes, reviewing React Query caching, monitoring AI call costs, or identifying N+1 queries.

0 0
Explore
Spectaculous-Code/raamattu-nyt

edge-function-generator

Expert assistant for creating and maintaining Supabase Edge Functions for the KR92 Bible Voice project. Use when creating Edge Functions, setting up CORS, integrating shared modules, adding JWT validation, or configuring environment variables.

0 0
Explore
Spectaculous-Code/raamattu-nyt

admin-panel-builder

Expert assistant for creating and maintaining admin panel pages in the KR92 Bible Voice project. Use when creating admin pages, building admin components, integrating with admin navigation, or adding admin features.

0 0
Explore
Spectaculous-Code/raamattu-nyt

lint-fixer

Expert assistant for analyzing and fixing linting and formatting issues in the KR92 Bible Voice project using Biome and TypeScript. Use when fixing lint errors, resolving TypeScript issues, applying code formatting, or reviewing code quality.

0 0
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results