react-native-teleflow-prompter 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Muhammet Atmaca (https://muhammetatmaca.com.tr)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,186 @@
+# react-native-teleflow-prompter
+
+[![npm version](https://img.shields.io/npm/v/react-native-teleflow-prompter.svg?style=flat-square)](https://www.npmjs.com/package/react-native-teleflow-prompter)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square)](https://opensource.org/licenses/MIT)
+[![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue.svg?style=flat-square)](https://www.typescriptlang.org/)
+[![React Native](https://img.shields.io/badge/React%20Native-Compatible-61dafb.svg?style=flat-square)](https://reactnative.dev/)
+[![Expo](https://img.shields.io/badge/Expo-Compatible-black.svg?style=flat-square)](https://expo.dev/)
+
+> High-performance 60 FPS teleprompter scrolling engine, Words-Per-Minute (WPM) speed calculator, speech timing math, and mirror optics transform generator for **React Native**, **Expo**, and **Web**.
+
+Extracted from and powering the production mobile app [**TeleFlow Prompter**](https://muhammetatmaca.com.tr/apps/teleflow-prompter) by [**Muhammet Atmaca**](https://muhammetatmaca.com.tr/) ([VirelonSoft](https://www.linkedin.com/company/virelonsoft/)).
+
+---
+
+## ✨ Features
+
+- 🏎️ **Butter-Smooth 60 FPS Scrolling**: Frame-independent delta timing via `requestAnimationFrame` preventing jitter on low-end devices.
+- ⏱️ **Words-Per-Minute (WPM) Calculator**: Compute exact speech durations based on conversational, presentation, or reading speeds (120–180 WPM).
+- 🪞 **Beam-Splitter Mirror Optics**: Native style transformations (`scaleX: -1`, `scaleY: -1`) for physical teleprompter glass reflection rigs.
+- 🧩 **Zero Dependencies**: Pure TypeScript, ultra-lightweight (< 3 kB gzipped).
+- 📱 **Universal Compatibility**: Works out of the box with React Native (Bare & Expo), React Web, Next.js, and Node.js.
+
+---
+
+## 📦 Installation
+
+```bash
+# npm
+npm install react-native-teleflow-prompter
+
+# pnpm
+pnpm add react-native-teleflow-prompter
+
+# yarn
+yarn add react-native-teleflow-prompter
+```
+
+---
+
+## 🚀 Quick Start (React Native & Expo)
+
+```tsx
+import React, { useRef, useEffect } from 'react';
+import { View, Text, ScrollView, TouchableOpacity, StyleSheet } from 'react-native';
+import { useTeleprompter, getMirrorTransform } from 'react-native-teleflow-prompter';
+
+export default function PrompterScreen() {
+  const scrollViewRef = useRef<ScrollView>(null);
+
+  const script = `
+    Welcome to this presentation. Today we are demonstrating
+    the TeleFlow teleprompter engine running smoothly at 60 FPS
+    with automatic Words-Per-Minute speed calculation.
+  `;
+
+  const {
+    isPlaying,
+    scrollOffset,
+    progress,
+    elapsedSeconds,
+    remainingSeconds,
+    totalDurationSeconds,
+    wpm,
+    toggle,
+    reset,
+    setWpm,
+  } = useTeleprompter({
+    text: script,
+    initialWpm: 145,
+    contentHeight: 1200,
+    viewportHeight: 500,
+    onComplete: () => console.log('Speech finished!'),
+  });
+
+  // Automatically scroll to calculated pixel offset
+  useEffect(() => {
+    scrollViewRef.current?.scrollTo({ y: scrollOffset, animated: false });
+  }, [scrollOffset]);
+
+  return (
+    <View style={styles.container}>
+      {/* Mirror transform support for teleprompter glass rigs */}
+      <View style={[styles.viewport, getMirrorTransform('none')]}>
+        <ScrollView ref={scrollViewRef} scrollEnabled={false}>
+          <Text style={styles.scriptText}>{script}</Text>
+        </ScrollView>
+      </View>
+
+      {/* Controller HUD */}
+      <View style={styles.hud}>
+        <Text style={styles.timer}>
+          {Math.floor(elapsedSeconds / 60)}:{(elapsedSeconds % 60).toString().padStart(2, '0')} / 
+          {Math.floor(totalDurationSeconds / 60)}:{(totalDurationSeconds % 60).toString().padStart(2, '0')}
+        </Text>
+        <Text style={styles.wpm}>{wpm} WPM ({(progress * 100).toFixed(0)}%)</Text>
+
+        <View style={styles.buttons}>
+          <TouchableOpacity onPress={toggle} style={styles.btn}>
+            <Text style={styles.btnText}>{isPlaying ? 'Pause' : 'Play'}</Text>
+          </TouchableOpacity>
+          <TouchableOpacity onPress={reset} style={styles.btn}>
+            <Text style={styles.btnText}>Reset</Text>
+          </TouchableOpacity>
+          <TouchableOpacity onPress={() => setWpm(wpm + 10)} style={styles.btn}>
+            <Text style={styles.btnText}>+10 WPM</Text>
+          </TouchableOpacity>
+          <TouchableOpacity onPress={() => setWpm(wpm - 10)} style={styles.btn}>
+            <Text style={styles.btnText}>-10 WPM</Text>
+          </TouchableOpacity>
+        </View>
+      </View>
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  container: { flex: 1, backgroundColor: '#0f172a' },
+  viewport: { height: 500, padding: 24 },
+  scriptText: { color: '#f8fafc', fontSize: 32, lineHeight: 48, fontWeight: '600' },
+  hud: { padding: 20, borderTopWidth: 1, borderColor: '#334155' },
+  timer: { color: '#38bdf8', fontSize: 20, fontWeight: 'bold' },
+  wpm: { color: '#94a3b8', fontSize: 14, marginBottom: 12 },
+  buttons: { flexDirection: 'row', gap: 10 },
+  btn: { backgroundColor: '#2563eb', paddingVertical: 10, paddingHorizontal: 16, borderRadius: 8 },
+  btnText: { color: '#ffffff', fontWeight: 'bold' },
+});
+```
+
+---
+
+## 🛠️ Standalone Calculation Utilities
+
+You can use the math utilities without React or React Native:
+
+```ts
+import { 
+  countWords, 
+  calculateDuration, 
+  calculateWpm, 
+  calculateScrollVelocity, 
+  getMirrorTransform,
+  chunkScript 
+} from 'react-native-teleflow-prompter';
+
+// 1. Count words accurately
+const wordCount = countWords("Hello world! Teleprompter math is easy."); // 6
+
+// 2. Estimate speech duration (at 150 WPM)
+const durationSeconds = calculateDuration(wordCount, 150); // seconds
+
+// 3. Calculate target WPM from fixed video length (e.g., 300 words in 120s)
+const targetWpm = calculateWpm(300, 120); // 150 WPM
+
+// 4. Calculate exact scroll velocity (pixels per second)
+const velocity = calculateScrollVelocity(2400, 800, 120); // px/sec
+
+// 5. Mirror transform for hardware beam-splitter glass
+const mirrorStyle = getMirrorTransform('horizontal'); // { transform: [{ scaleX: -1 }] }
+```
+
+---
+
+## 🎙️ Words-Per-Minute (WPM) Benchmark Guide
+
+| Speech Type | WPM Range | Typical Use Case |
+| :--- | :--- | :--- |
+| **Deliberate / Slow** | 100 – 125 WPM | Formal speeches, technical training, audiobooks |
+| **Conversational** | 130 – 160 WPM | Video podcasts, YouTube videos, YouTube Shorts / Reels |
+| **Rapid / Energetic** | 165 – 190 WPM | TV broadcast reporting, auctioneers, fast-paced marketing |
+
+---
+
+## 👨‍💻 Author & Credits
+
+Developed with ❤️ by **[Muhammet Atmaca](https://muhammetatmaca.com.tr)**:
+- 🌐 **Official Website**: [https://muhammetatmaca.com.tr](https://muhammetatmaca.com.tr)
+- 📱 **TeleFlow Prompter Mobile App**: [View on Portfolio](https://muhammetatmaca.com.tr/apps/teleflow-prompter)
+- 🐙 **GitHub**: [@muhammetatmaca](https://github.com/muhammetatmaca)
+- 💼 **LinkedIn**: [Muhammet Atmaca](https://www.linkedin.com/in/muhammet-atmaca-857481252/)
+- 🏢 **Company**: [VirelonSoft](https://www.linkedin.com/company/virelonsoft/)
+
+---
+
+## 📄 License
+
+MIT © [Muhammet Atmaca](https://muhammetatmaca.com.tr)

package/dist/index.d.ts

@@ -0,0 +1,97 @@
+/**
+ * react-native-teleflow-prompter
+ *
+ * High-performance 60fps teleprompter scroll engine, speech timing math,
+ * and mirror optics for React Native, Expo, and Web applications.
+ *
+ * Developed by Muhammet Atmaca (VirelonSoft)
+ * Website: https://muhammetatmaca.com.tr
+ * Portfolio App: TeleFlow Prompter (https://muhammetatmaca.com.tr/apps/teleflow-prompter)
+ * License: MIT
+ */
+export type MirrorMode = 'none' | 'horizontal' | 'vertical' | 'both';
+export interface ScriptChunk {
+    id: number;
+    text: string;
+    wordCount: number;
+    estimatedDurationSeconds: number;
+}
+export interface TeleprompterOptions {
+    /** The text content to be displayed and spoken */
+    text: string;
+    /** Initial speech speed in Words Per Minute (typical: 130 - 170 WPM) */
+    initialWpm?: number;
+    /** Total height of the scrollable content view in pixels */
+    contentHeight?: number;
+    /** Height of the visible screen/viewport in pixels */
+    viewportHeight?: number;
+    /** Auto-scroll frame rate target (default: 60) */
+    fps?: number;
+    /** Callback fired when scrolling reaches the end */
+    onComplete?: () => void;
+}
+export interface TeleprompterController {
+    /** Whether the prompter is currently actively scrolling */
+    isPlaying: boolean;
+    /** Progress through the text from 0.0 to 1.0 */
+    progress: number;
+    /** Calculated scroll offset in pixels */
+    scrollOffset: number;
+    /** Elapsed time in seconds */
+    elapsedSeconds: number;
+    /** Estimated remaining time in seconds */
+    remainingSeconds: number;
+    /** Total estimated speech duration in seconds */
+    totalDurationSeconds: number;
+    /** Current speech speed in words per minute */
+    wpm: number;
+    /** Total word count of the script */
+    wordCount: number;
+    /** Start scrolling */
+    play: () => void;
+    /** Pause scrolling */
+    pause: () => void;
+    /** Toggle play/pause state */
+    toggle: () => void;
+    /** Reset prompter to start (0 offset) */
+    reset: () => void;
+    /** Change speed in Words Per Minute */
+    setWpm: (newWpm: number) => void;
+    /** Seek directly to a progress position (0.0 to 1.0) */
+    seek: (progressRatio: number) => void;
+}
+/**
+ * Counts words accurately across multiple languages and whitespace boundaries.
+ */
+export declare function countWords(text: string): number;
+/**
+ * Calculates estimated speech duration in seconds based on word count and WPM.
+ */
+export declare function calculateDuration(wordCount: number, wpm?: number): number;
+/**
+ * Calculates the Words Per Minute rate from word count and duration.
+ */
+export declare function calculateWpm(wordCount: number, durationSeconds: number): number;
+/**
+ * Calculates pixel scroll velocity (pixels per second) needed to finish
+ * the entire content within the target duration.
+ */
+export declare function calculateScrollVelocity(contentHeight: number, viewportHeight: number | undefined, durationSeconds: number): number;
+/**
+ * Returns React Native compatible transform style for beam-splitter mirror optics.
+ * Physical teleprompter glass reflects text reversed, requiring horizontal or vertical inversion.
+ */
+export declare function getMirrorTransform(mode?: MirrorMode): {
+    transform: Array<{
+        scaleX?: number;
+        scaleY?: number;
+    }>;
+};
+/**
+ * Splits a long script into digestible chunks with word counts and time estimates.
+ */
+export declare function chunkScript(text: string, maxWordsPerChunk?: number): ScriptChunk[];
+/**
+ * React Hook providing a high-precision, 60fps auto-scroll controller for teleprompters.
+ */
+export declare function useTeleprompter(options: TeleprompterOptions): TeleprompterController;

package/dist/index.js

@@ -0,0 +1,195 @@
+"use strict";
+/**
+ * react-native-teleflow-prompter
+ *
+ * High-performance 60fps teleprompter scroll engine, speech timing math,
+ * and mirror optics for React Native, Expo, and Web applications.
+ *
+ * Developed by Muhammet Atmaca (VirelonSoft)
+ * Website: https://muhammetatmaca.com.tr
+ * Portfolio App: TeleFlow Prompter (https://muhammetatmaca.com.tr/apps/teleflow-prompter)
+ * License: MIT
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.countWords = countWords;
+exports.calculateDuration = calculateDuration;
+exports.calculateWpm = calculateWpm;
+exports.calculateScrollVelocity = calculateScrollVelocity;
+exports.getMirrorTransform = getMirrorTransform;
+exports.chunkScript = chunkScript;
+exports.useTeleprompter = useTeleprompter;
+const react_1 = require("react");
+/**
+ * Counts words accurately across multiple languages and whitespace boundaries.
+ */
+function countWords(text) {
+    if (!text || typeof text !== 'string')
+        return 0;
+    const trimmed = text.trim();
+    if (!trimmed)
+        return 0;
+    return trimmed.split(/\s+/).filter(Boolean).length;
+}
+/**
+ * Calculates estimated speech duration in seconds based on word count and WPM.
+ */
+function calculateDuration(wordCount, wpm = 140) {
+    if (wordCount <= 0 || wpm <= 0)
+        return 0;
+    return Math.round((wordCount / wpm) * 60);
+}
+/**
+ * Calculates the Words Per Minute rate from word count and duration.
+ */
+function calculateWpm(wordCount, durationSeconds) {
+    if (wordCount <= 0 || durationSeconds <= 0)
+        return 0;
+    return Math.round((wordCount / durationSeconds) * 60);
+}
+/**
+ * Calculates pixel scroll velocity (pixels per second) needed to finish
+ * the entire content within the target duration.
+ */
+function calculateScrollVelocity(contentHeight, viewportHeight = 0, durationSeconds) {
+    if (durationSeconds <= 0)
+        return 0;
+    const scrollableDistance = Math.max(0, contentHeight - viewportHeight);
+    return scrollableDistance / durationSeconds;
+}
+/**
+ * Returns React Native compatible transform style for beam-splitter mirror optics.
+ * Physical teleprompter glass reflects text reversed, requiring horizontal or vertical inversion.
+ */
+function getMirrorTransform(mode = 'none') {
+    switch (mode) {
+        case 'horizontal':
+            return { transform: [{ scaleX: -1 }] };
+        case 'vertical':
+            return { transform: [{ scaleY: -1 }] };
+        case 'both':
+            return { transform: [{ scaleX: -1 }, { scaleY: -1 }] };
+        case 'none':
+        default:
+            return { transform: [{ scaleX: 1 }, { scaleY: 1 }] };
+    }
+}
+/**
+ * Splits a long script into digestible chunks with word counts and time estimates.
+ */
+function chunkScript(text, maxWordsPerChunk = 40) {
+    if (!text)
+        return [];
+    const words = text.trim().split(/\s+/).filter(Boolean);
+    const chunks = [];
+    let currentWords = [];
+    for (let i = 0; i < words.length; i++) {
+        currentWords.push(words[i]);
+        const isLastWord = i === words.length - 1;
+        const reachedLimit = currentWords.length >= maxWordsPerChunk;
+        const endsWithPeriod = /[.!?]$/.test(words[i]);
+        if (isLastWord || (reachedLimit && endsWithPeriod) || currentWords.length >= maxWordsPerChunk * 1.5) {
+            const chunkText = currentWords.join(' ');
+            const chunkCount = currentWords.length;
+            chunks.push({
+                id: chunks.length + 1,
+                text: chunkText,
+                wordCount: chunkCount,
+                estimatedDurationSeconds: calculateDuration(chunkCount, 140),
+            });
+            currentWords = [];
+        }
+    }
+    return chunks;
+}
+/**
+ * React Hook providing a high-precision, 60fps auto-scroll controller for teleprompters.
+ */
+function useTeleprompter(options) {
+    const { text, initialWpm = 140, contentHeight = 1000, viewportHeight = 400, onComplete, } = options;
+    const wordCount = countWords(text);
+    const [wpm, setWpmState] = (0, react_1.useState)(initialWpm);
+    const [isPlaying, setIsPlaying] = (0, react_1.useState)(false);
+    const [scrollOffset, setScrollOffset] = (0, react_1.useState)(0);
+    const totalDurationSeconds = calculateDuration(wordCount, wpm);
+    const scrollableDistance = Math.max(0, contentHeight - viewportHeight);
+    const lastFrameTimeRef = (0, react_1.useRef)(null);
+    const rafIdRef = (0, react_1.useRef)(null);
+    const onCompleteRef = (0, react_1.useRef)(onComplete);
+    onCompleteRef.current = onComplete;
+    const play = (0, react_1.useCallback)(() => {
+        setIsPlaying(true);
+    }, []);
+    const pause = (0, react_1.useCallback)(() => {
+        setIsPlaying(false);
+        lastFrameTimeRef.current = null;
+    }, []);
+    const toggle = (0, react_1.useCallback)(() => {
+        setIsPlaying((prev) => !prev);
+    }, []);
+    const reset = (0, react_1.useCallback)(() => {
+        setIsPlaying(false);
+        setScrollOffset(0);
+        lastFrameTimeRef.current = null;
+    }, []);
+    const setWpm = (0, react_1.useCallback)((newWpm) => {
+        if (newWpm > 20 && newWpm <= 400) {
+            setWpmState(newWpm);
+        }
+    }, []);
+    const seek = (0, react_1.useCallback)((progressRatio) => {
+        const clamped = Math.max(0, Math.min(1, progressRatio));
+        setScrollOffset(clamped * scrollableDistance);
+    }, [scrollableDistance]);
+    // 60 FPS animation loop
+    (0, react_1.useEffect)(() => {
+        if (!isPlaying || scrollableDistance <= 0 || totalDurationSeconds <= 0) {
+            if (rafIdRef.current)
+                cancelAnimationFrame(rafIdRef.current);
+            lastFrameTimeRef.current = null;
+            return;
+        }
+        const velocityPxPerSec = scrollableDistance / totalDurationSeconds;
+        const tick = (now) => {
+            if (lastFrameTimeRef.current === null) {
+                lastFrameTimeRef.current = now;
+            }
+            const deltaSeconds = (now - lastFrameTimeRef.current) / 1000;
+            lastFrameTimeRef.current = now;
+            setScrollOffset((prev) => {
+                const next = prev + velocityPxPerSec * deltaSeconds;
+                if (next >= scrollableDistance) {
+                    setIsPlaying(false);
+                    if (onCompleteRef.current)
+                        onCompleteRef.current();
+                    return scrollableDistance;
+                }
+                return next;
+            });
+            rafIdRef.current = requestAnimationFrame(tick);
+        };
+        rafIdRef.current = requestAnimationFrame(tick);
+        return () => {
+            if (rafIdRef.current)
+                cancelAnimationFrame(rafIdRef.current);
+        };
+    }, [isPlaying, scrollableDistance, totalDurationSeconds]);
+    const progress = scrollableDistance > 0 ? Math.min(1, scrollOffset / scrollableDistance) : 0;
+    const elapsedSeconds = Math.round(progress * totalDurationSeconds);
+    const remainingSeconds = Math.max(0, totalDurationSeconds - elapsedSeconds);
+    return {
+        isPlaying,
+        progress,
+        scrollOffset,
+        elapsedSeconds,
+        remainingSeconds,
+        totalDurationSeconds,
+        wpm,
+        wordCount,
+        play,
+        pause,
+        toggle,
+        reset,
+        setWpm,
+        seek,
+    };
+}

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "react-native-teleflow-prompter",
+  "version": "1.0.0",
+  "description": "High-performance 60fps teleprompter scroll engine, WPM calculation, and mirror optics for React Native, Expo, and Web.",
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc"
+  },
+  "keywords": [
+    "react-native",
+    "expo",
+    "teleprompter",
+    "prompter",
+    "teleflow",
+    "autoscroll",
+    "speech-timer",
+    "wpm-calculator",
+    "mirror-optics",
+    "video-recording",
+    "muhammet-atmaca",
+    "virelonsoft"
+  ],
+  "author": {
+    "name": "Muhammet Atmaca",
+    "email": "muhammetatmaca79@gmail.com",
+    "url": "https://muhammetatmaca.com.tr"
+  },
+  "homepage": "https://muhammetatmaca.com.tr/apps/teleflow-prompter",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/muhammetatmaca/muhammet-atmaca-portfolio.git",
+    "directory": "packages/react-native-teleflow-prompter"
+  },
+  "bugs": {
+    "url": "https://muhammetatmaca.com.tr/#contact"
+  },
+  "license": "MIT",
+  "peerDependencies": {
+    "react": ">=16.8.0"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/react": "^18.2.0 || ^19.0.0",
+    "typescript": "~5.9.3"
+  }
+}