{"id":30046720,"url":"https://github.com/interactive-video-labs/interactive-video-core","last_synced_at":"2025-08-07T08:53:42.132Z","repository":{"id":306467840,"uuid":"1026295074","full_name":"interactive-video-labs/interactive-video-core","owner":"interactive-video-labs","description":"💡 Framework-agnostic TypeScript engine for building cue-based interactive video experiences. Lightweight, extendable, and works with any web framework — React, Vue, or plain JS.","archived":false,"fork":false,"pushed_at":"2025-07-31T18:46:42.000Z","size":309,"stargazers_count":1,"open_issues_count":2,"forks_count":2,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-07-31T19:58:29.883Z","etag":null,"topics":["framework-agnostic","front-end-library","html5-video","interactive-video","learning-platform","media-framework","npm-package","state-machine","typescript","video-cues","video-interaction","video-player","web-video"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/@interactive-video-labs/core","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/interactive-video-labs.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-07-25T16:28:55.000Z","updated_at":"2025-07-31T18:46:47.000Z","dependencies_parsed_at":"2025-07-31T19:58:33.107Z","dependency_job_id":null,"html_url":"https://github.com/interactive-video-labs/interactive-video-core","commit_stats":null,"previous_names":["interactive-video-labs/core","interactive-video-labs/interactive-video-core"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/interactive-video-labs/interactive-video-core","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/interactive-video-labs%2Finteractive-video-core","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/interactive-video-labs%2Finteractive-video-core/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/interactive-video-labs%2Finteractive-video-core/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/interactive-video-labs%2Finteractive-video-core/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/interactive-video-labs","download_url":"https://codeload.github.com/interactive-video-labs/interactive-video-core/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/interactive-video-labs%2Finteractive-video-core/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":269227926,"owners_count":24381839,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-07T02:00:09.698Z","response_time":73,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["framework-agnostic","front-end-library","html5-video","interactive-video","learning-platform","media-framework","npm-package","state-machine","typescript","video-cues","video-interaction","video-player","web-video"],"created_at":"2025-08-07T08:53:37.289Z","updated_at":"2025-08-07T08:53:42.098Z","avatar_url":"https://github.com/interactive-video-labs.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# @interactive-video-labs/core\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://raw.githubusercontent.com/interactive-video-labs/docs/main/logo.svg\" width=\"200px\" alt=\"Interactive Video Labs Logo\" /\u003e\n\u003c/p\u003e\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://img.shields.io/npm/v/@interactive-video-labs/core\" alt=\"NPM Version\" /\u003e\n  \u003cimg src=\"https://img.shields.io/npm/l/@interactive-video-labs/core\" alt=\"NPM License\" /\u003e\n  \u003cimg src=\"https://img.shields.io/npm/d18m/@interactive-video-labs/core?style=flat-square\" alt=\"NPM Downloads\" /\u003e\n  \u003ca href=\"https://github.com/interactive-video-labs/interactive-video-core/actions\"\u003e\n    \u003cimg src=\"https://github.com/interactive-video-labs/interactive-video-core/actions/workflows/release.yml/badge.svg\" alt=\"Build Status\" /\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\n\n\nWelcome to `@interactive-video-labs/core` — the framework-agnostic TypeScript module powering interactive video experiences. This engine is designed to be lightweight, extendable, and usable across React, Vue, or plain JavaScript apps.\n\n---\n\n## 🚀 Getting Started\n\nTo get started with `@interactive-video-labs/core`, follow these steps:\n\n### Installation\n\nIf you're integrating this module into an existing project, you can install it via `pnpm`, `npm`, or `yarn`:\n\n```bash\npnpm add @interactive-video-labs/core\n# or\nnpm install @interactive-video-labs/core\n# or\nyarn add @interactive-video-labs/core\n```\n\n### Basic Usage\n\nFor a basic working example, refer to the [`examples/index.html`](examples/index.html) file. It demonstrates how to initialize and use the `IVLabsPlayer` in a plain HTML setup.\n\nHere's a simplified snippet of how you might set up the player:\n\n```typescript\nimport { IVLabsPlayer, InMemoryDecisionAdapter, LocalStorageDecisionAdapter } from '@interactive-video-labs/core';\n\n// Initialize a decision adapter (e.g., for in-memory storage or local storage)\n// const decisionAdapter = new InMemoryDecisionAdapter();\nconst decisionAdapter = new LocalStorageDecisionAdapter();\n\nconst playerConfig = {\n    videoUrl: 'https://interactive-video-labs.github.io/assets/sample-video.mp4',\n    cues: [\n    {\n        id: 'intro',\n        time: 2,\n        label: 'Introduction',\n        payload: { message: 'Welcome!' }\n    },\n    {\n        id: 'question1',\n        time: 5,\n        label: 'Question 1',\n        payload: {\n            interaction: {\n                type: 'choice',\n                title: 'Quick Question',\n                description: 'Please select the correct answer.',\n                question: 'What is 2+2?',\n                options: ['3', '4', '5'],\n                correctAnswer: '4'\n            }\n        }\n    },\n    {\n        id: 'segmentChange',\n        time: 10,\n        label: 'Segment Change',\n        payload: {\n            interaction: {\n                type: 'choice-video-segment-change',\n                title: 'Choose your path',\n                description: 'Select a video segment to jump to.',\n                question: 'Where would you like to go?',\n                options: [\n                    {\n                        level: 'Segment A',\n                        video: 'https://interactive-video-labs.github.io/assets/sample-interaction-1.mp4'\n                    },\n                    {\n                        level: 'Segment B',\n                        video: 'https://interactive-video-labs.github.io/assets/sample-interaction-2.mp4'\n                    }\n                ]\n            }\n        }\n    },\n    {\n        id: 'midpoint',\n        time: 8,\n        label: 'Midpoint',\n        payload: { message: 'Halfway there!' }\n    },\n    {\n        id: 'question2',\n        time: 12,\n        label: 'Question 2',\n        payload: {\n            interaction: {\n                type: 'text',\n                title: 'Your Information',\n                description: 'Please enter your name below.',\n                question: 'Your name?'\n            }\n        }\n    },\n    {\n        id: 'end',\n        time: 15,\n        label: 'End',\n        payload: { message: 'Thanks for watching!' }\n    }\n],\n    initialState: 'idle',\n    decisionAdapter: decisionAdapter, // Pass the decision adapter to the player config\n};\n\n// Assuming you have a div with id=\"player-container\" in your HTML\nconst player = new IVLabsPlayer('player-container', playerConfig);\n\nplayer.init();\n// player.play(); // Start playback\n```\n\n### Decision Tracking and Persistence\n\nThe `@interactive-video-labs/core` module now supports tracking and persisting user decisions made during interactions. This is achieved through the `DecisionAdapter` interface, which allows you to define how decisions are stored and retrieved. Two concrete implementations are provided:\n\n*   **`InMemoryDecisionAdapter`**: Stores decisions in memory. This is useful for temporary tracking within a single session.\n*   **`LocalStorageDecisionAdapter`**: Stores decisions in the browser's local storage, providing persistence across sessions.\n\nTo use decision tracking, simply instantiate one of the adapters and pass it to the `IVLabsPlayer` configuration:\n\n```typescript\nimport { IVLabsPlayer, LocalStorageDecisionAdapter } from '@interactive-video-labs/core';\n\nconst decisionAdapter = new LocalStorageDecisionAdapter();\n\nconst playerConfig = {\n    // ... other player configurations\n    decisionAdapter: decisionAdapter,\n};\n\nconst player = new IVLabsPlayer('player-container', playerConfig);\nplayer.init();\n\n// To retrieve decision history:\nasync function getHistory() {\n    const history = await decisionAdapter.getDecisionHistory();\n    console.log('Decision History:', history);\n}\n\n// To clear decision history:\nasync function clearHistory() {\n    await decisionAdapter.clearDecisionHistory();\n    console.log('Decision History cleared.');\n}\n```\n\nThis allows you to easily integrate decision tracking into your interactive video experiences, enabling features like personalized content, progress saving, or analytics based on user choices.\n\n\n\n## ✨ Features\n\nThe `@interactive-video-labs/core` engine includes the following core functionalities:\n\n*   **Core Player (`IVLabsPlayer`):** Orchestrates video playback, cue handling, interactions, and analytics.\n*   **State Machine:** Manages player state transitions (e.g., idle, playing, waitingForInteraction).\n*   **Cue Handler:** Manages and triggers cue points based on video time updates.\n*   **Interaction Manager:** Renders and manages various interaction types (choice, text, video segment changes) and handles user responses.\n*   **Analytics System:** Provides a flexible hook system for tracking player and interaction events.\n*   **Segment Manager:** Handles seamless transitions between different video segments.\n*   **Centralized Types:** Defines all core types and interfaces for consistency across the module.\n*   **Basic HTML Demo:** A raw HTML demo (`examples/index.html`) to validate core functionality without frameworks.\n*   **Testing Framework:** Utilizes Vitest for comprehensive unit testing.\n*   **Localization Support:** Enabled for broader audience reach.\n*   **Subtitle-based Cue Generation:** Supports generating cues from subtitles.\n*   **Multi-segment Video Lessons:** Capability to support video content divided into multiple segments.\n*   **Build and Publish Pipeline:** Configured for NPM publishing.\n*   **Decision Tracking and Persistence:** Supports tracking and persisting user decisions using configurable adapters (e.g., `InMemoryDecisionAdapter`, `LocalStorageDecisionAdapter`).\n\n---\n\n## 📁 Examples\n\n```\n/examples/\n  └── index.html      # A raw HTML demo using the built UMD bundle\n```\n\nThis example helps test core functionality without frameworks like React/Vue.\n\n---\n\n## 🧑‍💻 For Developers\n\nFor detailed development setup, project structure, testing, build, and publishing instructions, please refer to our [Developer Guide](DEVELOPER.md).\n\n---\n\n## 🤝 Contributing\n\nWe welcome contributions! Please see our [CONTRIBUTING](CONTRIBUTING.md) for guidelines.\n\n---\n\n## 📄 License\n\nThis project is licensed under the [MIT License](LICENSE).","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Finteractive-video-labs%2Finteractive-video-core","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Finteractive-video-labs%2Finteractive-video-core","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Finteractive-video-labs%2Finteractive-video-core/lists"}