@ct-player/embed 1.0.0

package/README.md

@@ -0,0 +1,269 @@
+# @ct-player/embed
+
+Standalone embeddable interactive course player for `.ct` files. This package bundles all dependencies for easy integration into any React application.
+
+## Features
+
+- **Full Playback** - Video/audio + synchronized code, terminal, whiteboard
+- **Streaming Support** - HLS streaming with adaptive quality
+- **Interactive Mode** - Pause and edit code in real-time
+- **Embeddable** - Drop into any React 18/19 app
+- **Themeable** - Light/dark modes with customization
+- **Versioned** - Semantic versioning for easy updates
+
+## Installation
+
+```bash
+npm install @ct-player/embed
+```
+
+### Required Peer Dependencies
+
+```bash
+npm install react react-dom lucide-react
+```
+
+### Optional Peer Dependencies
+
+Install based on features you need:
+
+```bash
+# For code editor panels
+npm install @monaco-editor/react
+
+# For whiteboard panels  
+npm install @excalidraw/excalidraw
+
+# For PDF/document viewing
+npm install react-pdf
+```
+
+## Quick Start
+
+### Basic Player
+
+```tsx
+import { CoursePlayer } from '@ct-player/embed';
+import '@ct-player/embed/styles.css';
+
+function App() {
+  return (
+    <CoursePlayer
+      recordingUrl="https://cdn.example.com/course.ct"
+      theme="dark"
+      allowInteraction={true}
+      onComplete={() => console.log('Course completed!')}
+    />
+  );
+}
+```
+
+### Streaming Player (HLS/CDN)
+
+```tsx
+import { StreamingCoursePlayer } from '@ct-player/embed';
+import '@ct-player/embed/styles.css';
+
+function App() {
+  return (
+    <StreamingCoursePlayer
+      manifestUrl="https://cdn.example.com/course/manifest.json"
+      theme="dark"
+      autoPlay={false}
+      onProgress={(time, duration) => {
+        console.log(`Progress: ${time}/${duration}`);
+      }}
+    />
+  );
+}
+```
+
+## Props
+
+### CoursePlayer Props
+
+#### Data Source (one required)
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `recording` | `CTRecording` | Pre-loaded recording data |
+| `recordingUrl` | `string` | URL to a .ct file |
+| `recordingId` | `string` | ID to fetch from API |
+
+#### Appearance
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `theme` | `'light' \| 'dark' \| 'system'` | `'system'` | Color theme |
+| `aspectRatio` | `'16:9' \| '4:3' \| 'auto'` | `'16:9'` | Player aspect ratio |
+| `showToolbar` | `boolean` | `true` | Show playback controls |
+| `showTimeline` | `boolean` | `true` | Show timeline |
+| `showChapters` | `boolean` | `true` | Show chapter markers |
+
+#### Behavior
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `autoPlay` | `boolean` | `false` | Start playing when loaded |
+| `defaultSpeed` | `number` | `1.0` | Initial playback speed |
+| `allowInteraction` | `boolean` | `true` | Allow code editing when paused |
+| `allowFullscreen` | `boolean` | `true` | Allow fullscreen mode |
+
+#### Callbacks
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `onReady` | `() => void` | Called when player is ready |
+| `onPlay` | `() => void` | Called when playback starts |
+| `onPause` | `() => void` | Called when playback pauses |
+| `onProgress` | `(time, duration) => void` | Called on progress update |
+| `onComplete` | `() => void` | Called when playback completes |
+| `onError` | `(error) => void` | Called on error |
+
+### StreamingCoursePlayer Props
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `manifestUrl` | `string` | URL to streaming manifest |
+| `theme` | `'light' \| 'dark'` | Color theme |
+| `autoPlay` | `boolean` | Auto-start playback |
+| `initialTime` | `number` | Start position in ms |
+
+Plus all callback props from CoursePlayer.
+
+## Imperative API
+
+Use a ref to control the player programmatically:
+
+```tsx
+import { useRef } from 'react';
+import { CoursePlayer, CoursePlayerRef } from '@ct-player/embed';
+
+function App() {
+  const playerRef = useRef<CoursePlayerRef>(null);
+  
+  return (
+    <>
+      <CoursePlayer ref={playerRef} recordingUrl="/course.ct" />
+      <button onClick={() => playerRef.current?.play()}>Play</button>
+      <button onClick={() => playerRef.current?.pause()}>Pause</button>
+      <button onClick={() => playerRef.current?.seek(30000)}>Skip to 30s</button>
+      <button onClick={() => playerRef.current?.setSpeed(1.5)}>1.5x Speed</button>
+    </>
+  );
+}
+```
+
+### Available Ref Methods
+
+| Method | Description |
+|--------|-------------|
+| `play()` | Start playback |
+| `pause()` | Pause playback |
+| `seek(timeMs)` | Seek to specific time |
+| `setSpeed(speed)` | Set playback speed |
+| `setVolume(volume)` | Set volume (0-1) |
+| `toggleFullscreen()` | Toggle fullscreen |
+| `getState()` | Get current playback state |
+
+## Hooks
+
+For custom player implementations:
+
+```tsx
+import { usePlayback, useStreamingPlayback, useRemoteStreamingPlayback } from '@ct-player/embed';
+
+// Local .ct file playback
+const { state, controls } = usePlayback({ recording });
+
+// Chunked streaming
+const { state, controls, metrics } = useStreamingPlayback(options);
+
+// Remote CDN/HLS streaming
+const { state, controls } = useRemoteStreamingPlayback(options);
+```
+
+## Utilities
+
+### Reading .ct Files
+
+```tsx
+import { readCTFile } from '@ct-player/embed';
+
+const arrayBuffer = await file.arrayBuffer();
+const recording = await readCTFile(arrayBuffer, { loadAllEvents: true });
+```
+
+### HLS Support
+
+```tsx
+import { isHlsSupported, hasNativeHlsSupport } from '@ct-player/embed';
+
+if (isHlsSupported()) {
+  console.log('HLS playback available');
+}
+```
+
+## Styling
+
+The player comes with default styles. Import them in your app:
+
+```tsx
+import '@ct-player/embed/styles.css';
+```
+
+### CSS Variables
+
+Customize the theme using CSS variables:
+
+```css
+:root {
+  --ct-player-bg: #1a1a1a;
+  --ct-player-text: #ffffff;
+  --ct-player-accent: #3b82f6;
+  --ct-player-border: #333333;
+}
+```
+
+## Versioning
+
+This package follows semantic versioning:
+
+- **Patch** (1.0.x): Bug fixes, no breaking changes
+- **Minor** (1.x.0): New features, backward compatible
+- **Major** (x.0.0): Breaking changes
+
+### Updating
+
+```bash
+# Update to latest patch
+npm update @ct-player/embed
+
+# Update to specific version
+npm install @ct-player/embed@1.2.0
+
+# Check for updates
+npm outdated @ct-player/embed
+```
+
+## Browser Support
+
+- Chrome 80+
+- Firefox 75+
+- Safari 14+
+- Edge 80+
+
+## Bundle Size
+
+The package bundles core dependencies for convenience:
+- ~200KB minified (excluding peer dependencies)
+- Tree-shakeable exports for custom implementations
+
+## License
+
+MIT
+
+## Support
+
+- [GitHub Issues](https://github.com/ct-courses/ct-player/issues)
+- [Documentation](https://github.com/ct-courses/ct-player#readme)