`) that synchronizes and announces active subtitle text for visually impaired students using VoiceOver, NVDA, or JAWS.\r\n- **Comprehensive WAI-ARIA Controls**: Full `aria-label`, `aria-expanded`, `aria-pressed`, `aria-valuenow`, `aria-valuemin`, `aria-valuemax`, and `:focus-visible` outline indicators across all player buttons and volume sliders.\r\n\r\n### 💾 LocalStorage Student Preference Persistence\r\n- **Automatic Preference Restoration**: Student player choices (`volume`, `isMuted`, `playbackRate`, `selectedSubLanguage`, `selectedQuality`) are automatically saved to `localStorage` (`aitutor_user_preferences`) and restored seamlessly across course modules and page reloads.\r\n\r\n### 🌲 Tree-Shakeable Sub-Path Package Exports\r\n- **Modular Entrypoints**: Sub-path exports configured in `package.json`:\r\n - `import { AITutor } from \"tavi-video-tutor\";` (Main bundle)\r\n - `import { AITutor } from \"tavi-video-tutor/player\";` (Pure React Player - Zero CLI bloat)\r\n - `import { resolveSubtitleAvailability } from \"tavi-video-tutor/subtitles\";` (Resolver logic)\r\n - `import { resolveAudioAvailability } from \"tavi-video-tutor/audio\";` (Audio Resolver logic)\r\n - `import \"tavi-video-tutor/style.css\";` (CSS styling)\r\n\r\n### 🚀 Next.js & Server-Side Rendering (SSR) Integration\r\n- **SSR Safe**: Fully safe for Next.js (App Router & Pages Router) using `next/dynamic` with `ssr: false`:\r\n```jsx\r\n// components/VideoPlayer.jsx\r\nimport dynamic from 'next/dynamic';\r\nimport 'tavi-video-tutor/style.css';\r\n\r\nconst AITutor = dynamic(() => import('tavi-video-tutor/player').then(m => m.AITutor), {\r\n ssr: false\r\n});\r\n\r\nexport default function VideoLesson() {\r\n return
;\r\n}\r\n```\r\n\r\n---\r\n\r\n## 2. FEATURES\r\n\r\n- **React Video Tutor Component**: Custom HTML5 video player with subtitle rendering, audio dub sync, automatic video quality ladder selection (`144p` to `1080p`), canvas rendering, and modal editing.\r\n- **Automated Video Quality Transcoding Pipeline**: Multi-resolution H.264/AAC quality ladder generation (`720p`, `480p`, `360p`, `240p`, `144p`) with aspect ratio preservation and no-upscaling guarantee.\r\n- **Automated Subtitle Pipeline**: End-to-end processing from video file to Whisper speech-to-text, transcript normalization, cue segmentation, and WebVTT generation.\r\n- **109-Language Registry**: Standardized language metadata definitions for 109 global languages (13 languages with neural TTS capability present in the registry, 95 currently unsupported/unverified for production TTS, 1 partial entry) with full Right-to-Left (RTL) support for Arabic, Hebrew, Urdu, etc.\r\n- **Hybrid Online/Offline Translation**: High-speed online translation with automatic offline local NLLB (`@xenova/transformers`) fallback.\r\n- **Content-Aware Media Identity**: Smart cache fingerprinting based on canonical path, size, modification timestamp, and sampled binary content chunks (head + middle + tail 64KB).\r\n- **Four-Tier Subtitle Priority**: Smart resolver supporting User Uploaded > Developer Manual > Generated > Demo Fallback tracks per language.\r\n- **Local & Remote Video Resolution**: Safe resolution for local assets (`public/`) and remote HTTP/HTTPS video streams with built-in SSRF protection.\r\n- **CLI Management Suite**: Complete command-line tools for subtitle generation, cache status auditing, WebVTT validation, and selective cache cleanup.\r\n\r\n---\r\n\r\n## 3. HOW AITUTOR WORKS\r\n\r\nAITutor separates expensive heavy media processing (audio extraction, speech-to-text, multilingual translation, and multi-resolution video transcoding) from lightweight runtime client rendering:\r\n\r\n```text\r\n Video File (Local / Remote)\r\n │\r\n ┌────────────────────────┴────────────────────────┐\r\n ▼ ▼\r\n[ Subtitle Processing Pipeline ] [ Video Quality Transcoding Pipeline ]\r\n │ │\r\nFFmpeg Audio Extraction (16kHz PCM WAV) FFmpeg Probe Video Metadata\r\n │ │\r\nWhisper Speech-to-Text (Master Transcript) Quality Ladder Planner (Height <= Source)\r\n │ │\r\nTranscript Normalizer (Glossary Preservation) Multi-Resolution H.264/AAC Encoder\r\n │ (720p, 480p, 360p, 240p, 144p)\r\nSubtitle Segmenter (Readability & Timing) │\r\n │ │\r\nMultilingual Translation (Online / Offline NLLB) │\r\n │ │\r\nWebVTT File Generator (en.vtt, te.vtt...) │\r\n │ │\r\n └────────────────────────┬────────────────────────┘\r\n ▼\r\n Manifest Store (/public/aitutor/manifest.json)\r\n ▼\r\n
Player (Renders VTT & Transcoded Qualities)\r\n```\r\n\r\n- **Preprocessing Stage**: The CLI command `npx aitutor` probes video files, runs Whisper ASR speech-to-text, translates transcriptions into target languages, transcodes downscaled H.264/AAC quality renditions (`720p`, `480p`, `360p`, `240p`, `144p`), writes static assets to `public/aitutor/`, and registers everything in `public/aitutor/manifest.json`.\r\n- **Runtime Stage**: When `
` mounts in the browser, it loads `/aitutor/manifest.json`, discovers available WebVTT subtitle tracks and video quality renditions, and enables dynamic language & quality switching. Heavy processing (FFmpeg/Whisper/Transcoding) **never** runs in the student's browser.\r\n\r\n\r\n---\r\n\r\n## 4. REQUIREMENTS & DEPENDENCY ARCHITECTURE\r\n\r\n### Base Package\r\n- **Production Dependencies**: `ws` (`^8.18.0`) is the sole production runtime dependency of the package (used for server-side / CLI Edge TTS synthesis).\r\n- **Node.js**: `v18.0.0` or higher.\r\n- **npm**: `v9.0.0` or higher.\r\n- **Browsers**: Any modern browser supporting HTML5 Video and ES2022 JavaScript (Chrome, Firefox, Safari, Edge).\r\n\r\n### Optional Peer Dependencies\r\n- **React & React-DOM**: `^18.0.0 || ^19.0.0` (Optional peer dependencies; required only if rendering the `
` browser video player component in a React application).\r\n- **@huggingface/transformers**: `^4.2.0` (Optional peer dependency; required only for CLI speech-to-text / Whisper transcription and local NLLB translation via `npx aitutor generate`). The browser player bundle does NOT load or require this runtime.\r\n\r\n### External System Dependencies\r\n- **FFmpeg & FFprobe**: Required for CLI audio extraction, media probing, and multi-resolution video quality ladder transcoding. Must be on system PATH or configured via `process.env.FFMPEG_PATH` and `process.env.FFPROBE_PATH`. (Windows: `winget install Gyan.FFmpeg`, macOS: `brew install ffmpeg`, Linux: `sudo apt install ffmpeg`).\r\n\r\n### Optional Native Models & Runtimes\r\n- **Local Whisper Model**: Required for offline speech-to-text (e.g. `onnx-community/whisper-tiny`).\r\n- **Local NLLB Model**: Required for offline translation (`Xenova/nllb-200-distilled-600M`).\r\n- **Local TTS Engines**: Platform-supported local synthesis (Windows OneCore/SAPI, Piper, Kokoro, Meta MMS).\r\n\r\n---\r\n\r\n## 5. INSTALLATION\r\n\r\n### Base Package Installation (React Video Player SDK & CLI utilities)\r\n```bash\r\nnpm install tavi-video-tutor\r\n```\r\n\r\n### For React Web Applications (Peer Dependencies)\r\nIf using the React video player component `
`, ensure React is installed:\r\n```bash\r\nnpm install react react-dom\r\n```\r\n\r\n### For Subtitle Generation & Whisper Speech-to-Text (Optional Runtime)\r\nTo enable local speech-to-text and offline NLLB translation in the CLI (`npx aitutor generate`), install the optional peer dependency:\r\n```bash\r\nnpm install @huggingface/transformers\r\n# or run interactive environment setup:\r\nnpx aitutor setup\r\n```\r\n\r\n---\r\n\r\n## 6. YOUR FIRST AITUTOR VIDEO\r\n\r\n### 1. Place your video in `public/`\r\nCopy your video file into the `public` directory of your React project:\r\n\r\n```text\r\nmy-tutor-app/\r\n├── public/\r\n│ └── lesson.mp4\r\n├── src/\r\n│ └── App.jsx\r\n├── package.json\r\n└── ...\r\n```\r\n\r\n### 2. Add `
` to your React component\r\nIn `src/App.jsx`:\r\n\r\n```jsx\r\nimport React from 'react';\r\nimport { AITutor } from 'tavi-video-tutor';\r\nimport 'tavi-video-tutor/dist/style.css';\r\n\r\nexport default function App() {\r\n return (\r\n
\r\n );\r\n}\r\n```\r\n\r\n---\r\n\r\n## 7. AUTOMATIC SUBTITLE & VIDEO QUALITY GENERATION\r\n\r\nFollow this step-by-step workflow to generate multilingual subtitles and video quality renditions for your videos from zero:\r\n\r\n### Step 1: Create Starter Configuration (`npx aitutor init`)\r\nRun `npx aitutor init` to generate `aitutor.config.mjs` starter configuration automatically:\r\n\r\n```bash\r\nnpx aitutor init\r\n```\r\n\r\nOr create `aitutor.config.mjs` manually in your project root:\r\n\r\n```javascript\r\nexport default {\r\n subtitles: {\r\n languages: ['en', 'es', 'hi', 'te'], // Target subtitle languages (or 'all' for all 109 registry languages)\r\n quality: 'balanced', // 'fast' | 'balanced' | 'high'\r\n glossary: ['React', 'AITutor'] // Protected domain terms\r\n },\r\n qualities: {\r\n generate: true, // Automatically generate quality ladder (720p, 480p, 360p, 240p, 144p)\r\n targets: [1080, 720, 480, 360, 240, 144]\r\n },\r\n videos: [\r\n {\r\n id: 'lesson',\r\n src: './public/lesson.mp4',\r\n languages: ['en', 'es', 'hi', 'te']\r\n }\r\n ]\r\n};\r\n```\r\n\r\n#### Supported Configuration Formats\r\n\r\nAITutor automatically detects and loads any of the following configuration files in your project root:\r\n\r\n- **`aitutor.config.mjs` (ESM — Recommended)**:\r\n ```javascript\r\n export default {\r\n subtitles: { languages: ['en', 'es', 'hi', 'te'] },\r\n qualities: { generate: true },\r\n videos: [{ id: 'lesson', src: './public/lesson.mp4' }]\r\n };\r\n ```\r\n- **`aitutor.config.cjs` (CommonJS)**:\r\n ```javascript\r\n module.exports = {\r\n subtitles: { languages: ['en', 'es', 'hi', 'te'] },\r\n qualities: { generate: true },\r\n videos: [{ id: 'lesson', src: './public/lesson.mp4' }]\r\n };\r\n ```\r\n- **`aitutor.config.json` (JSON)**:\r\n ```json\r\n {\r\n \"subtitles\": { \"languages\": [\"en\", \"es\", \"hi\", \"te\"] },\r\n \"qualities\": { \"generate\": true },\r\n \"videos\": [{ \"id\": \"lesson\", \"src\": \"./public/lesson.mp4\" }]\r\n }\r\n ```\r\n- **`aitutor.config.js`**: Uses `export default` when host `package.json` contains `\"type\": \"module\"`, or `module.exports` when host `package.json` uses CommonJS.\r\n\r\n### Step 2: Run the AITutor Generator\r\nRun the CLI generator from your project terminal:\r\n\r\n```bash\r\nnpx aitutor\r\n```\r\n\r\n### Execution Output:\r\n```text\r\nAITUTOR PIPELINE ENGINE\r\n─────────────────────────────\r\nProcessing video 1 of 1: lesson\r\n → Probing video metadata for lesson (1920x1080 @ 30fps)\r\n ✓ Quality plan: 1080p, 720p, 480p, 360p, 240p, 144p\r\n ✓ 1080p (source file preserved)\r\n → Generating 720p [████████████████████] 100%\r\n ✓ 720p complete (8.2 MB)\r\n → Generating 480p [████████████████████] 100%\r\n ✓ 480p complete (5.1 MB)\r\n → Generating 360p [████████████████████] 100%\r\n ✓ 360p complete (3.3 MB)\r\n → Generating 240p [████████████████████] 100%\r\n ✓ 240p complete (2.1 MB)\r\n → Generating 144p [████████████████████] 100%\r\n ✓ 144p complete (1.2 MB)\r\n → Reading video URL with FFmpeg\r\n → Extracting audio stream\r\n ✓ Audio extracted (audio.wav, 2.40 MB)\r\n → Running Whisper Speech-to-Text\r\n ✓ Detected source language: English\r\n ✓ Segments count: 12\r\n → Generating WebVTT subtitles\r\n ✓ Generated en.vtt [PASS]\r\n ✓ Generated es.vtt [PASS]\r\n ✓ Generated hi.vtt [PASS]\r\n ✓ Generated te.vtt [PASS]\r\n✓ Video lesson completed successfully\r\n```\r\n\r\n---\r\n\r\n## 8. GENERATED ASSETS STRUCTURE\r\n\r\nSubtitle generation and video quality transcoding output public production assets and maintain an internal processing cache:\r\n\r\n```text\r\nmy-tutor-app/\r\n├── public/\r\n│ ├── lesson.mp4 # ORIGINAL SOURCE VIDEO\r\n│ └── aitutor/ # PUBLIC ASSETS (Deploy to Production)\r\n│ ├── manifest.json # Subtitles & Quality registry index\r\n│ ├── videos/\r\n│ │ └── lesson/ # TRANSCODED QUALITIES\r\n│ │ ├── 720.mp4\r\n│ │ ├── 480.mp4\r\n│ │ ├── 360.mp4\r\n│ │ ├── 240.mp4\r\n│ │ └── 144.mp4\r\n│ └── subtitles/\r\n│ └── lesson/ # MULTILINGUAL SUBTITLES\r\n│ ├── en.vtt\r\n│ ├── es.vtt\r\n│ ├── hi.vtt\r\n│ └── te.vtt\r\n│\r\n└── .aitutor/ # INTERNAL CACHE (DO NOT Commit/Deploy)\r\n ├── manifest.json\r\n ├── transcripts/\r\n │ └── lesson.json # Master ASR transcript cache\r\n └── videos/ # Transcoding cache\r\n```\r\n\r\n- **`public/aitutor/`**: Production static artifacts loaded by browser client. Must be included in your static site deployment.\r\n- **`.aitutor/`**: Local caching directory storing raw speech transcripts to prevent re-running Whisper ASR when modifying subtitle styles or adding languages.\r\n\r\n---\r\n\r\n## 9. USING GENERATED SUBTITLES\r\n\r\nOnce `npx aitutor` finishes, `
` automatically detects pre-generated subtitles without requiring manual VTT imports:\r\n\r\n1. `
` fetches `/aitutor/manifest.json`.\r\n2. It matches the video `src` or `id`.\r\n3. It loads the corresponding WebVTT track (e.g., `/aitutor/subtitles/lesson/en.vtt`).\r\n4. Subtitles display dynamically synced to video playback.\r\n\r\n---\r\n\r\n## 10. SELECTING SUBTITLE LANGUAGES & SHORTCUTS\r\n\r\nUsers can control subtitle display via the player UI controls or keyboard shortcuts:\r\n\r\n| Control / Shortcut | Action |\r\n| :--- | :--- |\r\n| **Subtitle Menu (`S`)** | Open/close language selection dropdown |\r\n| **Caption Toggle (`C`)** | Toggle subtitle visibility ON / OFF |\r\n| **Play / Pause (`Space` / `K`)** | Toggle video playback |\r\n| **Mute (`M`)** | Toggle audio mute |\r\n| **Fullscreen (`F`)** | Toggle full-screen mode |\r\n| **Seek Backward (`Left Arrow` / `J`)** | Seek backward 5 / 10 seconds |\r\n| **Seek Forward (`Right Arrow` / `L`)** | Seek forward 5 / 10 seconds |\r\n\r\n---\r\n\r\n## 11. LANGUAGE CAPABILITY MATRIX & REGISTRY\r\n\r\nAITutor provides a standardized multi-tier capability matrix across **109 global language definitions**. Registry presence is not marketed as verified production support; actual production capabilities strictly reflect verified evidence:\r\n\r\n| Capability | Supported Languages | Verification Status | Fallback / Notes |\r\n| :--- | :--- | :--- | :--- |\r\n| **Subtitle Transcription (ASR)** | All Whisper-supported languages (auto-detected) | Verified via Whisper neural ASR | Default English if undetected |\r\n| **Online Subtitle Translation** | **109 / 109 languages** | Production ready | Cloud translation providers |\r\n| **Offline Subtitle Translation** | **106 / 109 languages** | Production ready via local NLLB-200 | `bi`, `ch`, `doi` require online translation |\r\n| **Neural Audio Dubbing (TTS)** | **13 verified languages in registry** | Production verified real speech synthesis | Throws `AUDIO_NOT_AVAILABLE_FOR_LANGUAGE` if unsupported |\r\n\r\n### Language Registry Evidence Breakdown:\r\n- **109 Language Registry Definitions**: Standardized ISO-639-2/3, BCP-47 locales, and text direction metadata.\r\n- **13 Languages with Neural TTS Capability in Registry**: `en`, `hi`, `te`, `ta`, `bn`, `mr`, `gu`, `kn`, `ml`, `es`, `fr`, `de`, `ja`.\r\n- **95 Languages Unsupported / Unverified for Production TTS Claim**: Remaining registry entries lack verified neural voice mappings or verified production TTS synthesis.\r\n- **1 Partial Language Entry (`zh`)**: Subtitle translation tested, but lacks registered neural TTS voice mapping.\r\n\r\n> **Production Invariant**: AITutor **never claims** a language has audio dubbing support unless verified, genuine speech synthesis is functional for that locale. When TTS cannot generate real speech for a requested language, it raises an explicit `AUDIO_NOT_AVAILABLE_FOR_LANGUAGE` error rather than synthesizing flat tones, silence, or fake audio.\r\n\r\n
\r\nClick to View Complete 109 Language Code Registry
\r\n\r\n| Code | Name | Native Name | Direction |\r\n| :--- | :--- | :--- | :--- |\r\n| `af` | Afrikaans | Afrikaans | ltr |\r\n| `sq` | Albanian | Shqip | ltr |\r\n| `am` | Amharic | አማርኛ | ltr |\r\n| `ar` | Arabic | العربية | rtl |\r\n| `hy` | Armenian | Հայերեն | ltr |\r\n| `as` | Assamese | অসমীয়া | ltr |\r\n| `az` | Azerbaijani | Azərbaycan | ltr |\r\n| `eu` | Basque | Euskara | ltr |\r\n| `be` | Belarusian | Беларуская | ltr |\r\n| `bn` | Bengali | বাংলা | ltr |\r\n| `bho` | Bhojpuri | भोजपुरी | ltr |\r\n| `bi` | Bislama | Bislama | ltr |\r\n| `bg` | Bulgarian | Български | ltr |\r\n| `my` | Burmese | မြန်မာဘာသာ | ltr |\r\n| `yue` | Cantonese | 廣東話 | ltr |\r\n| `ca` | Catalan | Català | ltr |\r\n| `ceb` | Cebuano | Cebuano | ltr |\r\n| `ch` | Chamorro | Chamorro | ltr |\r\n| `zh` | Chinese (Mandarin) | 中文 | ltr |\r\n| `hr` | Croatian | Hrvatski | ltr |\r\n| `cs` | Czech | Čeština | ltr |\r\n| `da` | Danish | Dansk | ltr |\r\n| `doi` | Dogri | डोगरी | ltr |\r\n| `nl` | Dutch | Nederlands | ltr |\r\n| `en` | English | English | ltr |\r\n| `et` | Estonian | Eesti | ltr |\r\n| `fj` | Fijian | Na Vosa Vakaviti | ltr |\r\n| `tl` | Filipino (Tagalog) | Tagalog | ltr |\r\n| `fi` | Finnish | Suomi | ltr |\r\n| `fr` | French | Français | ltr |\r\n| `gl` | Galician | Galego | ltr |\r\n| `ka` | Georgian | ქართული | ltr |\r\n| `de` | German | Deutsch | ltr |\r\n| `el` | Greek | Ελληνικά | ltr |\r\n| `kl` | Greenlandic | Kalaallisut | ltr |\r\n| `gu` | Gujarati | ગુજરાતી | ltr |\r\n| `ha` | Hausa | Hausa | ltr |\r\n| `haw` | Hawaiian | Ōlelo Hawaiʻi | ltr |\r\n| `he` | Hebrew | עברית | rtl |\r\n| `hi` | Hindi | हिन्दी | ltr |\r\n| `hu` | Hungarian | Magyar | ltr |\r\n| `is` | Icelandic | Íslenska | ltr |\r\n| `ig` | Igbo | Asụsụ Igbo | ltr |\r\n| `id` | Indonesian | Bahasa Indonesia | ltr |\r\n| `ga` | Irish | Gaeilge | ltr |\r\n| `it` | Italian | Italiano | ltr |\r\n| `ja` | Japanese | 日本語 | ltr |\r\n| `jv` | Javanese | Basa Jawa | ltr |\r\n| `kn` | Kannada | ಕನ್ನಡ | ltr |\r\n| `kk` | Kazakh | Қазақ тілі | ltr |\r\n| `km` | Khmer | ភាសាខ្មែរ | ltr |\r\n| `rw` | Kinyarwanda | Ikinyarwanda | ltr |\r\n| `ko` | Korean | 한국어 | ltr |\r\n| `ku` | Kurdish | Kurdî | ltr |\r\n| `ky` | Kyrgyz | Кыргызча | ltr |\r\n| `lo` | Lao | ພາສາລາວ | ltr |\r\n| `la` | Latin | Lingua Latina | ltr |\r\n| `lv` | Latvian | Latviešu | ltr |\r\n| `lt` | Lithuanian | Lietuvių | ltr |\r\n| `lb` | Luxembourgish | Lëtzebuergesch | ltr |\r\n| `mk` | Macedonian | Македонски | ltr |\r\n| `mg` | Malagasy | Malagasy | ltr |\r\n| `ms` | Malay | Bahasa Melayu | ltr |\r\n| `ml` | Malayalam | മലയാളം | ltr |\r\n| `mt` | Maltese | Malti | ltr |\r\n| `mi` | Maori | Te Reo Māori | ltr |\r\n| `mr` | Marathi | मराठी | ltr |\r\n| `mn` | Mongolian | Монгол | ltr |\r\n| `ne` | Nepali | नेपाली | ltr |\r\n| `no` | Norwegian | Norsk | ltr |\r\n| `ny` | Nyanja (Chichewa) | Chinyanja | ltr |\r\n| `or` | Odia (Oriya) | ଓଡ଼ିଆ | ltr |\r\n| `ps` | Pashto | پښتو | rtl |\r\n| `fa` | Persian | فارسی | rtl |\r\n| `pl` | Polish | Polski | ltr |\r\n| `pt` | Portuguese | Português | ltr |\r\n| `pa` | Punjabi | ਪੰਜਾਬੀ | ltr |\r\n| `ro` | Romanian | Română | ltr |\r\n| `ru` | Russian | Русский | ltr |\r\n| `sm` | Samoan | Gagana Samoa | ltr |\r\n| `gd` | Scottish Gaelic | Gàidhlig | ltr |\r\n| `sr` | Serbian | Српски | ltr |\r\n| `st` | Sesotho | Sesotho | ltr |\r\n| `sn` | Shona | chiShona | ltr |\r\n| `sd` | Sindhi | سنڌي | rtl |\r\n| `si` | Sinhala | සිංහල | ltr |\r\n| `sk` | Slovak | Slovenčina | ltr |\r\n| `sl` | Slovenian | Slovenščina | ltr |\r\n| `so` | Somali | Soomaali | ltr |\r\n| `es` | Spanish | Español | ltr |\r\n| `su` | Sundanese | Basa Sunda | ltr |\r\n| `sw` | Swahili | Kiswahili | ltr |\r\n| `sv` | Swedish | Svenska | ltr |\r\n| `tg` | Tajik | Тоҷикӣ | ltr |\r\n| `ta` | Tamil | தமிழ் | ltr |\r\n| `tt` | Tatar | Татар | ltr |\r\n| `te` | Telugu | తెలుగు | ltr |\r\n| `th` | Thai | ไทย | ltr |\r\n| `to` | Tongan | Faka Tonga | ltr |\r\n| `tr` | Turkish | Türkçe | ltr |\r\n| `tk` | Turkmen | Türkmençe | ltr |\r\n| `uk` | Ukrainian | Українська | ltr |\r\n| `ur` | Urdu | اردو | rtl |\r\n| `uz` | Uzbek | Oʻzbekcha | ltr |\r\n| `vi` | Vietnamese | Tiếng Việt | ltr |\r\n| `cy` | Welsh | Cymraeg | ltr |\r\n| `xh` | Xhosa | isiXhosa | ltr |\r\n| `zu` | Zulu | isiZulu | ltr |\r\n\r\n \r\n\r\n---\r\n\r\n## 12. SUBTITLE SOURCE PRIORITY\r\n\r\nWhen multiple subtitle tracks exist for the same language, AITutor resolves tracks per language using a strict 4-tier priority order:\r\n\r\n```text\r\nHIGHEST 1. User Uploaded Subtitle (Runtime UI user upload)\r\n 2. Developer Manual Track (Passed via `subtitles` prop)\r\n 3. Generated Subtitle Track (From manifest.json)\r\nLOWEST 4. Demo Fallback Track (Sample demonstration track)\r\n```\r\n\r\n### Resolution Example:\r\n- **Generated Tracks**: `en`, `es`, `te`\r\n- **Developer Manual Prop**: `subtitles={{ en: \"/custom-en.vtt\" }}`\r\n\r\n**Resolved Result**:\r\n- `en` → Developer Manual Track (`/custom-en.vtt`)\r\n- `es` → Generated Track (`/aitutor/subtitles/lesson/es.vtt`)\r\n- `te` → Generated Track (`/aitutor/subtitles/lesson/te.vtt`)\r\n\r\n---\r\n\r\n## 13. DEVELOPER SUBTITLE VISIBILITY & CUSTOM TRACKS\r\n\r\nControl subtitle track visibility and supply custom WebVTT files using the `subtitles` prop on `
`:\r\n\r\n| Configuration | Behavior |\r\n| :--- | :--- |\r\n| **Omitted** | Show all available subtitle tracks (default) |\r\n| `\"all\"` | Show all available tracks |\r\n| `[\"en\", \"hi\", \"te\"]` | Only show those languages in player UI selector |\r\n| `{ en: \"/en.vtt\", hi: \"/hi.vtt\" }` | Use developer-provided custom VTT tracks |\r\n| `false` | Disable subtitle UI & cue rendering completely |\r\n\r\n### Examples\r\n\r\n```jsx\r\n// 1. Default Mode (shows all generated tracks for current video)\r\n
\r\n\r\n// 2. Explicit All Mode\r\n
\r\n\r\n// 3. Language Visibility Filter (UI menu only displays English, Hindi, Telugu)\r\n
\r\n\r\n// 4. Custom Developer WebVTT Files (overrides generated tracks for specified languages)\r\n
\r\n\r\n// 5. Disable Subtitle UI Completely\r\n
\r\n```\r\n\r\n---\r\n\r\n## 14. USER-UPLOADED SUBTITLES\r\n\r\nThe player UI includes a runtime subtitle upload button in the subtitle settings menu. Uploaded VTT/SRT files take the **highest priority** (Tier 1) for the current user session.\r\n\r\n---\r\n\r\n## 15. LOCAL VIDEOS\r\n\r\nSpecify relative paths to files located in your React `public/` directory:\r\n\r\n```jsx\r\n// Resolves to public/courses/react-101.mp4\r\n
\r\n```\r\n\r\n---\r\n\r\n## 16. REMOTE VIDEO URLS\r\n\r\nAITutor supports direct remote HTTP/HTTPS video URLs:\r\n\r\n```jsx\r\n
\r\n```\r\n\r\n- **Authentication Tokens**: Ephemeral signed query parameters (`token=`, `signature=`, `expires=`) are automatically stripped during fingerprinting so signed URL updates do not cause unnecessary re-transcription.\r\n- **SSRF Protection**: Private IP ranges (`127.0.0.1`, `10.x.x.x`, `192.168.x.x`, `169.254.169.254`) and non-HTTP protocols (`file://`, `gopher://`) are blocked for security.\r\n\r\n---\r\n\r\n## 17. CACHE SYSTEM & MEDIA FINGERPRINT\r\n\r\nAITutor implements a content-aware media fingerprint:\r\n\r\n```text\r\nCanonical Path + File Size + mtimeMs + Sampled Binary Hash (Head 64KB + Mid 64KB + Tail 64KB)\r\n```\r\n\r\n- **Cache Hit**: Running `npx aitutor` on an unchanged file completes in `<1ms`, skipping audio extraction and speech-to-text.\r\n- **Performance**: Reading 192KB sampled chunks uses **<0.5ms** CPU time and **<200KB** RAM, making it safe for 1GB+ video files.\r\n\r\n---\r\n\r\n## 18. CHANGING A VIDEO\r\n\r\nIf you replace a video file (e.g. replacing `/public/lesson.mp4` with a new recording using the same filename):\r\n\r\n1. Run `npx aitutor`.\r\n2. AITutor detects that the media content fingerprint changed.\r\n3. Old transcripts and WebVTT tracks are invalidated and re-generated automatically.\r\n\r\nTo force re-generation manually:\r\n```bash\r\nnpx aitutor --force\r\n```\r\n\r\n---\r\n\r\n## 19. TRANSLATION MODES\r\n\r\nConfigure translation behavior in `aitutor.config.js`:\r\n\r\n```javascript\r\nexport default {\r\n subtitles: {\r\n translation: {\r\n provider: 'auto' // 'auto' | 'online' | 'offline'\r\n }\r\n }\r\n};\r\n```\r\n\r\n- **`auto`**: Prefers online translation providers; falls back to local NLLB offline model if network is unavailable.\r\n- **`online`**: Online API translation.\r\n- **`offline`**: Pure local NLLB-200 translation running in Node.js via `@xenova/transformers`. (Downloads NLLB model files to local cache directory on first run).\r\n\r\n---\r\n\r\n## 20. CUSTOM TERMINOLOGY / GLOSSARY\r\n\r\nProtect brand names and technical jargon from being mis-translated:\r\n\r\n```javascript\r\n// aitutor.config.js\r\nexport default {\r\n subtitles: {\r\n glossary: [\r\n 'AITutor',\r\n 'React',\r\n 'Node.js',\r\n 'TypeScript',\r\n 'GraphQL'\r\n ]\r\n }\r\n};\r\n```\r\n\r\nProtected terms are preserved exactly as written during transcript normalization and multilingual translation.\r\n\r\n---\r\n\r\n## 21. CONFIGURATION REFERENCE (`aitutor.config.js`)\r\n\r\n```javascript\r\nexport default {\r\n // Global subtitle settings\r\n subtitles: {\r\n languages: ['en', 'es', 'hi', 'te'], // Target language codes\r\n quality: 'balanced', // 'fast' | 'balanced' | 'high'\r\n glossary: ['React', 'AITutor'], // Protected terms\r\n transcription: {\r\n model: 'Xenova/whisper-base' // Whisper ASR model\r\n },\r\n translation: {\r\n provider: 'auto' // 'auto' | 'online' | 'offline'\r\n }\r\n },\r\n\r\n // Video list\r\n videos: [\r\n {\r\n id: 'lesson_1',\r\n src: './public/lesson.mp4',\r\n languages: ['en', 'es', 'hi', 'te']\r\n }\r\n ]\r\n};\r\n```\r\n\r\n---\r\n\r\n## 22. CLI COMMAND REFERENCE\r\n\r\nExecute the CLI using `npx aitutor`:\r\n\r\n| Command | Scope & Capabilities | Required External / Optional Runtimes | Model Requirements | Network Required | Offline Possible |\r\n| :--- | :--- | :--- | :--- | :--- | :--- |\r\n| `npx aitutor init` | Base package: Generates `aitutor.config.mjs` and starter directory structure | None (Node.js only) | None | No | Yes |\r\n| `npx aitutor doctor` | Base package: Diagnoses environment, FFmpeg, Whisper provider, model caches | None (Runs inspection only) | None to run | No | Yes |\r\n| `npx aitutor status` | Base package: Inspects cached models, transcripts, audio dubs, and manifest entries | None | None | No | Yes |\r\n| `npx aitutor validate` | Base package: Audits generated WebVTT cue syntax and manifest integrity | None | None | No | Yes |\r\n| `npx aitutor clean` | Base package: Deletes generated subtitles, audio tracks, and manifests | None | None | No | Yes |\r\n| `npx aitutor setup` | Base package: Interactive environment setup wizard | Invokes system package managers (`winget`) and `npm` | Downloads requested models | Yes (if installing/downloading) | Yes (local check only) |\r\n| `npx aitutor generate` / `npx aitutor` | Full pipeline: Audio extraction, speech-to-text, translation, TTS dubbing, transcoding | **External system dependency**: FFmpeg/FFprobe
**Optional runtime**: `@huggingface/transformers` | **Cached model**: Whisper ASR (`whisper-tiny`), NLLB translation, TTS voice | Yes (for online API or model download)
No (if offline mode with cached models) | Yes (with cached models, optional runtime & system FFmpeg) |\r\n\r\n### Command Flags:\r\n- `--no-quality`: Skip video quality rendition transcoding during subtitle generation pipeline run.\r\n- `--force`: Ignore existing cache and force full re-transcription & translation.\r\n- `--keep-temp`: Retain temporary audio extraction workspace for debugging.\r\n- `--video
`: Target specific video ID for generation or cleanup.\r\n- `--audio-languages `: Filter or specify target audio dubbing languages (e.g. `--audio-languages en,hi,te`).\r\n- `--offline`: Strictly enforce offline execution; refuse cloud endpoints.\r\n- `--yes`, `-y`: Automatically confirm prompts in preflight remediation / setup.\r\n\r\n---\r\n\r\n## 23. DEVELOPMENT WORKFLOW\r\n\r\n```text\r\n1. Place video in public/ (e.g., public/lesson.mp4)\r\n ↓\r\n2. Configure aitutor.config.js\r\n ↓\r\n3. Run: npx aitutor\r\n ↓\r\n4. Add to React app\r\n ↓\r\n5. Start dev server: npm run dev\r\n ↓\r\n6. Test subtitle rendering & language switching\r\n ↓\r\n7. Build production site: npm run build\r\n ↓\r\n8. Deploy public/ & dist/ to static host\r\n```\r\n\r\n---\r\n\r\n## 24. PRODUCTION DEPLOYMENT\r\n\r\nEnsure your production build includes the generated static assets in `public/aitutor/`:\r\n\r\n```text\r\ndist/\r\n├── index.html\r\n├── assets/\r\n└── aitutor/\r\n ├── manifest.json\r\n └── subtitles/\r\n └── lesson/\r\n ├── en.vtt\r\n └── ...\r\n```\r\n\r\n- When students view your application in production, their browser fetches pre-generated WebVTT files directly from static hosting.\r\n- FFmpeg and Whisper **do not** run in the browser.\r\n\r\n---\r\n\r\n## 25. DEPLOYMENT EXAMPLES & SERVING\r\n\r\n### Static Server Headers (Nginx / Vercel / Netlify / Cloudflare)\r\nEnsure `.vtt` files are served with the correct MIME type:\r\n\r\n```text\r\nContent-Type: text/vtt; charset=utf-8\r\nAccess-Control-Allow-Origin: *\r\n```\r\n\r\n---\r\n\r\n## 26. TROUBLESHOOTING\r\n\r\n| Problem | Cause | Solution |\r\n| :--- | :--- | :--- |\r\n| **Subtitles not appearing in browser** | `public/aitutor/manifest.json` missing | Run `npx aitutor` to generate manifest & WebVTT tracks. |\r\n| **Stale subtitles after changing video** | Same filename retained old cache | Run `npx aitutor` (media identity fingerprint auto-detects changes). Use `--force` if needed. |\r\n| **FFmpeg exited with error** | FFmpeg binary not found on PATH | Install FFmpeg globally or set `process.env.FFMPEG_PATH=\"C:\\\\path\\\\to\\\\ffmpeg.exe\"`. |\r\n| **Remote video 403 / CORS Error** | Remote server blocks cross-origin requests | Ensure remote video host sets `Access-Control-Allow-Origin: *`. |\r\n| **Offline translation missing language** | Language unsupported by NLLB offline model | `bi`, `ch`, and `doi` require `online` or `auto` translation mode. |\r\n\r\n---\r\n\r\n## 27. DEBUGGING SUBTITLE SOURCES\r\n\r\nYou can inspect resolved track sources at runtime using `resolveSubtitleSources`:\r\n\r\n```javascript\r\nimport { resolveSubtitleSources } from 'tavi-video-tutor';\r\n\r\nconst result = resolveSubtitleSources({\r\n developerSubtitles: { en: '/custom-en.vtt' },\r\n generatedSubtitles: { en: '/aitutor/subtitles/lesson/en.vtt', es: '/aitutor/subtitles/lesson/es.vtt' }\r\n});\r\n\r\nconsole.log(result.sourceByLanguage);\r\n// Output: { en: 'developer', es: 'generated' }\r\n```\r\n\r\n---\r\n\r\n## 28. ACCESSIBILITY & RTL SUPPORT\r\n\r\nAITutor includes native accessibility and internationalization support:\r\n- **Right-to-Left (RTL)**: Automatic text direction formatting for Arabic (`ar`), Hebrew (`he`), Persian (`fa`), Pashto (`ps`), Urdu (`ur`), and Sindhi (`sd`).\r\n- **Keyboard Navigation**: Complete player navigation via standard hotkeys (`Space`, `K`, `C`, `S`, `M`, `F`, Arrow keys).\r\n\r\n---\r\n\r\n## 29. PERFORMANCE\r\n\r\n- **ASR & Translation Caching**: Pre-calculated master transcripts prevent duplicate Whisper processing.\r\n- **Memory Footprint**: Stabilized memory consumption (**<6.5 MB heap**) during long playback and 500+ language switches.\r\n- **Sampled File Fingerprinting**: Fast 192KB chunk reads enable instant cache checks for large multi-gigabyte video files.\r\n\r\n---\r\n\r\n## 30. SECURITY & ZERO-TRUST VALIDATION\r\n\r\nAITutor enforces multi-layer enterprise security across network fetching, process execution, and media validation:\r\n\r\n### 🛡️ 1. Advanced SSRF Defense & DNS Rebinding Mitigation\r\n- **Protocol Enforcement**: Only `http:` and `https:` protocols are accepted. File schemes (`file://`), loopback abstractions, and esoteric schemes (`gopher://`, `dict://`) are rejected immediately.\r\n- **Private Subnet & Cloud Metadata Blocking**: All target IPs are resolved before connecting. Private IPv4 ranges (`10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`), loopback (`127.0.0.0/8`), link-local / cloud metadata services (`169.254.0.0/16`), and IPv6 equivalents (`::1`, `fc00::/7`, `fe80::/10`, IPv4-mapped IPv6 `::ffff:127.0.0.1`) are denied.\r\n- **DNS Rebinding Protection via Native IP Pinning**: A custom Node.js `http.Agent` / `https.Agent` lookup resolver pins outgoing TCP sockets directly to the pre-validated IP address, eliminating TOCTOU (Time-of-Check to Time-of-Use) DNS rebinding attacks while preserving standard TLS SNI handshakes and HTTP `Host` headers.\r\n- **Strict Redirect Validation**: Up to 5 redirects are permitted, with every intermediate URL re-evaluating hostname and resolved IP before following. Downgrading from HTTPS to plain HTTP is prohibited.\r\n- **Resource Exhaustion Guards**: Network media fetching enforces an explicit 30-second socket timeout and aborts any download exceeding the 2 GB maximum file limit.\r\n\r\n### 🔍 2. Zero-Trust Media Validation\r\n- **Video Rendition Integrity**: Every transcoded MP4 rendition is probed with FFprobe before registration in `manifest.json`. Renditions must contain valid `h264` video streams, `aac` audio streams, non-zero frame dimensions, and matching duration. Corrupted or invalid renditions are discarded and re-transcoded.\r\n- **Audio Dub Volumetric Speech Verification**: Generated and cached multilingual audio tracks are validated using the FFmpeg `volumedetect` filter. Files where `max_volume < -50 dB` or `mean_volume < -60 dB` are rejected with `SILENT_AUDIO`, preventing silent tracks or tone artifacts from reaching learners.\r\n- **Subtitle WebVTT Verification**: Subtitle files are verified for the `WEBVTT` header, timestamp syntax (`00:00:00.000 --> 00:00:02.000`), non-empty cues, target-script range checks, and exact match detection against source VTT. Stale or untranslated VTT files are rejected on both generation and cache lookup.\r\n\r\n### 🔒 3. Process Isolation & Token Sanitization\r\n- **Safe Argument Spawning**: FFmpeg, FFprobe, and external utilities execute via parameterized argument arrays in `child_process.spawn`. Shell interpretation is disabled (`shell: false`), preventing shell injection vulnerabilities.\r\n- **Sensitive Token Sanitization**: Ephemeral authentication tokens (`token=`, `sig=`, `expires=`) are stripped from remote media URLs prior to generating cache keys, preventing credential leakage in logs and persistent cache manifests.\r\n\r\n---\r\n\r\n## 31. API REFERENCE\r\n\r\n### `` Props\r\n| Prop | Type | Default | Description |\r\n|---|---|---|---|\r\n| `qualities` | `Array<{quality: string, src: string, height?: number, width?: number}>` | `undefined` | Optional explicit array of video quality renditions. If omitted, renditions are automatically populated from `manifest.json`. |\r\n| `onQualityChange` | `(quality: string) => void` | `undefined` | Optional callback triggered when user switches video quality. |\r\n\r\n| Prop | Type | Default | Description |\r\n| :--- | :--- | :--- | :--- |\r\n| **`src`** | `string` | *(Required)* | Video file path (`/lesson.mp4`) or remote URL (`https://...`) |\r\n| **`id`** | `string` | `undefined` | Optional explicit video identifier |\r\n| **`subtitles`** | `'all' \\| false \\| string[] \\| Record` | `'all'` | Subtitle configuration & runtime visibility filter |\r\n| **`audioLanguages`** | `'all' \\| false \\| string[] \\| Record` | `'all'` | Audio dub configuration & runtime visibility filter |\r\n| **`defaultSubLanguage`** | `string` | `'en'` | Initial subtitle language code |\r\n| **`subLanguage`** | `string` | `undefined` | Controlled subtitle language state |\r\n| **`defaultAudioLanguage`** | `string` | `'original'` | Initial audio dub language |\r\n| **`playbackRates`** | `array` | `[0.5, 1, 1.25, 1.5, 2]` | Available playback speed options |\r\n| **`width`** | `string` | `'100%'` | Container width |\r\n| **`height`** | `string` | `'100%'` | Container height |\r\n| **`onPlay`** | `function` | `undefined` | Playback play event handler |\r\n| **`onPause`** | `function` | `undefined` | Playback pause event handler |\r\n| **`onEnded`** | `function` | `undefined` | Playback completion event handler |\r\n| **`onSubLanguageChange`** | `function` | `undefined` | Subtitle language change callback |\r\n| **`onAudioLanguageChange`** | `function` | `undefined` | Audio language change callback |\r\n\r\n---\r\n\r\n## 32. COMPLETE COPY-PASTE EXAMPLE\r\n\r\n### `aitutor.config.js`\r\n```javascript\r\nexport default {\r\n subtitles: {\r\n languages: ['en', 'es', 'hi', 'te'],\r\n glossary: ['React', 'AITutor']\r\n },\r\n videos: [\r\n {\r\n id: 'demo_lesson',\r\n src: './public/demo.mp4',\r\n languages: ['en', 'es', 'hi', 'te']\r\n }\r\n ]\r\n};\r\n```\r\n\r\n### `src/App.jsx`\r\n```jsx\r\nimport React from 'react';\r\nimport { AITutor } from 'tavi-video-tutor';\r\nimport 'tavi-video-tutor/dist/style.css';\r\n\r\nexport default function App() {\r\n return (\r\n \r\n
React AI Tutor Lesson
\r\n
\r\n
console.log('Selected language:', lang)}\r\n />\r\n \r\n