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"
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:
// 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
/tanaan→CinemaReaderScreen(mode="verseList") useTodayTasksnormalizes practices + plans + prayers →UnifiedTodayTask[]useDiscipleshipTasksconvenience hook composes all data sources- Task routing:
reading_plan→ verse reader,prayer/practice→DiscipleshipInlineTask - Quiz content types:
verse_memory,read_memory,reading_plan_memory→VerseMemoryQuiz - Between tasks:
DiscipleshipTransitionOverlaywith progress bar + free navigation DiscipleshipVerseBaron 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}, noonDiscipleshipToggle) - Skips reading plan memory quizzes (
!props.autoStartguard on quiz insertion) - Auto-skips transition overlays between tasks (useEffect at line ~1285-1290)
- When all tasks done: calls
onAllTasksCompletedand closes
Reading Plan Completion
handleComplete calls mark_reading_day_complete RPC when a reading plan finishes. Key details:
- Completion-type plans: RPC advances
current_dayimmediately (e.g. 5→6) - Dashboard fix:
get_today_dashboardcheckscompleted_at::date = CURRENT_DATEfor completion-type plans (notcurrent_daywhich already advanced) - Client-side fix:
useTodayTaskscheckscompleted_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_refsin 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 fromnytKoosteRefsRef.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
- Get voice ID from ElevenLabs → add to
elevenLabsVoices.ts→ add to admin UI → useelevenlabs:{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 specificationreferences/elevenlabs-api.md- ElevenLabs API referencereferences/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 modereferences/learnings.md- Bug patterns and fixes
Cross-cutting learnings: See .claude/LEARNINGS.md → "CSS/Layout" section for framer-motion patterns and animation gotchas.
Recommended Agent Skills
Expand your agent's capabilities with these related and highly-rated skills.
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.
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.
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.
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.
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.
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.
Didn't find tool you were looking for?